@gonvex/client 0.1.24 → 0.1.26

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import type { BrowserTelemetryInfo, JsonValue, MessageTrace, ServerCapabilities,
 import { type QueryCacheOptions, type QueryCacheStatus } from "./query-cache.js";
 import { type SyncStoreOptions } from "./sync-store.js";
 import { type ErrorReporterOptions } from "./error-reporter.js";
+import { OptimisticOverlay, type OptimisticPatch } from "./optimistic.js";
 export * from "./cache.js";
 export * from "./cache-coordinator.js";
 export * from "./browser-cache.js";
@@ -12,8 +13,21 @@ export * from "./persistent-cache.js";
 export * from "./query-cache.js";
 export * from "./sync-store.js";
 export * from "./error-reporter.js";
+export * from "./optimistic.js";
+export * from "./outbox.js";
+export * from "./signals.js";
 export type { QueryCacheDirective } from "@gonvex/protocol";
 type SubscriptionHandler = (message: ServerMessage) => void;
+export type SyncReadyMessage = Extract<ServerMessage, {
+    type: "sync.ready";
+}> & {
+    /** True when the server cut this collection at its row or byte budget. */
+    truncated?: boolean;
+};
+export type SyncMessage = Extract<ServerMessage, {
+    type: "sync.snapshot" | "sync.delta" | "sync.needHashes" | "sync.syncing" | "sync.reset" | "sync.error";
+}> | SyncReadyMessage;
+export type SyncSubscriptionHandler = (message: SyncMessage) => void;
 type WatchUpdateHandler = () => void;
 type TelemetryHandler = (event: GonvexTelemetryEvent) => void;
 type ConnectionStateHandler = (state: ConnectionState) => void;
@@ -31,7 +45,7 @@ export type GonvexClientErrorCode = "server" | "timeout" | "disconnected" | "clo
  * - `timeout`: no response arrived within the operation timeout. For
  *   mutations/actions the write may or may not have been applied.
  * - `disconnected`: the socket dropped while the operation was pending.
- *   Mutations/actions fail closed and are never replayed automatically.
+ *   Mutations/actions fail closed unless a mutation opted into the outbox.
  * - `closed`: the client was explicitly closed.
  * - `auth`: authentication was rejected.
  */
@@ -69,12 +83,50 @@ export declare const DEFAULT_ACTION_TIMEOUT_MS = 60000;
 export type CallOptions = {
     /** Per-call override of the operation timeout. `0` disables. */
     timeoutMs?: number;
+    /** Ordered row changes to expose until the mutation settles. */
+    optimistic?: OptimisticPatch[];
+    /** Queue transport failures durably instead of rejecting. Default `reject`. */
+    offline?: "queue" | "reject";
+};
+/** Returned when an offline mutation has been accepted by the local outbox. */
+export type QueuedMutationOutcome = {
+    status: "queued";
+    mutationId: string;
 };
+export type GonvexAuthTokenFetcher = (args: {
+    /** True when the server just rejected the current token — bypass any cache. */
+    forceRefreshToken: boolean;
+}) => Promise<string | null | undefined>;
 export type GonvexClientAuth = {
     project?: string;
     token?: string;
     tenant?: string;
     telemetry?: boolean;
+    /**
+     * Async source of the auth token, mirroring Convex's `fetchToken` contract.
+     * When installed, the client re-fetches before every auth send — on first
+     * connect, on every reconnect, and once more with `forceRefreshToken: true`
+     * when the server rejects the current token — so a socket that outlives a
+     * short-lived JWT (e.g. an ~1h Firebase ID token) reauthenticates with a
+     * live credential instead of replaying the expired one. A `token` passed in
+     * the same `setAuth` call is trusted and sent as-is; resolving `null` signs
+     * the session out; a rejected fetch keeps the currently installed token so
+     * an offline start is not signed out.
+     */
+    fetchToken?: GonvexAuthTokenFetcher;
+    /**
+     * Non-secret identity hint ({@link https://datatracker.ietf.org/doc/html/rfc7519 JWT}
+     * `sub` and `iss` claims) that stands in for a token when deriving the local
+     * cache identity. Lets a cold start with no usable token — e.g. an offline
+     * tab whose identity provider cannot refresh — recover the warm query-cache
+     * directive and serve cached reads. Never sent to the server; a parseable
+     * token always takes precedence, and both must derive the same key for the
+     * same user (persist the claims of the last token you installed).
+     */
+    identity?: {
+        sub: string;
+        iss?: string;
+    };
 };
 export type GonvexClientOptions = GonvexClientAuth & {
     queryCache?: false | QueryCacheOptions;
@@ -90,6 +142,14 @@ export type GonvexClientOptions = GonvexClientAuth & {
      */
     syncSubscriptionRetentionMs?: number;
     sync?: false | SyncStoreOptions;
+    /**
+     * Durable mutation queue settings. Every replay keeps its original
+     * idempotency key, making an accidental cross-tab double-send server-safe.
+     */
+    outbox?: {
+        databaseName?: string;
+        enabled?: boolean;
+    };
     errorReporting?: false | Omit<ErrorReporterOptions, "endpoint" | "project" | "tenant">;
     timeouts?: GonvexTimeoutOptions;
 };
@@ -124,6 +184,9 @@ export declare class GonvexClient {
     private auth;
     private authInFlight;
     private authWatchdogTimer;
+    private authFetchGeneration;
+    private authRetriedAfterError;
+    private readonly authErrorHandlers;
     private telemetryEnabled;
     private readonly queryCache;
     private readonly queryCacheWaitForScope;
@@ -131,6 +194,14 @@ export declare class GonvexClient {
     private readonly querySubscriptionRetentionMs;
     private readonly syncSubscriptionRetentionMs;
     private readonly syncStore;
+    private readonly mutationOutbox;
+    private readonly overlay;
+    private readonly optimisticMutationIds;
+    private readonly outboxReady;
+    private readonly unsubscribeOutbox;
+    private readonly unsubscribeOverlay;
+    private drainingOutbox;
+    private outboxDrainTimer;
     private queryCacheDirective;
     private queryCacheGeneration;
     private syncScopeGeneration;
@@ -149,12 +220,24 @@ export declare class GonvexClient {
     private connectionCount;
     private readonly timeouts;
     constructor(url: string, options?: GonvexClientOptions);
+    /** The client's materialized optimistic state for pending-row indicators. */
+    get optimisticOverlay(): OptimisticOverlay;
+    /** Number of mutations waiting for a definitive server result. */
+    outboxCount(): Promise<number>;
     connectionState(): ConnectionState;
     /** Metadata advertised by the runtime in its latest session.ready frame. */
     serverInfo(): Readonly<ServerCapabilities>;
     subscribeToConnectionState(handler: ConnectionStateHandler): () => void;
     private notifyConnectionState;
     setAuth(auth: GonvexClientAuth): void;
+    /**
+     * Subscribe to unrecoverable auth rejections: the server refused the
+     * credentials and, when a token fetcher is installed, a force-refreshed
+     * token did not fix it. Lets apps route to sign-in instead of silently
+     * degrading to an unauthenticated session.
+     */
+    onAuthError(handler: (error: string) => void): () => void;
+    private applyAuth;
     connect(): void;
     close(): void;
     private rejectPendingCalls;
@@ -171,7 +254,7 @@ export declare class GonvexClient {
         localQueryResult(): T | undefined;
         onUpdate(handler: WatchUpdateHandler): () => void;
     };
-    subscribeSync(ref: FunctionReference, args: JsonValue | undefined, onMessage: SubscriptionHandler): () => void;
+    subscribeSync(ref: FunctionReference, args: JsonValue | undefined, onMessage: SyncSubscriptionHandler): () => void;
     watchSync<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue): {
         localSyncResult(): T[] | undefined;
         status(): {
@@ -183,6 +266,8 @@ export declare class GonvexClient {
     private handleSyncMessage;
     private acceptSyncReady;
     private emitSyncMessage;
+    private materializeSyncMessage;
+    private emitOptimisticCollection;
     private markSyncSubscriptionsOutOfDate;
     private startSync;
     private sendSyncOpen;
@@ -191,6 +276,15 @@ export declare class GonvexClient {
     private unsubscribeSyncListener;
     private persistSyncSnapshot;
     private persistSyncDelta;
+    private restoreOutbox;
+    private addOptimisticMutation;
+    private settleOptimisticMutation;
+    private rejectOptimisticMutation;
+    private drainOutbox;
+    private scheduleOutboxDrain;
+    mutation<T = JsonValue>(ref: FunctionReference, args: JsonValue, options: CallOptions & {
+        offline: "queue";
+    }): Promise<T | QueuedMutationOutcome>;
     mutation<T = JsonValue>(ref: FunctionReference, args?: JsonValue, options?: CallOptions): Promise<T>;
     action<T = JsonValue>(ref: FunctionReference, args?: JsonValue, options?: CallOptions): Promise<T>;
     query<T = JsonValue>(ref: FunctionReference, args?: JsonValue, options?: CallOptions): Promise<T>;
@@ -243,6 +337,10 @@ export declare class GonvexClient {
     private emitTelemetry;
     private reportTelemetry;
     private sendAuth;
+    private sendAuthFrame;
+    private fetchAndSendAuth;
+    private refreshRejectedAuth;
+    private notifyAuthError;
     private armAuthWatchdog;
     private send;
     private sendNow;