Merge branch 'main' into update-readme

.github/release-please-manifest.json

@@ -1,9 +1,9 @@
 {
-  "packages/access-client": "15.1.0",
-  "packages/filecoin-api": "1.2.0",
-  "packages/filecoin-client": "1.2.0",
-  "packages/capabilities": "9.0.1",
-  "packages/upload-api": "5.0.0",
+  "packages/access-client": "15.2.0",
+  "packages/filecoin-api": "1.4.1",
+  "packages/filecoin-client": "1.3.0",
+  "packages/capabilities": "9.2.1",
+  "packages/upload-api": "5.2.0",
   "packages/upload-client": "9.1.1",
   "packages/w3up-client": "8.0.1",
   "packages/did-mailto": "2.0.0"

.github/workflows/release.yml

@@ -29,8 +29,8 @@ jobs:
       contains(fromJson(needs.release.outputs.paths_released), 'packages/did-mailto') ||
       contains(fromJson(needs.release.outputs.paths_released), 'packages/upload-client') ||
       contains(fromJson(needs.release.outputs.paths_released), 'packages/upload-api') ||
-      contains(fromJson(needs.release.outputs.paths_released), 'packages/aggregate-client') ||
-      contains(fromJson(needs.release.outputs.paths_released), 'packages/aggregate-api') ||
+      contains(fromJson(needs.release.outputs.paths_released), 'packages/filecoin-client') ||
+      contains(fromJson(needs.release.outputs.paths_released), 'packages/filecoin-api') ||
       contains(fromJson(needs.release.outputs.paths_released), 'packages/w3up-client')
     runs-on: ubuntu-latest
     steps:
@@ -53,6 +53,6 @@ jobs:
     if: |
       contains(fromJson(needs.release.outputs.paths_released), 'packages/access-client') ||
       contains(fromJson(needs.release.outputs.paths_released), 'packages/capabilities') ||
-      contains(fromJson(needs.release.outputs.paths_released), 'packages/aggregate-client') ||
+      contains(fromJson(needs.release.outputs.paths_released), 'packages/filecoin-client') ||
       contains(fromJson(needs.release.outputs.paths_released), 'packages/upload-client')
     uses: './.github/workflows/reusable-deploy-docs.yml'

packages/access-client/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [15.2.0](https://github.com/web3-storage/w3up/compare/access-v15.1.1...access-v15.2.0) (2023-08-29)
+
+
+### Features
+
+* make agent Service generic ([#875](https://github.com/web3-storage/w3up/issues/875)) ([cdfe36d](https://github.com/web3-storage/w3up/commit/cdfe36dc7298e92066d0454144f598b0e0535b19))
+
+## [15.1.1](https://github.com/web3-storage/w3up/compare/access-v15.1.0...access-v15.1.1) (2023-08-25)
+
+
+### Bug Fixes
+
+* update docs to bump version ([#870](https://github.com/web3-storage/w3up/issues/870)) ([d2eec7c](https://github.com/web3-storage/w3up/commit/d2eec7cff1125898c0388957aa7a91fbba2e54f2))
+
 ## [15.1.0](https://github.com/web3-storage/w3up/compare/access-v15.0.0...access-v15.1.0) (2023-08-09)
 
 

packages/access-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web3-storage/access",
-  "version": "15.1.0",
+  "version": "15.2.0",
   "description": "w3access client",
   "homepage": "https://github.com/web3-storage/w3-protocol/tree/main/packages/access-client",
   "repository": {

packages/access-client/src/agent.js

@@ -35,7 +35,7 @@ const PRINCIPAL = DID.parse('did:web:web3.storage')
  *
  * @deprecated - remove this when deprecated addSpacesFromDelegations is removed
  */
-/** @type {WeakMap<Agent, AgentData>} */
+/** @type {WeakMap<Agent<Record<string, any>>, AgentData>} */
 const agentToData = new WeakMap()
 
 /**
@@ -53,12 +53,13 @@ const agentToData = new WeakMap()
  * ```
  *
  * @template {Ucanto.DID} T - DID method
+ * @template {Record<string, any>} [S=Service]
  * @param {object} [options]
  * @param {Ucanto.Principal<T>} [options.principal] - w3access API Principal
  * @param {URL} [options.url] - w3access API URL
- * @param {Ucanto.Transport.Channel<Service>} [options.channel] - Ucanto channel to use
+ * @param {Ucanto.Transport.Channel<S>} [options.channel] - Ucanto channel to use
  * @param {typeof fetch} [options.fetch] - Fetch implementation to use
- * @returns {Ucanto.ConnectionView<Service>}
+ * @returns {Ucanto.ConnectionView<S>}
  */
 export function connection(options = {}) {
   return Client.connect({
@@ -82,17 +83,19 @@ export function connection(options = {}) {
  * ```js
  * import { Agent } from '@web3-storage/access/agent'
  * ```
+ *
+ * @template {Record<string, any>} [S=Service]
  */
 export class Agent {
   /** @type {import('./agent-data').AgentData} */
   #data
 
   /**
    * @param {import('./agent-data').AgentData} data - Agent data
-   * @param {import('./types').AgentOptions} [options]
+   * @param {import('./types').AgentOptions<S>} [options]
    */
   constructor(data, options = {}) {
-    /** @type { Client.Channel<Service> & { url?: URL } | undefined } */
+    /** @type { Client.Channel<S> & { url?: URL } | undefined } */
     const channel = options.connection?.channel
     this.url = options.url ?? channel?.url ?? new URL(HOST)
     this.connection =
@@ -108,8 +111,9 @@ export class Agent {
   /**
    * Create a new Agent instance, optionally with the passed initialization data.
    *
+   * @template {Record<string, any>} [R=Service]
    * @param {Partial<import('./types').AgentDataModel>} [init]
-   * @param {import('./types').AgentOptions & import('./types').AgentDataOptions} [options]
+   * @param {import('./types').AgentOptions<R> & import('./types').AgentDataOptions} [options]
    */
   static async create(init, options = {}) {
     const data = await AgentData.create(init, options)
@@ -119,8 +123,9 @@ export class Agent {
   /**
    * Instantiate an Agent from pre-exported agent data.
    *
+   * @template {Record<string, any>} [R=Service]
    * @param {import('./types').AgentDataExport} raw
-   * @param {import('./types').AgentOptions & import('./types').AgentDataOptions} [options]
+   * @param {import('./types').AgentOptions<R> & import('./types').AgentDataOptions} [options]
    */
   static from(raw, options = {}) {
     const data = AgentData.fromExport(raw, options)
@@ -378,9 +383,10 @@ export class Agent {
   }
 
   /**
-   * Invokes voucher/redeem for the free tier, wait on the websocket for the voucher/claim and invokes it
+   * Requests a subscription from a provider and attaches it to a space.
    *
-   * It also adds a full space delegation to the service in the voucher/claim invocation to allow for recovery
+   * It also adds a full space delegation to the service that can later
+   * be claimed by the currently authorized account to restore access to the space.
    *
    * @param {string} email
    * @param {object} [opts]
@@ -462,7 +468,7 @@ export class Agent {
    * @template {Ucanto.Caveats} C
    * @param {Ucanto.TheCapabilityParser<Ucanto.CapabilityMatch<A, R, C>>} cap
    * @param {import('./types').InvokeOptions<A, R, Ucanto.TheCapabilityParser<Ucanto.CapabilityMatch<A, R, C>>>} options
-   * @returns {Promise<Ucanto.InferReceipt<Ucanto.Capability<A, R, C>, import('./types').Service>>}
+   * @returns {Promise<Ucanto.InferReceipt<Ucanto.Capability<A, R, C>, S>>}
    */
   async invokeAndExecute(cap, options) {
     const inv = await this.invoke(cap, options)
@@ -486,7 +492,7 @@ export class Agent {
    *
    * ```
    * @template {Ucanto.Capability} C
-   * @template {Ucanto.Tuple<Ucanto.ServiceInvocation<C, import('./types').Service>>} I
+   * @template {Ucanto.Tuple<Ucanto.ServiceInvocation<C, S>>} I
    * @param {I} invocations
    */
   execute(...invocations) {
@@ -582,7 +588,7 @@ export class Agent {
       throw inv.out.error
     }
 
-    return inv.out.ok
+    return /** @type {import('./types').SpaceInfoResult} */ (inv.out.ok)
   }
 }
 
@@ -592,7 +598,8 @@ export class Agent {
  * @deprecated - trying to remove explicit space tracking from Agent/AgentData
  * in favor of functions that derive the space set from access.delegations
  *
- * @param {Agent} access
+ * @template {Record<string, any>} [S=Service]
+ * @param {Agent<S>} access
  * @param {Ucanto.Delegation<Ucanto.Capabilities>[]} delegations
  */
 export async function addSpacesFromDelegations(access, delegations) {

packages/access-client/src/types.ts

@@ -193,9 +193,9 @@ export interface SpaceMeta {
  * Agent class types
  */
 
-export interface AgentOptions {
+export interface AgentOptions<S extends Record<string, any>> {
   url?: URL
-  connection?: ConnectionView<Service>
+  connection?: ConnectionView<S>
   servicePrincipal?: Principal
 }
 

packages/capabilities/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [9.2.1](https://github.com/web3-storage/w3up/compare/capabilities-v9.2.0...capabilities-v9.2.1) (2023-08-30)
+
+
+### Bug Fixes
+
+* w3filecoin spec separate capabilities to queue and enqueue ([#856](https://github.com/web3-storage/w3up/issues/856)) ([6bf9142](https://github.com/web3-storage/w3up/commit/6bf9142636fa65367faed8414c50beb9c1791726)), closes [#855](https://github.com/web3-storage/w3up/issues/855)
+
+## [9.2.0](https://github.com/web3-storage/w3up/compare/capabilities-v9.1.0...capabilities-v9.2.0) (2023-08-22)
+
+
+### Features
+
+* change "total" to "limit" ([#867](https://github.com/web3-storage/w3up/issues/867)) ([8295070](https://github.com/web3-storage/w3up/commit/8295070c8fbbc508da2cfe6f32846090a530f282))
+
+## [9.1.0](https://github.com/web3-storage/w3up/compare/capabilities-v9.0.1...capabilities-v9.1.0) (2023-08-22)
+
+
+### Features
+
+* add subscriptions to CustomerGetSuccess ([#863](https://github.com/web3-storage/w3up/issues/863)) ([dd2e77c](https://github.com/web3-storage/w3up/commit/dd2e77c51d84a517cb50ff05199b8eebf9223bf2))
+
 ## [9.0.1](https://github.com/web3-storage/w3up/compare/capabilities-v9.0.0...capabilities-v9.0.1) (2023-08-10)
 
 

packages/capabilities/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web3-storage/capabilities",
-  "version": "9.0.1",
+  "version": "9.2.1",
   "description": "Capabilities provided by web3.storage",
   "homepage": "https://github.com/web3-storage/w3protocol/tree/main/packages/capabilities",
   "repository": {

packages/capabilities/src/filecoin.js

@@ -30,7 +30,37 @@ const PIECE_LINK = Schema.link({
 })
 
 /**
- * `filecoin/add` capability allows agent to add a filecoin piece to be aggregated
+ * `filecoin/queue` capability allows agent to queue a filecoin piece to be aggregated
+ * so that it can be stored by a Storage provider on a future time.
+ */
+export const filecoinQueue = capability({
+  can: 'filecoin/queue',
+  /**
+   * did:key identifier of the broker authority where offer is made available.
+   */
+  with: Schema.did(),
+  nb: Schema.struct({
+    /**
+     * CID of the content that resulted in Filecoin piece.
+     */
+    content: Schema.link(),
+    /**
+     * CID of the piece.
+     */
+    piece: /** @type {import('./types').PieceLinkSchema} */ (PIECE_LINK),
+  }),
+  derives: (claim, from) => {
+    return (
+      and(equalWith(claim, from)) ||
+      and(checkLink(claim.nb.content, from.nb.content, 'nb.content')) ||
+      and(checkLink(claim.nb.piece, from.nb.piece, 'nb.piece')) ||
+      ok({})
+    )
+  },
+})
+
+/**
+ * `filecoin/add` capability allows storefront to add a filecoin piece to be aggregated
  * so that it can be stored by a Storage provider on a future time.
  */
 export const filecoinAdd = capability({
@@ -62,7 +92,37 @@ export const filecoinAdd = capability({
 })
 
 /**
- * `aggregate/add` capability allows agent to add a piece to be aggregated
+ * `aggregate/queue` capability allows storefront to queue a piece to be aggregated
+ * so that it can be stored by a Storage provider on a future time.
+ */
+export const aggregateQueue = capability({
+  can: 'aggregate/queue',
+  /**
+   * did:key identifier of the broker authority where offer is made available.
+   */
+  with: Schema.did(),
+  nb: Schema.struct({
+    /**
+     * CID of the piece.
+     */
+    piece: /** @type {import('./types').PieceLinkSchema} */ (PIECE_LINK),
+    /**
+     * Grouping for the piece to be aggregated
+     */
+    group: Schema.text(),
+  }),
+  derives: (claim, from) => {
+    return (
+      and(equalWith(claim, from)) ||
+      and(checkLink(claim.nb.piece, from.nb.piece, 'nb.piece')) ||
+      and(equal(claim.nb.group, from.nb.group, 'nb.group')) ||
+      ok({})
+    )
+  },
+})
+
+/**
+ * `aggregate/add` capability allows aggregator to add a piece to aggregate
  * so that it can be stored by a Storage provider on a future time.
  */
 export const aggregateAdd = capability({
@@ -79,7 +139,7 @@ export const aggregateAdd = capability({
      */
     piece: /** @type {import('./types').PieceLinkSchema} */ (PIECE_LINK),
     /**
-     * Storefront requestin piece to be aggregated
+     * Storefront requesting piece to be aggregated
      */
     storefront: Schema.text(),
     /**
@@ -99,9 +159,51 @@ export const aggregateAdd = capability({
 })
 
 /**
- * `deal/add` capability allows agent to create a deal offer to get an aggregate
+ * `deal/queue` capability allows storefront to create a deal offer to get an aggregate
  * of CARs files in the market to be fetched and stored by a Storage provider.
  */
+export const dealQueue = capability({
+  can: 'deal/queue',
+  /**
+   * did:key identifier of the broker authority where offer is made available.
+   */
+  with: Schema.did(),
+  nb: Schema.struct({
+    /**
+     * CID of the DAG-CBOR encoded block with offer details.
+     * Service will queue given offer to be validated and handled.
+     */
+    pieces: Schema.link(),
+    /**
+     * Commitment proof for the aggregate being offered.
+     * https://github.com/filecoin-project/go-state-types/blob/1e6cf0d47cdda75383ef036fc2725d1cf51dbde8/abi/piece.go#L47-L50
+     */
+    aggregate: /** @type {import('./types').PieceLinkSchema} */ (PIECE_LINK),
+    /**
+     * Storefront requesting deal
+     */
+    storefront: Schema.text(),
+    /**
+     * arbitrary label to be added to the deal on chain
+     */
+    label: Schema.text().optional(),
+  }),
+  derives: (claim, from) => {
+    return (
+      and(equalWith(claim, from)) ||
+      and(checkLink(claim.nb.aggregate, from.nb.aggregate, 'nb.aggregate')) ||
+      and(checkLink(claim.nb.pieces, from.nb.pieces, 'nb.pieces')) ||
+      and(equal(claim.nb.storefront, from.nb.storefront, 'nb.storefront')) ||
+      and(equal(claim.nb.label, from.nb.label, 'nb.label')) ||
+      ok({})
+    )
+  },
+})
+
+/**
+ * `deal/add` capability allows Dealer to submit offer with an aggregate of
+ * Filecoin pieces in the market to be fetched and stored by a Storage provider.
+ */
 export const dealAdd = capability({
   can: 'deal/add',
   /**

packages/capabilities/src/index.js

@@ -52,8 +52,11 @@ export const abilitiesAsStrings = [
   RateLimit.add.can,
   RateLimit.remove.can,
   RateLimit.list.can,
+  Filecoin.filecoinQueue.can,
   Filecoin.filecoinAdd.can,
+  Filecoin.aggregateQueue.can,
   Filecoin.aggregateAdd.can,
+  Filecoin.dealQueue.can,
   Filecoin.dealAdd.can,
   Filecoin.chainTrackerInfo.can,
 ]