@helipod/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+import { P as PendingMutation, a as PoisonPolicy, O as OutboxLockManager, C as ClientTransport } from './client-mJZjEkhK.js';
+export { A as AUTH_REFRESH_UDF_PATH, b as AnyFunctionRef, c as AnyFunctionReference, d as ClientResetInfo, D as DEFAULT_DRAIN_CHUNK_SIZE, e as DEFAULT_DRAIN_INTERVAL_MS, f as DrainHost, F as FunctionArgs, g as FunctionReference, h as FunctionReturnType, H as HelipodClient, L as LoopbackLike, M as MutationFailedInfo, N as NON_REPLAYABLE_MUTATION_DROPPED, i as OFFLINE_IDENTITY_CHANGED, j as OptimisticLocalStore, k as OptimisticStoreView, l as OptimisticUpdate, m as OptimisticUpdateFn, n as OutboxBroadcastLike, o as OutboxBroadcastMessage, p as OutboxDrain, q as OutboxDrainOptions, r as PendingMutationEntry, s as PendingSummary, Q as QueryErrorListener, t as QueryListener, R as RefArgs, u as RefReturn, W as WebSocketTransportOptions, v as anyApi, w as computeDrainBackoff, x as createOptimisticLocalStore, y as getFunctionPath, z as loopbackTransport, B as reconnectDelayMs, E as webSocketTransport } from './client-mJZjEkhK.js';
+import { O as OutboxEntry, a as OutboxStorage } from './outbox-storage-C6VHkXs9.js';
+export { D as DEFAULT_OUTBOX_MAX_QUEUE_SIZE, H as HydrateResult, I as IndexedDBOutboxOptions, b as OfflineClientResetError, c as OutboxEntryError, d as OutboxEntryStatus, e as OutboxMeta, f as OutboxOverflowError, g as defaultMintClientId, i as indexedDBOutbox, m as memoryOutbox, h as mintIdentity } from './outbox-storage-C6VHkXs9.js';
+import { ClientMutationRef, ClientMessage } from '@helipod/sync';
+export { mintEncodedDocumentId as mintDocumentId } from '@helipod/id-codec';
+import '@helipod/values';
+
+/**
+ * The IndexedDB-backed `OutboxStorage` (verdict §(d) decision 8, `docs/dev/research/offline-outbox/
+ * verdict.md`). ONE database, `helipod-outbox` — the whole seam (the shared mutation queue AND
+ * per-clientId identity) lives together so an origin eviction takes BOTH atomically. That is
+ * verdict §(g) hazard 1 ("whole-origin eviction... co-evict — one database") pinned structurally:
+ * there is no separate identity store to fall out of sync with the queue, because there is only
+ * one store to begin with.
+ *
+ * Schema (v1):
+ *  - `entries` — keyPath `["clientId", "seq"]` (the durable identity pair, verdict §(b)'s governing
+ *                invariant: `(clientId, seq) -> payload` written exactly once); index `order`
+ *                (drain FIFO across the WHOLE shared queue, every clientId); index `status`
+ *                (candidate scans — e.g. everything still `unsent`/`inflight` — consumed from a
+ *                later task onward).
+ *  - `meta`    — keyPath `"clientId"`; one row per clientId, `{clientId, nextSeq, deployment}`.
+ *
+ * Write-behind: every mutating call (`append`/`updateStatus`/`dequeue`/`setMeta`) enqueues a
+ * pending op and schedules (once) a microtask flush that opens ONE `readwrite` transaction across
+ * both stores and applies every op queued since the last flush, in call order. Callers that fire
+ * several appends synchronously in the same microtask turn get ONE transaction, not N.
+ */
+
+/** Bump when the persisted entry shape changes incompatibly. A hydrate that finds an entry
+ *  stamped with a different version DROPS it (verdict §(g) hazard 10) — never runs it, never
+ *  guesses a migration. */
+declare const OUTBOX_VERSION = 1;
+
+/**
+ * S4 — `DeliveryPolicy`. Routes transport lifecycle events (v1: only *close*) into log
+ * transitions. The v1 policy is verdict §(c) event 6 verbatim: at close, NO optimistic layer of
+ * any kind survives into a new session (the ts-gate is only sound over a feed whose ts is
+ * monotone for THIS client, and a reconnect's resubscribe baseline arrives with the fresh
+ * session's ts — carrying a completed layer across would replay it on top of its own echo).
+ *
+ *  - `unsent`   → **retained** (never hit the wire; safe to (re)send on reconnect — T6).
+ *  - `inflight` → the promise **rejects** with `MutationUndeliveredError` and its layer **drops**
+ *                 (outcome genuinely unknowable — no server dedup exists; a blind resend would
+ *                 double-apply) — UNLESS the S4 swap is `armed` AND this entry's durable append
+ *                 has already committed, in which case it **parks** instead (Task 2): the promise
+ *                 stays PENDING (a future drain resolves it under its recorded `(clientId, seq)`),
+ *                 while its layer still drops (the no-layer-crosses-a-session rule is unchanged).
+ *  - `completed`→ already resolved at `MutationResponse` (D3); its layer **drops** too.
+ *  - `parked`   → already parked by an earlier close, with no drain yet built to resend it
+ *                 (T2's honest boundary — T4 owns the drain): left exactly as is.
+ */
+
+/**
+ * Rejection for a mutation whose outcome is unknowable because the transport dropped before its
+ * `MutationResponse` arrived. Typed so apps can distinguish "the server rejected this" (a plain
+ * `Error` from the handler) from "we never learned what happened" (retry is unsafe — there is no
+ * server-side dedup yet). The message deliberately contains "connection closed".
+ */
+declare class MutationUndeliveredError extends Error {
+    constructor(message?: string);
+}
+
+/**
+ * Shared identity-fingerprint primitives for the durable outbox (verdict §(d) hazard 9 / spec
+ * §(k)7). `client.ts`'s live `setAuth`/`setSessionFingerprint` and `headless-drain.ts`'s one-shot
+ * `drainOutboxOnce` must compute the EXACT SAME `identityFingerprint` for the same underlying
+ * identity, or the two never agree — a durable entry stamped by a live tab under a managed
+ * session's `sessionFingerprintKey` hash would otherwise look "foreign" to the headless drain's own
+ * differently-formatted hash and terminal-fail with `OFFLINE_IDENTITY_CHANGED` even though nothing
+ * about the identity actually changed. One shared module, not two hand-synced copies, is how that's
+ * kept impossible by construction.
+ */
+/** SHA-256 hex digest of `input`. */
+declare function sha256Hex(input: string): Promise<string>;
+/** The string a managed `createAuthClient` session's outbox fingerprint hashes (never the raw
+ *  `sessionId` alone) — `client.ts#setSessionFingerprint` and `headless-drain.ts`'s `getSessionId`
+ *  option both route through this ONE function so the "session:" prefix convention can never drift
+ *  between the two call sites (spec decision 9). */
+declare function sessionFingerprintKey(sessionId: string): string;
+
+/**
+ * The `Connect` resume handshake's pure computation (verdict §(c) event 6, §(e)) — `held` (every
+ * durable `(clientId, seq)` still awaiting a verdict) and `ackedThrough` (the contiguous
+ * settled-prefix per clientId, for server-side retention pruning), plus the wire message itself.
+ *
+ * Extracted from `client.ts` (T3) so a SECOND caller with no `HelipodClient` can send the SAME
+ * handshake shape — the headless drain (`headless-drain.ts`, the Background Sync seam). A Service
+ * Worker has no live in-memory `MutationLog`, only the durable `OutboxStorage` rows, so
+ * {@link outboxHeldFromStore} computes `held` straight from those instead of a live
+ * `PendingMutation` log ({@link outboxHeldFromLog}, `HelipodClient`'s own source). Both feed the
+ * SAME {@link outboxAckedThrough}/{@link buildConnectMessage} — the wire shape is identical either
+ * way, only the source of `held` differs.
+ */
+
+/** `held` from a LIVE `HelipodClient`'s in-memory log — every entry with a recorded `(clientId,
+ *  seq)` whose status is still unsettled. */
+declare function outboxHeldFromLog(entries: Iterable<PendingMutation>): ClientMutationRef[];
+/** `held` from a store-only host (the headless drain — no live log, only persisted rows) — the same
+ *  three statuses, read straight off the persisted `OutboxEntry.status` (identical strings, identical
+ *  meaning, to the live `PendingMutation.status.type` above). */
+declare function outboxHeldFromStore(entries: Iterable<OutboxEntry>): ClientMutationRef[];
+/** The highest CONTIGUOUS settled-prefix seq per clientId (verdict §(c) Retention / spec decision
+ *  3). Under the FIFO one-unacked-chunk drain a seq can never settle past an unsettled earlier one,
+ *  so for each clientId the settled prefix is exactly `(lowest still-held seq) - 1`; a clientId
+ *  whose lowest held seq is 0 has acked nothing and is omitted. */
+declare function outboxAckedThrough(held: ClientMutationRef[]): ClientMutationRef[];
+/** Build the `Connect` resume handshake wire message. `sessionId` is a fresh per-connect id (the
+ *  server routes the handshake by the transport-level session, so this field is only
+ *  informational); `clientId` is likewise informational server-side — `handleConnect` classifies
+ *  purely off each `held`/`ackedThrough` entry's OWN `clientId`/`seq` pair, never the top-level
+ *  field — so a caller whose held set spans several prior tab-sessions' clientIds (the headless
+ *  drain) can safely omit it. */
+declare function buildConnectMessage(sessionId: string, clientId: string | undefined, held: ClientMutationRef[]): Extract<ClientMessage, {
+    type: "Connect";
+}>;
+
+interface HeadlessDrainOptions {
+    /** The ws(s) sync endpoint. Ignored when `_transport` is injected (tests). */
+    url: string;
+    /** Defaults to `indexedDBOutbox()` — IndexedDB exists in a Service Worker just as it does in a
+     *  tab, so the SAME durable queue a live client wrote is readable here with no extra plumbing. */
+    outbox?: OutboxStorage;
+    /** Distinguishes the drain's Web Locks name per deployment, matching a live client's own
+     *  `outboxDeployment` constructor option (`client.ts:320`'s naming) — MUST agree with whatever a
+     *  live tab configured, or the two will never contend for the same lock. Defaults to `"default"`. */
+    deployment?: string;
+    /** SW-readable auth (the app owns SW-readable token storage — this function only documents the
+     *  constraint, it does not build one). Replayed as `SetAuth` BEFORE `Connect`, exactly as a
+     *  reconnecting `HelipodClient` replays its last-set token. */
+    getAuthToken?: () => Promise<string | null>;
+    /** For a `createAuthClient`-managed session (spec decision 9): resolve the PERSISTED
+     *  `SessionInfo.sessionId` so this drain computes the outbox `identityFingerprint` the exact same
+     *  way a live tab's `setSessionFingerprint` does (`sha256Hex(sessionFingerprintKey(sessionId))`,
+     *  never a token hash) — otherwise every entry a managed session stamped looks "foreign" here and
+     *  terminal-fails with `OFFLINE_IDENTITY_CHANGED` on every headless drain, composition the live
+     *  client never hits. Read the SAME storage row the auth client persists to — by default
+     *  `SESSION_STORAGE_KEY` (`"helipod.session"`, exported from `auth-client.ts`) in `localStorage`,
+     *  or wherever a custom `SessionStorage`/`localStorageSession(key)` was configured to write it; a
+     *  Service Worker reads it via `clients.matchAll()`-relayed message, a mirrored IndexedDB copy, or
+     *  any other SW-reachable channel the app wires up — this function only documents the contract, it
+     *  does not build the plumbing. When this resolves to a non-null id, it takes priority over
+     *  `getAuthToken`'s token-hash fingerprint (which still governs `SetAuth` on the wire); omit it (or
+     *  resolve `null`) for a client that never adopted a managed session — the token-hash fingerprint
+     *  (or `"anon"`) applies exactly as before this option existed. */
+    getSessionId?: () => Promise<string | null>;
+    /** How a coded (terminal, server-recorded) failure is handled — `"skip"` (default: settle
+     *  terminally and continue) or `"pause"` (halt the whole drain and surface via `onPause`).
+     *
+     *  Prefer the default `"skip"` in headless contexts (a Service Worker's `sync` handler, a cron-like
+     *  invocation, etc.) — there is no live UI here to observe an `onPause` callback and call `resume()`
+     *  on the drain's behalf, so a paused drain just sits paused until some LATER invocation happens to
+     *  clear it. Worse, `"pause"` combined with a below-floor `STALE_CLIENT` verdict can livelock: the
+     *  reset path re-queues the stale entry (`revertActive`), the next invocation re-flushes it, the
+     *  server replies `STALE_CLIENT` again, and the drain re-pauses on the SAME entry every single run
+     *  — with nothing headless to break the cycle. `"skip"` settles it terminally (once) instead and
+     *  moves on. */
+    poisonPolicy?: PoisonPolicy;
+    /** The whole-drain wall-clock budget — after this the socket is closed and the current counts are
+     *  returned, whatever state the drain is in. Default 30 000ms. */
+    timeoutMs?: number;
+    /** The Web Locks manager — `undefined` probes the ambient `navigator.locks`, `null` forces
+     *  single-tab (no contention check at all — ALWAYS drains), an object is used directly (tests
+     *  inject a fake). Mirrors `OutboxDrainOptions.locks`. */
+    locks?: OutboxLockManager | null;
+    /** @internal test seam — inject a transport instead of opening a real WebSocket. Kept
+     *  underscore-internal: not part of the documented public surface. */
+    _transport?: ClientTransport;
+}
+/**
+ * Drain the durable outbox once: connect, hand `Connect`+`MutationBatch` traffic to the SAME
+ * {@link OutboxDrain} state machine a live tab uses, and resolve once the queue is empty/terminal
+ * or `timeoutMs` elapses — whichever comes first. Safe to call from a Service Worker's `sync` event
+ * handler inside `event.waitUntil(...)`, or from any other script with no live `HelipodClient`.
+ */
+declare function drainOutboxOnce(opts: HeadlessDrainOptions): Promise<{
+    drained: number;
+    failed: number;
+    remaining: number;
+}>;
+
+/**
+ * `createAuthClient` — a thin token-lifecycle manager over a `HelipodClient` (auth slice A1).
+ * Sign-in flows stay ordinary app mutations; the app hands the mint result to `setSession`. From
+ * there this manages: persistence (default `localStorage`, memory fallback), applying the access
+ * token via `client.setAuth` + re-applying on reconnect (SetAuth replay handles the wire side),
+ * refresh scheduling at ~80% of the access TTL, a Web-Locks single-refresher, a BroadcastChannel
+ * pair broadcast to sibling tabs, `REFRESH_STALE` wait-for-broadcast, and terminal-clear +
+ * `onSignedOut` on `REFRESH_EXPIRED`/`REFRESH_REUSED`. The outbox fingerprint is switched to the
+ * stable `sessionId` while a session is managed (spec decision 9).
+ *
+ * Non-browser hosts fall back to in-process serialization (no Web Locks) and a no-op broadcast; two
+ * independent PROCESSES sharing one refresh token is documented as unsupported (spec decision 5).
+ */
+/** The persisted mint result — the raw pair + the stable ids the manager needs across a reload. */
+interface SessionInfo {
+    token: string;
+    refreshToken: string;
+    sessionId: string;
+    userId: string;
+    /** Absolute wall-clock ms when the ACCESS token expires (mint `expiresAt`). Drives the 80% schedule. */
+    expiresAt: number;
+}
+/** The minimal `HelipodClient` surface `createAuthClient` needs (kept structural for testability).
+ *  `mutation` deliberately returns `Promise<unknown>` (not a generic) so `HelipodClient`'s
+ *  overloaded `mutation(...): Promise<Value>` is structurally assignable; call sites cast. */
+interface AuthManagedClient {
+    setAuth(token: string | null): void;
+    setSessionFingerprint(sessionId: string | null): void;
+    /** `opts.transient` is threaded straight to `HelipodClient.mutation`'s own escape hatch — the
+     *  refresh call below always passes `{ transient: true }` so a refresh mutation never durably
+     *  enqueues, even when the app configured an `outbox` (see the file doc's outbox-fingerprint
+     *  paragraph and `client.ts#mutation`'s doc for why replaying a refresh is never safe). */
+    mutation(ref: string, args?: Record<string, unknown>, opts?: {
+        transient?: boolean;
+    }): Promise<unknown>;
+}
+/** Pluggable synchronous session store (same shape idea as the outbox storage seam). */
+interface SessionStorage {
+    load(): SessionInfo | null;
+    save(info: SessionInfo): void;
+    clear(): void;
+}
+/** A minimal single-refresher lock seam (a subset of the Web Locks API). Non-browser → in-process. */
+interface RefreshLock {
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+/** A minimal cross-tab broadcast seam over the new pair. */
+interface PairBroadcast {
+    post(info: SessionInfo): void;
+    onMessage(cb: (info: SessionInfo) => void): void;
+    close(): void;
+}
+interface CreateAuthClientOptions {
+    storage?: SessionStorage;
+    lock?: RefreshLock;
+    broadcast?: PairBroadcast;
+    /** Injectable clock (tests). Defaults to `Date.now`. */
+    now?: () => number;
+    /** Refresh at this fraction of the access TTL (default 0.8). */
+    refreshAtFraction?: number;
+    /** Called when the session terminally ends (REFRESH_EXPIRED / REFRESH_REUSED, or clearSession). */
+    onSignedOut?: () => void;
+    /** Fixed function path for the refresh mutation (default "auth:refresh"). */
+    refreshPath?: string;
+}
+interface AuthClient {
+    setSession(info: SessionInfo): void;
+    clearSession(): void;
+    getSessionInfo(): SessionInfo | null;
+    close(): void;
+}
+/** The default `localStorage` key `localStorageSession()` persists under — a `SessionInfo` JSON
+ *  blob, `.sessionId` being the field a headless host needs for `headless-drain.ts`'s `getSessionId`
+ *  option (mirroring the SAME managed-session fingerprint a live tab's `setSessionFingerprint`
+ *  computes). Exported so a Service Worker (which shares `localStorage`'s *origin* but typically not
+ *  a synchronous API to it) or any other headless host can name the same storage row without
+ *  hand-copying the string literal. A custom `storage`/key (via `localStorageSession(key)` or a
+ *  fully custom `SessionStorage`) is, of course, this app's own convention to document instead. */
+declare const SESSION_STORAGE_KEY = "helipod.session";
+/** localStorage-backed store with an in-memory fallback wherever localStorage is unavailable/throws. */
+declare function localStorageSession(key?: string): SessionStorage;
+/** In-memory store — nothing survives a reload; the default fallback and a test seam. */
+declare function memorySession(): SessionStorage;
+declare function createAuthClient(client: AuthManagedClient, opts?: CreateAuthClientOptions): AuthClient;
+
+export { type AuthClient, type AuthManagedClient, ClientTransport, type CreateAuthClientOptions, type HeadlessDrainOptions, MutationUndeliveredError, OUTBOX_VERSION, OutboxEntry, OutboxLockManager, OutboxStorage, type PairBroadcast, PoisonPolicy, type RefreshLock, SESSION_STORAGE_KEY, type SessionInfo, type SessionStorage, buildConnectMessage, createAuthClient, drainOutboxOnce, localStorageSession, memorySession, outboxAckedThrough, outboxHeldFromLog, outboxHeldFromStore, sessionFingerprintKey, sha256Hex };