@interop/was-react 0.1.0

package/dist/sync/types.d.ts

@@ -0,0 +1,194 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Shared types for the collection-agnostic WAS replication adapter.
+ *
+ * The adapter drives an RxDB `replicateRxCollection` state machine against a
+ * remote WAS Collection's replication endpoints. It is deliberately free of any
+ * React or app imports so it can stand alone; all WAS access is injected through
+ * the {@link WasSyncPort} seam rather than importing `@interop/was-client`
+ * directly.
+ *
+ * The wire contract follows the WAS `changes` feed and its V2 encrypted-metadata
+ * profile: a synced document carries both a content revision (`version` /
+ * `data`) and an independently-versioned metadata sub-resource (`metaVersion` /
+ * `custom`). A metadata-only edit re-surfaces the resource with a bumped
+ * `updatedAt` / `metaVersion` but unchanged `version` / `data`. The sync layer
+ * moves both bodies opaquely: `data` is the stored content body (plaintext JSON,
+ * or the EDV envelope on an encrypted collection) and `custom` is the stored
+ * metadata body (an opaque envelope on an encrypted collection); encrypt/decrypt
+ * stays a read/write-time concern above this layer.
+ */
+/**
+ * A JSON value -- the opaque stored resource body the sync layer moves verbatim.
+ * For a plaintext collection this is the user document; for an encrypted one it
+ * is the EDV envelope. The adapter never inspects or transforms it.
+ */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * The keyset position in the change feed: the `{ id, updatedAt }` of the last
+ * document a pull returned. Passed back verbatim to resume, and used as the
+ * RxDB replication checkpoint. `id` is the total-order tiebreaker within a
+ * single `updatedAt`.
+ */
+export interface SyncCheckpoint {
+    id: string;
+    updatedAt: string;
+}
+/**
+ * One document as it travels on the `changes` feed wire
+ * (`POST /space/:s/:c/query`, profile `changes`). `id` is the WAS resourceId,
+ * `version` is the content master revision (feeds the content push `If-Match`
+ * ETag) and the user content body is nested under `data`; `metaVersion` is the
+ * independent metadata revision (feeds the `/meta` push `If-Match` ETag) and the
+ * user-writable metadata body is under `custom`. A tombstone carries
+ * `_deleted: true` with no `data`. `metaVersion` / `custom` are present only
+ * once metadata has been written for the resource.
+ */
+export interface WireDoc {
+    id: string;
+    _deleted: boolean;
+    updatedAt: string;
+    version: number;
+    metaVersion?: number;
+    data?: Json;
+    custom?: Json;
+}
+/**
+ * The local RxDB document shape, shared across every synced collection. The
+ * envelope fields are top-level (`id` primary key, `updatedAt` the checkpoint
+ * sort field, `version` / `metaVersion` the server master revisions); the user
+ * bodies stay nested (`data` for content, `custom` for metadata) to avoid field
+ * collisions. `_deleted` is managed by RxDB via `deletedField` and so is not
+ * part of this "clean" shape (handlers work with RxDB's `WithDeleted<SyncedDoc>`).
+ */
+export interface SyncedDoc {
+    id: string;
+    updatedAt: string;
+    version: number;
+    metaVersion?: number;
+    data?: Json;
+    custom?: Json;
+}
+/**
+ * The current master state of a single resource, as read back for the 412
+ * conflict path. `deleted` distinguishes a tombstone from a live resource;
+ * `metaVersion` / `custom` are present only once metadata has been written.
+ */
+export interface MasterState {
+    version: number;
+    updatedAt: string;
+    deleted: boolean;
+    metaVersion?: number;
+    data?: Json;
+    custom?: Json;
+}
+/**
+ * The injected WAS-access seam. An adapter (the app-side `wasSyncPort.ts`)
+ * implements this over `@interop/was-client`; the core module depends only on
+ * this interface, never on `was-client` itself. Every method moves the stored
+ * body verbatim -- no codec, no key handling -- so the same port works for
+ * plaintext and encrypted collections alike.
+ *
+ * `putContent` / `deleteContent` / `putMeta` MUST throw
+ * {@link WasSyncConflictError} when the server rejects a conditional write with
+ * `412 precondition-failed`, and let every other error propagate so RxDB's
+ * retry/backoff handles it.
+ */
+export interface WasSyncPort {
+    /**
+     * Pulls one page of the `changes` feed. Omit `checkpoint` for the first page.
+     * Returns the page's `documents` and its resume `checkpoint`, or
+     * `checkpoint: null` for an empty (no-change) page.
+     *
+     * @param options {object}
+     * @param [options.checkpoint] {SyncCheckpoint}   resume position
+     * @param options.limit {number}                  requested batch size
+     * @returns {Promise<{ documents: WireDoc[], checkpoint: SyncCheckpoint | null }>}
+     */
+    query(options: {
+        checkpoint?: SyncCheckpoint;
+        limit: number;
+    }): Promise<{
+        documents: WireDoc[];
+        checkpoint: SyncCheckpoint | null;
+    }>;
+    /**
+     * Conditionally writes the content body verbatim (`PUT /:id`). Pass
+     * `ifNoneMatch: true` for a create-if-absent, or `ifMatch` (a quoted ETag over
+     * the content `version`) for an update-if-unchanged.
+     *
+     * @param options {object}
+     * @param options.id {string}
+     * @param options.data {Json}
+     * @param [options.ifMatch] {string}
+     * @param [options.ifNoneMatch] {boolean}
+     * @returns {Promise<void>}
+     */
+    putContent(options: {
+        id: string;
+        data: Json;
+        ifMatch?: string;
+        ifNoneMatch?: boolean;
+    }): Promise<void>;
+    /**
+     * Conditionally deletes a resource (writes a tombstone; `DELETE /:id`). Pass
+     * `ifMatch` (a quoted ETag over the content `version`) to delete only if
+     * unchanged.
+     *
+     * @param options {object}
+     * @param options.id {string}
+     * @param [options.ifMatch] {string}
+     * @returns {Promise<void>}
+     */
+    deleteContent(options: {
+        id: string;
+        ifMatch?: string;
+    }): Promise<void>;
+    /**
+     * Conditionally writes the metadata body verbatim (`PUT /:id/meta`, body
+     * `{ custom }`). Pass `ifNoneMatch: true` when the resource has no metadata
+     * yet, or `ifMatch` (a quoted ETag over `metaVersion`) for an
+     * update-if-unchanged. The resource must already exist (the server does not
+     * create a resource from a `/meta` write).
+     *
+     * @param options {object}
+     * @param options.id {string}
+     * @param options.custom {Json}
+     * @param [options.ifMatch] {string}
+     * @param [options.ifNoneMatch] {boolean}
+     * @returns {Promise<void>}
+     */
+    putMeta(options: {
+        id: string;
+        custom: Json;
+        ifMatch?: string;
+        ifNoneMatch?: boolean;
+    }): Promise<void>;
+    /**
+     * Re-reads a single resource's current master state (content + metadata) for
+     * the 412 conflict assembler. Returns `null` when the resource is genuinely
+     * absent (a delete/delete race).
+     *
+     * @param options {object}
+     * @param options.id {string}
+     * @returns {Promise<MasterState | null>}
+     */
+    get(options: {
+        id: string;
+    }): Promise<MasterState | null>;
+}
+/**
+ * Thrown by a {@link WasSyncPort} implementation when a conditional write is
+ * rejected with `412 precondition-failed` (a lost-update conflict, or a
+ * create-if-absent whose target already exists). The core push handler catches
+ * exactly this type to trigger the re-read-and-report-conflict path; any other
+ * error propagates to RxDB for retry.
+ */
+export declare class WasSyncConflictError extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sync/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,MAAM,MAAM,IAAI,GACd,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAErE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,OAAO,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,MAAM,CAAC,EAAE,IAAI,CAAA;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,MAAM,CAAC,EAAE,IAAI,CAAA;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,MAAM,CAAC,EAAE,IAAI,CAAA;CACd;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,EAAE;QAAE,UAAU,CAAC,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QACtE,SAAS,EAAE,OAAO,EAAE,CAAA;QACpB,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;KAClC,CAAC,CAAA;IAEF;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,OAAO,EAAE;QAClB,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,IAAI,CAAA;QACV,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE,OAAO,CAAA;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjB;;;;;;;;;OASG;IACH,aAAa,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvE;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,OAAO,EAAE;QACf,EAAE,EAAE,MAAM,CAAA;QACV,MAAM,EAAE,IAAI,CAAA;QACZ,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE,OAAO,CAAA;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjB;;;;;;;;OAQG;IACH,GAAG,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC1D;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,SAA+C;CAInE"}

package/dist/sync/types.js

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Shared types for the collection-agnostic WAS replication adapter.
+ *
+ * The adapter drives an RxDB `replicateRxCollection` state machine against a
+ * remote WAS Collection's replication endpoints. It is deliberately free of any
+ * React or app imports so it can stand alone; all WAS access is injected through
+ * the {@link WasSyncPort} seam rather than importing `@interop/was-client`
+ * directly.
+ *
+ * The wire contract follows the WAS `changes` feed and its V2 encrypted-metadata
+ * profile: a synced document carries both a content revision (`version` /
+ * `data`) and an independently-versioned metadata sub-resource (`metaVersion` /
+ * `custom`). A metadata-only edit re-surfaces the resource with a bumped
+ * `updatedAt` / `metaVersion` but unchanged `version` / `data`. The sync layer
+ * moves both bodies opaquely: `data` is the stored content body (plaintext JSON,
+ * or the EDV envelope on an encrypted collection) and `custom` is the stored
+ * metadata body (an opaque envelope on an encrypted collection); encrypt/decrypt
+ * stays a read/write-time concern above this layer.
+ */
+/**
+ * Thrown by a {@link WasSyncPort} implementation when a conditional write is
+ * rejected with `412 precondition-failed` (a lost-update conflict, or a
+ * create-if-absent whose target already exists). The core push handler catches
+ * exactly this type to trigger the re-read-and-report-conflict path; any other
+ * error propagates to RxDB for retry.
+ */
+export class WasSyncConflictError extends Error {
+    constructor(message = 'WAS conditional write precondition failed.') {
+        super(message);
+        this.name = 'WasSyncConflictError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/sync/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AAoKH;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,GAAG,4CAA4C;QAChE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACpC,CAAC;CACF"}

package/dist/sync/wasReplication.d.ts

@@ -0,0 +1,47 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * `createWasReplication` -- wires an RxDB collection to a remote WAS Collection
+ * through the collection-agnostic pull/push handlers. This is the single public
+ * entry point of the sync module; the caller supplies an already-open RxDB
+ * collection and a {@link WasSyncPort} (its only WAS dependency), and gets back
+ * the live `RxReplicationState` to observe (`error$` / `active$`) and control
+ * (`reSync()` / `cancel()`).
+ *
+ * No React and no `@interop/was-client` imports -- only RxDB (the replication
+ * engine being wrapped) and the injected port. This is the seam that keeps the
+ * WAS access injectable.
+ */
+import { type RxReplicationState } from 'rxdb/plugins/replication';
+import type { RxCollection } from 'rxdb/plugins/core';
+import type { SyncCheckpoint, SyncedDoc, WasSyncPort } from './types.js';
+/**
+ * Starts (or configures) replication of one RxDB collection against a remote WAS
+ * Collection. Poll-based only -- no `pull.stream$` (live streaming is deferred
+ * server-side); RxDB's own `retryTime` backoff and `error$` are the reachability
+ * signal (the replication attempt is the probe).
+ *
+ * @param options {object}
+ * @param options.rxCollection {RxCollection<SyncedDoc>}   the local replica
+ * @param options.wasPort {WasSyncPort}                    injected WAS access
+ * @param options.replicationIdentifier {string}   stable id (include the server
+ *   URL + collection) so RxDB can resume across reloads
+ * @param [options.batchSize] {number}    pull `limit` / push batch (default 100)
+ * @param [options.retryTime] {number}    ms backoff between failed cycles
+ * @param [options.live] {boolean}        ongoing (default true) vs one-shot
+ * @param [options.autoStart] {boolean}   start immediately (default true)
+ * @param [options.deletedField] {string} RxDB deleted flag (default `_deleted`)
+ * @returns {RxReplicationState<SyncedDoc, SyncCheckpoint>}
+ */
+export declare function createWasReplication({ rxCollection, wasPort, replicationIdentifier, batchSize, retryTime, live, autoStart, deletedField }: {
+    rxCollection: RxCollection<SyncedDoc>;
+    wasPort: WasSyncPort;
+    replicationIdentifier: string;
+    batchSize?: number;
+    retryTime?: number;
+    live?: boolean;
+    autoStart?: boolean;
+    deletedField?: string;
+}): RxReplicationState<SyncedDoc, SyncCheckpoint>;
+//# sourceMappingURL=wasReplication.d.ts.map

package/dist/sync/wasReplication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasReplication.d.ts","sourceRoot":"","sources":["../../src/sync/wasReplication.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;GAWG;AACH,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAA;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAIxE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,YAAY,EACZ,OAAO,EACP,qBAAqB,EACrB,SAAe,EACf,SAAS,EACT,IAAW,EACX,SAAgB,EAChB,YAAyB,EAC1B,EAAE;IACD,YAAY,EAAE,YAAY,CAAC,SAAS,CAAC,CAAA;IACrC,OAAO,EAAE,WAAW,CAAA;IACpB,qBAAqB,EAAE,MAAM,CAAA;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,GAAG,kBAAkB,CAAC,SAAS,EAAE,cAAc,CAAC,CAiBhD"}

package/dist/sync/wasReplication.js

@@ -0,0 +1,55 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * `createWasReplication` -- wires an RxDB collection to a remote WAS Collection
+ * through the collection-agnostic pull/push handlers. This is the single public
+ * entry point of the sync module; the caller supplies an already-open RxDB
+ * collection and a {@link WasSyncPort} (its only WAS dependency), and gets back
+ * the live `RxReplicationState` to observe (`error$` / `active$`) and control
+ * (`reSync()` / `cancel()`).
+ *
+ * No React and no `@interop/was-client` imports -- only RxDB (the replication
+ * engine being wrapped) and the injected port. This is the seam that keeps the
+ * WAS access injectable.
+ */
+import { replicateRxCollection } from 'rxdb/plugins/replication';
+import { createPullHandler } from './changesQuery.js';
+import { createPushHandler } from './pushWrites.js';
+/**
+ * Starts (or configures) replication of one RxDB collection against a remote WAS
+ * Collection. Poll-based only -- no `pull.stream$` (live streaming is deferred
+ * server-side); RxDB's own `retryTime` backoff and `error$` are the reachability
+ * signal (the replication attempt is the probe).
+ *
+ * @param options {object}
+ * @param options.rxCollection {RxCollection<SyncedDoc>}   the local replica
+ * @param options.wasPort {WasSyncPort}                    injected WAS access
+ * @param options.replicationIdentifier {string}   stable id (include the server
+ *   URL + collection) so RxDB can resume across reloads
+ * @param [options.batchSize] {number}    pull `limit` / push batch (default 100)
+ * @param [options.retryTime] {number}    ms backoff between failed cycles
+ * @param [options.live] {boolean}        ongoing (default true) vs one-shot
+ * @param [options.autoStart] {boolean}   start immediately (default true)
+ * @param [options.deletedField] {string} RxDB deleted flag (default `_deleted`)
+ * @returns {RxReplicationState<SyncedDoc, SyncCheckpoint>}
+ */
+export function createWasReplication({ rxCollection, wasPort, replicationIdentifier, batchSize = 100, retryTime, live = true, autoStart = true, deletedField = '_deleted' }) {
+    return replicateRxCollection({
+        replicationIdentifier,
+        collection: rxCollection,
+        deletedField,
+        live,
+        autoStart,
+        ...(retryTime !== undefined && { retryTime }),
+        pull: {
+            handler: createPullHandler(wasPort),
+            batchSize
+        },
+        push: {
+            handler: createPushHandler(wasPort),
+            batchSize
+        }
+    });
+}
+//# sourceMappingURL=wasReplication.js.map

package/dist/sync/wasReplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasReplication.js","sourceRoot":"","sources":["../../src/sync/wasReplication.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;GAWG;AACH,OAAO,EACL,qBAAqB,EAEtB,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,oBAAoB,CAAC,EACnC,YAAY,EACZ,OAAO,EACP,qBAAqB,EACrB,SAAS,GAAG,GAAG,EACf,SAAS,EACT,IAAI,GAAG,IAAI,EACX,SAAS,GAAG,IAAI,EAChB,YAAY,GAAG,UAAU,EAU1B;IACC,OAAO,qBAAqB,CAA4B;QACtD,qBAAqB;QACrB,UAAU,EAAE,YAAY;QACxB,YAAY;QACZ,IAAI;QACJ,SAAS;QACT,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,IAAI,EAAE;YACJ,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC;YACnC,SAAS;SACV;QACD,IAAI,EAAE;YACJ,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC;YACnC,SAAS;SACV;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/sync/wasSyncPort.d.ts

@@ -0,0 +1,45 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The app-side seam between the generic sync adapter and `@interop/was-client`.
+ * Implements the `WasSyncPort` interface for one remote WAS Collection using the
+ * raw, signed `was.request()` escape hatch.
+ *
+ * Using `request()` (rather than the `Resource` / `Collection` handles) is
+ * deliberate: it moves the stored body VERBATIM, bypassing the encryption codec.
+ * The `changes` feed already ships opaque stored bodies (plaintext for a
+ * plaintext collection, the EDV envelope for an encrypted one), and the push
+ * side must write those same bytes back unchanged -- running them through
+ * `resource.put()` would re-encrypt an already-encrypted envelope. Encrypt /
+ * decrypt stays a read/write-time concern above this layer; this port is
+ * collection-agnostic and never touches keys.
+ *
+ * Conditional writes ride the server's monotonic `version` (content) and
+ * `metaVersion` (metadata) ETags, which the reference server enforces uniformly
+ * for plaintext and encrypted resources alike -- so there is no plaintext-vs-
+ * encrypted fork here.
+ */
+import type { WasClient } from '@interop/was-client';
+import type { IZcap } from '@interop/data-integrity-core';
+import { type WasSyncPort } from './types.js';
+/**
+ * Builds a `WasSyncPort` bound to a single Space + Collection on the remote WAS
+ * server, backed by the session's signed `WasClient`.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}       the session client (holds the signer)
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}   the WAS collection id (e.g. `public-credentials`)
+ * @param [options.capability] {IZcap}   the delegated session capability for
+ *   this collection (a restored `delegated` tier session); absent in the full
+ *   tier, where requests invoke root capabilities
+ * @returns {WasSyncPort}
+ */
+export declare function createWasSyncPort({ was, spaceId, collectionId, capability }: {
+    was: WasClient;
+    spaceId: string;
+    collectionId: string;
+    capability?: IZcap;
+}): WasSyncPort;
+//# sourceMappingURL=wasSyncPort.d.ts.map

package/dist/sync/wasSyncPort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasSyncPort.d.ts","sourceRoot":"","sources":["../../src/sync/wasSyncPort.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAA;AACzD,OAAO,EAKL,KAAK,WAAW,EAEjB,MAAM,YAAY,CAAA;AAgCnB;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,GAAG,EACH,OAAO,EACP,YAAY,EACZ,UAAU,EACX,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,KAAK,CAAA;CACnB,GAAG,WAAW,CA0Jd"}

package/dist/sync/wasSyncPort.js

@@ -0,0 +1,170 @@
+import { WasSyncConflictError } from './types.js';
+/**
+ * Extracts an HTTP status from a raw ky/ezcap error. `was.request()` rejects on
+ * any non-2xx with `err.status` set (see `@interop/http-client`'s error
+ * normaliser); this reads it defensively from either location.
+ *
+ * @param err {unknown}
+ * @returns {number | undefined}
+ */
+function errorStatus(err) {
+    return (err.status ??
+        err.response?.status);
+}
+/**
+ * Parses a quoted strong ETag (`"3"`) into its numeric revision, or `undefined`
+ * when the header is absent (the resource has no such revision yet).
+ *
+ * @param etag {string | null}
+ * @returns {number | undefined}
+ */
+function parseEtag(etag) {
+    if (!etag) {
+        return undefined;
+    }
+    const revision = Number(etag.replace(/"/g, ''));
+    return Number.isFinite(revision) ? revision : undefined;
+}
+/**
+ * Builds a `WasSyncPort` bound to a single Space + Collection on the remote WAS
+ * server, backed by the session's signed `WasClient`.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}       the session client (holds the signer)
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}   the WAS collection id (e.g. `public-credentials`)
+ * @param [options.capability] {IZcap}   the delegated session capability for
+ *   this collection (a restored `delegated` tier session); absent in the full
+ *   tier, where requests invoke root capabilities
+ * @returns {WasSyncPort}
+ */
+export function createWasSyncPort({ was, spaceId, collectionId, capability }) {
+    const collectionPath = `/space/${spaceId}/${collectionId}`;
+    const resourcePath = (id) => `${collectionPath}/${encodeURIComponent(id)}`;
+    /**
+     * Builds the conditional-write headers from the port's precondition options.
+     */
+    const writeHeaders = ({ ifMatch, ifNoneMatch }) => {
+        const headers = {};
+        if (ifMatch !== undefined) {
+            headers['if-match'] = ifMatch;
+        }
+        if (ifNoneMatch) {
+            headers['if-none-match'] = '*';
+        }
+        return Object.keys(headers).length > 0 ? headers : undefined;
+    };
+    /**
+     * Runs a conditional write, mapping the server's `412 precondition-failed`
+     * into the core's `WasSyncConflictError` and letting all else propagate.
+     */
+    const conditionalWrite = async (run) => {
+        try {
+            await run();
+        }
+        catch (err) {
+            if (errorStatus(err) === 412) {
+                throw new WasSyncConflictError();
+            }
+            throw err;
+        }
+    };
+    return {
+        async query({ checkpoint, limit }) {
+            const response = await was.request({
+                capability,
+                path: `${collectionPath}/query`,
+                method: 'POST',
+                json: {
+                    profile: 'changes',
+                    ...(checkpoint !== undefined && { checkpoint }),
+                    limit
+                }
+            });
+            return response.data;
+        },
+        async putContent({ id, data, ifMatch, ifNoneMatch }) {
+            await conditionalWrite(() => was.request({
+                capability,
+                path: resourcePath(id),
+                method: 'PUT',
+                json: data,
+                headers: writeHeaders({ ifMatch, ifNoneMatch })
+            }));
+        },
+        async deleteContent({ id, ifMatch }) {
+            await conditionalWrite(() => was.request({
+                capability,
+                path: resourcePath(id),
+                method: 'DELETE',
+                headers: writeHeaders({ ifMatch })
+            }));
+        },
+        async putMeta({ id, custom, ifMatch, ifNoneMatch }) {
+            await conditionalWrite(() => was.request({
+                capability,
+                path: `${resourcePath(id)}/meta`,
+                method: 'PUT',
+                json: { custom },
+                headers: writeHeaders({ ifMatch, ifNoneMatch })
+            }));
+        },
+        async get({ id }) {
+            // Content re-read: raw GET returns the stored body verbatim (no decrypt)
+            // and the content `version` in the ETag. A 404 means the resource is gone
+            // (or tombstoned) -- report absent so the core synthesizes a tombstone.
+            let contentResponse;
+            try {
+                contentResponse = await was.request({
+                    capability,
+                    path: resourcePath(id),
+                    method: 'GET'
+                });
+            }
+            catch (err) {
+                if (errorStatus(err) === 404) {
+                    return null;
+                }
+                throw err;
+            }
+            const master = {
+                version: parseEtag(contentResponse.headers.get('etag')) ?? 0,
+                // Filled from the `/meta` body's server-managed `updatedAt` below; the
+                // change feed remains the authority on ordering, so this only feeds the
+                // one-off conflict entry and is corrected on the next pull.
+                updatedAt: '',
+                deleted: false,
+                data: contentResponse.data
+            };
+            // Metadata re-read: the `/meta` body carries the server-managed
+            // `updatedAt` plus the user-writable `custom` (opaque), and its own
+            // `metaVersion` ETag (absent until metadata has been written).
+            try {
+                const metaResponse = await was.request({
+                    capability,
+                    path: `${resourcePath(id)}/meta`,
+                    method: 'GET'
+                });
+                const metaBody = metaResponse.data;
+                if (metaBody?.updatedAt) {
+                    master.updatedAt = metaBody.updatedAt;
+                }
+                const metaVersion = parseEtag(metaResponse.headers.get('etag'));
+                if (metaVersion !== undefined) {
+                    master.metaVersion = metaVersion;
+                }
+                if (metaBody?.custom !== undefined) {
+                    master.custom = metaBody.custom;
+                }
+            }
+            catch (err) {
+                // Metadata is optional; only a hard error (not 404) should propagate.
+                if (errorStatus(err) !== 404) {
+                    throw err;
+                }
+            }
+            return master;
+        }
+    };
+}
+//# sourceMappingURL=wasSyncPort.js.map

package/dist/sync/wasSyncPort.js.map

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