@interop/was-client 0.2.0 → 0.4.0

package/README.md

@@ -1,19 +1,25 @@
 # Wallet Attached Storage Client _(@interop/was-client)_
 
+[![Node.js CI](https://github.com/interop-alliance/was-client/workflows/CI/badge.svg)](https://github.com/interop-alliance/was-client/actions?query=workflow%3A%22CI%22)
 [![NPM Version](https://img.shields.io/npm/v/@interop/was-client.svg)](https://npm.im/@interop/was-client)
 
 > A developer-friendly client for Wallet Attached Storage (WAS) servers, with a
-> MongoDB-driver-inspired navigational API over zcap-authorized HTTP.
+> database-driver-inspired navigational API over zcap-authorized HTTP.
 
 ## Table of Contents
 
 - [Background](#background)
 - [Install](#install)
 - [Usage](#usage)
-  - [Construction](#construction)
+  - [Creating a client (signer + zcapClient)](#creating-a-client-signer--zcapclient)
   - [The handle model](#the-handle-model)
+  - [Spaces](#spaces)
+  - [Collections](#collections)
   - [Resources: JSON and binary](#resources-json-and-binary)
   - [Delegation and sharing](#delegation-and-sharing)
+  - [Public sharing and access-control policies](#public-sharing-and-access-control-policies)
+  - [Resource metadata](#resource-metadata)
+  - [Storage introspection: backends and quotas](#storage-introspection-backends-and-quotas)
   - [Export and import](#export-and-import)
   - [The manual-request escape hatch](#the-manual-request-escape-hatch)
 - [Errors and the 404/null caveat](#errors-and-the-404null-caveat)
@@ -22,23 +28,19 @@
 
 ## Background
 
-The WAS protocol exposes a containment model --
+The WAS protocol exposes a general purpose database-like container model --
 `SpacesRepository > Space > Collection > Resource` -- over HTTP, authorized with
-[Authorization Capabilities (zcaps)](https://w3c-ccg.github.io/zcap-spec/). The
-low-level transport is an
-[`@interop/ezcap`](https://www.npmjs.com/package/@interop/ezcap) `ZcapClient`,
-where every operation hand-builds a URL, picks a trailing-slash variant, threads
-JSON vs binary bodies, and reasons about delegation inline.
+[Authorization Capabilities (zcaps)](https://w3c-ccg.github.io/zcap-spec/).
 
 `@interop/was-client` wraps that `ZcapClient` and exposes the containment model
-through cheap, lazy navigational handles modeled on the MongoDB driver's DX
+through cheap, lazy navigational handles modeled on a document store's DX
 (`client > db > collection`), using WAS-specific verbs
 (`add`/`get`/`put`/`list`/`delete`) rather than `insertOne`/`findOne` (WAS has
 no query-by-filter yet).
 
-| MongoDB driver                      | WAS client                                 |
+| Document db driver                  | WAS client                                 |
 | ----------------------------------- | ------------------------------------------ |
-| `new MongoClient(url)`              | `new WasClient({ serverUrl, zcapClient })` |
+| `new Client(url)`                   | `new WasClient({ serverUrl, zcapClient })` |
 | `client.db('app')`                  | `was.space(spaceId)`                       |
 | `db.collection('users')`            | `space.collection(collectionId)`           |
 | `collection.insertOne(doc)`         | `collection.add(doc)`                      |
@@ -57,34 +59,86 @@ pnpm install @interop/was-client
 
 ## Usage
 
-### Construction
+### Creating a client (signer + zcapClient)
+
+A `WasClient` signs every request with a key you control. The key is held by an
+ezcap `ZcapClient`, which you build from a `did:key` identity. You will need two
+companion packages alongside this one (this library already depends on
+`@interop/ed25519-signature`):
+
+```
+pnpm install @interop/ezcap @interop/did-method-key @interop/ed25519-verification-key
+```
+
+The primary form wraps a `ZcapClient` you build yourself. The `did:key` driver
+generates a key pair and a matching DID document, wiring the signer's
+`id`/`controller` correctly:
 
 ```ts
+import { ZcapClient } from '@interop/ezcap'
+import * as didKey from '@interop/did-method-key'
+import { Ed25519Signature2020 } from '@interop/ed25519-signature'
+import { Ed25519VerificationKey } from '@interop/ed25519-verification-key'
 import { WasClient } from '@interop/was-client'
 
-// Primary form: wrap an existing ezcap ZcapClient (which holds the signer).
-const was = new WasClient({ serverUrl, zcapClient })
+// 1. Generate a did:key identity (didDocument + keyPairs).
+const didKeyDriver = didKey.driver()
+didKeyDriver.use({ keyPairClass: Ed25519VerificationKey })
+const { didDocument, keyPairs } = await didKeyDriver.generate()
 
-// Convenience: build the ZcapClient internally from a signer
-// (uses the Ed25519Signature2020 suite).
-const was = WasClient.fromSigner({ serverUrl, signer })
+// 2. Build the ezcap ZcapClient (it holds the signer and signs every request).
+const zcapClient = new ZcapClient({
+  didDocument,
+  keyPairs,
+  SuiteClass: Ed25519Signature2020
+})
+
+// 3. Wrap it.
+const was = new WasClient({ serverUrl: 'https://was.example', zcapClient })
 ```
 
+If you already have a single signer, `WasClient.fromSigner()` builds the
+`ZcapClient` internally (using the `Ed25519Signature2020` suite). A signer is
+any object with `{ id, sign() }`; here we get one from a generated key. The
+signer's `id` must be a `did:key` so the server can resolve and verify it:
+
+```ts
+import { Ed25519VerificationKey } from '@interop/ed25519-verification-key'
+import { WasClient } from '@interop/was-client'
+
+// Pass a 32-byte `seed` for a deterministic key, or omit it for a random one.
+const keyPair = await Ed25519VerificationKey.generate({ seed })
+keyPair.controller = `did:key:${keyPair.fingerprint()}`
+keyPair.id = `${keyPair.controller}#${keyPair.fingerprint()}`
+
+const was = WasClient.fromSigner({
+  serverUrl: 'https://was.example',
+  signer: keyPair.signer()
+})
+```
+
+The `seed` is where a passphrase-, stored-secret-, or KMS-derived key plugs in:
+deriving the same 32-byte seed yields the same DID, and therefore access to the
+same spaces. (Apps with user accounts often derive the signer from a passphrase
+via `CapabilityAgent.fromSecret()` from `@digitalbazaar/webkms-client` -- not
+required, just a common alternative.)
+
 `serverUrl` is the base for both URL building and zcap `invocationTarget`s, so
 the "server URL must equal the invocation target host:port" constraint holds by
 construction.
 
 ### The handle model
 
+The client exposes the WAS containment model
+(`SpacesRepository > Space > Collection > Resource`) as navigational handles.
 Handles are lazy and synchronous to obtain -- only the verb methods hit the
 network. Lazy chains never throw: `was.space(x).collection(y)` does no I/O and
 just accumulates URL context. Existence is checked on the first network verb.
 
 ```ts
-const space = await was.createSpace({ name: 'Home' }) // POST /spaces/
+const space = await was.createSpace({ name: 'Home' })
 
 const collection = await space.createCollection({
-  id: 'credentials',
   name: 'Verifiable Credentials'
 })
 
@@ -94,18 +148,99 @@ await collection.put('vc-1', {
 })
 const vc = await collection.get('vc-1') // parsed JSON object, or null on a miss
 
-const listing = await collection.list() // { id, url, totalItems, items, ... }
-
 await collection.resource('vc-1').delete() // delete one resource by id
 await space.delete() // delete the whole space (idempotent)
 ```
 
 `delete()` is uniform at every level, takes no argument, and always deletes the
 thing the handle points at -- so there is no "delete the collection" vs "delete
-one item" footgun.
+one item" footgun. The next sections cover each level in turn.
+
+### Spaces
+
+A Space is the top-level container, created from the spaces repository. The
+server requires a `name`; `controller` defaults to the client's own DID, and the
+server generates the id unless you pass one.
+
+```ts
+const space = await was.createSpace({ name: 'Home' }) // POST /spaces/
+
+// Lazy handle to an existing space by id -- no I/O until a verb runs.
+const same = was.space(space.id)
+
+// Read the Space Description (null if missing or not visible to you).
+const desc = await space.describe() // { id, type: ['Space'], name, controller } | null
+
+// Upsert: merges the given fields over the current description.
+await space.configure({ name: 'Home (renamed)' })
+
+await space.delete() // idempotent
+```
+
+Listing every space in the repository (`was.listSpaces()`) is specified but not
+yet implemented by the reference server, so it currently throws
+`NotImplementedError`. To enumerate what is _inside_ a space, use
+`space.collections()` (below).
+
+### Collections
+
+A Collection lives inside a Space and holds resources. WAS does not auto-create
+parents, so `createCollection` throws `NotFoundError` if the space does not
+exist. The server generates the id unless you pass one (a handful of reserved
+ids are rejected).
+
+```ts
+// Create.
+const collection = await space.createCollection({
+  name: 'Verifiable Credentials'
+})
+
+// Lazy handle to an existing collection by id.
+const same = space.collection(collection.id)
+
+// Read the Collection Description (null if missing or not visible).
+const desc = await collection.describe() // { id, type: ['Collection'], name } | null
+
+// Update (upsert; merges over the current description).
+await collection.configure({ name: 'Credentials' })
+
+// List the collections in a space.
+const collections = await space.collections()
+// { url, totalItems, items: [{ id, name, url }, ...] } | null
+
+// List the resources inside this collection.
+const resources = await collection.list()
+// { id, url, totalItems, items: [{ id, url, contentType }, ...], ... } | null
+
+await collection.delete() // deletes the whole collection; idempotent
+```
+
+To delete a single resource instead of the whole collection, use
+`collection.resource(id).delete()`.
 
 ### Resources: JSON and binary
 
+A Resource is a JSON object or binary blob keyed by id within a Collection. Use
+`add()` for a server-generated id or `put(id, ...)` to create-or-replace at a
+known id (both throw `NotFoundError` if the parent collection is missing):
+
+```ts
+// Server-generated id; returns { id, url, contentType? }.
+const added = await collection.add({
+  type: ['VerifiableCredential'],
+  name: 'Diploma'
+})
+
+// Create or replace at a known id (upsert).
+await collection.put('vc-1', {
+  type: ['VerifiableCredential'],
+  name: 'Diploma'
+})
+
+const vc = await collection.get('vc-1') // parsed JSON object, or null on a miss
+await collection.resource('vc-1').delete() // idempotent
+```
+
 Writes detect the payload: a plain object/array is sent as JSON; a
 `Blob`/`Uint8Array`/`Buffer` is sent as binary, with the content-type taken from
 `options.contentType`, the `Blob.type`, or `application/octet-stream`.
@@ -168,6 +303,7 @@ const link = added.url // hand this URL out; a plain GET resolves it
 
 // Inspect or revoke.
 const policy = await collection.getPolicy() // { type: 'PublicCanRead' } | null
+const isPublic = await collection.isPublic() // true if its own policy is PublicCanRead
 await collection.clearPolicy() // revert to capability-only access (idempotent)
 
 // setPolicy() is the generic, forward-compatible primitive; setPublic() is sugar.
@@ -176,10 +312,71 @@ await resource.setPublic() // a single public resource
 ```
 
 Policies are resolved most-specific-first (Resource over Collection over Space)
-and are permissive-only -- they broaden access, never restrict a valid capability
-holder. Managing a policy is a controller-level operation. Discover a policy via
-`space.linkset()` / `collection.linkset()` (RFC9264) or the `linkset` property on
-a description.
+and are permissive-only -- they broaden access, never restrict a valid
+capability holder. Managing a policy is a controller-level operation. Discover a
+policy via `space.linkset()` / `collection.linkset()` (RFC9264) or the `linkset`
+property on a description.
+
+`isPublic()` is a read-only convenience that returns `true` when the Space,
+Collection, or Resource has a `{ type: 'PublicCanRead' }` policy -- that is,
+when it has been made public via `setPublic()` (or an equivalent `setPolicy()`
+call). It's meant to drive data-browser style UI, to show a "This
+space(/collection/resource) has been shared publicly" type of icon.
+
+#### Consuming public links (unauthenticated reads)
+
+The flip side of `setPublic()`: reading a `PublicCanRead` resource or collection
+with no authorization, by its URL. These use an unsigned plain `fetch` (no
+capability invocation), so they work for a consumer who only holds the link.
+
+```ts
+// Fetch a single public resource (auto-parses JSON, returns binary as a Blob).
+const doc = await was.publicRead({
+  resourceUrl: 'https://was.example/space/s/c/r'
+}) // Json | Blob | null
+
+// List a public collection -- e.g. a blog published as a public-read collection.
+const listing = await was.publicListCollection({
+  collectionUrl: 'https://was.example/space/s/c'
+}) // ResourceListing | null
+```
+
+Both follow the read-method 404/null caveat: a missing or non-public target
+resolves to `null`.
+
+### Resource metadata
+
+Each Resource has a metadata object at its reserved `/meta` path: server-managed
+properties (`contentType`, `size`, optional `createdAt` / `updatedAt`) plus a
+user-writable `custom` object (`name` and `tags`).
+
+```ts
+const resource = collection.resource('vc-1')
+
+const meta = await resource.meta() // ResourceMetadata | null (null on a miss)
+
+// setMeta() is a full replacement of `custom`; omitted properties are cleared.
+await resource.setMeta({ custom: { name: 'Diploma', tags: { year: '2026' } } })
+
+// setName() / setTags() are read-modify-write sugar that preserve the other.
+await resource.setName('Renamed diploma') // keeps existing tags
+await resource.setTags({ status: 'verified' }) // keeps existing name
+```
+
+The `custom.name` is the same value surfaced as a resource's `name` in
+collection listings; updating one updates the other.
+
+### Storage introspection: backends and quotas
+
+A Space can report the storage backends available to it and a per-backend usage
+report. Both are optional server features (a server without them surfaces a
+`NotImplementedError`); both follow the read-method 404/null caveat.
+
+```ts
+const backends = await space.backends() // BackendDescriptor[] | null
+const report = await space.quotas() // SpaceQuotaReport | null
+// report.backends[i]: { id, state, usageBytes, limit, restrictedActions, ... }
+```
 
 ### Export and import
 
@@ -208,20 +405,28 @@ MongoDB's `findOne` semantics. **WAS returns 404 for both not-found and
 unauthorized**, so `null` means "not visible to you" rather than strictly "does
 not exist". Write/delete methods throw a typed error instead.
 
-| Status | Read methods          | Write / delete methods |
-| ------ | --------------------- | ---------------------- |
-| 404    | `null`                | `NotFoundError`        |
-| 400    | `ValidationError`     | `ValidationError`      |
-| 401    | `AuthRequiredError`   | `AuthRequiredError`    |
-| 501    | `NotImplementedError` | `NotImplementedError`  |
-| 5xx    | `WasServerError`      | `WasServerError`       |
-
-All error classes extend `WasError` (carrying `status`, `title`, `details`, and
-`requestUrl`). `delete()` additionally treats a 404 as success, so it is
-idempotent.
-
-Some spec endpoints (`listSpaces()`, `meta`, `query`, ...) are not yet
-implemented by the reference server and currently surface `NotImplementedError`.
+| Status | Read methods           | Write / delete methods |
+| ------ | ---------------------- | ---------------------- |
+| 404    | `null`                 | `NotFoundError`        |
+| 400    | `ValidationError`      | `ValidationError`      |
+| 401    | `AuthRequiredError`    | `AuthRequiredError`    |
+| 409    | `ConflictError`        | `ConflictError`        |
+| 413    | `PayloadTooLargeError` | `PayloadTooLargeError` |
+| 501    | `NotImplementedError`  | `NotImplementedError`  |
+| 507    | `QuotaExceededError`   | `QuotaExceededError`   |
+| 5xx    | `WasServerError`       | `WasServerError`       |
+
+All error classes extend `WasError` (carrying `status`, the problem-kind `type`
+URI, `title`, `details`, and `requestUrl`). When the server sends a
+`problem+json` `type` (the spec's Error Type Registry), `mapError()` dispatches
+on that kind first and falls back to the HTTP status -- so, for example, a 409
+`id-conflict` from `createSpace({ id })` is catchable as a `ConflictError`, and
+a 507 `quota-exceeded` (a client-actionable storage-full condition, not a server
+fault) as a `QuotaExceededError`. `delete()` additionally treats a 404 as
+success, so it is idempotent.
+
+Some spec endpoints (`listSpaces()`, ...) are not yet implemented by the
+reference server and currently surface `NotImplementedError`.
 
 ## Contribute
 

package/dist/Collection.d.ts

@@ -1,6 +1,6 @@
 import type { ClientContext } from './internal/request.js';
 import { Resource } from './Resource.js';
-import type { AddResult, BackendReference, CollectionDescription, GrantOptions, HandleOptions, IDelegatedZcap, IZcap, Json, LinkSet, PolicyDocument, ResourceListing } from './types.js';
+import type { AddResult, BackendReference, CollectionDescription, GrantOptions, HandleOptions, IDelegatedZcap, IZcap, Json, LinkSet, PolicyDocument, CollectionResourcesList } from './types.js';
 export declare class Collection {
     readonly spaceId: string;
     readonly id: string;
@@ -97,9 +97,9 @@ export declare class Collection {
      * Lists the items in the collection. Returns `null` if the collection is
      * missing or not visible to you (404 conflation caveat).
      *
-     * @returns {Promise<ResourceListing | null>}
+     * @returns {Promise<CollectionResourcesList | null>}
      */
-    list(): Promise<ResourceListing | null>;
+    list(): Promise<CollectionResourcesList | null>;
     /**
      * Delegates access to this collection. Prefills the grant `target` with this
      * collection's URL (and the bound `capability`, if any, for re-delegation).
@@ -124,6 +124,12 @@ export declare class Collection {
      * @returns {Promise<void>}
      */
     setPolicy(policy: PolicyDocument): Promise<void>;
+    /**
+     * Returns `true` when this collection's policy is `PublicCanRead`.
+     *
+     * @returns {Promise<boolean>}
+     */
+    isPublic(): Promise<boolean>;
     /**
      * Makes the collection world-readable: every resource in it becomes readable
      * without authorization (unless overridden by a more specific policy). Sugar

package/dist/Collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Collection.d.ts","sourceRoot":"","sources":["../src/Collection.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,KAAK,EACL,IAAI,EACJ,OAAO,EACP,cAAc,EACd,eAAe,EAChB,MAAM,YAAY,CAAA;AAEnB,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAO;IAEpC;;;;;;;OAOG;gBACS,EACV,OAAO,EACP,OAAO,EACP,YAAY,EACZ,UAAU,EACX,EAAE;QACD,OAAO,EAAE,aAAa,CAAA;QACtB,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,CAAC,EAAE,KAAK,CAAA;KACnB;IAOD,OAAO,KAAK,KAAK,GAEhB;IAED,OAAO,KAAK,UAAU,GAErB;IAED;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAUvD;;;;;;;;OAQG;IACG,SAAS,CAAC,IAAI,EAAE;QACpB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,gBAAgB,CAAA;KAC3B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAoBlC;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAS7B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,QAAQ;IAUnE;;;;;;;;;OASG;IACG,GAAG,CACP,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,UAAU,EAC9B,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GACrC,OAAO,CAAC,SAAS,CAAC;IAgCrB;;;;;;;OAOG;IACG,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAU1D;;;;;;;;OAQG;IACG,GAAG,CACP,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,UAAU,EAC9B,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GACrC,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAU7C;;;;;;OAMG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAU3D;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAUjD;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAStD;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IASlC;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;CASzC"}
+{"version":3,"file":"Collection.d.ts","sourceRoot":"","sources":["../src/Collection.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,KAAK,EACL,IAAI,EACJ,OAAO,EACP,cAAc,EACd,uBAAuB,EACxB,MAAM,YAAY,CAAA;AAEnB,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAO;IAEpC;;;;;;;OAOG;gBACS,EACV,OAAO,EACP,OAAO,EACP,YAAY,EACZ,UAAU,EACX,EAAE;QACD,OAAO,EAAE,aAAa,CAAA;QACtB,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,CAAC,EAAE,KAAK,CAAA;KACnB;IAOD,OAAO,KAAK,KAAK,GAEhB;IAED,OAAO,KAAK,UAAU,GAErB;IAED;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAUvD;;;;;;;;OAQG;IACG,SAAS,CAAC,IAAI,EAAE;QACpB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,gBAAgB,CAAA;KAC3B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAqBlC;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAS7B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,QAAQ;IAUnE;;;;;;;;;OASG;IACG,GAAG,CACP,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,UAAU,EAC9B,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GACrC,OAAO,CAAC,SAAS,CAAC;IAgCrB;;;;;;;OAOG;IACG,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAU1D;;;;;;;;OAQG;IACG,GAAG,CACP,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,UAAU,EAC9B,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GACrC,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC;IAUrD;;;;;;OAMG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAU3D;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAUjD;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAStD;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAKlC;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IASlC;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;CASzC"}

package/dist/Collection.js

@@ -8,6 +8,7 @@
  */
 import { collectionPath, collectionItems, collectionPolicy, collectionLinkset, resourcePath, toUrl } from './internal/paths.js';
 import { prepareBody, parseResource } from './internal/content.js';
+import { assertNotReserved } from './internal/reserved.js';
 import { delegateGrant } from './internal/grant.js';
 import { send } from './internal/request.js';
 import { Resource } from './Resource.js';
@@ -62,6 +63,7 @@ export class Collection {
      * @returns {Promise<CollectionDescription>}
      */
     async configure(desc) {
+        assertNotReserved(this.id, 'collection');
         const current = await this.describe();
         const name = desc.name ?? current?.name;
         const body = { id: this.id, name };
@@ -179,7 +181,7 @@ export class Collection {
      * Lists the items in the collection. Returns `null` if the collection is
      * missing or not visible to you (404 conflation caveat).
      *
-     * @returns {Promise<ResourceListing | null>}
+     * @returns {Promise<CollectionResourcesList | null>}
      */
     async list() {
         const response = await send(this._context, {
@@ -236,6 +238,15 @@ export class Collection {
             json: policy
         });
     }
+    /**
+     * Returns `true` when this collection's policy is `PublicCanRead`.
+     *
+     * @returns {Promise<boolean>}
+     */
+    async isPublic() {
+        const policy = await this.getPolicy();
+        return policy?.type === 'PublicCanRead';
+    }
     /**
      * Makes the collection world-readable: every resource in it becomes readable
      * without authorization (unless overridden by a more specific policy). Sugar

package/dist/Collection.js.map

@@ -1 +1 @@
-{"version":3,"file":"Collection.js","sourceRoot":"","sources":["../src/Collection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Collection.js","sourceRoot":"","sources":["../src/Collection.ts"],"names":[],"mappings":"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"}

package/dist/Resource.d.ts

@@ -1,5 +1,5 @@
 import type { ClientContext } from './internal/request.js';
-import type { IZcap, Json, PolicyDocument } from './types.js';
+import type { IZcap, Json, PolicyDocument, ResourceMetadata, ResourceMetadataCustom } from './types.js';
 export declare class Resource {
     readonly spaceId: string;
     readonly collectionId: string;
@@ -63,6 +63,46 @@ export declare class Resource {
      * @returns {Promise<void>}
      */
     delete(): Promise<void>;
+    private get _metaPath();
+    /**
+     * Reads the resource's metadata object (server-managed `contentType` / `size`
+     * / timestamps plus the user-writable `custom` object). Returns `null` if the
+     * resource is missing or not visible to you (404 conflation caveat). A server
+     * without metadata support surfaces its 501 as `NotImplementedError`.
+     *
+     * @returns {Promise<ResourceMetadata | null>}
+     */
+    meta(): Promise<ResourceMetadata | null>;
+    /**
+     * Replaces the resource's user-writable metadata (`custom`). This is a full
+     * replacement: any property omitted from `custom` is cleared, and an omitted
+     * `custom` clears them all. Does not create the resource -- a `PUT` to the
+     * metadata of a nonexistent resource throws `NotFoundError`. Servers without
+     * metadata support surface their 501 as `NotImplementedError`.
+     *
+     * @param meta {object}
+     * @param [meta.custom] {ResourceMetadataCustom}   the user-writable properties
+     * @returns {Promise<void>}
+     */
+    setMeta(meta?: {
+        custom?: ResourceMetadataCustom;
+    }): Promise<void>;
+    /**
+     * Sets the resource's human-readable `name` (the value surfaced in collection
+     * listings), preserving any existing `tags`. Convenience over `setMeta()`.
+     *
+     * @param name {string}
+     * @returns {Promise<void>}
+     */
+    setName(name: string): Promise<void>;
+    /**
+     * Sets the resource's `tags`, preserving any existing `name`. Convenience over
+     * `setMeta()`.
+     *
+     * @param tags {Record<string, string>}
+     * @returns {Promise<void>}
+     */
+    setTags(tags: Record<string, string>): Promise<void>;
     private get _policyPath();
     /**
      * Reads the resource's access-control policy. Returns `null` when no policy is
@@ -86,6 +126,12 @@ export declare class Resource {
      * @returns {Promise<void>}
      */
     setPublic(): Promise<void>;
+    /**
+     * Returns `true` when this resource policy is `PublicCanRead`.
+     *
+     * @returns {Promise<boolean>}
+     */
+    isPublic(): Promise<boolean>;
     /**
      * Removes the resource's access-control policy, reverting it to
      * capability-only access. Idempotent.

package/dist/Resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Resource.d.ts","sourceRoot":"","sources":["../src/Resource.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE7D,qBAAa,QAAQ;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAO;IAEpC;;;;;;;OAOG;gBACS,EACV,OAAO,EACP,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACX,EAAE;QACD,OAAO,EAAE,aAAa,CAAA;QACtB,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,CAAC,EAAE,KAAK,CAAA;KACnB;IAQD,OAAO,KAAK,KAAK,GAEhB;IAED;;;;;;OAMG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAUxC;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUvC;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAa5C;;;;;;;;;OASG;IACG,GAAG,CACP,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,UAAU,EAC9B,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GACrC,OAAO,CAAC,IAAI,CAAC;IAehB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAS7B,OAAO,KAAK,WAAW,GAEtB;IAED;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAUjD;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAStD;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAQnC"}
+{"version":3,"file":"Resource.d.ts","sourceRoot":"","sources":["../src/Resource.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D,OAAO,KAAK,EACV,KAAK,EACL,IAAI,EACJ,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AAEnB,qBAAa,QAAQ;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAO;IAEpC;;;;;;;OAOG;gBACS,EACV,OAAO,EACP,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACX,EAAE;QACD,OAAO,EAAE,aAAa,CAAA;QACtB,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,CAAC,EAAE,KAAK,CAAA;KACnB;IAQD,OAAO,KAAK,KAAK,GAEhB;IAED;;;;;;OAMG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAUxC;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUvC;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAa5C;;;;;;;;;OASG;IACG,GAAG,CACP,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,UAAU,EAC9B,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GACrC,OAAO,CAAC,IAAI,CAAC;IAehB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAS7B,OAAO,KAAK,SAAS,GAEpB;IAED;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAU9C;;;;;;;;;;OAUG;IACG,OAAO,CAAC,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,sBAAsB,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5E;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1C;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1D,OAAO,KAAK,WAAW,GAEtB;IAED;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAUjD;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAStD;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAKlC;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAQnC"}

package/dist/Resource.js

@@ -6,7 +6,7 @@
  * keyed by id within a Collection). Sugar over the Collection item operations,
  * with explicit `getText()` / `getBytes()` escape hatches.
  */
-import { resourcePath, resourcePolicy } from './internal/paths.js';
+import { resourcePath, resourcePolicy, resourceMeta } from './internal/paths.js';
 import { prepareBody, parseResource } from './internal/content.js';
 import { assertNotReserved } from './internal/reserved.js';
 import { send } from './internal/request.js';
@@ -120,6 +120,67 @@ export class Resource {
             idempotent: true
         });
     }
+    get _metaPath() {
+        return resourceMeta(this.spaceId, this.collectionId, this.id);
+    }
+    /**
+     * Reads the resource's metadata object (server-managed `contentType` / `size`
+     * / timestamps plus the user-writable `custom` object). Returns `null` if the
+     * resource is missing or not visible to you (404 conflation caveat). A server
+     * without metadata support surfaces its 501 as `NotImplementedError`.
+     *
+     * @returns {Promise<ResourceMetadata | null>}
+     */
+    async meta() {
+        const response = await send(this._context, {
+            path: this._metaPath,
+            method: 'GET',
+            capability: this._capability,
+            read: true
+        });
+        return response === null ? null : response.data;
+    }
+    /**
+     * Replaces the resource's user-writable metadata (`custom`). This is a full
+     * replacement: any property omitted from `custom` is cleared, and an omitted
+     * `custom` clears them all. Does not create the resource -- a `PUT` to the
+     * metadata of a nonexistent resource throws `NotFoundError`. Servers without
+     * metadata support surface their 501 as `NotImplementedError`.
+     *
+     * @param meta {object}
+     * @param [meta.custom] {ResourceMetadataCustom}   the user-writable properties
+     * @returns {Promise<void>}
+     */
+    async setMeta(meta = {}) {
+        await send(this._context, {
+            path: this._metaPath,
+            method: 'PUT',
+            capability: this._capability,
+            json: { custom: meta.custom ?? {} }
+        });
+    }
+    /**
+     * Sets the resource's human-readable `name` (the value surfaced in collection
+     * listings), preserving any existing `tags`. Convenience over `setMeta()`.
+     *
+     * @param name {string}
+     * @returns {Promise<void>}
+     */
+    async setName(name) {
+        const current = await this.meta();
+        await this.setMeta({ custom: { ...current?.custom, name } });
+    }
+    /**
+     * Sets the resource's `tags`, preserving any existing `name`. Convenience over
+     * `setMeta()`.
+     *
+     * @param tags {Record<string, string>}
+     * @returns {Promise<void>}
+     */
+    async setTags(tags) {
+        const current = await this.meta();
+        await this.setMeta({ custom: { ...current?.custom, tags } });
+    }
     get _policyPath() {
         return resourcePolicy(this.spaceId, this.collectionId, this.id);
     }
@@ -162,6 +223,15 @@ export class Resource {
     async setPublic() {
         await this.setPolicy({ type: 'PublicCanRead' });
     }
+    /**
+     * Returns `true` when this resource policy is `PublicCanRead`.
+     *
+     * @returns {Promise<boolean>}
+     */
+    async isPublic() {
+        const policy = await this.getPolicy();
+        return policy?.type === 'PublicCanRead';
+    }
     /**
      * Removes the resource's access-control policy, reverting it to
      * capability-only access. Idempotent.