@happyvertical/smrt-web 0.51.32 → 0.51.34

package/dist/offline/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @happyvertical/smrt-web — offline outbox shared types (#1762).
+ *
+ * The SMRT-owned vocabulary the outbox modules (`durable-queue`, `leader`,
+ * `engine`) and the public surface (`offline.ts`) share. Kept in its own leaf
+ * module — imported by everything, importing nothing from the package — so there
+ * is no cycle back through `index.ts` and the whole outbox stays inside the
+ * engine-absorption boundary (#1761): NOT ONE `@tanstack/*` type appears here.
+ *
+ * The sync-apply op/status/reason names mirror
+ * `packages/core/src/sync/apply.ts` (the replay target) verbatim, so a queue row
+ * maps to a batch item and a batch result maps to a state transition with no
+ * translation layer. smrt-web has no inter-smrt dependency (dependency-DAG
+ * guardrails), so these are re-declared here rather than imported from core.
+ */
+/**
+ * Mutation kinds the sync-apply batch endpoint accepts. Mirrors core's
+ * `SyncApplyOp`. The outbox maps the capability seam's insert/update/delete
+ * envelope kinds onto these (`insert → create`).
+ */
+export type SyncApplyOp = 'create' | 'update' | 'delete';
+/**
+ * Per-item outcome status from a sync-apply batch result. Mirrors core's
+ * `SyncApplyStatus`. The engine maps each onto a durable transition per the
+ * contract's "Web outbox (#1762)" consumer notes.
+ */
+export type SyncApplyStatus = 'applied' | 'conflict' | 'rejected';
+/**
+ * Machine-readable reasons a sync-apply item was `conflict` or `rejected`.
+ * Mirrors core's `SyncApplyReason` union. Drives the engine's result mapping:
+ * `auth_required`/`forbidden` pause the loop; `write_failed` retries; the rest
+ * are terminal.
+ */
+export type SyncApplyReason = 'invalid_item' | 'invalid_id' | 'invalid_payload' | 'unknown_object' | 'op_not_allowed' | 'auth_required' | 'forbidden' | 'not_found' | 'id_conflict' | 'write_failed' | 'stale_write' | 'create_conflict';
+/**
+ * One item in a `POST {basePath}/sync/apply` request body. Mirrors core's
+ * `SyncApplyItem`. Built from an {@link OutboxRow} 1:1.
+ */
+export interface SyncApplyItem {
+    itemId: string;
+    object: string;
+    op: SyncApplyOp;
+    id: string;
+    payload?: Record<string, unknown>;
+    baseUpdatedAt?: string;
+}
+/**
+ * One entry in a sync-apply batch response's `results[]`. Mirrors core's
+ * `SyncApplyItemResult`. `results[i]` corresponds to `items[i]` positionally;
+ * `itemId` is echoed for convenience.
+ */
+export interface SyncApplyItemResult {
+    itemId: string | null;
+    id: string | null;
+    status: SyncApplyStatus;
+    reason?: SyncApplyReason;
+    updatedAt?: string;
+}
+/** The HTTP-200 response body of `POST {basePath}/sync/apply`. */
+export interface SyncApplyBatchResponse {
+    results: SyncApplyItemResult[];
+}
+/**
+ * Maximum items the endpoint accepts in one batch (core's
+ * `MAX_SYNC_APPLY_BATCH_SIZE`). The engine chunks a larger backlog into
+ * successive POSTs, oldest-first, so FIFO order is preserved across chunks.
+ */
+export declare const MAX_SYNC_APPLY_BATCH_SIZE = 1000;
+/**
+ * The URL segments of the batch apply endpoint relative to the API base path:
+ * `POST {basePath}/sync/apply` (core's `SYNC_APPLY_ROUTE_SEGMENTS`).
+ */
+export declare const SYNC_APPLY_ROUTE_SEGMENTS: readonly ["sync", "apply"];
+/**
+ * The app-observable sync state of a queued mutation — the SAME four-state
+ * machine the KMP mobile foundation exposes (ADR 0001), so web and mobile
+ * outbox indicators render identically:
+ *
+ * - `pending` — enqueued, awaiting (re)send.
+ * - `uploading` — currently in a sync-apply POST.
+ * - `synced` — the mutation's effect is confirmed on the server (a terminal
+ *   success — INCLUDING a surfaced conflict, which is a RESOLVED outcome: the
+ *   server state won and the item left the queue).
+ * - `failed` — a terminal rejection the client cannot resolve by retrying
+ *   (`invalid_*`, `not_found`, `id_conflict`, `op_not_allowed`, …) — surfaced
+ *   for app-level handling.
+ */
+export type OutboxSyncState = 'pending' | 'uploading' | 'synced' | 'failed';
+/**
+ * A sync-state transition delivered to {@link OfflineOutboxConfig.onSyncStateChange}.
+ * A PUSH callback (not a subscribable store): smrt-svelte wraps it into a
+ * reactive binding later (#1762 follow-on). Carries enough for an app to render
+ * a per-row indicator and a retry affordance.
+ */
+export interface SyncStateEvent {
+    /** The queue row's `itemId` (its idempotency handle) this state is for. */
+    itemId: string;
+    /** The client-generated row UUID the mutation targets. */
+    rowId: string;
+    /** The collection route segment (e.g. `products`). */
+    object: string;
+    /** The new observable state. */
+    state: OutboxSyncState;
+    /** How many replay attempts have run (0 until the first send). */
+    attempts: number;
+    /** The last replay error message, when `state` is `pending` after a retry. */
+    error?: string;
+}
+/**
+ * A conflict surfaced to {@link OfflineOutboxConfig.onConflict} when a replayed
+ * item comes back `conflict`. Per the contract this is a RESOLVED outcome — the
+ * server state won, the item is removed, and its terminal observable state is
+ * `synced` — so an app treats it as "your write was superseded; here is the
+ * server's `updatedAt` to rebase from", NOT as a failure to retry.
+ */
+export interface OutboxConflict {
+    /** The queue row's `itemId`. */
+    itemId: string;
+    /** The collection route segment. */
+    object: string;
+    /** The client-generated row UUID that conflicted. */
+    rowId: string;
+    /**
+     * Why the item conflicted: `stale_write` (an update/delete whose
+     * `baseUpdatedAt` was older than the server row) or `create_conflict` (a
+     * create landing on an existing, diverged row).
+     */
+    reason: 'stale_write' | 'create_conflict';
+    /**
+     * The server row's `updated_at` after processing — the value to persist as
+     * the new `baseUpdatedAt` before re-editing. Present when the endpoint
+     * returned it.
+     */
+    serverUpdatedAt?: string;
+}
+/**
+ * One queued write handed to a consumer-declared {@link OutboxCommandTransport}
+ * at replay time (#3021). The transport replays it through a server operation
+ * the consumer owns — a data-surface action, a named remote command, a
+ * hand-written permission-gated service — instead of the generated
+ * `sync/apply`, which calls `collection.create()` directly.
+ */
+export interface OutboxCommand {
+    /**
+     * The durable, client-minted idempotency key (the queue row's `itemId`). It
+     * is IDENTICAL on every attempt of this write — including a blind resend
+     * after a lost response — so the server operation MUST dedupe on it; that is
+     * what makes the outbox's ambiguous-failure retries safe on this path.
+     */
+    idempotencyKey: string;
+    /** The transport name the write was queued under. */
+    name: string;
+    /** The mutation kind in sync-apply terms. */
+    op: SyncApplyOp;
+    /** The client-generated row id the write targets. */
+    rowId: string;
+    /** Row / changed fields (create, update); absent for delete. */
+    payload?: Record<string, unknown>;
+    /** The server `updated_at` the client last saw, when the caller supplied one. */
+    baseUpdatedAt?: string;
+    /** 1-based number of this attempt (`1` on the first send). */
+    attempt: number;
+    /** The value this write's transport pinned on an earlier attempt, if any. */
+    pinned?: unknown;
+    /**
+     * Durably pin a structured-clone-safe value to this write before sending,
+     * so a later attempt (including after a reload) sees it as `pinned`. A
+     * transport whose server fingerprints the request per idempotency key pins
+     * the request it built, so a resend after a lost response is identical.
+     */
+    pin(value: unknown): Promise<void>;
+}
+/**
+ * The server's outcome for one {@link OutboxCommand}, in the SAME vocabulary
+ * the sync-apply replay maps — so the four-state machine and backoff are
+ * shared, not re-derived:
+ *
+ * - `applied` → removed, `synced`.
+ * - `conflict` → removed, `onConflict` fired, `synced` (a RESOLVED outcome).
+ * - `rejected` with `write_failed` → kept, backoff, `pending` (retryable).
+ * - `rejected` with `auth_required` / `forbidden` → the whole loop pauses until
+ *   re-auth (a later enqueue or `retry()`), kept `pending`.
+ * - `rejected` with any other reason → removed, `failed` (terminal).
+ *
+ * A transport that THROWS (network error, lost response, 5xx) is the ambiguous
+ * path: the write stays `pending` with backoff and is blindly resent later
+ * under the same {@link OutboxCommand.idempotencyKey}.
+ */
+export type OutboxCommandResult = {
+    status: 'applied';
+    updatedAt?: string;
+} | {
+    status: 'conflict';
+    reason?: 'stale_write' | 'create_conflict';
+    updatedAt?: string;
+} | {
+    status: 'rejected';
+    reason: SyncApplyReason | (string & {});
+};
+/** Replays one queued write through a consumer-declared server operation. */
+export type OutboxCommandTransport = (command: OutboxCommand) => Promise<OutboxCommandResult>;
+/** Exponential-backoff tuning for retryable replay failures. */
+export interface OutboxBackoff {
+    /** Delay before the first retry, ms (default 1000). */
+    initialDelayMs?: number;
+    /** Multiplier applied per attempt (default 2). */
+    multiplier?: number;
+    /** Ceiling on the computed delay, ms (default 60000). */
+    maxDelayMs?: number;
+}
+/** Resolved backoff config (defaults filled in). */
+export interface ResolvedBackoff {
+    initialDelayMs: number;
+    multiplier: number;
+    maxDelayMs: number;
+}
+/** Backoff defaults, per the blueprint (initial=1s, ×2, cap 60s). */
+export declare const DEFAULT_BACKOFF: ResolvedBackoff;
+/**
+ * Compute the backoff delay before the NEXT attempt given how many attempts
+ * have already been made. Exponential with a ceiling, then multiplied by a
+ * jitter factor in `[0.5, 1.0)` to spread a thundering herd of tabs/rows
+ * reconnecting at once: `min(maxDelay, initial * mult ** attempts) * jitter`.
+ *
+ * `attempts` is the count BEFORE this retry (so the first retry, after attempts
+ * became 1, uses `initial * mult ** 1`? no — see below). We pass the attempt
+ * count AFTER incrementing, and index the exponent off `attempts - 1` so the
+ * first retry waits ~`initialDelayMs`. `random` is injectable for deterministic
+ * tests.
+ */
+export declare function computeBackoffDelay(attempts: number, backoff: ResolvedBackoff, random?: () => number): number;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/offline.d.ts

@@ -0,0 +1,258 @@
+/**
+ * @happyvertical/smrt-web — the durable offline outbox capability (#1762).
+ *
+ * The web twin of the KMP mobile write queue: mutations against opted-in
+ * collections are captured in a durable browser-side outbox (IndexedDB) that
+ * survives reloads and crashes, then replayed FIFO against the idempotent
+ * sync-apply batch contract when connectivity returns, with exponential-backoff
+ * retries. Because items carry client-generated UUIDs and the endpoint is
+ * idempotent (`_insertOnly` create + no-op re-apply), blind retries after an
+ * ambiguous failure (request sent, response lost) can never duplicate rows — see
+ * the "Idempotency" section of docs/content/architecture/sync-apply-contract.md.
+ *
+ * This is a {@link SmrtWebCapability} plug-in, so it lives in its OWN module and
+ * an app opts a collection in by passing `offlineOutbox(config)` in that
+ * collection's `capabilities` array. A collection WITHOUT it is byte-for-byte
+ * the collection of today (the seam's no-op guarantee), which is exactly the
+ * "offline is opt-in per model" acceptance criterion.
+ *
+ * ## How it plugs into the seam
+ *
+ * - `wrapMutation(envelope, ctx)` — BEFORE the fetcher, it enqueues the write
+ *   durably and returns `{ handled: true, result: envelope.data }`. The factory
+ *   then SUPPRESSES the post-mutation refetch + `invalidateRelated()` (its
+ *   `{ refetch: false }` path), so the optimistic row the app just inserted
+ *   STANDS instead of being dropped by a refetch of a server list that has never
+ *   seen the offline write. If the durable queue is unavailable, it returns
+ *   `{ handled: false }` so the normal fetcher path runs instead of silently
+ *   acknowledging a non-durable write. A handled write never touches
+ *   `ctx.fetchers.create` — it replays ONLY through `sync/apply`, which is
+ *   load-bearing: the normal REST create strips the client id (#1540) and would
+ *   mint a NEW server id, orphaning the optimistic row; sync/apply's
+ *   strict-insert path preserves the client UUID (#1540, #1540's
+ *   mass-assignment guard on the sync path).
+ * - `onAttach(ctx)` — attaches this collection to the shared, namespace-keyed
+ *   {@link OutboxEngine} (ref-counted so N collections share ONE engine / IDB
+ *   db / leader lock / FIFO queue).
+ * - `teardown(ctx)` — detaches; the last detach disposes the engine (the durable
+ *   ROWS survive for the next load).
+ *
+ * ## Observable state (push callbacks, not a store)
+ *
+ * Per-mutation sync state — `pending → uploading → synced` (and `→ failed` /
+ * conflict) — is delivered through {@link OfflineOutboxConfig.onSyncStateChange}
+ * and {@link OfflineOutboxConfig.onConflict}, PUSH callbacks matching the KMP
+ * foundation's `pending/uploading/synced/failed` state machine. This is
+ * deliberately not a subscribable store: smrt-svelte wraps it into a reactive
+ * binding in a later slice. Programmatic access to the durable queue is via
+ * {@link getOutboxHandle} (a bridge like `getEngineCollection`).
+ *
+ * ## Known gap (this slice's scope)
+ *
+ * The outbox does NOT rehydrate the READ cache after a reload — a reloaded tab's
+ * `collection.toArray()` will NOT show captured-offline rows until a fetch runs;
+ * that read-side rehydrate is #1764's `warmStart`. So the outbox's durability is
+ * proven via {@link OutboxHandle.snapshot} / the raw IndexedDB store, NOT via
+ * `collection.toArray()`. The WRITE side (capture → durable → exactly-once
+ * replay) is complete here.
+ *
+ * Engine-free public surface: no `@tanstack/*` type appears — inside the
+ * engine-absorption boundary (#1761), verified by
+ * scripts/check-smrt-web-engine-boundary.mjs.
+ */
+import type { SmrtWebCapability } from './capability.js';
+import { type DurableStoreKey } from './durable-store.js';
+import { type OutboxBackoff, type OutboxCommandTransport, type OutboxConflict, type SyncApplyOp, type SyncStateEvent } from './offline/types.js';
+export type { OutboxBackoff, OutboxCommand, OutboxCommandResult, OutboxCommandTransport, OutboxConflict, OutboxSyncState, SyncStateEvent, } from './offline/types.js';
+/**
+ * Configuration for {@link offlineOutbox}. Generic in the collection's row type
+ * `TData` so the capability matches the collection it plugs into.
+ */
+export interface OfflineOutboxConfig<TData extends object = object> {
+    /**
+     * The generated collection definition this outbox serves — its `name` is the
+     * sync-apply `object` route segment, so it MUST be the SAME definition passed
+     * to {@link createSmrtCollection}. (Named `object` to mirror the capability
+     * context; carries the collection's REST route segment.)
+     */
+    object: {
+        name: string;
+        _row?: TData;
+    };
+    /**
+     * The durable-store identity this outbox's queue is namespaced under — folds
+     * api base / tenant / identity / manifest hash, so a logout or tenant switch
+     * lands on a different IndexedDB database (never cross-identity reuse). Shared
+     * with #1764's persistence slice via the same {@link durableStoreNamespace}.
+     * `manifestHash` is opaque caller-supplied config for #1762; its canonical
+     * source is #1764's call (a schema-shape digest) — comment your call site.
+     */
+    namespace: DurableStoreKey;
+    /**
+     * API base path the sync-apply endpoint lives under (`POST
+     * {syncApplyBasePath}/sync/apply`). Defaults to `/api/v1`, matching the REST
+     * generator's default. Set to the SvelteKit route base (`/api`) when replaying
+     * against the generated SvelteKit `sync/apply/+server.ts`. Ignored when
+     * {@link transport} is set.
+     */
+    syncApplyBasePath?: string;
+    /**
+     * Replay this collection's queued writes through a consumer-declared server
+     * operation instead of the generated `sync/apply` (#3021) — for a model whose
+     * generated write verbs are closed because a hand-written, permission-gated
+     * service owns its write rules. Rows are queued under `object.name` and replay
+     * ONLY through this transport (never `sync/apply`), each carrying its durable
+     * `idempotencyKey`, with the same four-state machine, per-route FIFO, and
+     * backoff.
+     * See {@link offlineCommandQueue} for writes with no collection at all.
+     */
+    transport?: OutboxCommandTransport;
+    /** Fetch implementation override (tests, SSR). Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+    /** Exponential-backoff tuning for retryable replay failures. */
+    backoff?: OutboxBackoff;
+    /**
+     * Called on every observable sync-state transition of a captured mutation
+     * (`pending → uploading → synced`, `→ failed`, and the `pending` re-arm after
+     * a retryable failure). A push callback; smrt-svelte turns it into a reactive
+     * binding later.
+     */
+    onSyncStateChange?: (event: SyncStateEvent) => void;
+    /**
+     * Called when a replayed mutation comes back `conflict` — a RESOLVED outcome
+     * (server state won; the item leaves the queue with terminal state `synced`).
+     * Persist `serverUpdatedAt` as the new `baseUpdatedAt`, refetch the row, and
+     * surface the conflict to the user as appropriate.
+     */
+    onConflict?: (conflict: OutboxConflict) => void;
+    /** Test-only: inject a deterministic RNG for backoff jitter. */
+    random?: () => number;
+}
+/**
+ * A programmatic handle to one namespace's outbox — the bridge pattern (like
+ * `getEngineCollection`) for trusted callers (an app's outbox panel, a
+ * smrt-svelte binding, tests). Fetched via {@link getOutboxHandle}.
+ */
+export interface OutboxHandle {
+    /**
+     * A read-only snapshot of the durable queue (every state). The way to prove
+     * durability after a reload, since this slice does not rehydrate the read
+     * cache (that's #1764).
+     */
+    snapshot(): Promise<OutboxSnapshotItem[]>;
+    /**
+     * Force a retry of a specific queued item now (clears its backoff gate, wakes
+     * the loop, and clears an auth pause). A no-op for an item no longer queued.
+     */
+    retry(itemId: string): Promise<void>;
+}
+/** One item in an {@link OutboxHandle.snapshot} result. */
+export interface OutboxSnapshotItem {
+    /** The transport name, when the item replays through one (#3021). */
+    transport?: string;
+    /** The queue row's idempotency handle. */
+    itemId: string;
+    /** The collection route segment. */
+    object: string;
+    /** The mutation kind, in sync-apply terms. */
+    op: 'create' | 'update' | 'delete';
+    /** The client-generated row UUID. */
+    rowId: string;
+    /** The on-disk lifecycle state. */
+    state: 'pending' | 'synced' | 'failed';
+    /** Replay attempts so far. */
+    attempts: number;
+    /** Epoch ms before which this row won't be retried (backoff). */
+    nextAttemptAt: number;
+    /** Last replay error, if any. */
+    lastError?: string;
+}
+/**
+ * Build a durable offline-outbox capability for a collection. Add the returned
+ * capability to the collection's `capabilities` array; a collection without it
+ * is unaffected (the seam's no-op guarantee — the "opt-in per model" AC).
+ *
+ * The same `namespace` across multiple collections shares ONE engine (one IDB
+ * db, one queue) — so cross-collection ordering and the multi-tab
+ * single-replayer guarantee hold across every sync-apply collection of a given
+ * identity (one route). A collection with a `transport` is its own route.
+ */
+export declare function offlineOutbox<TData extends object = object>(config: OfflineOutboxConfig<TData>): SmrtWebCapability<TData>;
+/** Configuration for {@link offlineCommandQueue}. */
+export interface OfflineCommandQueueConfig {
+    /**
+     * The queue's name — the key queued writes are stored and routed under. It
+     * shares the namespace's durable queue and per-object event routing with
+     * every collection outbox, so it MUST NOT equal a sibling collection's
+     * `definition.name` (their events would cross). Durable: a write queued under a name replays only once a queue
+     * with that name (and a transport) is attached again, e.g. after a reload.
+     */
+    name: string;
+    /** The durable-store identity — the SAME key the app's other outboxes use. */
+    namespace: DurableStoreKey;
+    /** Replays each queued write through the consumer's own server operation. */
+    transport: OutboxCommandTransport;
+    /** Exponential-backoff tuning for retryable replay failures. */
+    backoff?: OutboxBackoff;
+    /** Push callback for every sync-state transition (see {@link offlineOutbox}). */
+    onSyncStateChange?: (event: SyncStateEvent) => void;
+    /** Push callback for a `conflict` outcome (a RESOLVED outcome). */
+    onConflict?: (conflict: OutboxConflict) => void;
+    /** Test-only: inject a deterministic RNG for backoff jitter. */
+    random?: () => number;
+}
+/** One write for {@link OfflineCommandQueue.enqueue}. */
+export interface OfflineCommandInput {
+    /** Command arguments — structured-clone-safe; persisted verbatim. */
+    payload?: Record<string, unknown>;
+    /** The row the write targets, when there is one. Defaults to the item id. */
+    rowId?: string;
+    /** Mutation kind, passed through to the transport. Defaults to `create`. */
+    op?: SyncApplyOp;
+    /** The server `updated_at` last seen, passed through to the transport. */
+    baseUpdatedAt?: string;
+}
+/** A durable queue of consumer-declared server operations (#3021). */
+export interface OfflineCommandQueue {
+    /**
+     * Durably queue one write and kick replay. Resolves to its idempotency key
+     * once the write is committed to IndexedDB, or `undefined` when the durable
+     * queue is unavailable (no IndexedDB) or the queue was disposed — the write
+     * was NOT captured, so the caller must perform it online itself or surface
+     * the failure; it is never acknowledged non-durably.
+     */
+    enqueue(input: OfflineCommandInput): Promise<string | undefined>;
+    /** The namespace's durable queue (every route), like {@link OutboxHandle}. */
+    snapshot(): Promise<OutboxSnapshotItem[]>;
+    /** Force a retry of a queued item now (clears backoff and an auth pause). */
+    retry(itemId: string): Promise<void>;
+    /** Detach. Queued writes stay on disk and replay on the next attach. */
+    dispose(): Promise<void>;
+}
+/**
+ * A durable offline queue for writes that go through a consumer-declared
+ * server operation — a data-surface action, a named remote command, a
+ * permission-gated service — rather than a generated collection (#3021).
+ *
+ * Shares the namespace's outbox engine with every {@link offlineOutbox}: one
+ * IndexedDB queue, a cross-tab leader per route, FIFO within the route, the
+ * `pending → uploading → synced | failed` state machine, backoff, auth pause,
+ * and the `wipeDurableStore` registration. Each replay carries the write's
+ * durable `idempotencyKey`, which the server operation must dedupe on — that
+ * is what makes a blind resend after a lost response safe.
+ *
+ * Attaches immediately; call `dispose()` when the owning view unmounts.
+ */
+export declare function offlineCommandQueue(config: OfflineCommandQueueConfig): OfflineCommandQueue;
+/**
+ * Retrieve the programmatic {@link OutboxHandle} for a durable-store namespace,
+ * or `undefined` if no opted-in collection is currently attached under it. The
+ * bridge for trusted callers (outbox UI, smrt-svelte binding, tests) to read the
+ * durable queue and force retries. Pass the SAME
+ * `durableStoreNamespace(config.namespace)` string the capability used.
+ *
+ * Mirrors the `getEngineCollection` bridge convention: an escape hatch that
+ * returns a narrow SMRT-owned surface rather than the engine itself.
+ */
+export declare function getOutboxHandle(namespace: string): OutboxHandle | undefined;
+//# sourceMappingURL=offline.d.ts.map

package/dist/offline.d.ts.map

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

package/dist/persistence/snapshot-store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @happyvertical/smrt-web — the durable collection snapshot store (#1764).
+ *
+ * The read-side twin of the offline outbox's write queue: a raw IndexedDB store
+ * that persists ONE blob per (namespace, collection) — the collection's last
+ * known rows — so a reload can warm-start (render stale instantly) before the
+ * engine revalidates in the background. One database per durable-store namespace
+ * ({@link durableStoreNamespace}), one object store (`snapshots`) keyed by the
+ * collection name, each record `{ collection, rows }`.
+ *
+ * ## Why raw IndexedDB, mirroring offline/durable-queue.ts
+ *
+ * Same decisive finding as #1762's outbox: the TanStack persistence layer's
+ * public API is engine-typed, so importing it would emit a `@tanstack/`
+ * specifier into a `.d.ts` and fail `scripts/check-smrt-web-engine-boundary.mjs`.
+ * So persistence is hand-rolled over `indexedDB` with ZERO new runtime
+ * dependency and stays inside the engine-absorption boundary (#1761) — this
+ * module speaks only plain rows, never an engine type.
+ *
+ * Rows are stored as structured-clone-safe plain objects (the public DTOs the
+ * factory already projects); IndexedDB clones on write, so callers may keep
+ * mutating the source array after a save.
+ *
+ * The namespace already folds api base / tenant / identity / manifest hash (see
+ * {@link durableStoreNamespace}), so a logout, tenant switch, or contract-
+ * changing deploy lands on a DIFFERENT database — a stale-schema snapshot is
+ * simply never found (the read returns nothing and the engine fetches fresh),
+ * which is exactly the "manifest-hash change drops persisted caches" guarantee
+ * without any explicit invalidation.
+ */
+/** IndexedDB object-store name inside every snapshot database. */
+export declare const SNAPSHOT_STORE = "snapshots";
+/** IndexedDB schema version. Bump only on a store/index migration. */
+export declare const SNAPSHOT_DB_VERSION = 1;
+/**
+ * Suffix appended to the durable-store namespace to form this store's OWN
+ * IndexedDB database name. Distinct DBs per store are REQUIRED for correctness:
+ * the merged outbox (#1762) already opens the BARE namespace as a v1 database
+ * with only its `outbox` object store. If persistence opened the same bare
+ * namespace at v1, whichever store opened SECOND would find the existing v1 DB,
+ * `onupgradeneeded` would NOT fire, and `objectStore('snapshots')` would throw
+ * `NotFoundError` — silently disabling persistence (or the outbox). A distinct
+ * DB name sidesteps the collision entirely; `wipeDurableStore` still clears both
+ * because it fans out via each registered resource's `clear()`, never by DB name.
+ */
+export declare const SNAPSHOT_DB_SUFFIX = "::snapshots";
+/** One persisted collection snapshot record. */
+export interface SnapshotRecord {
+    /** The REST collection name — the store key. */
+    collection: string;
+    /** The rows last seen for this collection (plain public DTOs). */
+    rows: Array<Record<string, unknown>>;
+}
+/**
+ * Feature-detect a usable IndexedDB. Some environments expose `indexedDB` but
+ * throw on `open()` (private-mode Firefox historically, sandboxed iframes), so a
+ * real probe opens a throwaway database. Returns `false` rather than throwing so
+ * the persistence capability can degrade to non-persistent instead of crashing
+ * the host — matching the outbox's `probeIndexedDb()` posture.
+ */
+export declare function probeIndexedDb(): Promise<boolean>;
+/**
+ * The durable snapshot store over one IndexedDB database. Constructed via
+ * {@link openSnapshotStore} (async open + schema upgrade), then used through the
+ * async methods below (each resolves once its txn commits).
+ *
+ * One store backs EVERY opted-in collection under a namespace, each keyed by its
+ * collection name — so N persisted collections of one identity share one
+ * database (like the outbox's shared queue), and the durable-store `clear()`
+ * wipes them all at once.
+ */
+export declare class SnapshotStore {
+    private readonly db;
+    /** The IndexedDB database name (== the durable-store namespace). */
+    readonly dbName: string;
+    constructor(db: IDBDatabase, dbName: string);
+    /**
+     * Read the persisted rows for `collection`, or `undefined` if none were ever
+     * saved (or the record is malformed). `undefined` is the warm-start "nothing
+     * on disk" signal — the engine then fetches fresh.
+     */
+    load(collection: string): Promise<Array<Record<string, unknown>> | undefined>;
+    /**
+     * Write (replacing) the snapshot for `collection`. Resolves once the write is
+     * durably committed. A single blob per collection — the whole current row set,
+     * not a delta — so a restore is one read with no reconciliation.
+     */
+    save(collection: string, rows: Array<Record<string, unknown>>): Promise<void>;
+    /**
+     * Drop the snapshot for a single `collection` (its capability's own teardown
+     * does NOT clear — the persisted rows must survive for the next load; this is
+     * only for an explicit targeted purge). Kept for completeness / tests.
+     */
+    remove(collection: string): Promise<void>;
+    /**
+     * Drop EVERY snapshot — the durable-store `clear()` for `wipeDurableStore`.
+     * Empties the store but keeps the database so a subsequent save still works.
+     */
+    clear(): Promise<void>;
+    /** Close the underlying database handle (called on the last detach). */
+    close(): void;
+}
+/**
+ * Open (creating/upgrading as needed) the snapshot database for `namespace` and
+ * wrap it in a {@link SnapshotStore}. `namespace` MUST be a
+ * {@link durableStoreNamespace} string — already `encodeURIComponent`-safe and
+ * carrying the api/tenant/identity/manifest isolation boundary, so two
+ * identities never share one snapshot database.
+ *
+ * The actual IndexedDB database name is `${namespace}${SNAPSHOT_DB_SUFFIX}` — a
+ * DISTINCT database from the merged outbox's bare-namespace one, so persistence +
+ * outbox under a shared namespace never collide on a single-store v1 DB (see
+ * {@link SNAPSHOT_DB_SUFFIX}).
+ *
+ * The `onupgradeneeded` handler creates the `snapshots` store keyed by
+ * `collection`. Idempotent: re-opening an existing database at the same version
+ * skips the upgrade — the reload path (a new tab re-opens the same durable
+ * backing and sees prior snapshots).
+ */
+export declare function openSnapshotStore(namespace: string): Promise<SnapshotStore>;
+//# sourceMappingURL=snapshot-store.d.ts.map

package/dist/persistence/snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-store.d.ts","sourceRoot":"","sources":["../../src/persistence/snapshot-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,kEAAkE;AAClE,eAAO,MAAM,cAAc,cAAc,CAAC;AAC1C,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtC;AA8BD;;;;;;GAMG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAsBvD;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAc;IACjC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM;IAK3C;;;;OAIG;IACG,IAAI,CACR,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAYtD;;;;OAIG;IACG,IAAI,CACR,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;OAIG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,wEAAwE;IACxE,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA8B3E"}