@interop/was-client 0.11.0 → 0.13.0

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

package/dist/internal/request.js.map

@@ -1 +1 @@
-{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/internal/request.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AA6ClC,SAAS,iBAAiB,CAAC,OAAsB,EAAE,KAAgB;IACjE,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC,GAAG,CAAA;IAClB,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAA;IAC5D,CAAC;IACD,OAAO,KAAK,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAsB,EACtB,KAAgB;IAEhB,MAAM,GAAG,GAAG,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IAC7C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAA;IACpC,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;QAChC,GAAG;QACH,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM;QACN,2EAA2E;QAC3E,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,MAAM;QAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAKrC;IACC,IAAI,QAAkB,CAAA;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,KAAK;YAC7B,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAA;IACrB,CAAC;IACD,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;QAChB,OAAO,QAAwB,CAAA;IACjC,CAAC;IACD,6EAA6E;IAC7E,0EAA0E;IAC1E,kEAAkE;IAClE,4DAA4D;IAC5D,IACE,KAAK,CAAC,IAAI;QACV,CAAC,QAAQ,CAAC,MAAM,KAAK,GAAG;YACtB,QAAQ,CAAC,MAAM,KAAK,GAAG;YACvB,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAC,EAC1B,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IACD,0EAA0E;IAC1E,IAAI,IAAa,CAAA;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAA;AAC1E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,OAAsB,EACtB,KAAgB;IAEhB,IAAI,CAAC;QACH,OAAO,MAAM,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;YAChE,OAAO,IAAI,CAAA;QACb,CAAC;QACD,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAA;IACrB,CAAC;AACH,CAAC"}
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/internal/request.ts"],"names":[],"mappings":"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"}

package/dist/internal/reserved.d.ts

@@ -2,10 +2,14 @@
  * Throws a `ValidationError` if the given id collides with a reserved path
  * segment for its kind.
  *
- * @param id {string}     the proposed collection or resource id
- * @param kind {string}   'collection' or 'resource', selects the reserved set
- *                        and is used in the message
+ * @param options {object}
+ * @param options.id {string}     the proposed collection or resource id
+ * @param options.kind {string}   'collection' or 'resource', selects the
+ *   reserved set and is used in the message
  * @returns {void}
  */
-export declare function assertNotReserved(id: string, kind: 'collection' | 'resource'): void;
+export declare function assertNotReserved({ id, kind }: {
+    id: string;
+    kind: 'collection' | 'resource';
+}): void;
 //# sourceMappingURL=reserved.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"reserved.d.ts","sourceRoot":"","sources":["../../src/internal/reserved.ts"],"names":[],"mappings":"AAmBA;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,YAAY,GAAG,UAAU,GAC9B,IAAI,CAQN"}
+{"version":3,"file":"reserved.d.ts","sourceRoot":"","sources":["../../src/internal/reserved.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,EAAE,EACF,IAAI,EACL,EAAE;IACD,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,YAAY,GAAG,UAAU,CAAA;CAChC,GAAG,IAAI,CAQP"}

package/dist/internal/reserved.js

@@ -16,12 +16,13 @@ import { ValidationError } from '../errors.js';
  * Throws a `ValidationError` if the given id collides with a reserved path
  * segment for its kind.
  *
- * @param id {string}     the proposed collection or resource id
- * @param kind {string}   'collection' or 'resource', selects the reserved set
- *                        and is used in the message
+ * @param options {object}
+ * @param options.id {string}     the proposed collection or resource id
+ * @param options.kind {string}   'collection' or 'resource', selects the
+ *   reserved set and is used in the message
  * @returns {void}
  */
-export function assertNotReserved(id, kind) {
+export function assertNotReserved({ id, kind }) {
     const reserved = kind === 'collection' ? RESERVED_COLLECTION_IDS : RESERVED_RESOURCE_IDS;
     if (reserved.has(id)) {
         throw new ValidationError(`Cannot use reserved path segment "${id}" as a ${kind} id.`);

package/dist/internal/reserved.js.map

@@ -1 +1 @@
-{"version":3,"file":"reserved.js","sourceRoot":"","sources":["../../src/internal/reserved.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,EAAU,EACV,IAA+B;IAE/B,MAAM,QAAQ,GACZ,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,qBAAqB,CAAA;IACzE,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,eAAe,CACvB,qCAAqC,EAAE,UAAU,IAAI,MAAM,CAC5D,CAAA;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"reserved.js","sourceRoot":"","sources":["../../src/internal/reserved.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAChC,EAAE,EACF,IAAI,EAIL;IACC,MAAM,QAAQ,GACZ,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,qBAAqB,CAAA;IACzE,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,eAAe,CACvB,qCAAqC,EAAE,UAAU,IAAI,MAAM,CAC5D,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/internal/write.d.ts

@@ -2,14 +2,17 @@
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
 /**
- * The shared write orchestration: turn a codec's {@link EncodedWrite} plus a
- * conditional-write precondition into request headers and send it. Captures the
- * `writeHeaders(...) + send(...)` shape that `Collection.add` and `Resource.put`
- * would otherwise each re-implement.
+ * The shared write orchestration. `sendEncodedWrite` turns a codec's
+ * {@link EncodedWrite} plus a conditional-write precondition into request
+ * headers and sends it (the shape `Collection.add` and `Resource.put` would
+ * otherwise each re-implement). `upsertResource` layers the upsert flow on
+ * top: the conditional-codec pre-read of the current document, the
+ * codec-vs-caller precondition selection, and the masked-404 policy for a
+ * document that exists but is not readable with the bound capability.
  */
 import type { HttpResponse } from '@interop/http-client';
-import type { EncodedWrite } from '../codec.js';
-import type { IZcap } from '../types.js';
+import type { EncodedWrite, ResourceCodec } from '../codec.js';
+import type { IZcap, ResourceData } from '../types.js';
 import type { ClientContext } from './request.js';
 import type { WritePrecondition } from './conditional.js';
 /**
@@ -34,4 +37,42 @@ export declare function sendEncodedWrite(context: ClientContext, { path, method,
     capability?: IZcap;
     precondition?: WritePrecondition;
 }): Promise<HttpResponse>;
+/**
+ * Creates or replaces a resource by id (upsert) through its codec, owning the
+ * conditional-write orchestration in one place:
+ *
+ * - A conditional codec (e.g. the EDV codec) needs the current stored document
+ *   to advance its sequence and pin the write to the current ETag, so the
+ *   current document is pre-read; the codec then computes the precondition
+ *   itself. A plaintext codec needs no pre-read and defers to the caller's
+ *   explicit precondition.
+ * - The pre-read cannot distinguish "absent" from "unreadable with this
+ *   capability" (WAS masks unauthorized reads as 404), so a conditional codec
+ *   encodes a fresh insert (`If-None-Match: *`) in both cases. When the target
+ *   in fact exists, a conditional-writes backend rejects that insert with 412;
+ *   that 412 is re-thrown here with a message naming the real cause, instead
+ *   of surfacing as an inexplicable failed create. Conditional codecs
+ *   therefore need read access to update an existing document.
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.path {string}                  the resource path to write
+ * @param options.codec {ResourceCodec}          the collection's resolved codec
+ * @param options.id {string}                    the resource id
+ * @param options.data {ResourceData}            the plaintext value
+ * @param [options.contentType] {string}         caller-supplied content type
+ * @param [options.capability] {IZcap}
+ * @param [options.precondition] {WritePrecondition}   the caller's explicit
+ *   precondition (used only for a non-conditional codec)
+ * @returns {Promise<HttpResponse>}
+ */
+export declare function upsertResource(context: ClientContext, { path, codec, id, data, contentType, capability, precondition }: {
+    path: string;
+    codec: ResourceCodec;
+    id: string;
+    data: ResourceData;
+    contentType?: string;
+    capability?: IZcap;
+    precondition?: WritePrecondition;
+}): Promise<HttpResponse>;
 //# sourceMappingURL=write.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/internal/write.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAGjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEzD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,EACtB,EACE,IAAI,EACJ,MAAM,EACN,OAAO,EACP,UAAU,EACV,YAAY,EACb,EAAE;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,CAAC,EAAE,KAAK,CAAA;IAClB,YAAY,CAAC,EAAE,iBAAiB,CAAA;CACjC,GACA,OAAO,CAAC,YAAY,CAAC,CAUvB"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/internal/write.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE9D,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAGjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEzD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,EACtB,EACE,IAAI,EACJ,MAAM,EACN,OAAO,EACP,UAAU,EACV,YAAY,EACb,EAAE;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,CAAC,EAAE,KAAK,CAAA;IAClB,YAAY,CAAC,EAAE,iBAAiB,CAAA;CACjC,GACA,OAAO,CAAC,YAAY,CAAC,CAUvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,EACE,IAAI,EACJ,KAAK,EACL,EAAE,EACF,IAAI,EACJ,WAAW,EACX,UAAU,EACV,YAAY,EACb,EAAE;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,aAAa,CAAA;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,YAAY,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,KAAK,CAAA;IAClB,YAAY,CAAC,EAAE,iBAAiB,CAAA;CACjC,GACA,OAAO,CAAC,YAAY,CAAC,CA2CvB"}

package/dist/internal/write.js

@@ -1,3 +1,4 @@
+import { PreconditionFailedError } from '../errors.js';
 import { send } from './request.js';
 import { writeHeaders } from './conditional.js';
 /**
@@ -22,8 +23,77 @@ export async function sendEncodedWrite(context, { path, method, encoded, capabil
         capability,
         json: encoded.json,
         body: encoded.body,
-        headers: writeHeaders(encoded.contentType, precondition)
+        headers: writeHeaders({ contentType: encoded.contentType, precondition })
     });
     return response;
 }
+/**
+ * Creates or replaces a resource by id (upsert) through its codec, owning the
+ * conditional-write orchestration in one place:
+ *
+ * - A conditional codec (e.g. the EDV codec) needs the current stored document
+ *   to advance its sequence and pin the write to the current ETag, so the
+ *   current document is pre-read; the codec then computes the precondition
+ *   itself. A plaintext codec needs no pre-read and defers to the caller's
+ *   explicit precondition.
+ * - The pre-read cannot distinguish "absent" from "unreadable with this
+ *   capability" (WAS masks unauthorized reads as 404), so a conditional codec
+ *   encodes a fresh insert (`If-None-Match: *`) in both cases. When the target
+ *   in fact exists, a conditional-writes backend rejects that insert with 412;
+ *   that 412 is re-thrown here with a message naming the real cause, instead
+ *   of surfacing as an inexplicable failed create. Conditional codecs
+ *   therefore need read access to update an existing document.
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.path {string}                  the resource path to write
+ * @param options.codec {ResourceCodec}          the collection's resolved codec
+ * @param options.id {string}                    the resource id
+ * @param options.data {ResourceData}            the plaintext value
+ * @param [options.contentType] {string}         caller-supplied content type
+ * @param [options.capability] {IZcap}
+ * @param [options.precondition] {WritePrecondition}   the caller's explicit
+ *   precondition (used only for a non-conditional codec)
+ * @returns {Promise<HttpResponse>}
+ */
+export async function upsertResource(context, { path, codec, id, data, contentType, capability, precondition }) {
+    let current;
+    if (codec.conditionalWrites) {
+        current = await send(context, {
+            path,
+            method: 'GET',
+            capability,
+            read: true
+        });
+    }
+    const encoded = await codec.encode({ id, data, contentType, current });
+    // A conditional codec computes the precondition itself (from the sequence /
+    // ETag); a plaintext codec defers to the caller's explicit options.
+    const chosen = codec.conditionalWrites
+        ? { ifMatch: encoded.ifMatch, ifNoneMatch: encoded.ifNoneMatch }
+        : precondition;
+    try {
+        return await sendEncodedWrite(context, {
+            path,
+            method: 'PUT',
+            capability,
+            encoded,
+            precondition: chosen
+        });
+    }
+    catch (err) {
+        if (err instanceof PreconditionFailedError &&
+            codec.conditionalWrites &&
+            current === null) {
+            const { status, type, title, details, requestUrl } = err;
+            throw new PreconditionFailedError(`Cannot update the document at "${path}": it exists, but its current ` +
+                'version is not readable with this capability (WAS masks ' +
+                'unauthorized reads as 404), so the write was encoded as a fresh ' +
+                'insert and the server rejected it. A conditional-writes codec ' +
+                '(e.g. the EDV codec) needs read access to update an existing ' +
+                'document.', { status, type, title, details, requestUrl, cause: err });
+        }
+        throw err;
+    }
+}
 //# sourceMappingURL=write.js.map

package/dist/internal/write.js.map

@@ -1 +1 @@
-{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/internal/write.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAG/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAsB,EACtB,EACE,IAAI,EACJ,MAAM,EACN,OAAO,EACP,UAAU,EACV,YAAY,EAOb;IAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE;QACnC,IAAI;QACJ,MAAM;QACN,UAAU;QACV,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC;KACzD,CAAC,CAAA;IACF,OAAO,QAAwB,CAAA;AACjC,CAAC"}
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/internal/write.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAGtD,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAG/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAsB,EACtB,EACE,IAAI,EACJ,MAAM,EACN,OAAO,EACP,UAAU,EACV,YAAY,EAOb;IAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE;QACnC,IAAI;QACJ,MAAM;QACN,UAAU;QACV,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,YAAY,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,YAAY,EAAE,CAAC;KAC1E,CAAC,CAAA;IACF,OAAO,QAAwB,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAsB,EACtB,EACE,IAAI,EACJ,KAAK,EACL,EAAE,EACF,IAAI,EACJ,WAAW,EACX,UAAU,EACV,YAAY,EASb;IAED,IAAI,OAAwC,CAAA;IAC5C,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC5B,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE;YAC5B,IAAI;YACJ,MAAM,EAAE,KAAK;YACb,UAAU;YACV,IAAI,EAAE,IAAI;SACX,CAAC,CAAA;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAA;IACtE,4EAA4E;IAC5E,oEAAoE;IACpE,MAAM,MAAM,GAAG,KAAK,CAAC,iBAAiB;QACpC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE;QAChE,CAAC,CAAC,YAAY,CAAA;IAChB,IAAI,CAAC;QACH,OAAO,MAAM,gBAAgB,CAAC,OAAO,EAAE;YACrC,IAAI;YACJ,MAAM,EAAE,KAAK;YACb,UAAU;YACV,OAAO;YACP,YAAY,EAAE,MAAM;SACrB,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IACE,GAAG,YAAY,uBAAuB;YACtC,KAAK,CAAC,iBAAiB;YACvB,OAAO,KAAK,IAAI,EAChB,CAAC;YACD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,GAAG,CAAA;YACxD,MAAM,IAAI,uBAAuB,CAC/B,kCAAkC,IAAI,gCAAgC;gBACpE,0DAA0D;gBAC1D,kEAAkE;gBAClE,gEAAgE;gBAChE,+DAA+D;gBAC/D,WAAW,EACb,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,CACzD,CAAA;QACH,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@interop/was-client",
   "description": "A developer-friendly client for Wallet Attached Storage (WAS) servers.",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "scripts": {
     "build": "pnpm run clear && tsc",
@@ -44,7 +44,7 @@
   "dependencies": {
     "@interop/data-integrity-core": "^8.1.0",
     "@interop/ed25519-signature": "^7.1.3",
-    "@interop/edv-client": "^17.3.1",
+    "@interop/edv-client": "^17.4.0",
     "@interop/ezcap": "^7.3.2",
     "@interop/http-client": "^1.0.4",
     "@interop/storage-core": "^0.3.1"