@baukit/sync-client 0.1.2 → 0.2.0

package/README.md

@@ -53,14 +53,20 @@ non-Expo consumers never import this subpath.
 
 ## Transport
 
-The original `SyncTransport` constructor wraps an injected `fetch` and auth header provider, and
-turns every failure into a typed error:
+The fetch-backed `SyncTransport` constructor wraps an injected `fetch` and auth header provider.
+It classifies failures as follows:
 
-- `SyncAuthError` for 401, never retryable;
-- `SyncPartitionMismatchError` when the body carries the configured partition-mismatch code,
-  meaning the local database belongs to an erased or replaced owner;
-- `SyncTransportError` otherwise, with `retryable` true for 408, 429, and 5xx, plus network and
-  body-read failures.
+- `SyncAuthError` for 401, never retryable
+- `SyncPartitionMismatchError` when the body carries the configured partition-mismatch code
+- `SyncRateLimitError` for 429, always retryable and carrying `retryAt` plus the raw `retryAfter`
+  header
+- `SyncNetworkError` when `fetch` or response-body reading fails, always retryable
+- `SyncServerError` for other HTTP failures, retryable for 408 and 5xx
+- `SyncPayloadCompatibilityError` when a successful response is not valid JSON, never retryable
+
+`Retry-After` accepts integer delta seconds and HTTP dates. Missing, invalid, negative, and past
+values use `now + retryAfterFallbackMs`. The default fallback is 60 seconds. Tests and products
+with another policy can inject `now` and `retryAfterFallbackMs` in the fetch-backed constructor.
 
 Auth headers resolve per attempt, so a token refreshed between retries is picked up. The
 partition header is sent only when the caller passes a `partitionId`, and both its name and the
@@ -86,8 +92,8 @@ await transport.request('/api/v1/sync/push', {
 
 This mode builds the relative path, query string, JSON body, and partition header, then delegates.
 The request function owns decoding and errors, which keeps the product API client's existing auth
-recovery intact. The fetch-backed constructor remains unchanged for products that want
-`SyncTransportError` classification from response status and body.
+recovery intact. Use the fetch-backed constructor when the product wants package-owned response
+classification.
 
 ## Status store
 
@@ -99,13 +105,24 @@ wrong:
   still reads `attention`;
 - unsent work outranks a bare error, so a failed run with pending changes reads `pending`,
   not `error`;
-- the first run is the initial pull; later runs are settled activity.
+- the first run is the initial pull; later runs are settled activity;
+- a failure updates `lastAttemptAt` without changing `lastSuccessAt` or clearing `pendingCount`.
+
+Call `setSyncing(attemptAt)` when an attempt starts. `setIdle(successAt)` records a successful
+attempt and clears work only after the product's success predicate passes. `setFailure` accepts
+machine-readable metadata with one of these kinds: `auth`, `partition_mismatch`, `rate_limited`,
+`network`, `server`, `payload_compatibility`, or `local_apply`. Product copy remains in the
+separate `error` field.
+
+Rate-limit metadata contains `retryAt`. Other retryable failures can pass `retryAt` in the
+`SyncFailureUpdate` argument or call `setRetrying(retryAt)`. Snapshots expose both `retrying` and
+`retryAt`, so a screen can distinguish scheduled retries and rate limits from an offline state.
 
 `refreshRevision` increments whenever a run delivers a new authoritative snapshot.
 `deriveLocalStoreReadiness` compares it against what a consumer has actually rendered, which is
 how a cold start avoids flashing an empty state over data that is still arriving.
-`deriveInitialSyncState` maps a snapshot onto the contract's `unknown` / `syncing` /
-`offline-cached` / `settled` vocabulary.
+`deriveInitialSyncState` maps a snapshot onto `unknown`, `syncing`, `offline-cached`,
+`sync-error-cached`, or `settled`. Only a first-run `network` failure maps to `offline-cached`.
 
 The store is generic over its attention item and defaults to the existing
 `{ entityType, entityId }` shape. This keeps one store API while allowing a product to retain the
@@ -127,7 +144,12 @@ For stores and screens that use API-style names, `toSnakeCaseSnapshot` returns a
 ```ts
 const snapshot = toSnakeCaseSnapshot(status.getSnapshot());
 
+snapshot.last_attempt_at;
+snapshot.last_success_at;
 snapshot.last_sync_at;
+snapshot.failure;
+snapshot.retrying;
+snapshot.retry_at;
 snapshot.pending_count;
 snapshot.initial_pull_status;
 snapshot.refresh_revision;
@@ -137,6 +159,29 @@ snapshot.security_block;
 `status`, `error`, and `attention` keep their names. Attention items also keep their original
 shape.
 
+### Timestamp migration
+
+`lastSyncAt` and `last_sync_at` are deprecated compatibility fields for one release cycle. They
+are derived from `lastSuccessAt` and `last_success_at`. New code must not write or persist them as
+attempt timestamps.
+
+Replace `snapshot.lastSyncAt` with `snapshot.lastSuccessAt`. Replace `snapshot.last_sync_at` with
+`snapshot.last_success_at`. Persist both attempt and success timestamps, then hydrate with an
+object:
+
+```ts
+status.hydrate({
+  lastAttemptAt: persisted.lastAttemptAt,
+  lastSuccessAt: persisted.lastSuccessAt,
+  attention: persisted.attention,
+  pendingCount: persisted.pendingCount,
+});
+```
+
+The deprecated `hydrate(lastSyncAt, attention, pendingCount)` overload treats the old value as
+both the last attempt and last success. Remove that overload call when the persisted schema has
+both fields.
+
 ## Push batch ranking
 
 `rankPushBatch` orders one push batch so a parent is never sent after its children.
@@ -163,3 +208,48 @@ missing. Held-back entities do not consume batch-size slots.
 
 Entity names, the dependency order, and the hold-back predicate are all product inputs. Baukit
 knows only that a rank exists.
+
+## Payload validators
+
+Call `validatePushOutcomeCoverage` before acknowledging any submitted change. Pass one key reader
+for submitted entities and one for outcomes, then combine all accepted and rejected outcomes in
+the second argument. The function throws `SyncPayloadCompatibilityError` if any submitted entity
+has no outcome.
+
+Call `validatePullPage(currentCursor, page, compare)` before following `hasMore`. Cursors are
+opaque. The injected comparator defines their order. A regressing cursor, a non-finite comparison,
+or `hasMore` without cursor progress throws `SyncPayloadCompatibilityError`.
+
+`commitCursorAfterLocalTransaction` runs the supplied local transaction first. It invokes
+`commitCursor` only after that promise resolves, and wraps local failures in `SyncLocalApplyError`.
+This ordering prevents a failed local apply from skipping remote changes on the next pull.
+
+## Conformance harness
+
+`@baukit/sync-client/conformance` exports `createSyncConformanceTests`. It returns plain async test
+cases and has no Vitest or Jest dependency. Register the returned cases with the runner already in
+the product:
+
+```ts
+import { createSyncConformanceTests } from '@baukit/sync-client/conformance';
+
+describe('product sync contract', () => {
+  for (const testCase of createSyncConformanceTests(productAdapter)) {
+    it(testCase.name, testCase.run);
+  }
+});
+```
+
+The adapter supplies two isolated clients and one fake server per case. It also supplies callbacks
+for outbox enqueue, listing, acknowledgement, and rejection storage; atomic pull application and
+cursor storage; pending-state reporting; wire encoding and decoding; and fake-server push, pull,
+seeding, snapshots, and fault injection. Canonical fixture changes contain opaque entity names,
+values, logical times, dependencies, and tombstones. The adapter maps them to the product's schema
+and payloads.
+
+The cases cover replay, transaction rollback, paged cursor progress, stalled and regressing
+cursors, complete push outcomes, pending state after network, server, and local failures,
+actionable rejections, dependency-safe push order, and two-client convergence with a tombstone.
+`wire.decodePush` must call `validatePushOutcomeCoverage` before returning acknowledged rows. The
+local apply callback must commit the page and cursor in one transaction. Its injected failure must
+roll both back.

package/dist/conformance.d.ts

@@ -0,0 +1,80 @@
+export type SyncConformanceOperation = 'upsert' | 'delete';
+export type SyncConformancePushFailure = 'network' | 'server';
+export type SyncConformancePullFault = 'regress' | 'stall';
+export interface SyncConformanceEntityRef {
+    entityType: string;
+    entityId: string;
+}
+export interface SyncConformanceChange extends SyncConformanceEntityRef {
+    changeId: string;
+    operation: SyncConformanceOperation;
+    value: string | null;
+    logicalTime: number;
+    dependsOn?: SyncConformanceEntityRef;
+}
+export interface SyncConformanceRow extends SyncConformanceEntityRef {
+    value: string | null;
+    logicalTime: number;
+    deleted: boolean;
+}
+export interface SyncConformanceRejection extends SyncConformanceEntityRef {
+    reason: string;
+}
+export interface SyncConformancePullPage<TChange, TCursor> {
+    changes: readonly TChange[];
+    nextCursor: TCursor;
+    hasMore: boolean;
+}
+export interface SyncConformancePushResult<TPending> {
+    acknowledged: readonly TPending[];
+    rejected: readonly SyncConformanceRejection[];
+}
+export interface SyncConformancePendingState {
+    pending: boolean;
+    pendingCount: number;
+}
+export interface SyncConformanceLocalApplyOptions {
+    failAfterChanges?: number;
+}
+export interface SyncConformanceScenario<TClient, TServer> {
+    clients: readonly [TClient, TClient];
+    server: TServer;
+}
+export interface SyncConformanceAdapter<TClient, TServer, TPending, TPushRequest, TPushResponse, TPullResponse, TRemoteChange, TCursor> {
+    createScenario(): Promise<SyncConformanceScenario<TClient, TServer>> | SyncConformanceScenario<TClient, TServer>;
+    disposeScenario?(scenario: SyncConformanceScenario<TClient, TServer>): Promise<void> | void;
+    outbox: {
+        enqueue(client: TClient, change: SyncConformanceChange): Promise<void> | void;
+        listPending(client: TClient): Promise<readonly TPending[]> | readonly TPending[];
+        markAcknowledged(client: TClient, pending: readonly TPending[]): Promise<void> | void;
+        recordRejected(client: TClient, rejected: readonly SyncConformanceRejection[]): Promise<void> | void;
+        listRejected(client: TClient): Promise<readonly SyncConformanceRejection[]> | readonly SyncConformanceRejection[];
+    };
+    local: {
+        readCursor(client: TClient): Promise<TCursor> | TCursor;
+        applyPullPage(client: TClient, page: SyncConformancePullPage<TRemoteChange, TCursor>, options?: SyncConformanceLocalApplyOptions): Promise<void> | void;
+        snapshot(client: TClient): Promise<readonly SyncConformanceRow[]> | readonly SyncConformanceRow[];
+        readPendingState(client: TClient): Promise<SyncConformancePendingState> | SyncConformancePendingState;
+    };
+    wire: {
+        encodePush(pending: readonly TPending[]): Promise<TPushRequest> | TPushRequest;
+        decodePush(response: TPushResponse, submitted: readonly TPending[]): Promise<SyncConformancePushResult<TPending>> | SyncConformancePushResult<TPending>;
+        decodePull(response: TPullResponse): Promise<SyncConformancePullPage<TRemoteChange, TCursor>> | SyncConformancePullPage<TRemoteChange, TCursor>;
+        compareCursors(left: TCursor, right: TCursor): number;
+    };
+    server: {
+        acceptPush(server: TServer, request: TPushRequest): Promise<TPushResponse>;
+        servePull(server: TServer, cursor: TCursor, pageSize: number): Promise<TPullResponse>;
+        seed(server: TServer, change: SyncConformanceChange): Promise<void> | void;
+        snapshot(server: TServer): Promise<readonly SyncConformanceRow[]> | readonly SyncConformanceRow[];
+        failNextPush(server: TServer, failure: SyncConformancePushFailure): Promise<void> | void;
+        omitNextPushOutcome(server: TServer): Promise<void> | void;
+        faultNextPull(server: TServer, fault: SyncConformancePullFault): Promise<void> | void;
+    };
+}
+export interface SyncConformanceTestCase {
+    readonly name: string;
+    readonly run: () => Promise<void>;
+}
+export declare function createSyncConformanceTests<TClient, TServer, TPending, TPushRequest, TPushResponse, TPullResponse, TRemoteChange, TCursor>(adapter: SyncConformanceAdapter<TClient, TServer, TPending, TPushRequest, TPushResponse, TPullResponse, TRemoteChange, TCursor>): readonly SyncConformanceTestCase[];
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

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

package/dist/conformance.js

@@ -0,0 +1,251 @@
+import { validatePullPage } from './transport.js';
+const PAGE_SIZE = 2;
+const parentChange = {
+    changeId: 'change-parent',
+    entityType: 'container',
+    entityId: 'parent',
+    operation: 'upsert',
+    value: 'parent value',
+    logicalTime: 10,
+};
+const childChange = {
+    changeId: 'change-child',
+    entityType: 'item',
+    entityId: 'child',
+    operation: 'upsert',
+    value: 'child value',
+    logicalTime: 11,
+    dependsOn: { entityType: 'container', entityId: 'parent' },
+};
+function change(changeId, entityId, logicalTime, value) {
+    return {
+        changeId,
+        entityType: 'record',
+        entityId,
+        operation: 'upsert',
+        value,
+        logicalTime,
+    };
+}
+function tombstone(changeId, entityId, logicalTime) {
+    return {
+        changeId,
+        entityType: 'record',
+        entityId,
+        operation: 'delete',
+        value: null,
+        logicalTime,
+    };
+}
+function fail(message) {
+    throw new Error(`Sync conformance failed: ${message}`);
+}
+function assert(condition, message) {
+    if (!condition)
+        fail(message);
+}
+function sortedRows(rows) {
+    return [...rows].sort((left, right) => left.entityType.localeCompare(right.entityType) ||
+        left.entityId.localeCompare(right.entityId));
+}
+function sameRows(left, right) {
+    return JSON.stringify(sortedRows(left)) === JSON.stringify(sortedRows(right));
+}
+async function expectFailure(run, message) {
+    try {
+        await run();
+    }
+    catch {
+        return;
+    }
+    fail(message);
+}
+export function createSyncConformanceTests(adapter) {
+    async function inScenario(run) {
+        const scenario = await adapter.createScenario();
+        const [clientA, clientB] = scenario.clients;
+        try {
+            await run({ clientA, clientB, server: scenario.server });
+        }
+        finally {
+            await adapter.disposeScenario?.(scenario);
+        }
+    }
+    async function pending(client) {
+        return adapter.outbox.listPending(client);
+    }
+    async function assertPendingState(client, expectedCount) {
+        const actual = await pending(client);
+        const reported = await adapter.local.readPendingState(client);
+        assert(actual.length === expectedCount, `expected ${String(expectedCount)} pending changes`);
+        assert(reported.pendingCount === actual.length, 'reported pending count differs from the outbox');
+        assert(reported.pending === actual.length > 0, 'reported pending flag differs from the outbox');
+    }
+    async function push(client, server) {
+        const submitted = await pending(client);
+        if (submitted.length === 0)
+            return;
+        const request = await adapter.wire.encodePush(submitted);
+        const response = await adapter.server.acceptPush(server, request);
+        const outcome = await adapter.wire.decodePush(response, submitted);
+        await adapter.outbox.markAcknowledged(client, outcome.acknowledged);
+        await adapter.outbox.recordRejected(client, outcome.rejected);
+    }
+    async function pullPage(client, server, options) {
+        const cursor = (await adapter.local.readCursor(client));
+        const response = await adapter.server.servePull(server, cursor, PAGE_SIZE);
+        const page = await adapter.wire.decodePull(response);
+        validatePullPage(cursor, page, (left, right) => adapter.wire.compareCursors(left, right));
+        await adapter.local.applyPullPage(client, page, options);
+        return page.hasMore;
+    }
+    async function pullAll(client, server) {
+        let hasMore = true;
+        while (hasMore)
+            hasMore = await pullPage(client, server);
+    }
+    return [
+        {
+            name: 'replayed pushes create one server change',
+            run: () => inScenario(async ({ clientA, server }) => {
+                await adapter.outbox.enqueue(clientA, change('change-replay', 'replay', 10, 'once'));
+                const submitted = await pending(clientA);
+                const request = await adapter.wire.encodePush(submitted);
+                const first = await adapter.server.acceptPush(server, request);
+                const second = await adapter.server.acceptPush(server, request);
+                await adapter.wire.decodePush(first, submitted);
+                await adapter.wire.decodePush(second, submitted);
+                const rows = (await adapter.server.snapshot(server)).filter((row) => row.entityType === 'record' && row.entityId === 'replay');
+                assert(rows.length === 1, 'replay created a duplicate server row');
+            }),
+        },
+        {
+            name: 'an interrupted local transaction preserves data, cursor, and pending work',
+            run: () => inScenario(async ({ clientA, server }) => {
+                await adapter.outbox.enqueue(clientA, change('change-pending', 'pending', 30, 'local'));
+                await adapter.server.seed(server, change('seed-first', 'first', 10, 'remote first'));
+                await adapter.server.seed(server, change('seed-second', 'second', 20, 'remote second'));
+                const cursorBefore = await adapter.local.readCursor(clientA);
+                const rowsBefore = await adapter.local.snapshot(clientA);
+                await expectFailure(() => pullPage(clientA, server, { failAfterChanges: 1 }).then(() => undefined), 'local apply failure resolved successfully');
+                const cursorAfter = await adapter.local.readCursor(clientA);
+                const rowsAfter = await adapter.local.snapshot(clientA);
+                assert(adapter.wire.compareCursors(cursorAfter, cursorBefore) === 0, 'local apply failure advanced the cursor');
+                assert(sameRows(rowsAfter, rowsBefore), 'local apply failure committed part of the page');
+                await assertPendingState(clientA, 1);
+            }),
+        },
+        {
+            name: 'pull cursors advance monotonically across pages',
+            run: () => inScenario(async ({ clientA, server }) => {
+                await adapter.server.seed(server, change('seed-one', 'one', 10, 'one'));
+                await adapter.server.seed(server, change('seed-two', 'two', 20, 'two'));
+                await adapter.server.seed(server, change('seed-three', 'three', 30, 'three'));
+                const start = await adapter.local.readCursor(clientA);
+                await pullAll(clientA, server);
+                const end = await adapter.local.readCursor(clientA);
+                assert(adapter.wire.compareCursors(end, start) > 0, 'pull did not advance the cursor');
+                assert(sameRows(await adapter.local.snapshot(clientA), await adapter.server.snapshot(server)), 'paged pull skipped or duplicated server state');
+            }),
+        },
+        {
+            name: 'a regressing pull cursor is rejected before local apply',
+            run: () => inScenario(async ({ clientA, server }) => {
+                await adapter.server.seed(server, change('seed-regress', 'regress', 10, 'remote'));
+                await pullAll(clientA, server);
+                const cursor = await adapter.local.readCursor(clientA);
+                const rows = await adapter.local.snapshot(clientA);
+                await adapter.server.faultNextPull(server, 'regress');
+                await expectFailure(() => pullPage(clientA, server).then(() => undefined), 'regressing cursor was accepted');
+                assert(adapter.wire.compareCursors(await adapter.local.readCursor(clientA), cursor) === 0, 'regressing page changed the cursor');
+                assert(sameRows(await adapter.local.snapshot(clientA), rows), 'regressing page changed data');
+            }),
+        },
+        {
+            name: 'hasMore requires cursor progress',
+            run: () => inScenario(async ({ clientA, server }) => {
+                const cursor = await adapter.local.readCursor(clientA);
+                await adapter.server.faultNextPull(server, 'stall');
+                await expectFailure(() => pullPage(clientA, server).then(() => undefined), 'hasMore without cursor progress was accepted');
+                assert(adapter.wire.compareCursors(await adapter.local.readCursor(clientA), cursor) === 0, 'stalled page changed the cursor');
+            }),
+        },
+        {
+            name: 'partial push outcomes are rejected before acknowledgement',
+            run: () => inScenario(async ({ clientA, server }) => {
+                await adapter.outbox.enqueue(clientA, change('change-covered-a', 'covered-a', 10, 'a'));
+                await adapter.outbox.enqueue(clientA, change('change-covered-b', 'covered-b', 20, 'b'));
+                await adapter.server.omitNextPushOutcome(server);
+                await expectFailure(() => push(clientA, server), 'partial push outcomes were accepted');
+                await assertPendingState(clientA, 2);
+            }),
+        },
+        {
+            name: 'network failure keeps pending state truthful',
+            run: () => inScenario(async ({ clientA, server }) => {
+                await adapter.outbox.enqueue(clientA, change('change-network', 'network', 10, 'local'));
+                await adapter.server.failNextPush(server, 'network');
+                await expectFailure(() => push(clientA, server), 'network failure resolved successfully');
+                await assertPendingState(clientA, 1);
+            }),
+        },
+        {
+            name: 'server failure keeps pending state truthful',
+            run: () => inScenario(async ({ clientA, server }) => {
+                await adapter.outbox.enqueue(clientA, change('change-server', 'server', 10, 'local'));
+                await adapter.server.failNextPush(server, 'server');
+                await expectFailure(() => push(clientA, server), 'server failure resolved successfully');
+                await assertPendingState(clientA, 1);
+            }),
+        },
+        {
+            name: 'complete rejection outcomes are recorded without hidden pending work',
+            run: () => inScenario(async ({ clientA, server }) => {
+                await adapter.server.seed(server, change('seed-newer', 'rejected', 20, 'server'));
+                await adapter.outbox.enqueue(clientA, change('change-older', 'rejected', 10, 'local'));
+                await push(clientA, server);
+                await assertPendingState(clientA, 0);
+                const rejected = await adapter.outbox.listRejected(clientA);
+                assert(rejected.length === 1, 'actionable rejection was not recorded');
+                assert(rejected[0]?.entityId === 'rejected', 'wrong rejection was recorded');
+            }),
+        },
+        {
+            name: 'pushes referenced records before dependent records',
+            run: () => inScenario(async ({ clientA, server }) => {
+                await adapter.outbox.enqueue(clientA, childChange);
+                await adapter.outbox.enqueue(clientA, parentChange);
+                await push(clientA, server);
+                await assertPendingState(clientA, 0);
+                const rows = await adapter.server.snapshot(server);
+                assert(rows.some((row) => row.entityType === 'container' && row.entityId === 'parent'), 'referenced record did not reach the server');
+                assert(rows.some((row) => row.entityType === 'item' && row.entityId === 'child'), 'dependent record was rejected because push order was unsafe');
+            }),
+        },
+        {
+            name: 'two clients converge after alternating sync, including a tombstone',
+            run: () => inScenario(async ({ clientA, clientB, server }) => {
+                await adapter.outbox.enqueue(clientA, change('change-a', 'alpha', 10, 'from A'));
+                await adapter.outbox.enqueue(clientB, change('change-b', 'beta', 20, 'from B'));
+                await push(clientA, server);
+                await pullAll(clientB, server);
+                await push(clientB, server);
+                await pullAll(clientA, server);
+                await adapter.outbox.enqueue(clientB, tombstone('change-delete', 'alpha', 30));
+                await push(clientB, server);
+                await pullAll(clientA, server);
+                await pullAll(clientB, server);
+                const rowsA = await adapter.local.snapshot(clientA);
+                const rowsB = await adapter.local.snapshot(clientB);
+                const serverRows = await adapter.server.snapshot(server);
+                assert(sameRows(rowsA, rowsB), 'clients did not converge to the same state');
+                assert(sameRows(rowsA, serverRows), 'clients did not converge to server state');
+                const deleted = rowsA.find((row) => row.entityType === 'record' && row.entityId === 'alpha');
+                assert(deleted?.deleted === true, 'tombstone did not converge');
+                await assertPendingState(clientA, 0);
+                await assertPendingState(clientB, 0);
+            }),
+        },
+    ];
+}
+//# sourceMappingURL=conformance.js.map

package/dist/conformance.js.map

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

package/dist/error.d.ts

@@ -1,3 +1,27 @@
+/** Machine-readable failure metadata. Products own any message shown to users. */
+export type SyncFailure = {
+    readonly kind: 'auth';
+} | {
+    readonly kind: 'partition_mismatch';
+} | {
+    readonly kind: 'rate_limited';
+    readonly retryAt: string;
+} | {
+    readonly kind: 'network';
+} | {
+    readonly kind: 'server';
+} | {
+    readonly kind: 'payload_compatibility';
+} | {
+    readonly kind: 'local_apply';
+};
+/** Snake-case projection of {@link SyncFailure}. */
+export type SnakeCaseSyncFailure = Exclude<SyncFailure, {
+    readonly kind: 'rate_limited';
+}> | {
+    readonly kind: 'rate_limited';
+    readonly retry_at: string;
+};
 /** A sync request failed. `retryable` decides whether a later attempt may win. */
 export declare class SyncTransportError extends Error {
     readonly retryable: boolean;
@@ -9,12 +33,42 @@ export declare class SyncAuthError extends SyncTransportError {
     readonly kind = "auth";
     constructor(message: string, cause?: unknown);
 }
+/** The request did not reach a usable HTTP response. */
+export declare class SyncNetworkError extends SyncTransportError {
+    readonly kind = "network";
+    constructor(message: string, cause?: unknown);
+}
+/** The server returned an HTTP failure other than authentication or rate limiting. */
+export declare class SyncServerError extends SyncTransportError {
+    readonly kind = "server";
+    constructor(message: string, retryable: boolean, cause?: unknown);
+}
+/** HTTP 429 with its raw `Retry-After` value and resolved retry time. */
+export declare class SyncRateLimitError extends SyncTransportError {
+    readonly retryAt: string;
+    readonly retryAfter: string | null;
+    readonly kind = "rate_limited";
+    constructor(message: string, retryAt: string, retryAfter: string | null, cause?: unknown);
+}
 /**
  * The server rejected the caller's local-data partition, so the local database
  * belongs to an erased or replaced owner and must not be reused.
  */
 export declare class SyncPartitionMismatchError extends SyncTransportError {
-    readonly kind = "partition-mismatch";
+    readonly kind = "partition_mismatch";
+    constructor(message: string, cause?: unknown);
+}
+/** A decoded response violates the sync payload contract. */
+export declare class SyncPayloadCompatibilityError extends SyncTransportError {
+    readonly kind = "payload_compatibility";
+    constructor(message: string, cause?: unknown);
+}
+/** Remote data or a cursor could not be committed to local storage. */
+export declare class SyncLocalApplyError extends Error {
+    readonly kind = "local_apply";
     constructor(message: string, cause?: unknown);
 }
+/** Maps package errors onto store failure metadata. */
+export declare function syncFailureFromError(error: unknown): SyncFailure;
+export declare function toSnakeCaseFailure(failure: SyncFailure): SnakeCaseSyncFailure;
 //# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,SAAS,EAAE,OAAO;aACT,KAAK,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,OAAO,EACT,KAAK,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED,4EAA4E;AAC5E,qBAAa,aAAc,SAAQ,kBAAkB;IACnD,QAAQ,CAAC,IAAI,UAAU;gBAEX,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED;;;GAGG;AACH,qBAAa,0BAA2B,SAAQ,kBAAkB;IAChE,QAAQ,CAAC,IAAI,wBAAwB;gBAEzB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAA;CAAE,GACvC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAA;CAAE,GAC1C;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAErC,oDAAoD;AACpD,MAAM,MAAM,oBAAoB,GAC5B,OAAO,CAAC,WAAW,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,kFAAkF;AAClF,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,SAAS,EAAE,OAAO;aACT,KAAK,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,OAAO,EACT,KAAK,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED,4EAA4E;AAC5E,qBAAa,aAAc,SAAQ,kBAAkB;IACnD,QAAQ,CAAC,IAAI,UAAU;gBAEX,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,wDAAwD;AACxD,qBAAa,gBAAiB,SAAQ,kBAAkB;IACtD,QAAQ,CAAC,IAAI,aAAa;gBAEd,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,sFAAsF;AACtF,qBAAa,eAAgB,SAAQ,kBAAkB;IACrD,QAAQ,CAAC,IAAI,YAAY;gBAEb,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,OAAO;CAIjE;AAED,yEAAyE;AACzE,qBAAa,kBAAmB,SAAQ,kBAAkB;IAKtD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IALpC,QAAQ,CAAC,IAAI,kBAAkB;gBAG7B,OAAO,EAAE,MAAM,EACN,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GAAG,IAAI,EAClC,KAAK,CAAC,EAAE,OAAO;CAKlB;AAED;;;GAGG;AACH,qBAAa,0BAA2B,SAAQ,kBAAkB;IAChE,QAAQ,CAAC,IAAI,wBAAwB;gBAEzB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,6DAA6D;AAC7D,qBAAa,6BAA8B,SAAQ,kBAAkB;IACnE,QAAQ,CAAC,IAAI,2BAA2B;gBAE5B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,uEAAuE;AACvE,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,iBAAiB;gBAElB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,uDAAuD;AACvD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAchE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,oBAAoB,CAI7E"}