docs: add required capabilities listings to client methods (#1490)

...also adds deprecation notices to `client.capability.store.*`

packages/upload-api/test/handlers/web3.storage.js

@@ -678,8 +678,13 @@ export const test = {
     const delegation = blobAccept.fx.fork[0]
     assert.equal(delegation.capabilities.length, 1)
     assert.ok(delegation.capabilities[0].can, Assert.location.can)
-    // @ts-expect-error nb unknown
-    assert.ok(equals(delegation.capabilities[0].nb.content.digest, content.multihash.bytes))
+    assert.ok(
+      equals(
+        // @ts-expect-error nb unknown
+        delegation.capabilities[0].nb.content.digest,
+        content.multihash.bytes
+      )
+    )
     // @ts-expect-error nb unknown
     const locations = delegation.capabilities[0].nb.location
     assert.equal(locations.length, 1)

packages/w3up-client/src/capability/blob.js

@@ -9,6 +9,9 @@ export class BlobClient extends Base {
   /**
    * Store a Blob to the resource.
    *
+   * Required delegated capabilities:
+   * - `space/blob/add`
+   *
    * @param {Blob} blob - blob data.
    * @param {import('../types.js').RequestOptions} [options]
    */
@@ -21,6 +24,9 @@ export class BlobClient extends Base {
   /**
    * List blobs stored to the resource.
    *
+   * Required delegated capabilities:
+   * - `space/blob/list`
+   *
    * @param {import('../types.js').ListRequestOptions} [options]
    */
   async list(options = {}) {
@@ -32,6 +38,9 @@ export class BlobClient extends Base {
   /**
    * Remove a stored blob by multihash digest.
    *
+   * Required delegated capabilities:
+   * - `space/blob/remove`
+   *
    * @param {import('multiformats').MultihashDigest} digest - digest of blob to remove.
    * @param {import('../types.js').RequestOptions} [options]
    */

packages/w3up-client/src/capability/filecoin.js

@@ -9,6 +9,9 @@ export class FilecoinClient extends Base {
   /**
    * Offer a Filecoin "piece" to the resource.
    *
+   * Required delegated capabilities:
+   * - `filecoin/offer`
+   *
    * @param {import('multiformats').UnknownLink} content
    * @param {import('@web3-storage/capabilities/types').PieceLink} piece
    * @param {object} [options]
@@ -25,6 +28,9 @@ export class FilecoinClient extends Base {
   /**
    * Request info about a content piece in Filecoin deals
    *
+   * Required delegated capabilities:
+   * - `filecoin/info`
+   *
    * @param {import('@web3-storage/capabilities/types').PieceLink} piece
    * @param {object} [options]
    * @param {string} [options.nonce]

packages/w3up-client/src/capability/index.js

@@ -9,6 +9,9 @@ export class IndexClient extends Base {
   /**
    * Register an "index" to the resource.
    *
+   * Required delegated capabilities:
+   * - `space/index/add`
+   *
    * @param {import('../types.js').CARLink} index - CID of the CAR file that contains the index data.
    * @param {import('../types.js').RequestOptions} [options]
    */

packages/w3up-client/src/capability/plan.js

@@ -4,6 +4,8 @@ import * as Plan from '@web3-storage/capabilities/plan'
 
 export class PlanClient extends Base {
   /**
+   * Required delegated capabilities:
+   * - `plan/get`
    *
    * @param {import('@web3-storage/access').AccountDID} account
    * @param {object} [options]
@@ -21,6 +23,8 @@ export class PlanClient extends Base {
   }
 
   /**
+   * Required delegated capabilities:
+   * - `plan/set`
    *
    * @param {API.AccountDID} account
    * @param {API.DID} product

packages/w3up-client/src/capability/space.js

@@ -7,6 +7,9 @@ export class SpaceClient extends Base {
   /**
    * Get information about a space.
    *
+   * Required delegated capabilities:
+   * - `space/info`
+   *
    * @param {import('../types.js').DID} space - DID of the space to retrieve info about.
    * @param {object} [options]
    * @param {string} [options.nonce]

packages/w3up-client/src/capability/store.js

@@ -9,6 +9,10 @@ export class StoreClient extends Base {
   /**
    * Store a DAG encoded as a CAR file.
    *
+   * Required delegated capabilities:
+   * - `store/add`
+   *
+   * @deprecated Use `client.capability.blob.add()` instead.
    * @param {Blob} car - CAR file data.
    * @param {import('../types.js').RequestOptions} [options]
    */
@@ -21,6 +25,10 @@ export class StoreClient extends Base {
   /**
    * Get details of a stored item.
    *
+   * Required delegated capabilities:
+   * - `store/get`
+   *
+   * @deprecated Use `client.capability.blob.get()` instead.
    * @param {import('../types.js').CARLink} link - Root data CID for the DAG that was stored.
    * @param {import('../types.js').RequestOptions} [options]
    */
@@ -33,6 +41,10 @@ export class StoreClient extends Base {
   /**
    * List CAR files stored to the resource.
    *
+   * Required delegated capabilities:
+   * - `store/list`
+   *
+   * @deprecated Use `client.capability.blob.list()` instead.
    * @param {import('../types.js').ListRequestOptions} [options]
    */
   async list(options = {}) {
@@ -44,6 +56,10 @@ export class StoreClient extends Base {
   /**
    * Remove a stored CAR file by CAR CID.
    *
+   * Required delegated capabilities:
+   * - `store/remove`
+   *
+   * @deprecated Use `client.capability.blob.remove()` instead.
    * @param {import('../types.js').CARLink} link - CID of CAR file to remove.
    * @param {import('../types.js').RequestOptions} [options]
    */

packages/w3up-client/src/capability/subscription.js

@@ -9,6 +9,9 @@ export class SubscriptionClient extends Base {
   /**
    * List subscriptions for the passed account.
    *
+   * Required delegated capabilities:
+   * - `subscription/list`
+   *
    * @param {import('@web3-storage/access').AccountDID} account
    * @param {object} [options]
    * @param {string} [options.nonce]

packages/w3up-client/src/capability/upload.js

@@ -9,6 +9,9 @@ export class UploadClient extends Base {
   /**
    * Register an "upload" to the resource.
    *
+   * Required delegated capabilities:
+   * - `upload/add`
+   *
    * @param {import('../types.js').UnknownLink} root - Root data CID for the DAG that was stored.
    * @param {import('../types.js').CARLink[]} shards - CIDs of CAR files that contain the DAG.
    * @param {import('../types.js').RequestOptions} [options]
@@ -22,6 +25,9 @@ export class UploadClient extends Base {
   /**
    * Get details of an "upload".
    *
+   * Required delegated capabilities:
+   * - `upload/get`
+   *
    * @param {import('../types.js').UnknownLink} root - Root data CID for the DAG that was stored.
    * @param {import('../types.js').RequestOptions} [options]
    */
@@ -34,6 +40,9 @@ export class UploadClient extends Base {
   /**
    * List uploads registered to the resource.
    *
+   * Required delegated capabilities:
+   * - `upload/list`
+   *
    * @param {import('../types.js').ListRequestOptions} [options]
    */
   async list(options = {}) {
@@ -45,6 +54,9 @@ export class UploadClient extends Base {
   /**
    * Remove an upload by root data CID.
    *
+   * Required delegated capabilities:
+   * - `upload/remove`
+   *
    * @param {import('../types.js').UnknownLink} root - Root data CID to remove.
    * @param {import('../types.js').RequestOptions} [options]
    */

packages/w3up-client/src/capability/usage.js

@@ -9,6 +9,9 @@ export class UsageClient extends Base {
   /**
    * Get a usage report for the passed space in the given time period.
    *
+   * Required delegated capabilities:
+   * - `usage/report`
+   *
    * @param {import('../types.js').SpaceDID} space
    * @param {{ from: Date, to: Date }} period
    * @param {object} [options]

packages/w3up-client/src/client.js

@@ -109,6 +109,12 @@ export class Client extends Base {
    * Uploads a file to the service and returns the root data CID for the
    * generated DAG.
    *
+   * Required delegated capabilities:
+   * - `filecoin/offer`
+   * - `space/blob/add`
+   * - `space/index/add`
+   * - `upload/add`
+   *
    * @param {import('./types.js').BlobLike} file - File data.
    * @param {import('./types.js').UploadOptions} [options]
    */
@@ -128,6 +134,12 @@ export class Client extends Base {
    * for the generated DAG. All files are added to a container directory, with
    * paths in file names preserved.
    *
+   * Required delegated capabilities:
+   * - `filecoin/offer`
+   * - `space/blob/add`
+   * - `space/index/add`
+   * - `upload/add`
+   *
    * @param {import('./types.js').FileLike[]} files - File data.
    * @param {import('./types.js').UploadDirectoryOptions} [options]
    */
@@ -145,13 +157,19 @@ export class Client extends Base {
   /**
    * Uploads a CAR file to the service.
    *
-   * The difference between this function and `capability.store.add` is that
+   * The difference between this function and `capability.blob.add` is that
    * the CAR file is automatically sharded, an index is generated, uploaded and
    * registered (see `capability.index.add`) and finally an an "upload" is
    * registered, linking the individual shards (see `capability.upload.add`).
    *
    * Use the `onShardStored` callback to obtain the CIDs of the CAR file shards.
    *
+   * Required delegated capabilities:
+   * - `filecoin/offer`
+   * - `space/blob/add`
+   * - `space/index/add`
+   * - `upload/add`
+   *
    * @param {import('./types.js').BlobLike} car - CAR file.
    * @param {import('./types.js').UploadOptions} [options]
    */
@@ -317,6 +335,12 @@ export class Client extends Base {
    * ⚠️ If `shards` option is `true` all shards will be deleted even if there is another upload(s) that
    * reference same shards, which in turn could corrupt those uploads.
    *
+   * Required delegated capabilities:
+   * - `space/blob/remove`
+   * - `store/remove`
+   * - `upload/get`
+   * - `upload/remove`
+   *
    * @param {import('multiformats').UnknownLink} contentCID
    * @param {object} [options]
    * @param {boolean} [options.shards]