From b7a0b7d770cee6dd13babe6a2d50e9dbb7c82b17 Mon Sep 17 00:00:00 2001 From: Alan Shaw Date: Tue, 4 Jun 2024 13:57:49 +0100 Subject: [PATCH] docs: add required capabilities listings to client methods (#1490) ...also adds deprecation notices to `client.capability.store.*` --- .../upload-api/test/handlers/web3.storage.js | 9 +++++-- 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 ++++++++++++++++++- 11 files changed, 91 insertions(+), 3 deletions(-) diff --git a/packages/upload-api/test/handlers/web3.storage.js b/packages/upload-api/test/handlers/web3.storage.js index d326b08ce..87c702ada 100644 --- a/packages/upload-api/test/handlers/web3.storage.js +++ b/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) diff --git a/packages/w3up-client/src/capability/blob.js b/packages/w3up-client/src/capability/blob.js index e2e57b03b..f267d949a 100644 --- a/packages/w3up-client/src/capability/blob.js +++ b/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] */ 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..e963f1ec0 100644 --- a/packages/w3up-client/src/capability/index.js +++ b/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] */ 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..5b709bf9d 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 = {}) { @@ -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] */ 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 2af93f561..59dd4b19d 100644 --- a/packages/w3up-client/src/client.js +++ b/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]