From 5a398ef05ba37efaf3bec57887dd31c58592d2c9 Mon Sep 17 00:00:00 2001
From: Alan Shaw <alan.shaw@protocol.ai>
Date: Tue, 4 Jun 2024 13:45:33 +0100
Subject: [PATCH 1/3] docs: add required capabilities listings to client
 methods

---
 packages/w3up-client/src/capability/blob.js   |  9 +++++++
 .../w3up-client/src/capability/filecoin.js    |  6 +++++
 packages/w3up-client/src/capability/index.js  |  3 +++
 packages/w3up-client/src/capability/plan.js   |  4 +++
 packages/w3up-client/src/capability/space.js  |  3 +++
 packages/w3up-client/src/capability/store.js  | 16 ++++++++++++
 .../src/capability/subscription.js            |  3 +++
 packages/w3up-client/src/capability/upload.js | 12 +++++++++
 packages/w3up-client/src/capability/usage.js  |  3 +++
 packages/w3up-client/src/client.js            | 26 ++++++++++++++++++-
 10 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/packages/w3up-client/src/capability/blob.js b/packages/w3up-client/src/capability/blob.js
index e2e57b03b..168d7c301 100644
--- a/packages/w3up-client/src/capability/blob.js
+++ b/packages/w3up-client/src/capability/blob.js
@@ -8,6 +8,9 @@ import { Base } from '../base.js'
 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]
@@ -20,6 +23,9 @@ export class BlobClient extends Base {
 
   /**
    * List blobs stored to the resource.
+   * 
+   * Required delegated capabilities:
+   * - `space/blob/list`
    *
    * @param {import('../types.js').ListRequestOptions} [options]
    */
@@ -31,6 +37,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]
diff --git a/packages/w3up-client/src/capability/filecoin.js b/packages/w3up-client/src/capability/filecoin.js
index 28182267e..54c8e3a02 100644
--- a/packages/w3up-client/src/capability/filecoin.js
+++ b/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]
diff --git a/packages/w3up-client/src/capability/index.js b/packages/w3up-client/src/capability/index.js
index af3b6a941..36ee2650a 100644
--- a/packages/w3up-client/src/capability/index.js
+++ b/packages/w3up-client/src/capability/index.js
@@ -8,6 +8,9 @@ import { Base } from '../base.js'
 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]
diff --git a/packages/w3up-client/src/capability/plan.js b/packages/w3up-client/src/capability/plan.js
index 679487f14..bdc1562b4 100644
--- a/packages/w3up-client/src/capability/plan.js
+++ b/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
diff --git a/packages/w3up-client/src/capability/space.js b/packages/w3up-client/src/capability/space.js
index e660812fa..f37d31fae 100644
--- a/packages/w3up-client/src/capability/space.js
+++ b/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]
diff --git a/packages/w3up-client/src/capability/store.js b/packages/w3up-client/src/capability/store.js
index d5053645b..1f9a3f56d 100644
--- a/packages/w3up-client/src/capability/store.js
+++ b/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]
    */
diff --git a/packages/w3up-client/src/capability/subscription.js b/packages/w3up-client/src/capability/subscription.js
index ce6baf9a3..6ef9d496e 100644
--- a/packages/w3up-client/src/capability/subscription.js
+++ b/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]
diff --git a/packages/w3up-client/src/capability/upload.js b/packages/w3up-client/src/capability/upload.js
index c9d9b3e72..318abb25b 100644
--- a/packages/w3up-client/src/capability/upload.js
+++ b/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 = {}) {
@@ -44,6 +53,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]
diff --git a/packages/w3up-client/src/capability/usage.js b/packages/w3up-client/src/capability/usage.js
index 81cf5aa84..19b53ba7c 100644
--- a/packages/w3up-client/src/capability/usage.js
+++ b/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]
diff --git a/packages/w3up-client/src/client.js b/packages/w3up-client/src/client.js
index bc7851f93..52581e3b9 100644
--- a/packages/w3up-client/src/client.js
+++ b/packages/w3up-client/src/client.js
@@ -108,6 +108,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,12 +157,18 @@ 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]
@@ -336,6 +354,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]

From 2b5bfb0187bd8b56649f7a84aa5276f7ac2d8e55 Mon Sep 17 00:00:00 2001
From: Alan Shaw <alan.shaw@protocol.ai>
Date: Tue, 4 Jun 2024 13:48:32 +0100
Subject: [PATCH 2/3] chore: appease linter

---
 packages/upload-api/test/handlers/web3.storage.js | 7 ++++++-
 packages/w3up-client/src/capability/blob.js       | 6 +++---
 packages/w3up-client/src/capability/index.js      | 2 +-
 packages/w3up-client/src/capability/upload.js     | 2 +-
 packages/w3up-client/src/client.js                | 6 +++---
 5 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/packages/upload-api/test/handlers/web3.storage.js b/packages/upload-api/test/handlers/web3.storage.js
index d326b08ce..9ec1189f9 100644
--- a/packages/upload-api/test/handlers/web3.storage.js
+++ b/packages/upload-api/test/handlers/web3.storage.js
@@ -679,7 +679,12 @@ export const test = {
     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(
+        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)
diff --git a/packages/w3up-client/src/capability/blob.js b/packages/w3up-client/src/capability/blob.js
index 168d7c301..f267d949a 100644
--- a/packages/w3up-client/src/capability/blob.js
+++ b/packages/w3up-client/src/capability/blob.js
@@ -8,7 +8,7 @@ import { Base } from '../base.js'
 export class BlobClient extends Base {
   /**
    * Store a Blob to the resource.
-   * 
+   *
    * Required delegated capabilities:
    * - `space/blob/add`
    *
@@ -23,7 +23,7 @@ export class BlobClient extends Base {
 
   /**
    * List blobs stored to the resource.
-   * 
+   *
    * Required delegated capabilities:
    * - `space/blob/list`
    *
@@ -37,7 +37,7 @@ export class BlobClient extends Base {
 
   /**
    * Remove a stored blob by multihash digest.
-   * 
+   *
    * Required delegated capabilities:
    * - `space/blob/remove`
    *
diff --git a/packages/w3up-client/src/capability/index.js b/packages/w3up-client/src/capability/index.js
index 36ee2650a..e963f1ec0 100644
--- a/packages/w3up-client/src/capability/index.js
+++ b/packages/w3up-client/src/capability/index.js
@@ -8,7 +8,7 @@ import { Base } from '../base.js'
 export class IndexClient extends Base {
   /**
    * Register an "index" to the resource.
-   * 
+   *
    * Required delegated capabilities:
    * - `space/index/add`
    *
diff --git a/packages/w3up-client/src/capability/upload.js b/packages/w3up-client/src/capability/upload.js
index 318abb25b..5b709bf9d 100644
--- a/packages/w3up-client/src/capability/upload.js
+++ b/packages/w3up-client/src/capability/upload.js
@@ -53,7 +53,7 @@ export class UploadClient extends Base {
 
   /**
    * Remove an upload by root data CID.
-   * 
+   *
    * Required delegated capabilities:
    * - `upload/remove`
    *
diff --git a/packages/w3up-client/src/client.js b/packages/w3up-client/src/client.js
index 52581e3b9..99b9903d2 100644
--- a/packages/w3up-client/src/client.js
+++ b/packages/w3up-client/src/client.js
@@ -108,7 +108,7 @@ 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`
@@ -163,7 +163,7 @@ export class Client extends Base {
    * 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`
@@ -354,7 +354,7 @@ 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`

From ccfdf0d09654b86e8359f4d2680c5b83f6f193c4 Mon Sep 17 00:00:00 2001
From: Alan Shaw <alan.shaw@protocol.ai>
Date: Tue, 4 Jun 2024 13:54:48 +0100
Subject: [PATCH 3/3] chore: oh great thanks prettier

---
 packages/upload-api/test/handlers/web3.storage.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/upload-api/test/handlers/web3.storage.js b/packages/upload-api/test/handlers/web3.storage.js
index 9ec1189f9..87c702ada 100644
--- a/packages/upload-api/test/handlers/web3.storage.js
+++ b/packages/upload-api/test/handlers/web3.storage.js
@@ -678,9 +678,9 @@ 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(
+        // @ts-expect-error nb unknown
         delegation.capabilities[0].nb.content.digest,
         content.multihash.bytes
       )