@voltro/client 0.38.0 → 0.39.0

package/dist/index.d.ts

@@ -296,8 +296,18 @@ export declare interface BuildApiRuntimeOptions {
     readonly name: string;
     /** WebSocket URL of the api (`ws(s)://host:port/ws`). */
     readonly wsUrl: string;
-    /** The api's rpc group (its typed procedure surface). */
-    readonly group: RpcGroup.RpcGroup<Rpc.Any>;
+    /**
+     * The api's rpc group, as the ERASED `RpcGroup.Any`.
+     *
+     * `RpcGroup` is declared `in out` in @effect/rpc — invariant on purpose — so a
+     * CONCRETE group (the `appGroup` codegen emits) is not assignable to
+     * `RpcGroup<Rpc.Any>`, and a boundary typed that way rejects the only value
+     * anyone ever passes it. This mirrors what `ApiHandle.client` already does:
+     * erase at the handle boundary, restore the types at the call site via
+     * `createHooks<T>()` / `useAppClient<T>()`. The concrete rpc types are
+     * irrelevant to building a transport — they matter to the caller, not here.
+     */
+    readonly group: RpcGroup.Any;
     /** Per-connection auth headers (see {@link ResolvableHeaders}). */
     readonly headers?: ResolvableHeaders | undefined;
     /** How to construct a WebSocket. Web wraps `globalThis.WebSocket` with
@@ -306,6 +316,8 @@ export declare interface BuildApiRuntimeOptions {
     readonly webSocketConstructor: (url: string, protocols?: string | ReadonlyArray<string>) => globalThis.WebSocket;
 }
 
+export declare type BuildClient = (api: MountedApi, generation: number, onSocketOpen: () => void, onSocketIssue: (kind: SocketIssueKind) => void) => Promise<ResolvedClient>;
+
 /** The transport-level pieces of one api's client stack. Combined with the
  *  api's descriptor map + inspect base URL, this is an `ApiHandle`. */
 export declare interface BuiltApiRuntime {
@@ -349,6 +361,11 @@ declare interface CacheEntry {
      *  server-side subscription is one per cache-entry key, not per
      *  subscriber. */
     fetch: (() => Stream.Stream<SubscriptionEvent<unknown>, unknown, never>) | null;
+    /** The runtime the saved `fetch` was forked against. Stored so a SINGLE entry
+     *  can be re-issued without the whole-cache `refreshAll(runtime)` — the
+     *  confirmed-patch resync needs exactly one, and threading a runtime down
+     *  from a `setTimeout` is not available to it. */
+    runtime: AnyRuntime | null;
     /** W3C trace id of the live stream, captured when the fiber starts.
      *  Shared with the server (the subscription span propagates it) and
      *  attached to error-bus events so a failure points at the right
@@ -492,6 +509,20 @@ export declare const clearStoreHistory: () => void;
 
 export declare const CLIENT_NAME: "framework-client";
 
+/**
+ * Per-rpc-tag metadata the client uses to route cache updates: what kind of
+ * procedure a tag is, which query it reads from, and which tables a mutation
+ * targets (driving auto-optimistic updates). Produced by codegen.
+ *
+ * It is the CANONICAL `ClientDescriptor` from `@voltro/protocol`, not a
+ * structural copy of it. The copy that used to live here narrowed `source` to a
+ * single string while the real descriptor allows several — so a generated
+ * `appDescriptors` did not fit the type the client declared for it. Nothing
+ * caught that: the only place the two meet is a GENERATED entry, and no harness
+ * typechecks a generated entry.
+ */
+export declare type ClientDescriptorMap = Readonly<Record<string, ClientDescriptor>>;
+
 export declare interface ClientErrorEvent {
     /** The thrown value (Error | anything). */
     readonly error: unknown;
@@ -1047,6 +1078,27 @@ export declare const markFailed: (queue: Outbox, id: string, error: unknown) =>
 
 export declare const markSent: (queue: Outbox, id: string) => Outbox;
 
+/**
+ * One api the client is mounted against: its name, its typed rpc surface, its
+ * descriptor map and where to connect.
+ *
+ * `headers` are sent in the per-request MESSAGE frame, NOT the WebSocket
+ * upgrade — a browser cannot set upgrade headers — so the server's
+ * AuthMiddleware sees them on every call, which is what lets a cross-origin api
+ * authenticate WS subscriptions. A thunk is resolved fresh on every (re)connect,
+ * so a rotating token is pulled anew per connection instead of frozen at first
+ * mount.
+ */
+export declare interface MountedApi {
+    readonly name: string;
+    /** Erased — see `BuildApiRuntimeOptions.group` for why an invariant
+     *  `RpcGroup<Rpc.Any>` cannot hold a generated `appGroup`. */
+    readonly group: RpcGroup.Any;
+    readonly descriptors: ClientDescriptorMap;
+    readonly wsUrl: string;
+    readonly headers?: ResolvableHeaders | undefined;
+}
+
 export declare interface MutateOptions<Input, Output> {
     /** Ran after the server confirms the write. */
     readonly onSuccess?: (output: Output, input: Input) => void;
@@ -1242,6 +1294,31 @@ export declare interface PersistOptions<S> {
  *  `initialSnapshot` are its own concern. */
 export declare type PreloadedSubscriptionOptions = Pick<SubscriptionOptions<never>, 'skip'>;
 
+/**
+ * What this hook returns: the subscription's state, plus whether the SERVER
+ * tried to preload it and failed.
+ *
+ * `preloadFailed` is the difference between "this page has no data yet" and
+ * "the server could not get this page's data" — two states that were one
+ * observation before it existed, because both arrive as the absence of a seed.
+ * A consumer whose session had expired rendered skeleton titles over empty
+ * tables and found the cause only in a server WARN line.
+ *
+ * It says nothing about WHY, deliberately (`PreloadSeed.failed`), and nothing
+ * about the LIVE subscription — which usually recovers on its own, since the
+ * browser reconnects with a credential the SSR request did not have. So the
+ * honest reading is "the first paint has no server data and that was not for
+ * lack of asking", which is exactly enough to choose a spinner over an
+ * empty-state.
+ *
+ * Widened on THIS hook rather than on `SubscriptionState`, so no existing
+ * `useSubscription` call site is un-narrowed by it — the same scoping rule the
+ * `skip`/`idle` overload follows.
+ */
+export declare type PreloadedSubscriptionState<T> = (SubscriptionState<T> | SubscriptionIdle) & {
+    readonly preloadFailed?: true;
+};
+
 /** One preloaded subscription snapshot, as it travels in the hydration payload. */
 export declare interface PreloadSeed {
     /** The api mount name the subscription reads from (first arg of `useSubscription`). */
@@ -1249,8 +1326,25 @@ export declare interface PreloadSeed {
     /** `stableKey([rpcTag, input])` — identical to the SubscriptionCache's own key,
      *  so the seed and the live subscription address the same entry. */
     readonly key: string;
-    /** The server-fetched snapshot value. */
+    /** The server-fetched snapshot value. `undefined` when `failed`. */
     readonly value: unknown;
+    /**
+     * The server ATTEMPTED this preload and it failed.
+     *
+     * Reported by a consumer whose SSR seeds all failed at once (an expired
+     * session token — the api answered every preload with a scope error): the
+     * page rendered a skeleton title and an empty table, and the ONLY record of
+     * it was a `preload seed failed` WARN in the server log. The client could not
+     * tell that state from "this page declares no preload", because both arrive
+     * as the absence of a seed. So an app cannot distinguish "still loading" from
+     * "actually empty" without inventing its own convention — which the reporting
+     * consumer then did, page by page.
+     *
+     * NOTHING about the cause travels. A boolean is the whole contract: the
+     * server's failure text is for the server's log, and a reason string here
+     * would be an error message from a refused call rendered into a browser.
+     */
+    readonly failed?: true;
 }
 
 /** Collects preload seeds for ONE request. The server creates one per render. */
@@ -1389,6 +1483,17 @@ export declare interface QueryFiltersState<Row> {
 
 declare type QueryTag<P extends ProcedureTypeMap> = TagsOfKind<P, 'query'>;
 
+/**
+ * Did the server attempt this preload, and did it work?
+ *
+ * `'absent'` means the page declared no preload for it (or the server never
+ * rendered this route — a client-side SPA navigation). `'failed'` means the
+ * server tried and the query threw. Those two were the same observation before
+ * this existed, which is why a page could not tell "still loading" from
+ * "genuinely empty".
+ */
+export declare const readPreloadedSeedOutcome: (api: string, rpcTag: string, input: Readonly<Record<string, unknown>>) => "seeded" | "failed" | "absent";
+
 /**
  * The preloaded snapshot for `(api, rpcTag, input)`, or `undefined` when none was
  * seeded. On the SERVER it reads the current request's bag directly, so the SSR
@@ -1433,6 +1538,9 @@ export declare const resetPreloadSeeds: () => void;
 /** Test helper: forget every defined store. NEVER call this in app code. */
 export declare const resetStoreRegistryForTests: () => void;
 
+/** Test seam: forget both the installed provider and the used flag. */
+export declare const resetStoreStorageForTest: () => void;
+
 /** Auth headers to attach to every rpc MESSAGE frame, resolved on EVERY
  *  (re)connect so a rotating token (a `() => Promise<…>` thunk) is fetched anew
  *  each connection rather than frozen at first build. */
@@ -1440,6 +1548,15 @@ export declare type ResolvableHeaders = Readonly<Record<string, string>> | (() =
 
 export declare const resolveByTag: (client: unknown, tag: string) => unknown;
 
+export declare interface ResolvedClient {
+    readonly runtime: AnyRuntime;
+    readonly cache: SubscriptionCache;
+    readonly client: RpcClient.RpcClient<Rpc.Any, RpcClientError.RpcClientError>;
+}
+
+/** Resolve the storage for an area. Internal to the store layer. */
+export declare const resolveStoreStorage: (area: StoreStorageArea) => StoreStorage | null;
+
 /** Resolve one map entry against the props. Pure. */
 export declare const resolveTrackingEvent: <P>(entry: TrackingEntry<P> | undefined, props: P) => TrackingEvent | null;
 
@@ -1613,6 +1730,16 @@ export declare const schemaToFields: (schema: Schema.Schema.Any) => ReadonlyArra
  */
 export declare const seedPreloadedSubscription: (api: string, rpcTag: string, input: Readonly<Record<string, unknown>>, value: unknown) => void;
 
+/**
+ * Record that this preload was ATTEMPTED and failed, so the client can tell an
+ * empty page from a broken one.
+ *
+ * Same request-scoping and the same key as the success path — a failure the
+ * client cannot address to a subscription is no better than the WARN line it
+ * replaces. It carries no reason: see `PreloadSeed.failed`.
+ */
+export declare const seedPreloadedSubscriptionFailure: (api: string, rpcTag: string, input: Readonly<Record<string, unknown>>) => void;
+
 /**
  * Seed a store for THIS request's hydration. Call it anywhere on the server
  * during a render — a loader, a layout loader — and the value reaches the
@@ -1694,6 +1821,21 @@ export declare const setPreloadSeedResolver: (resolver: (() => PreloadSeedBag |
  */
 export declare const setStoreSeedResolver: (resolver: (() => StoreSeedBag | null) | null) => void;
 
+/**
+ * Install the process-wide backing store for persisted stores.
+ *
+ * Call it BEFORE the first read of a persisted store — on React Native, after
+ * awaiting the adapter's `hydrate()` and before rendering the app. Pass `null`
+ * to restore the browser default.
+ *
+ * Installing after a persisted store has already read logs a warning rather
+ * than throwing: the app is running and the value is merely from the wrong
+ * backend, so failing the boot would be the worse outcome. It is a warning that
+ * means something, though — the store that read first is now inconsistent with
+ * every store defined after it.
+ */
+export declare const setStoreStorage: (provider: StoreStorageProvider | null) => void;
+
 /**
  * Transition a pending mutation to 'success' or 'error'. Updates the
  * existing entry in-place (preserves order in the buffer) so the
@@ -1726,6 +1868,8 @@ export declare const shallowArrayEqual: (a: ReadonlyArray<unknown>, b: ReadonlyA
 
 declare type SignalPayload<Messages extends WorkflowClientMessages, Name extends string> = NonNullable<Messages['signals']> extends Readonly<Record<Name, infer Payload>> ? Payload : unknown;
 
+export declare type SocketIssueKind = 'close' | 'error' | 'connect-timeout';
+
 export declare interface SortState {
     readonly column: string;
     readonly direction: 'asc' | 'desc';
@@ -1745,6 +1889,14 @@ export declare const ssrStubHandle: ApiHandle;
  */
 export declare const stableKey: (key: ReadonlyArray<unknown>) => string;
 
+/**
+ * Spawn the per-api connect + reconnect supervisor.
+ *
+ * Returns a handle whose `dispose()` cancels everything pending and
+ * disposes every live ResolvedClient. Calling dispose() twice is safe.
+ */
+export declare const startApiSupervisor: (options: SupervisorOptions) => SupervisorHandle;
+
 /**
  * Publish a NEW (pending) mutation event. Caller is responsible for
  * calling `settleMutation(id, ...)` later. Returns the id used to
@@ -1934,6 +2086,22 @@ export declare interface StoreSeedBag {
     readonly seeds: StoreSeed[];
 }
 
+/** The synchronous subset of the DOM `Storage` interface a persisted store
+ *  needs. `removeItem` is optional — nothing in the store layer clears keys. */
+export declare interface StoreStorage {
+    readonly getItem: (key: string) => string | null;
+    readonly setItem: (key: string, value: string) => void;
+    readonly removeItem?: (key: string) => void;
+}
+
+/** Which area a store asked for. Platforms without a session/local split map
+ *  both onto one backing store; that is expected, not a downgrade. */
+export declare type StoreStorageArea = 'local' | 'session';
+
+/** A backing store provider: given the requested area, return the storage to
+ *  use, or `null` for "there is none here" (the store then does not persist). */
+export declare type StoreStorageProvider = (area: StoreStorageArea) => StoreStorage | null;
+
 export declare interface StoreUseOptions<T> {
     /** Which instance to read. Omitted = the global one. */
     readonly key?: string;
@@ -2037,6 +2205,31 @@ export declare class SubscriptionCache {
      * resolve briefly exposes a stale base before the server delta lands.
      */
     confirmByMutation(mutationId: string): void;
+    /**
+     * The confirmed-patch window expired: a committed write never got its
+     * superseding server event. Re-issue the affected subscriptions instead of
+     * discarding the write's preview.
+     *
+     * Three things are load-bearing, and each was a way to reintroduce the bug:
+     *
+     *   - **The patch is KEPT across the resync.** `refreshAll` already
+     *     establishes that shape ("the new base snapshot will land on top of
+     *     them"). Clearing it here would be the revert again, wearing a longer
+     *     word.
+     *   - **A stub entry — no `fetch`, no `runtime` — is left ALONE.** There is
+     *     nothing to re-issue, and the only other option is to show a base the
+     *     client knows is stale. Keeping the patch is the honest state.
+     *   - **It is LOUD.** The reporter found the jump only by reading minified
+     *     source, because in the UI it is indistinguishable from "the server did
+     *     not save it" — and that is the false trail they followed first. This
+     *     goes to the error bus, so it reaches `voltro logs` rather than only a
+     *     console nobody has open.
+     *
+     * No second timer is armed: this runs once per mutation, from the one
+     * `confirmByMutation` scheduled it, so a server that never echoes cannot put
+     * the client into a resync loop.
+     */
+    private resyncUnechoedMutation;
     /**
      * Auto-derive optimistic patches from a mutation's declared target(s).
      * Iterates every cache entry whose `source` table matches a target's
@@ -2098,6 +2291,18 @@ export declare class SubscriptionCache {
      * promote naturally on their next subscriber.
      */
     refreshAll(runtime: AnyRuntime): void;
+    /**
+     * Re-issue ONE entry's subscription: interrupt the fiber, reset the base,
+     * re-fork through the saved `fetch`.
+     *
+     * Extracted so `refreshAll` and the confirmed-patch resync cannot disagree
+     * about it — and the thing they must agree on is that **optimistic patches
+     * survive**. For a re-auth they belong to in-flight mutations; for the resync
+     * they describe a write the server has already committed. Dropping them here
+     * would be a revert with a longer name, which is the defect the resync exists
+     * to remove.
+     */
+    private reissue;
     /**
      * Seed this (fresh) cache with the last-known-good rows held by the cache it
      * REPLACES, so a transport rebuild degrades to STALE DATA rather than to
@@ -2315,6 +2520,98 @@ export declare interface SubscriptionStateWithFallback<T> extends SubscriptionMe
     readonly isEmpty: boolean;
 }
 
+/**
+ * May this server event retire the CONFIRMED optimistic patches on an entry?
+ *
+ * **A rollback happens if and only if the write FAILED.** Nothing else — no
+ * timer, no elapsed window, no "probably fine by now" — may take an optimistic
+ * preview away from a write the server acknowledged. This function is the other
+ * half of that rule: it decides when a patch is *superseded* rather than rolled
+ * back, and superseding is only honest when the authoritative state has actually
+ * arrived and actually says something.
+ *
+ * Three answers, each of which was a way to lose a committed write:
+ *
+ *   - **delta → YES.** A delta IS the echo of committed writes. This is the
+ *     seamless hand-off: base gains the real row and the placeholder goes in the
+ *     same update, so there is no flash and no optimistic+real duplicate.
+ *   - **error → NO.** An error does not advance `base`; it sets `baseError` and
+ *     leaves the rows where they were. Dropping here would discard the preview
+ *     in favour of a base the client knows does not reflect the write.
+ *   - **snapshot → only if it MOVED the base.** A resync after a missing echo
+ *     re-asks the server, and if the answer comes back byte-identical then the
+ *     write is still not reflected in it. Retiring the patch on that would be
+ *     the reported bug reached by a longer route: the user watches their saved
+ *     change disappear, and the client did it while holding evidence that the
+ *     server's answer had not changed.
+ *
+ * The comparison only runs when confirmed patches exist, which is rare and
+ * short-lived, so the stringify is not on any hot path.
+ */
+export declare const supersedesConfirmedPatches: (event: SubscriptionEvent<unknown>, baseBefore: unknown, baseAfter: unknown) => boolean;
+
+export declare interface SupervisorHandle {
+    readonly dispose: () => void;
+    /** Force a fresh ws connect for every api (carrying the browser's current
+     *  cookies) so a cookie-based login re-resolves the authenticated Subject
+     *  in place, without a page reload. No-op for UI-only (no-api) apps. */
+    readonly reconnect: () => void;
+}
+
+export declare interface SupervisorOptions {
+    readonly apis: ReadonlyArray<MountedApi>;
+    readonly buildClient: BuildClient;
+    /**
+     * Called whenever the resolved-clients map changes (initial resolve,
+     * reconnect swap, api removed). The React layer mirrors this into
+     * setState so the component tree sees the latest clients.
+     */
+    readonly onChange: (clients: ReadonlyMap<string, ResolvedClient>, initialized: boolean) => void;
+    /**
+     * Override the retry-delay calculation. Default: 500ms × 2^(attempt-1),
+     * capped at 5s after the 5th attempt. Tests inject a deterministic
+     * function so assertions don't depend on the cap shape.
+     */
+    readonly retryDelayMs?: (attempt: number) => number;
+    /**
+     * Override the stable-connection window (default 5s). When the
+     * elapsed time since `onSocketOpen` exceeds this AND `failureCount`
+     * hasn't moved, the connection is treated as stable and the count
+     * resets to zero so the next failure starts fresh at attempt=1.
+     */
+    readonly stableWindowMs?: number;
+    /**
+     * Indirection for the JS scheduler. Production uses globalThis's
+     * `setTimeout`/`clearTimeout`/`queueMicrotask`; tests inject fake
+     * versions to step time deterministically.
+     */
+    readonly scheduler?: {
+        readonly setTimeout: (cb: () => void, ms: number) => unknown;
+        readonly clearTimeout: (handle: unknown) => void;
+        readonly queueMicrotask: (cb: () => void) => void;
+    };
+    /**
+     * Called when an api enters the reconnecting state, and again — via the
+     * returned dispose — when it reconnects or the supervisor is torn down.
+     * Exactly one entry per api per disconnect cycle: repeated retries within one
+     * cycle do NOT call this again, so a status surface cannot stack duplicates.
+     *
+     * The web passes its devtools status bus. RN omits it.
+     */
+    readonly onReconnecting?: (apiName: string) => () => void;
+    /**
+     * Recovery for a socket that never re-opens (see the note above `ApiSlot`).
+     * `arm` is called once, for an api that HAD been healthy, after
+     * `afterFailures` consecutive failed reconnects; its returned stop function
+     * runs on the next successful open or on dispose. What arming DOES is the
+     * caller's: the web polls the page origin and hard-reloads when it answers.
+     */
+    readonly wedgeBackstop?: {
+        readonly afterFailures: number;
+        readonly arm: (apiName: string) => () => void;
+    };
+}
+
 /** The tags in `P` whose procedure is of kind `K`. */
 export declare type TagsOfKind<P extends ProcedureTypeMap, K extends string> = {
     [T in keyof P]: P[T] extends {
@@ -2727,7 +3024,7 @@ export declare const usePermissions: () => PermissionState_2;
  * @param options  `{ skip }` — defers the subscription. `initialSnapshot`
  *                 comes from the preload payload, not from here.
  */
-export declare function usePreloadedSubscription<T = unknown>(apiName: string, rpcTag: string, input?: Readonly<Record<string, unknown>>, options?: PreloadedSubscriptionOptions): SubscriptionState<T> | SubscriptionIdle;
+export declare function usePreloadedSubscription<T = unknown>(apiName: string, rpcTag: string, input?: Readonly<Record<string, unknown>>, options?: PreloadedSubscriptionOptions): PreloadedSubscriptionState<T>;
 
 export declare const usePreview: <Input = Record<string, unknown>>(apiName: string, previewTag: string) => PreviewState<Input>;