chore: add doc comments to the capabilities

packages/access-api/package.json

@@ -17,13 +17,13 @@
   "license": "(Apache-2.0 OR MIT)",
   "dependencies": {
     "@ipld/dag-ucan": "^2.0.1",
-    "@ucanto/client": "^3.0.1",
-    "@ucanto/core": "^3.0.1",
-    "@ucanto/interface": "^3.0.0",
-    "@ucanto/principal": "^3.0.0",
-    "@ucanto/server": "^3.0.1",
-    "@ucanto/transport": "^3.0.1",
-    "@ucanto/validator": "^3.0.1",
+    "@ucanto/client": "^3.0.2",
+    "@ucanto/core": "^3.0.2",
+    "@ucanto/interface": "^3.0.1",
+    "@ucanto/principal": "^3.0.1",
+    "@ucanto/server": "^3.0.4",
+    "@ucanto/transport": "^3.0.2",
+    "@ucanto/validator": "^3.0.4",
     "@web3-storage/access": "workspace:^",
     "@web3-storage/worker-utils": "0.4.3-dev",
     "multiformats": "^10.0.2",

packages/access-api/test/helpers/utils.js

@@ -22,7 +22,7 @@ export async function send(ucan, mf) {
 
 /**
  * @param {Types.Signer} issuer
- * @param {Types.Principal} service
+ * @param {Types.Principal<"key">} service
  * @param {Types.ConnectionView<import('@web3-storage/access/types').Service>} conn
  * @param {string} email
  */

packages/access/package.json

@@ -62,13 +62,13 @@
     "@ipld/dag-ucan": "^2.0.1",
     "@noble/ed25519": "^1.7.1",
     "@types/ws": "^8.5.3",
-    "@ucanto/client": "^3.0.1",
-    "@ucanto/core": "^3.0.1",
-    "@ucanto/interface": "^3.0.0",
-    "@ucanto/principal": "^3.0.0",
-    "@ucanto/server": "^3.0.1",
-    "@ucanto/transport": "^3.0.1",
-    "@ucanto/validator": "^3.0.1",
+    "@ucanto/client": "^3.0.2",
+    "@ucanto/core": "^3.0.2",
+    "@ucanto/interface": "^3.0.1",
+    "@ucanto/principal": "^3.0.1",
+    "@ucanto/server": "^3.0.4",
+    "@ucanto/transport": "^3.0.2",
+    "@ucanto/validator": "^3.0.4",
     "@web-std/fetch": "^4.1.0",
     "bigint-mod-arith": "^3.1.2",
     "conf": "^10.1.2",

packages/access/src/agent.js

@@ -63,7 +63,7 @@ export async function connection(principal, _fetch, url) {
  * Agent
  */
 export class Agent {
-  /** @type {Ucanto.Principal|undefined} */
+  /** @type {Ucanto.Principal<"key">|undefined} */
   #service
 
   /** @type {typeof fetch} */

packages/access/src/capabilities/store.js

@@ -1,17 +1,27 @@
+/* eslint-disable jsdoc/require-param */
 import { capability, Failure, Link, URI, Schema } from '@ucanto/validator'
 import { equalLink, equalWith } from './utils.js'
 import { any } from './any.js'
 
 /**
- * all the `store/*` capabilities which can also be derived
- * from any capability.
+ * Capability can only be delegated (but not invoked) allowing audience to
+ * derived any `store/` prefixed capability for the (memory) space identified
+ * by did:key in the `with` field.
  */
 export const store = any.derive({
   to: capability({
     can: 'store/*',
+    /**
+     * did:key identifier of the (memory) space where CAR is intended to
+     * be stored.
+     */
     with: URI.match({ protocol: 'did:' }),
     derives: equalWith,
   }),
+  /**
+   * `store/*` can be derived from the `*` capability as long as `with` field
+   * is the same.
+   */
   derives: equalWith,
 })
 
@@ -23,17 +33,42 @@ export const store = any.derive({
 const base = any.or(store)
 
 /**
- * `store/add` can be derived from the `store/*` capability
- * as long as with fields match.
+ * `store/add` capability allows agent to store a CAR file into a (memory) space
+ * identified by did:key in the `with` field. Agent must precompute CAR locally
+ * and provide it's CID and size using `nb.link` and `nb.size` fields, allowing
+ * a service to provision a write location for the agent to PUT or POST desired
+ * CAR into.
  */
 export const add = base.derive({
   to: capability({
     can: 'store/add',
+    /**
+     * did:key identifier of the (memory) space where CAR is intended to
+     * be stored.
+     */
     with: URI.match({ protocol: 'did:' }),
     nb: {
-      link: Link.optional(),
+      /**
+       * CID of the CAR file to be stored. Service will provision write target
+       * for this exact CAR file for agent to PUT or POST it. Attempt to write
+       * any other content will fail.
+       */
+      link: Link,
+      /**
+       * Size of the CAR file to be stored. Service will provision write target
+       * for this exact size. Attempt to write a larger CAR file will fail.
+       */
+      size: Schema.integer(),
+      /**
+       * Agent may optionally provide a link to a related CAR file using `origin`
+       * field. This is useful when storing large DAGs, agent could shard it
+       * across multiple CAR files and then link each shard with a previous one.
+       *
+       * Providing this relation tells service that given CAR is shard of the
+       * larger DAG as opposed to it being intentionally partial DAG. When DAG is
+       * not sharded, there will be only one `store/add` with `origin` left out.
+       */
       origin: Link.optional(),
-      size: Schema.integer().optional(),
     },
     derives: (claim, from) => {
       const result = equalLink(claim, from)
@@ -50,24 +85,51 @@ export const add = base.derive({
       }
     },
   }),
+  /**
+   * `store/add` can be derived from the `store/*` & `*` capability
+   * as long as the `with` fields match.
+   */
   derives: equalWith,
 })
 
+/**
+ * Capability can be used to remove the stored CAR file from the (memory)
+ * space identified by `with` field.
+ */
 export const remove = base.derive({
   to: capability({
     can: 'store/remove',
+    /**
+     * did:key identifier of the (memory) space where CAR is intended to
+     * be stored.
+     */
     with: URI.match({ protocol: 'did:' }),
     nb: {
-      link: Link.optional(),
+      /**
+       * CID of the CAR file to be removed from the store.
+       */
+      link: Link,
     },
     derives: equalLink,
   }),
+  /**
+   * `store/remove` can be derived from the `store/*` & `*` capability
+   * as long as the `with` fields match.
+   */
   derives: equalWith,
 })
 
+/**
+ * Capability can be invoked to request a list of stored CAR files in the
+ * (memory) space identified by `with` field.
+ */
 export const list = base.derive({
   to: capability({
     can: 'store/list',
+    /**
+     * did:key identifier of the (memory) space where CAR is intended to
+     * be stored.
+     */
     with: URI.match({ protocol: 'did:' }),
     derives: (claimed, delegated) => {
       if (claimed.with !== delegated.with) {
@@ -78,6 +140,10 @@ export const list = base.derive({
       return true
     },
   }),
+  /**
+   * `store/list` can be derived from the `store/*` & `*` capability
+   * as long as the `with` fields match.
+   */
   derives: equalWith,
 })
 

packages/access/src/capabilities/upload.js

@@ -1,18 +1,27 @@
 import { capability, Link, URI } from '@ucanto/validator'
-import { codec } from '@ucanto/transport/car'
+import { codec as CAR } from '@ucanto/transport/car'
 import { equalWith, fail, equal } from './utils.js'
 import { any } from './any.js'
 
 /**
- * All the `upload/*` capabilities which can also be derived
- * from `any` (a.k.a `*`) capability.
+ * Capability can only be delegated (but not invoked) allowing audience to
+ * derived any `upload/` prefixed capability for the (memory) space identified
+ * by did:key in the `with` field.
  */
 export const upload = any.derive({
   to: capability({
     can: 'upload/*',
+    /**
+     * did:key identifier of the (memory) space where upload is add to the
+     * upload list.
+     */
     with: URI.match({ protocol: 'did:' }),
     derives: equalWith,
   }),
+  /**
+   * `upload/*` can be derived from the `*` capability as long as `with` field
+   * is the same.
+   */
   derives: equalWith,
 })
 
@@ -23,18 +32,45 @@ export const upload = any.derive({
 // `upload/*`.
 const base = any.or(upload)
 
-const CARLink = Link.match({ code: codec.code, version: 1 })
+/**
+ * Schema representing a link (a.k.a CID) to a CAR file. Enforces CAR codec code and CID v1.
+ */
+const CARLink = Link.match({ code: CAR.code, version: 1 })
 
 /**
- * `upload/add` can be derived from the `upload/*` capability
- * as long as with fields match.
+ * Capability allows an agent to add an arbitrary DAG (root) to the upload list
+ * of the specified (memory) space (identified by did:key in the `with` field).
+ * It is recommended to provide an optional list of shard links that contain
+ * fragments of this DAG, as it allows system to optimize block discovery, it is
+ * also a way to communicate DAG partiality - this upload contains partial DAG
+ * identified by the given `root`.
+ *
+ * Usually when agent wants to upload a DAG it will encode it as a one or more
+ * CAR files (shards) and invoke `store/add` capability for each one. Once all
+ * shards are stored it will invoke `upload/add` capability (providing link to
+ * a DAG root and all the shards) to add it the upload list.
+ *
+ * That said `upload/add` could be invoked without invoking `store/add`s e.g.
+ * because another (memory) space may already have those CARs.
+ *
+ * Note: If DAG with the given root is already in the upload list, invocation
+ * will simply update `shards` to be a union of existing and new shards.
  */
 export const add = base.derive({
   to: capability({
     can: 'upload/add',
+    /**
+     * did:key identifier of the (memory) space where uploaded is added.
+     */
     with: URI.match({ protocol: 'did:' }),
     nb: {
-      root: Link.optional(),
+      /**
+       * Root CID of the DAG to be added to the upload list.
+       */
+      root: Link,
+      /**
+       * CIDs to the CAR files that contain blocks of the DAG.
+       */
       shards: CARLink.array().optional(),
     },
     derives: (self, from) => {
@@ -46,15 +82,30 @@ export const add = base.derive({
       )
     },
   }),
+  /**
+   * `upload/add` can be derived from the `upload/*` & `*` capability
+   * as long as `with` fields match.
+   */
   derives: equalWith,
 })
 
+/**
+ * Capability removes an upload (identified by it's root CID) from the upload
+ * list. Please note that removing an upload does not delete corresponding shards
+ * from the store, however that could be done via `store/remove` invocations.
+ */
 export const remove = base.derive({
   to: capability({
     can: 'upload/remove',
+    /**
+     * did:key identifier of the (memory) space where uploaded is removed from.
+     */
     with: URI.match({ protocol: 'did:' }),
     nb: {
-      root: Link.optional(),
+      /**
+       * Root CID of the DAG to be removed from the upload list.
+       */
+      root: Link,
     },
     derives: (self, from) => {
       return (
@@ -64,13 +115,25 @@ export const remove = base.derive({
       )
     },
   }),
+  /**
+   * `upload/remove` can be derived from the `upload/*` & `*` capability
+   * as long as `with` fields match.
+   */
   derives: equalWith,
 })
 
+/**
+ * Capability can be invoked to request a list of uploads in the (memory) space
+ * identified by the `with` field.
+ */
 export const list = base.derive({
   to: capability({
     can: 'upload/list',
     with: URI.match({ protocol: 'did:' }),
   }),
+  /**
+   * `upload/list` can be derived from the `upload/*` & `*` capability
+   * as long as with fields match.
+   */
   derives: equalWith,
 })