chore: more docs

.github/workflows/manual.yml

@@ -114,6 +114,7 @@ jobs:
           registry-url: 'https://registry.npmjs.org'
           cache: 'pnpm'
       - run: pnpm install
+      - run: pnpm run lint
       - run: pnpm run docs
       - uses: actions/configure-pages@v2
       - uses: actions/upload-pages-artifact@v1

.github/workflows/reuse-deploy-api.yml

@@ -45,6 +45,7 @@ jobs:
       - run: pnpm -r --filter @web3-storage/access-api exec wrangler d1 migrations apply __D1_BETA__ --env ${{ inputs.environment }}
         env:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CF_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}
       # Publish worker to cloudflare
       - uses: cloudflare/wrangler-action@2.0.0
         with:

packages/access-client/src/agent.js

@@ -324,7 +324,7 @@ export class Agent {
       throw new Error('No space selected')
     }
 
-    const inv = await this.execute(Voucher.claim, {
+    const inv = await this.invokeAndExecute(Voucher.claim, {
       nb: {
         identity: URI.from(`mailto:${email}`),
         product: 'product:free',
@@ -333,7 +333,7 @@ export class Agent {
     })
 
     if (inv && inv.error) {
-      throw new Error('Voucher claim failed', { cause: inv.error })
+      throw new Error('Voucher claim failed', { cause: inv })
     }
 
     const voucherRedeem = await this.#waitForVoucherRedeem(opts)
@@ -346,7 +346,7 @@ export class Agent {
       },
     })
 
-    const accInv = await this.execute(Voucher.redeem, {
+    const accInv = await this.invokeAndExecute(Voucher.redeem, {
       with: URI.from(service.did()),
       nb: {
         space,
@@ -439,16 +439,93 @@ export class Agent {
   }
 
   /**
-   * Execute the given capability on the Access service connection
+   * Invoke and execute the given capability on the Access service connection
+   *
+   * Sugar for :
+   *
+   * ```js
+   *
+   * await agent.invokeAndExecute(Space.recover, {
+   *   nb: {
+   *     identity: 'mailto: email@gmail.com',
+   *   },
+   * })
+   *
+   * // sugar for
+   * const recoverInvocation = await agent.invoke(Space.recover, {
+   *   nb: {
+   *     identity: 'mailto: email@gmail.com',
+   *   },
+   * })
+   *
+   * await recoverInvocation.execute(agent.connection)
+   * ```
+   *
+   * @template {Ucanto.Ability} A
+   * @template {Ucanto.URI} R
+   * @template {Ucanto.TheCapabilityParser<Ucanto.CapabilityMatch<A, R, C>>} CAP
+   * @template {Ucanto.Caveats} [C={}]
+   * @param {CAP} cap
+   * @param {import('./types').InvokeOptions<A, R, CAP>} options
+   */
+  async invokeAndExecute(cap, options) {
+    const inv = await this.invoke(cap, options)
+
+    // @ts-ignore
+    const out = inv.execute(this.connection)
+
+    return /** @type {Promise<Ucanto.InferServiceInvocationReturn<Ucanto.InferInvokedCapability<CAP>, import('./types').Service>>} */ (
+      out
+    )
+  }
+
+  /**
+   * Execute invocations on the agent's connection
+   *
+   * @example
+   * ```js
+   * const i1 = await agent.invoke(Space.info, {})
+   * const i2 = await agent.invoke(Space.recover, {
+   *   nb: {
+   *     identity: 'mailto:hello@web3.storage',
+   *   },
+   * })
+   *
+   * const results = await agent.execute2(i1, i2)
+   *
+   * ```
+   * @template {Ucanto.Capability} C
+   * @template {Ucanto.Tuple<Ucanto.ServiceInvocation<C, import('./types').Service>>} I
+   * @param {I} invocations
+   */
+  execute(...invocations) {
+    return this.connection.execute(...invocations)
+  }
+
+  /**
+   * Creates an invocation for the given capability with Agent's proofs, service, issuer and space.
+   *
+   * @example
+   * ```js
+   * const recoverInvocation = await agent.invoke(Space.recover, {
+   *   nb: {
+   *     identity: 'mailto: email@gmail.com',
+   *   },
+   * })
+   *
+   * await recoverInvocation.execute(agent.connection)
+   * // or
+   * await agent.execute(recoverInvocation)
+   * ```
    *
    * @template {Ucanto.Ability} A
    * @template {Ucanto.URI} R
    * @template {Ucanto.TheCapabilityParser<Ucanto.CapabilityMatch<A, R, C>>} CAP
    * @template {Ucanto.Caveats} [C={}]
    * @param {CAP} cap
-   * @param {import('./types').ExecuteOptions<A, R, CAP>} options
+   * @param {import('./types').InvokeOptions<A, R, CAP>} options
    */
-  async execute(cap, options) {
+  async invoke(cap, options) {
     const space = options.with || this.currentSpace()
     if (!space) {
       throw new Error('No space selected, you need pass a resource.')
@@ -479,11 +556,8 @@ export class Agent {
       proofs: [...proofs, ...extraProofs],
     })
 
-    // @ts-ignore
-    const out = inv.execute(this.connection)
-
-    return /** @type {Promise<Ucanto.InferServiceInvocationReturn<Ucanto.InferInvokedCapability<CAP>, import('./types').Service>>} */ (
-      out
+    return /** @type {Ucanto.IssuedInvocationView<Ucanto.InferInvokedCapability<CAP>>} */ (
+      inv
     )
   }
 
@@ -505,7 +579,7 @@ export class Agent {
     if (!_space) {
       throw new Error('No space selected, you need pass a resource.')
     }
-    const inv = await this.execute(Space.info, {
+    const inv = await this.invokeAndExecute(Space.info, {
       with: _space,
     })
 

packages/access-client/src/types.ts

@@ -152,7 +152,7 @@ export interface AgentCreateOptions<T> {
   fetch?: typeof fetch
 }
 
-export type ExecuteOptions<
+export type InvokeOptions<
   A extends Ability,
   R extends Resource,
   CAP extends CapabilityParser<

packages/access-client/test/agent.test.js

@@ -90,7 +90,7 @@ describe('Agent', function () {
     )
   })
 
-  it('should execute', async function () {
+  it('should invoke and execute', async function () {
     const store = await StoreMemory.create()
     const agent = await Agent.create({
       store,
@@ -100,7 +100,7 @@ describe('Agent', function () {
     const space = await agent.createSpace('execute')
     await agent.setCurrentSpace(space.did)
 
-    const out = await agent.execute(Space.info, {
+    const out = await agent.invokeAndExecute(Space.info, {
       audience: fixtures.service,
     })
 
@@ -114,6 +114,43 @@ describe('Agent', function () {
     })
   })
 
+  it('should execute', async function () {
+    const store = await StoreMemory.create()
+    const agent = await Agent.create({
+      store,
+      channel: createServer(),
+    })
+
+    const space = await agent.createSpace('execute')
+    await agent.setCurrentSpace(space.did)
+
+    const i1 = await agent.invoke(Space.info, {
+      audience: fixtures.service,
+    })
+    const i2 = await agent.invoke(Space.recover, {
+      audience: fixtures.service,
+      nb: {
+        identity: 'mailto: email@gmail.com',
+      },
+    })
+
+    const out = await agent.execute(i1, i2)
+
+    assert.deepStrictEqual(out, [
+      {
+        did: 'did:key:sss',
+        agent: 'did:key:agent',
+        email: 'mail@mail.com',
+        product: 'product:free',
+        updated_at: 'sss',
+        inserted_at: 'date',
+      },
+      {
+        recover: true,
+      },
+    ])
+  })
+
   it('should fail execute with no proofs', async function () {
     const store = await StoreMemory.create()
     const agent = await Agent.create({
@@ -123,7 +160,7 @@ describe('Agent', function () {
 
     await assert.rejects(
       async () => {
-        await agent.execute(Space.info, {
+        await agent.invokeAndExecute(Space.info, {
           audience: fixtures.service,
           with: URI.from(fixtures.alice.did()),
         })

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

@@ -52,6 +52,11 @@ export function createServer() {
             inserted_at: 'date',
           }
         }),
+        recover: Server.provide(Space.recover, async ({ capability }) => {
+          return {
+            recover: true,
+          }
+        }),
       },
     },
   })