@interop/was-client 0.12.0 → 0.13.0

package/dist/internal/content.js

@@ -1,5 +1,10 @@
 import { ValidationError, WasServerError } from '../errors.js';
 const OCTET_STREAM = 'application/octet-stream';
+/**
+ * A shared `TextEncoder` for serializing an explicitly-typed JSON write to
+ * bytes (stateless, so one instance is reused).
+ */
+const ENCODER = new TextEncoder();
 /**
  * Whether a content-type denotes JSON -- `application/json` or any
  * `application/<prefix>+json` structured-suffix variant (e.g.
@@ -103,40 +108,81 @@ export function toPlainBytes(bytes) {
     return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
 }
 /**
- * Inspects write data and resolves it to a JSON or binary payload.
+ * Classifies write data as binary or JSON and resolves the binary
+ * content-type -- the single source of the detection and precedence rules
+ * shared by the plaintext `prepareBody` and the EDV codec's document builder.
  *
  * The binary content-type resolves in precedence order: an explicit
- * `options.contentType`, then a non-empty `Blob.type`, then a guess from
- * `options.filename`'s extension, then `application/octet-stream`. (Coalescing
- * with `||` rather than `??` so an empty-string `Blob.type` -- a typeless Blob
- * -- falls through to the guess instead of becoming an empty content-type.)
+ * `contentType`, then a non-empty `Blob.type`, then a guess from the resource
+ * `id`'s extension, then `application/octet-stream`. (Coalescing with `||`
+ * rather than `??` so an empty-string `Blob.type` -- a typeless Blob -- falls
+ * through to the guess instead of becoming an empty content-type.)
  *
- * @param data {ResourceData}                the resource content
  * @param options {object}
+ * @param options.data {ResourceData}       the resource content
  * @param [options.contentType] {string}    overrides the inferred content-type
  *   for binary data
- * @param [options.filename] {string}       resource id used to guess a
+ * @param [options.id] {string}             resource id used to guess a
  *   content-type by extension when none is given (binary data only)
- * @returns {PreparedBody}
+ * @returns {ResolvedPayload}
  */
-export function prepareBody(data, options = {}) {
-    const guessed = options.filename
-        ? guessContentTypeFromId(options.filename)
-        : undefined;
+export function resolvePayload({ data, contentType, id }) {
+    const guessed = id ? guessContentTypeFromId(id) : undefined;
     if (isBlob(data)) {
         return {
-            body: data,
-            contentType: options.contentType || data.type || guessed || OCTET_STREAM
+            kind: 'binary',
+            data,
+            contentType: contentType || data.type || guessed || OCTET_STREAM
         };
     }
     if (data instanceof Uint8Array) {
         return {
-            body: toPlainBytes(data),
-            contentType: options.contentType || guessed || OCTET_STREAM
+            kind: 'binary',
+            data,
+            contentType: contentType || guessed || OCTET_STREAM
         };
     }
     if (data !== null && typeof data === 'object') {
-        // Plain object or array -- send as JSON.
+        return { kind: 'json' };
+    }
+    return { kind: 'invalid' };
+}
+/**
+ * Inspects write data and resolves it to a JSON or binary payload, using
+ * {@link resolvePayload} for the detection and content-type precedence rules.
+ *
+ * @param data {ResourceData}                the resource content
+ * @param options {object}
+ * @param [options.contentType] {string}    overrides the inferred content-type
+ *   for binary data
+ * @param [options.filename] {string}       resource id used to guess a
+ *   content-type by extension when none is given (binary data only)
+ * @returns {PreparedBody}
+ */
+export function prepareBody(data, options = {}) {
+    const payload = resolvePayload({
+        data,
+        contentType: options.contentType,
+        id: options.filename
+    });
+    if (payload.kind === 'binary') {
+        return {
+            body: isBlob(payload.data) ? payload.data : toPlainBytes(payload.data),
+            contentType: payload.contentType
+        };
+    }
+    if (payload.kind === 'json') {
+        // Plain object or array -- send as JSON. An explicit `contentType` (e.g.
+        // `application/ld+json`) is honored by serializing the value ourselves and
+        // sending it with that content-type header; the bare `json` shorthand
+        // would silently store it as `application/json`, losing the declared media
+        // type (which the encrypted path preserves).
+        if (options.contentType !== undefined) {
+            return {
+                body: ENCODER.encode(JSON.stringify(data)),
+                contentType: options.contentType
+            };
+        }
         return { json: data };
     }
     throw new ValidationError('Resource data must be a plain object/array (JSON) or a ' +
@@ -172,15 +218,18 @@ export function createdId(response) {
 }
 /**
  * Unwraps a read response's pre-parsed JSON `data` as `T`, mapping a `null`
- * response (a 404 that a `read` request resolved to `null`) to `null`. Captures
- * the `response === null ? null : response.data as T` idiom shared across the
- * handle read methods.
+ * response (a 404 that a `read` request resolved to `null`) to `null`. The
+ * http-client leaves `data` undefined for a non-JSON content-type or a 204;
+ * that is also mapped to `null`, so the declared `T | null` is honest and a
+ * caller never dereferences `undefined` cast as `T`.
  *
  * @param response {HttpResponse | null}
  * @returns {T | null}
  */
 export function dataOrNull(response) {
-    return response === null ? null : response.data;
+    return response === null || response.data === undefined
+        ? null
+        : response.data;
 }
 /**
  * Reads a JSON response body, preferring the http-client's pre-parsed `data`

package/dist/internal/content.js.map

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

package/dist/internal/grant.d.ts

@@ -8,7 +8,7 @@
  * the server (which matches actions case-sensitively against `'GET'`).
  */
 import type { ClientContext } from './request.js';
-import type { GrantOptions, IDelegatedZcap } from '../types.js';
+import type { GrantOptions, IDelegatedZcap, IZcap } from '../types.js';
 /**
  * Delegates a capability per `GrantOptions`, returning the signed zcap to hand
  * off out-of-band.
@@ -17,5 +17,23 @@ import type { GrantOptions, IDelegatedZcap } from '../types.js';
  * @param options {GrantOptions}
  * @returns {Promise<IDelegatedZcap>}
  */
-export declare function delegateGrant(context: ClientContext, options: GrantOptions): Promise<IDelegatedZcap>;
+export declare function delegateGrant(context: ClientContext, { to, actions, expires, target, capability }: GrantOptions): Promise<IDelegatedZcap>;
+/**
+ * The scoped-grant sugar shared by `Space.grant` and `Collection.grant`:
+ * delegates per `GrantOptions` with the grant `target` prefilled from the
+ * handle's `path` (and the handle's bound `capability`, if any, as the parent
+ * for re-delegation). Explicit options win over both prefills.
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.path {string}           the handle's path (target fallback)
+ * @param options.options {GrantOptions}  the caller's grant options
+ * @param [options.capability] {IZcap}    the handle's bound capability
+ * @returns {Promise<IDelegatedZcap>}
+ */
+export declare function delegateGrantAt(context: ClientContext, { path, options, capability }: {
+    path: string;
+    options: GrantOptions;
+    capability?: IZcap;
+}): Promise<IDelegatedZcap>;
 //# sourceMappingURL=grant.d.ts.map

package/dist/internal/grant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../src/internal/grant.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE/D;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,cAAc,CAAC,CASzB"}
+{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../src/internal/grant.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAEtE;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,YAAY,GACzD,OAAO,CAAC,cAAc,CAAC,CAQzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,EACtB,EACE,IAAI,EACJ,OAAO,EACP,UAAU,EACX,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAC7D,OAAO,CAAC,cAAc,CAAC,CAMzB"}

package/dist/internal/grant.js

@@ -1,3 +1,4 @@
+import { toUrl } from './paths.js';
 /**
  * Delegates a capability per `GrantOptions`, returning the signed zcap to hand
  * off out-of-band.
@@ -6,8 +7,7 @@
  * @param options {GrantOptions}
  * @returns {Promise<IDelegatedZcap>}
  */
-export async function delegateGrant(context, options) {
-    const { to, actions, expires, target, capability } = options;
+export async function delegateGrant(context, { to, actions, expires, target, capability }) {
     return context.zcapClient.delegate({
         controller: to,
         invocationTarget: target,
@@ -16,4 +16,24 @@ export async function delegateGrant(context, options) {
         capability
     });
 }
+/**
+ * The scoped-grant sugar shared by `Space.grant` and `Collection.grant`:
+ * delegates per `GrantOptions` with the grant `target` prefilled from the
+ * handle's `path` (and the handle's bound `capability`, if any, as the parent
+ * for re-delegation). Explicit options win over both prefills.
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.path {string}           the handle's path (target fallback)
+ * @param options.options {GrantOptions}  the caller's grant options
+ * @param [options.capability] {IZcap}    the handle's bound capability
+ * @returns {Promise<IDelegatedZcap>}
+ */
+export async function delegateGrantAt(context, { path, options, capability }) {
+    return delegateGrant(context, {
+        ...options,
+        target: options.target ?? toUrl({ serverUrl: context.serverUrl, path }),
+        capability: options.capability ?? capability
+    });
+}
 //# sourceMappingURL=grant.js.map

package/dist/internal/grant.js.map

@@ -1 +1 @@
-{"version":3,"file":"grant.js","sourceRoot":"","sources":["../../src/internal/grant.ts"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAsB,EACtB,OAAqB;IAErB,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAA;IAC5D,OAAO,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;QACjC,UAAU,EAAE,EAAE;QACd,gBAAgB,EAAE,MAAM;QACxB,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAC3D,OAAO;QACP,UAAU;KACX,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"grant.js","sourceRoot":"","sources":["../../src/internal/grant.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAGlC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAsB,EACtB,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAgB;IAE1D,OAAO,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;QACjC,UAAU,EAAE,EAAE;QACd,gBAAgB,EAAE,MAAM;QACxB,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAC3D,OAAO;QACP,UAAU;KACX,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAsB,EACtB,EACE,IAAI,EACJ,OAAO,EACP,UAAU,EACkD;IAE9D,OAAO,aAAa,CAAC,OAAO,EAAE;QAC5B,GAAG,OAAO;QACV,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;QACvE,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,UAAU;KAC7C,CAAC,CAAA;AACJ,CAAC"}

package/dist/internal/pagination.d.ts

@@ -21,6 +21,22 @@ export interface PageWalk {
     firstUrl: string;
     fetchPage: (url: string) => Promise<CollectionResourcesList | null>;
 }
+/**
+ * Builds a {@link PageWalk} by fetching the first page with the same
+ * `fetchPage` used for every following page -- the shared shape of the signed
+ * (`Collection._listWalk`) and unsigned (`WasClient._publicListWalk`) walks,
+ * which differ only in how a single page URL is fetched. Returns `null` when
+ * the first page is missing/unauthorized (404 conflation caveat).
+ *
+ * @param options {object}
+ * @param options.firstUrl {string}      the absolute listing URL
+ * @param options.fetchPage {function}   fetches one page by absolute URL
+ * @returns {Promise<PageWalk | null>}
+ */
+export declare function buildPageWalk({ firstUrl, fetchPage }: {
+    firstUrl: string;
+    fetchPage: PageWalk['fetchPage'];
+}): Promise<PageWalk | null>;
 /**
  * Lazily walks a list response page by page, yielding the first page and then
  * each page reached by following `next`. Each `next` is resolved relative to the

package/dist/internal/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/internal/pagination.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAE1D;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,uBAAuB,CAAA;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAA;CACpE;AAED;;;;;;;;;GASG;AACH,wBAAuB,SAAS,CAC9B,IAAI,EAAE,QAAQ,GACb,cAAc,CAAC,uBAAuB,CAAC,CAoBzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,uBAAuB,CAAC,CAWlC"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/internal/pagination.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAE1D;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,uBAAuB,CAAA;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAA;CACpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,EAClC,QAAQ,EACR,SAAS,EACV,EAAE;IACD,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAA;CACjC,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAG3B;AAED;;;;;;;;;GASG;AACH,wBAAuB,SAAS,CAC9B,IAAI,EAAE,QAAQ,GACb,cAAc,CAAC,uBAAuB,CAAC,CAwBzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,uBAAuB,CAAC,CAWlC"}

package/dist/internal/pagination.js

@@ -1,3 +1,19 @@
+/**
+ * Builds a {@link PageWalk} by fetching the first page with the same
+ * `fetchPage` used for every following page -- the shared shape of the signed
+ * (`Collection._listWalk`) and unsigned (`WasClient._publicListWalk`) walks,
+ * which differ only in how a single page URL is fetched. Returns `null` when
+ * the first page is missing/unauthorized (404 conflation caveat).
+ *
+ * @param options {object}
+ * @param options.firstUrl {string}      the absolute listing URL
+ * @param options.fetchPage {function}   fetches one page by absolute URL
+ * @returns {Promise<PageWalk | null>}
+ */
+export async function buildPageWalk({ firstUrl, fetchPage }) {
+    const first = await fetchPage(firstUrl);
+    return first === null ? null : { first, firstUrl, fetchPage };
+}
 /**
  * Lazily walks a list response page by page, yielding the first page and then
  * each page reached by following `next`. Each `next` is resolved relative to the
@@ -11,7 +27,11 @@
 export async function* walkPages(walk) {
     const { first, firstUrl, fetchPage } = walk;
     yield first;
-    const seen = new Set([firstUrl]);
+    // Seed the cycle guard with the canonicalized first URL -- every followed
+    // `next` is canonicalized via `new URL(...)`, so an equivalent-but-unequal
+    // seed (e.g. an explicit default port) would let a next-link back to page 1
+    // defeat the guard and yield its items twice.
+    const seen = new Set([new URL(firstUrl).toString()]);
     let baseUrl = firstUrl;
     let next = first.next;
     while (next) {

package/dist/internal/pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/internal/pagination.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,SAAS,CAC9B,IAAc;IAEd,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;IAC3C,MAAM,KAAK,CAAA;IACX,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,QAAQ,CAAC,CAAC,CAAA;IACxC,IAAI,OAAO,GAAG,QAAQ,CAAA;IACtB,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACrB,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAA;QACjD,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACtB,MAAK;QACP,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACjB,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;QACrC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAK;QACP,CAAC;QACD,MAAM,IAAI,CAAA;QACV,OAAO,GAAG,OAAO,CAAA;QACjB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAc;IAEd,IAAI,SAA8C,CAAA;IAClD,MAAM,KAAK,GAAqC,EAAE,CAAA;IAClD,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,SAAS,KAAK,IAAI,CAAA;QAClB,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;IACD,iEAAiE;IACjE,MAAM,MAAM,GAA4B,EAAE,GAAG,SAAU,EAAE,KAAK,EAAE,CAAA;IAChE,OAAO,MAAM,CAAC,IAAI,CAAA;IAClB,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/internal/pagination.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAClC,QAAQ,EACR,SAAS,EAIV;IACC,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAA;IACvC,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;AAC/D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,SAAS,CAC9B,IAAc;IAEd,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;IAC3C,MAAM,KAAK,CAAA;IACX,0EAA0E;IAC1E,2EAA2E;IAC3E,4EAA4E;IAC5E,8CAA8C;IAC9C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;IAC5D,IAAI,OAAO,GAAG,QAAQ,CAAA;IACtB,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACrB,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAA;QACjD,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACtB,MAAK;QACP,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACjB,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;QACrC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAK;QACP,CAAC;QACD,MAAM,IAAI,CAAA;QACV,OAAO,GAAG,OAAO,CAAA;QACjB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAc;IAEd,IAAI,SAA8C,CAAA;IAClD,MAAM,KAAK,GAAqC,EAAE,CAAA;IAClD,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,SAAS,KAAK,IAAI,CAAA;QAClB,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;IACD,iEAAiE;IACjE,MAAM,MAAM,GAA4B,EAAE,GAAG,SAAU,EAAE,KAAK,EAAE,CAAA;IAChE,OAAO,MAAM,CAAC,IAAI,CAAA;IAClB,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/internal/paths.d.ts

@@ -1,24 +1,7 @@
-/*!
- * Copyright (c) 2026 Interop Alliance. All rights reserved.
- */
-/**
- * URL path builders for the WAS server, encoding the trailing-slash
- * canonicalization once. Item-create and listing endpoints use a trailing
- * slash; get/put/delete-by-id endpoints do not. Path segments are
- * percent-encoded so ids never break out of their slot.
- *
- * The zcap `invocationTarget` is derived from the request URL, so these
- * trailing-slash rules must match the server's per-operation `allowedTarget`
- * exactly or signature verification fails.
- */
 /**
  * `/spaces/` -- the SpacesRepository (create / list spaces).
  */
 export declare function spacesRoot(): string;
-/**
- * `/spaces/:spaceId` -- canonical location of a created space (POST response).
- */
-export declare function spaceLocation(spaceId: string): string;
 /**
  * `/space/:spaceId` -- get / update / delete a space (no trailing slash).
  */
@@ -123,4 +106,52 @@ export declare function toUrl({ serverUrl, path }: {
     serverUrl: string;
     path: string;
 }): string;
+/**
+ * Canonicalizes an absolute collection URL to its items/listing endpoint --
+ * the trailing-slash form (`/space/:id/:collectionId/`). This module owns the
+ * trailing-slash rules, so callers that receive a collection URL from outside
+ * (e.g. a public link) normalize it here rather than re-encoding the rule.
+ *
+ * @param collectionUrl {string}   an absolute collection URL
+ * @returns {string}
+ */
+export declare function collectionItemsUrl(collectionUrl: string): string;
+/**
+ * The classification of a WAS pathname by the depth it addresses. The three
+ * containment kinds map onto navigational handles; `sub-resource` covers every
+ * reserved sub-endpoint the builders above produce (`/space/:id/policy`,
+ * `/space/:id/:c/backend`, `/space/:id/:c/:r/meta`, ...), which has no handle of
+ * its own.
+ */
+export type ParsedSpacePath = {
+    kind: 'space';
+    spaceId: string;
+} | {
+    kind: 'collection';
+    spaceId: string;
+    collectionId: string;
+} | {
+    kind: 'resource';
+    spaceId: string;
+    collectionId: string;
+    resourceId: string;
+} | {
+    kind: 'sub-resource';
+    spaceId: string;
+    segments: string[];
+};
+/**
+ * Parses a server pathname back into the containment depth it addresses -- the
+ * inverse of the builders above, kept next to them so the grammar is owned in
+ * one place. Segments are percent-decoded (the builders re-encode them).
+ * Returns `null` for a pathname outside the `/space/...` tree; the caller
+ * chooses the error. A path that addresses a reserved sub-endpoint rather than
+ * a space/collection/resource -- e.g. `/space/s/policy`, `/space/s/c/backend`,
+ * or any 5-segment target like `/space/s/c/r/meta` -- is classified
+ * `sub-resource`, never silently truncated to the nearest handle.
+ *
+ * @param pathname {string}   a URL pathname (e.g. from `new URL(...).pathname`)
+ * @returns {ParsedSpacePath | null}
+ */
+export declare function parseSpacePath(pathname: string): ParsedSpacePath | null;
 //# sourceMappingURL=paths.d.ts.map

package/dist/internal/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/internal/paths.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;GASG;AAMH;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EACpB,SAAS,EACT,IAAI,EACL,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;CACb,GAAG,MAAM,CAOT"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/internal/paths.ts"],"names":[],"mappings":"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"}

package/dist/internal/paths.js

@@ -10,8 +10,33 @@
  * The zcap `invocationTarget` is derived from the request URL, so these
  * trailing-slash rules must match the server's per-operation `allowedTarget`
  * exactly or signature verification fails.
+ *
+ * This module also owns the inverse grammar: `parseSpacePath` classifies a
+ * server pathname back into the handle depth it addresses (space / collection /
+ * resource / sub-resource), so `WasClient.fromCapability` and the builders stay
+ * in lockstep.
+ */
+import { RESERVED_COLLECTION_IDS, RESERVED_RESOURCE_IDS } from '@interop/storage-core';
+import { ValidationError } from '../errors.js';
+/**
+ * Rejects an id that would escape its path slot even after percent-encoding:
+ * `encodeURIComponent` leaves `.` and `..` intact, and WHATWG URL resolution
+ * collapses dot segments -- so `resource('.').delete()` would target the
+ * collection items endpoint and `'..'` the parent space. An empty id likewise
+ * collapses into the parent's trailing-slash endpoint. One guard here covers
+ * every builder.
+ *
+ * @param segment {string}   the proposed id
+ * @returns {void}
  */
+function assertValidId(segment) {
+    if (segment === '' || segment === '.' || segment === '..') {
+        throw new ValidationError(`Invalid id ${JSON.stringify(segment)}: an empty or dot-segment id ` +
+            'would resolve to a different endpoint than its own.');
+    }
+}
 function encode(segment) {
+    assertValidId(segment);
     return encodeURIComponent(segment);
 }
 /**
@@ -20,12 +45,6 @@ function encode(segment) {
 export function spacesRoot() {
     return '/spaces/';
 }
-/**
- * `/spaces/:spaceId` -- canonical location of a created space (POST response).
- */
-export function spaceLocation(spaceId) {
-    return `/spaces/${encode(spaceId)}`;
-}
 /**
  * `/space/:spaceId` -- get / update / delete a space (no trailing slash).
  */
@@ -172,4 +191,64 @@ export function toUrl({ serverUrl, path }) {
     const relative = path.startsWith('/') ? path.slice(1) : path;
     return new URL(relative, base).toString();
 }
+/**
+ * Canonicalizes an absolute collection URL to its items/listing endpoint --
+ * the trailing-slash form (`/space/:id/:collectionId/`). This module owns the
+ * trailing-slash rules, so callers that receive a collection URL from outside
+ * (e.g. a public link) normalize it here rather than re-encoding the rule.
+ *
+ * @param collectionUrl {string}   an absolute collection URL
+ * @returns {string}
+ */
+export function collectionItemsUrl(collectionUrl) {
+    return collectionUrl.endsWith('/') ? collectionUrl : `${collectionUrl}/`;
+}
+/**
+ * Parses a server pathname back into the containment depth it addresses -- the
+ * inverse of the builders above, kept next to them so the grammar is owned in
+ * one place. Segments are percent-decoded (the builders re-encode them).
+ * Returns `null` for a pathname outside the `/space/...` tree; the caller
+ * chooses the error. A path that addresses a reserved sub-endpoint rather than
+ * a space/collection/resource -- e.g. `/space/s/policy`, `/space/s/c/backend`,
+ * or any 5-segment target like `/space/s/c/r/meta` -- is classified
+ * `sub-resource`, never silently truncated to the nearest handle.
+ *
+ * @param pathname {string}   a URL pathname (e.g. from `new URL(...).pathname`)
+ * @returns {ParsedSpacePath | null}
+ */
+export function parseSpacePath(pathname) {
+    const segments = pathname.split('/').filter(Boolean).map(decodeURIComponent);
+    if (segments[0] !== 'space' || segments[1] === undefined) {
+        return null;
+    }
+    const [, spaceId, ...rest] = segments;
+    if (rest.length === 0) {
+        return { kind: 'space', spaceId };
+    }
+    // A reserved segment directly under the space (`policy`, `backends`,
+    // `export`, ...) addresses a space-level sub-endpoint, as does anything
+    // nested beneath one (`/space/s/backends/:backendId`).
+    if (RESERVED_COLLECTION_IDS.has(rest[0])) {
+        return { kind: 'sub-resource', spaceId, segments: rest };
+    }
+    if (rest.length === 1) {
+        return { kind: 'collection', spaceId, collectionId: rest[0] };
+    }
+    // A reserved segment under the collection (`policy`, `backend`, `quota`,
+    // ...) addresses a collection-level sub-endpoint.
+    if (RESERVED_RESOURCE_IDS.has(rest[1])) {
+        return { kind: 'sub-resource', spaceId, segments: rest };
+    }
+    if (rest.length === 2) {
+        return {
+            kind: 'resource',
+            spaceId,
+            collectionId: rest[0],
+            resourceId: rest[1]
+        };
+    }
+    // Anything deeper (`/space/s/c/r/meta`, `/space/s/c/r/policy`, chunk
+    // sub-segments, ...) is a resource-level sub-endpoint.
+    return { kind: 'sub-resource', spaceId, segments: rest };
+}
 //# sourceMappingURL=paths.js.map

package/dist/internal/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/internal/paths.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;GASG;AAEH,SAAS,MAAM,CAAC,OAAe;IAC7B,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,WAAW,MAAM,CAAC,OAAO,CAAC,EAAE,CAAA;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,EAAE,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,GAAG,CAAA;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,eAAe,CAAA;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,SAAS,CAAA;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,SAAS,CAAA;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,WAAW,CAAA;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,SAAiB;IAClE,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,aAAa,MAAM,CAAC,SAAS,CAAC,EAAE,CAAA;AAClE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,SAAS,CAAA;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,SAAS,CAAA;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,UAAU,CAAA;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,YAAoB;IAClE,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,EAAE,CAAA;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,YAAoB;IACnE,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,CAAA;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,YAAoB;IAEpB,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,SAAS,CAAA;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,YAAoB;IAEpB,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,UAAU,CAAA;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,YAAoB;IAEpB,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,UAAU,CAAA;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,YAAoB;IACnE,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAA;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAe,EACf,YAAoB,EACpB,UAAkB;IAElB,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,EAAE,CAAA;AAClF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAe,EACf,YAAoB,EACpB,UAAkB;IAElB,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAA;AACvF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,YAAoB,EACpB,UAAkB;IAElB,OAAO,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,SAAS,CAAA;AACzF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,KAAK,CAAC,EACpB,SAAS,EACT,IAAI,EAIL;IACC,2EAA2E;IAC3E,2EAA2E;IAC3E,qDAAqD;IACrD,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,CAAA;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC5D,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAA;AAC3C,CAAC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/internal/paths.ts"],"names":[],"mappings":"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"}

package/dist/internal/request.d.ts

@@ -11,7 +11,7 @@
 import type { ZcapClient } from '@interop/ezcap';
 import type { HttpResponse } from '@interop/http-client';
 import type { EncryptionProvider } from '../codec.js';
-import type { IZcap } from '../types.js';
+import type { IZcap, RequestInput } from '../types.js';
 /**
  * The shared context threaded through every handle: the server base URL, the
  * wrapped ezcap client, the cached controller DID of its signer, and the
@@ -25,18 +25,11 @@ export interface ClientContext {
     encryption?: EncryptionProvider;
 }
 /**
- * A single signed request. Either `path` (resolved against `serverUrl`) or
- * `url` (absolute) must be given.
+ * A single signed request: the public `RequestInput` shape (either `path`,
+ * resolved against `serverUrl`, or an absolute `url` must be given) plus the
+ * `send()`-level 404 translations.
  */
-export interface SendInput {
-    path?: string;
-    url?: string;
-    method?: string;
-    action?: string;
-    headers?: Record<string, string>;
-    json?: object;
-    body?: Blob | Uint8Array;
-    capability?: IZcap;
+export interface SendInput extends RequestInput {
     /**
      * When true, a 404 response resolves to `null` instead of throwing.
      */
@@ -87,4 +80,20 @@ export declare function unsignedRequest(input: {
  * @returns {Promise<HttpResponse | null>}
  */
 export declare function send(context: ClientContext, input: SendInput): Promise<HttpResponse | null>;
+/**
+ * The GET-a-JSON-description read shared across the handles: a signed
+ * null-on-404 `GET` of `path` whose pre-parsed body is unwrapped as `T`. Both
+ * a missing/unauthorized target (404) and a bodyless/non-JSON response resolve
+ * to `null` (see `dataOrNull`).
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.path {string}          the path to read
+ * @param [options.capability] {IZcap}   capability attached to the request
+ * @returns {Promise<T | null>}
+ */
+export declare function readData<T>(context: ClientContext, { path, capability }: {
+    path: string;
+    capability?: IZcap;
+}): Promise<T | null>;
 //# sourceMappingURL=request.d.ts.map

package/dist/internal/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/internal/request.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAGxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,UAAU,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,kBAAkB,CAAA;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IAExB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,IAAI,GAAG,UAAU,CAAA;IACxB,UAAU,CAAC,EAAE,KAAK,CAAA;IAClB;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAYD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,YAAY,CAAC,CAavB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAiC/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CACxB,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/internal/request.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAIxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,UAAU,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,kBAAkB,CAAA;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,YAAY;IAC7C;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAYD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,YAAY,CAAC,CAavB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAiC/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CACxB,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,OAAO,EAAE,aAAa,EACtB,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GACzD,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAQnB"}

package/dist/internal/request.js

@@ -1,5 +1,6 @@
 import { mapError, httpStatus } from '../errors.js';
 import { toUrl } from './paths.js';
+import { dataOrNull } from './content.js';
 function resolveRequestUrl(context, input) {
     if (input.url !== undefined) {
         return input.url;
@@ -100,4 +101,25 @@ export async function send(context, input) {
         throw mapError(err);
     }
 }
+/**
+ * The GET-a-JSON-description read shared across the handles: a signed
+ * null-on-404 `GET` of `path` whose pre-parsed body is unwrapped as `T`. Both
+ * a missing/unauthorized target (404) and a bodyless/non-JSON response resolve
+ * to `null` (see `dataOrNull`).
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.path {string}          the path to read
+ * @param [options.capability] {IZcap}   capability attached to the request
+ * @returns {Promise<T | null>}
+ */
+export async function readData(context, { path, capability }) {
+    const response = await send(context, {
+        path,
+        method: 'GET',
+        capability,
+        read: true
+    });
+    return dataOrNull(response);
+}
 //# sourceMappingURL=request.js.map