@gonvex/client 0.1.25 → 0.1.27

package/dist/index.js

@@ -1,6 +1,8 @@
 import { createQueryCacheStore, defaultQueryCacheReadTimeoutMs, } from "./query-cache.js";
 import { createSyncStore, syncHashesDigest, syncRowsHashes, } from "./sync-store.js";
 import { GonvexErrorReporter } from "./error-reporter.js";
+import { OptimisticOverlay } from "./optimistic.js";
+import { createMutationOutbox, } from "./outbox.js";
 export * from "./cache.js";
 export * from "./cache-coordinator.js";
 export * from "./browser-cache.js";
@@ -11,6 +13,9 @@ 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";
 /**
  * Typed error for every rejected Gonvex operation. `code` distinguishes
  * server-side failures from transport-level ones so apps can decide whether
@@ -20,7 +25,7 @@ export * from "./error-reporter.js";
  * - `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.
  */
@@ -54,6 +59,9 @@ const maxSyncBatchOpens = 256;
 // start into a cold open — never into a permanently empty screen. Reads
 // normally settle in a few milliseconds.
 const syncStoreReadTimeoutMs = 1_000;
+// Watermarks can arrive for every tenant revision. Bound cursor-only IndexedDB
+// writes per collection while keeping the in-memory resume cursor immediate.
+const syncWatermarkPersistDelayMs = 1_000;
 export class GonvexClient {
     url;
     socket;
@@ -72,6 +80,14 @@ export class GonvexClient {
     auth = {};
     authInFlight = false;
     authWatchdogTimer;
+    // Monotonic guard for async token fetches: a resolve whose generation is no
+    // longer current was superseded (newer setAuth, watchdog re-issue, or a
+    // reconnect's own fetch) and must be discarded.
+    authFetchGeneration = 0;
+    // At most one forced refresh per rejection cycle; cleared when auth settles
+    // or a fresh send cycle starts, so a bad token can't refresh-loop forever.
+    authRetriedAfterError = false;
+    authErrorHandlers = new Set();
     telemetryEnabled = false;
     queryCache;
     queryCacheWaitForScope;
@@ -79,6 +95,14 @@ export class GonvexClient {
     querySubscriptionRetentionMs;
     syncSubscriptionRetentionMs;
     syncStore;
+    mutationOutbox;
+    overlay = new OptimisticOverlay();
+    optimisticMutationIds = new Set();
+    outboxReady;
+    unsubscribeOutbox;
+    unsubscribeOverlay;
+    drainingOutbox = false;
+    outboxDrainTimer;
     queryCacheDirective;
     queryCacheGeneration = 0;
     // Sync collections live under a visibility-only scope that survives query
@@ -108,6 +132,14 @@ export class GonvexClient {
         this.querySubscriptionRetentionMs = normalizeQuerySubscriptionRetentionMs(options.querySubscriptionRetentionMs);
         this.syncSubscriptionRetentionMs = normalizeQuerySubscriptionRetentionMs(options.syncSubscriptionRetentionMs);
         this.syncStore = createSyncStore(options.sync);
+        this.mutationOutbox = createMutationOutbox(options.outbox);
+        this.unsubscribeOutbox = this.mutationOutbox.subscribe(() => {
+            void this.drainOutbox();
+        });
+        this.unsubscribeOverlay = this.overlay.subscribe((collection) => {
+            this.emitOptimisticCollection(collection);
+        });
+        this.outboxReady = this.restoreOutbox();
         this.timeouts = {
             queryTimeoutMs: options.timeouts?.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
             mutationTimeoutMs: options.timeouts?.mutationTimeoutMs ?? DEFAULT_MUTATION_TIMEOUT_MS,
@@ -118,6 +150,15 @@ export class GonvexClient {
         }
         this.recoverWarmSyncDirective();
     }
+    /** The client's materialized optimistic state for pending-row indicators. */
+    get optimisticOverlay() {
+        return this.overlay;
+    }
+    /** Number of mutations waiting for a definitive server result. */
+    async outboxCount() {
+        await this.outboxReady;
+        return this.mutationOutbox.count();
+    }
     connectionState() {
         const inflightMutations = countPendingCalls(this.pendingCalls, "mutation");
         const inflightActions = countPendingCalls(this.pendingCalls, "action");
@@ -152,6 +193,29 @@ export class GonvexClient {
         }
     }
     setAuth(auth) {
+        this.applyAuth(auth);
+        // The caller owns auth now: a token fetch still in flight from the
+        // previous installation must not clobber this one when it resolves.
+        this.authFetchGeneration += 1;
+        if (this.socket?.readyState === WebSocket.OPEN) {
+            // A token supplied in this very call was just minted by the caller —
+            // send it as-is instead of paying another fetch round trip.
+            this.sendAuth(true, { useFetcher: !hasOwn(auth, "token") });
+        }
+    }
+    /**
+     * 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) {
+        this.authErrorHandlers.add(handler);
+        return () => {
+            this.authErrorHandlers.delete(handler);
+        };
+    }
+    applyAuth(auth) {
         const nextAuth = { ...this.auth, ...auth };
         const tokenScopeChanged = hasOwn(auth, "token")
             && auth.token !== this.auth.token
@@ -176,9 +240,6 @@ export class GonvexClient {
         if (auth.telemetry !== undefined) {
             this.telemetryEnabled = auth.telemetry === true;
         }
-        if (this.socket?.readyState === WebSocket.OPEN) {
-            this.sendAuth(true);
-        }
     }
     connect() {
         if (this.socket && this.socket.readyState <= WebSocket.OPEN)
@@ -202,6 +263,7 @@ export class GonvexClient {
             this.sendAuth(false);
             if (isReconnect)
                 this.resubscribeQueries(generation);
+            void this.drainOutbox();
             this.notifyConnectionState();
         });
         socket.addEventListener("close", () => {
@@ -258,18 +320,39 @@ export class GonvexClient {
                     this.authWatchdogTimer = undefined;
                 }
                 if (message.type === "auth.result") {
+                    this.authRetriedAfterError = false;
                     this.installQueryCacheDirective(queryCacheDirectiveFromAuthResult(message.result));
                     this.queryCacheNegotiatedSocketGeneration = this.socketGeneration;
                     this.resumeQuerySubscriptions();
                 }
                 else {
+                    const fetcher = this.auth.fetchToken;
+                    if (fetcher && !this.authRetriedAfterError) {
+                        // The installed token was rejected — typically expired while the
+                        // socket was down. Force-refresh through the fetcher and retry
+                        // once before treating the rejection as final.
+                        this.authRetriedAfterError = true;
+                        this.authInFlight = true;
+                        this.armAuthWatchdog();
+                        void this.refreshRejectedAuth(fetcher, this.auth.token, message.error);
+                        return;
+                    }
+                    this.authRetriedAfterError = false;
                     this.resetQueryCacheScope();
+                    this.notifyAuthError(message.error);
                 }
                 this.flushPendingMessages();
             }
             if (message.type === "sync.readyMany") {
                 for (const ready of message.ready) {
-                    this.handlers.get(ready.id)?.({ type: "sync.ready", ...ready });
+                    const readyMessage = { type: "sync.ready", ...ready };
+                    this.handlers.get(ready.id)?.(readyMessage);
+                }
+                return;
+            }
+            if (message.type === "sync.watermark") {
+                if (this.serverCapabilities.syncWatermark === 1) {
+                    this.handleSyncWatermark(message.revision);
                 }
                 return;
             }
@@ -294,6 +377,11 @@ export class GonvexClient {
             this.clearSyncRetry(subscription);
             if (subscription.unsubscribeTimer)
                 clearTimeout(subscription.unsubscribeTimer);
+            if (subscription.watermarkPersistTimer) {
+                clearTimeout(subscription.watermarkPersistTimer);
+                subscription.watermarkPersistTimer = undefined;
+                this.persistSyncSnapshot(subscription, true);
+            }
         }
         if (this.syncOpenFlushTimer) {
             clearTimeout(this.syncOpenFlushTimer);
@@ -305,6 +393,12 @@ export class GonvexClient {
             this.querySubscribeFlushTimer = undefined;
         }
         this.pendingQuerySubscribes.clear();
+        if (this.outboxDrainTimer) {
+            clearTimeout(this.outboxDrainTimer);
+            this.outboxDrainTimer = undefined;
+        }
+        this.unsubscribeOutbox();
+        this.unsubscribeOverlay();
         for (const subscription of this.querySubscriptions.values()) {
             if (subscription.cacheReadFallbackTimer)
                 clearTimeout(subscription.cacheReadFallbackTimer);
@@ -313,6 +407,10 @@ export class GonvexClient {
         this.querySubscriptions.clear();
         this.syncSubscriptions.clear();
         this.sessionScopeHandlers.clear();
+        this.authErrorHandlers.clear();
+        // Invalidate any token fetch still in flight so its resolve can't touch
+        // the closed client's caches.
+        this.authFetchGeneration += 1;
         this.queryCacheGeneration += 1;
         this.queryCacheDirective = undefined;
         this.queryCache?.close();
@@ -579,8 +677,9 @@ export class GonvexClient {
             existing.listeners.add(onMessage);
             if (existing.lastMessage) {
                 queueMicrotask(() => {
-                    if (existing.listeners.has(onMessage) && existing.lastMessage)
-                        onMessage(existing.lastMessage);
+                    if (existing.listeners.has(onMessage) && existing.lastMessage) {
+                        onMessage(this.materializeSyncMessage(existing, existing.lastMessage));
+                    }
                 });
             }
             return () => this.unsubscribeSyncListener(key, onMessage);
@@ -681,6 +780,7 @@ export class GonvexClient {
             subscription.cursor = message.cursor;
             subscription.keyField = message.key;
             subscription.mode = message.mode;
+            subscription.truncated = undefined;
             subscription.orderBy = message.orderBy;
             subscription.orderDirection = message.orderDirection;
             subscription.maxRows = message.maxRows;
@@ -689,6 +789,7 @@ export class GonvexClient {
             subscription.hashes = { ...(message.hashes ?? {}) };
             subscription.integrityDigest = undefined;
             subscription.integrityRows = undefined;
+            subscription.integrityEpoch = undefined;
             const snapshot = { ...message, result: subscription.rows };
             subscription.lastMessage = snapshot;
             this.emitSyncMessage(subscription, snapshot);
@@ -711,6 +812,7 @@ export class GonvexClient {
             Object.assign(subscription.hashes, message.hashes ?? {});
             subscription.integrityDigest = undefined;
             subscription.integrityRows = undefined;
+            subscription.integrityEpoch = undefined;
             const snapshot = {
                 type: "sync.snapshot",
                 id: subscription.id,
@@ -731,14 +833,20 @@ export class GonvexClient {
         }
         if (message.type === "sync.reset") {
             this.clearSyncRetry(subscription, true);
+            if (subscription.watermarkPersistTimer) {
+                clearTimeout(subscription.watermarkPersistTimer);
+                subscription.watermarkPersistTimer = undefined;
+            }
             subscription.verificationGeneration += 1;
             subscription.isUpToDate = false;
             subscription.cursor = undefined;
+            subscription.truncated = undefined;
             subscription.rows = [];
             subscription.persistedRows = undefined;
             subscription.hashes = {};
             subscription.integrityDigest = undefined;
             subscription.integrityRows = undefined;
+            subscription.integrityEpoch = undefined;
             subscription.forceFullIntegrity = false;
             subscription.lastMessage = undefined;
             subscription.opening = false;
@@ -786,6 +894,20 @@ export class GonvexClient {
                 });
                 return;
             }
+            if (!subscription.forceFullIntegrity
+                && subscription.integrityRows === subscription.rows
+                && subscription.integrityDigest
+                && subscription.integrityEpoch === subscription.cursor.epoch) {
+                if (message.digest && subscription.integrityDigest !== message.digest) {
+                    // Re-hash once before treating the server/memo disagreement as an
+                    // integrity failure. The memo may be stale even though row identity
+                    // says the collection has not changed.
+                }
+                else {
+                    this.acceptSyncReady(subscription, message, subscription.integrityDigest);
+                    return;
+                }
+            }
             void syncRowsHashes(subscription.rows, subscription.keyField).then((hashes) => (syncHashesDigest(hashes).then((digest) => ({ digest, hashes })))).then(({ digest, hashes }) => {
                 if (generation !== subscription.verificationGeneration
                     || this.syncSubscriptions.get(subscription.key) !== subscription)
@@ -829,8 +951,10 @@ export class GonvexClient {
         subscription.opening = false;
         subscription.cursor = message.cursor;
         subscription.mode = message.mode ?? subscription.mode;
+        subscription.truncated = message.truncated;
         subscription.integrityDigest = verifiedDigest;
         subscription.integrityRows = subscription.rows;
+        subscription.integrityEpoch = message.cursor.epoch;
         subscription.forceFullIntegrity = false;
         this.persistSyncSnapshot(subscription);
         // Every emitted ready frame is self-describing: when a legacy runtime
@@ -838,9 +962,53 @@ export class GonvexClient {
         // observe one contract regardless of the peer's protocol generation.
         this.emitSyncMessage(subscription, message.digest === verifiedDigest ? message : { ...message, digest: verifiedDigest });
     }
+    handleSyncWatermark(revision) {
+        if (!Number.isSafeInteger(revision) || revision < 0)
+            return;
+        for (const subscription of this.syncSubscriptions.values()) {
+            const cursor = subscription.cursor;
+            if (!cursor
+                || cursor.revision >= revision
+                || !subscription.isUpToDate
+                || subscription.opening
+                || subscription.forceFullIntegrity
+                || subscription.integrityRows !== subscription.rows
+                || !subscription.integrityDigest
+                || subscription.integrityEpoch !== cursor.epoch)
+                continue;
+            subscription.cursor = { ...cursor, revision };
+            this.scheduleSyncWatermarkPersistence(subscription);
+        }
+    }
+    scheduleSyncWatermarkPersistence(subscription) {
+        if (subscription.watermarkPersistTimer)
+            return;
+        subscription.watermarkPersistTimer = setTimeout(() => {
+            subscription.watermarkPersistTimer = undefined;
+            if (this.syncSubscriptions.get(subscription.key) !== subscription)
+                return;
+            this.persistSyncSnapshot(subscription, true);
+        }, syncWatermarkPersistDelayMs);
+    }
     emitSyncMessage(subscription, message) {
+        const outgoing = this.materializeSyncMessage(subscription, message);
         for (const listener of Array.from(subscription.listeners))
-            listener(message);
+            listener(outgoing);
+    }
+    materializeSyncMessage(subscription, message) {
+        if (message.type !== "sync.snapshot")
+            return message;
+        return {
+            ...message,
+            result: this.overlay.apply(subscription.path, message.result, message.key),
+        };
+    }
+    emitOptimisticCollection(collection) {
+        for (const subscription of this.syncSubscriptions.values()) {
+            if (subscription.path !== collection || subscription.lastMessage?.type !== "sync.snapshot")
+                continue;
+            this.emitSyncMessage(subscription, subscription.lastMessage);
+        }
     }
     markSyncSubscriptionsOutOfDate() {
         for (const subscription of this.syncSubscriptions.values()) {
@@ -905,6 +1073,7 @@ export class GonvexClient {
                 subscription.cursor = cached.cursor;
                 subscription.keyField = cached.keyField;
                 subscription.mode = cached.mode;
+                subscription.truncated = cached.truncated;
                 subscription.orderBy = cached.orderBy;
                 subscription.orderDirection = cached.orderDirection;
                 subscription.maxRows = cached.maxRows;
@@ -915,6 +1084,7 @@ export class GonvexClient {
                 subscription.hashes = {};
                 subscription.integrityDigest = undefined;
                 subscription.integrityRows = undefined;
+                subscription.integrityEpoch = undefined;
                 const message = {
                     type: "sync.snapshot",
                     id: subscription.id,
@@ -958,6 +1128,7 @@ export class GonvexClient {
                 subscription.hashes = hashes;
                 subscription.integrityDigest = digest;
                 subscription.integrityRows = rows;
+                subscription.integrityEpoch = subscription.cursor?.epoch;
                 subscription.opening = false;
                 this.sendSyncOpen(subscription);
             }).catch(() => {
@@ -1039,7 +1210,11 @@ export class GonvexClient {
             this.send({ type: "sync.close", id: latest.id });
         }, this.syncSubscriptionRetentionMs);
     }
-    persistSyncSnapshot(subscription) {
+    persistSyncSnapshot(subscription, fromWatermark = false) {
+        if (!fromWatermark && subscription.watermarkPersistTimer) {
+            clearTimeout(subscription.watermarkPersistTimer);
+            subscription.watermarkPersistTimer = undefined;
+        }
         const directive = this.queryCacheDirective;
         const store = this.syncStore;
         if (!directive || !store || !subscription.cursor)
@@ -1054,6 +1229,7 @@ export class GonvexClient {
             cursor: subscription.cursor,
             keyField: subscription.keyField,
             mode: subscription.mode,
+            truncated: subscription.truncated,
             orderBy: subscription.orderBy,
             orderDirection: subscription.orderDirection,
             maxRows: subscription.maxRows,
@@ -1065,6 +1241,10 @@ export class GonvexClient {
         this.enqueueSyncPersistence(subscription, scope, () => store.replace(scope, subscription.path, subscription.args, value));
     }
     persistSyncDelta(subscription, upserts, deleted) {
+        if (subscription.watermarkPersistTimer) {
+            clearTimeout(subscription.watermarkPersistTimer);
+            subscription.watermarkPersistTimer = undefined;
+        }
         const directive = this.queryCacheDirective;
         const store = this.syncStore;
         if (!directive || !store || !subscription.cursor)
@@ -1074,6 +1254,7 @@ export class GonvexClient {
             cursor: subscription.cursor,
             keyField: subscription.keyField,
             mode: subscription.mode,
+            truncated: subscription.truncated,
             orderBy: subscription.orderBy,
             orderDirection: subscription.orderDirection,
             upserts,
@@ -1087,8 +1268,100 @@ export class GonvexClient {
         subscription.persistedRows = subscription.rows;
         this.enqueueSyncPersistence(subscription, scope, () => store.applyDelta(scope, subscription.path, subscription.args, value));
     }
+    async restoreOutbox() {
+        const entries = await this.mutationOutbox.loadAll();
+        if (this.manuallyClosed)
+            return;
+        for (const entry of entries) {
+            this.addOptimisticMutation(entry.idempotencyKey, entry.patches ?? []);
+        }
+        const nextAttemptAt = Math.min(...entries
+            .filter((entry) => entry.state === "pending")
+            .map((entry) => entry.nextAttemptAt));
+        if (Number.isFinite(nextAttemptAt) && nextAttemptAt > Date.now()) {
+            this.scheduleOutboxDrain(nextAttemptAt - Date.now());
+        }
+    }
+    addOptimisticMutation(mutationId, patches) {
+        if (patches.length === 0 || this.optimisticMutationIds.has(mutationId))
+            return;
+        this.optimisticMutationIds.add(mutationId);
+        this.overlay.add(mutationId, patches);
+    }
+    settleOptimisticMutation(mutationId) {
+        this.optimisticMutationIds.delete(mutationId);
+        this.overlay.settle(mutationId);
+    }
+    rejectOptimisticMutation(mutationId) {
+        this.optimisticMutationIds.delete(mutationId);
+        this.overlay.reject(mutationId);
+    }
+    async drainOutbox() {
+        await this.outboxReady;
+        if (this.drainingOutbox
+            || this.manuallyClosed
+            || !this.socket
+            || this.socket.readyState !== WebSocket.OPEN)
+            return;
+        this.drainingOutbox = true;
+        try {
+            while (!this.manuallyClosed && this.socket?.readyState === WebSocket.OPEN) {
+                const entry = await this.mutationOutbox.nextReady(Date.now());
+                if (!entry)
+                    return;
+                await this.mutationOutbox.markInflight(entry.id);
+                try {
+                    await this.call("mutation", { kind: "mutation", path: entry.path }, entry.args, this.timeouts.mutationTimeoutMs, entry.idempotencyKey);
+                    await this.mutationOutbox.ack(entry.id);
+                    this.settleOptimisticMutation(entry.idempotencyKey);
+                }
+                catch (error) {
+                    if (error instanceof GonvexClientError && error.code === "server") {
+                        await this.mutationOutbox.ack(entry.id);
+                        this.rejectOptimisticMutation(entry.idempotencyKey);
+                        continue;
+                    }
+                    await this.mutationOutbox.fail(entry.id, mutationErrorMessage(error));
+                    this.scheduleOutboxDrain(Math.min(30_000, 1_000 * (2 ** (entry.attempts + 1))));
+                    return;
+                }
+            }
+        }
+        finally {
+            this.drainingOutbox = false;
+        }
+    }
+    scheduleOutboxDrain(delay) {
+        if (this.manuallyClosed)
+            return;
+        if (this.outboxDrainTimer)
+            clearTimeout(this.outboxDrainTimer);
+        this.outboxDrainTimer = setTimeout(() => {
+            this.outboxDrainTimer = undefined;
+            void this.drainOutbox();
+        }, delay);
+    }
     mutation(ref, args = {}, options = {}) {
-        return this.call("mutation", ref, args, options.timeoutMs ?? this.timeouts.mutationTimeoutMs);
+        const mutationId = randomID();
+        const patches = options.optimistic ?? [];
+        this.addOptimisticMutation(mutationId, patches);
+        return this.call("mutation", ref, args, options.timeoutMs ?? this.timeouts.mutationTimeoutMs, mutationId).then((result) => {
+            this.settleOptimisticMutation(mutationId);
+            return result;
+        }).catch(async (error) => {
+            if (isQueueableMutationError(error) && options.offline === "queue") {
+                await this.mutationOutbox.enqueue({
+                    path: ref.path,
+                    args,
+                    idempotencyKey: mutationId,
+                    entityKeys: patches.map((patch) => patch.rowId),
+                    patches,
+                });
+                return { status: "queued", mutationId };
+            }
+            this.rejectOptimisticMutation(mutationId);
+            throw error;
+        });
     }
     action(ref, args = {}, options = {}) {
         return this.call("action", ref, args, options.timeoutMs ?? this.timeouts.actionTimeoutMs);
@@ -1206,9 +1479,9 @@ export class GonvexClient {
         this.notifyConnectionState();
         return Promise.all(registered.map((entry) => settle(entry.promise, entry.path)));
     }
-    call(kind, ref, args, timeoutMs) {
+    call(kind, ref, args, timeoutMs, id) {
         this.connect();
-        const entry = this.registerCall(kind, ref, args, timeoutMs);
+        const entry = this.registerCall(kind, ref, args, timeoutMs, id);
         if (kind === "mutation") {
             try {
                 const w = globalThis;
@@ -1224,8 +1497,8 @@ export class GonvexClient {
         this.notifyConnectionState();
         return entry.promise;
     }
-    registerCall(kind, ref, args, timeoutMs) {
-        const id = randomID();
+    registerCall(kind, ref, args, timeoutMs, callId = randomID()) {
+        const id = callId;
         const clientSentAtMs = nowMs();
         const promise = new Promise((resolve, reject) => {
             const pending = { id, kind, path: ref.path, reject };
@@ -1525,12 +1798,17 @@ export class GonvexClient {
         this.syncScopeGeneration += 1;
         for (const subscription of this.syncSubscriptions.values()) {
             this.clearSyncRetry(subscription, true);
+            if (subscription.watermarkPersistTimer) {
+                clearTimeout(subscription.watermarkPersistTimer);
+                subscription.watermarkPersistTimer = undefined;
+            }
             subscription.isUpToDate = false;
             subscription.rows = [];
             subscription.persistedRows = undefined;
             subscription.hashes = {};
             subscription.integrityDigest = undefined;
             subscription.integrityRows = undefined;
+            subscription.integrityEpoch = undefined;
             subscription.forceFullIntegrity = false;
             subscription.cursor = undefined;
             subscription.lastMessage = undefined;
@@ -1675,11 +1953,20 @@ export class GonvexClient {
             device: event.device ?? browserTelemetryInfo(),
         });
     }
-    sendAuth(force) {
-        if (!force && !this.auth.token && !this.auth.tenant && !this.auth.project)
+    sendAuth(force, options = {}) {
+        if (!force && !this.auth.token && !this.auth.tenant && !this.auth.project && !this.auth.fetchToken)
             return;
         this.authInFlight = true;
+        this.authRetriedAfterError = false;
         this.armAuthWatchdog();
+        const fetcher = this.auth.fetchToken;
+        if (fetcher && options.useFetcher !== false) {
+            void this.fetchAndSendAuth(fetcher);
+            return;
+        }
+        this.sendAuthFrame();
+    }
+    sendAuthFrame() {
         this.sendNow({
             type: "auth",
             id: randomID(),
@@ -1687,8 +1974,77 @@ export class GonvexClient {
             project: this.auth.project,
             tenant: this.auth.tenant,
             device: browserTelemetryInfo(),
+            capabilities: { syncReadyMany: 1, syncWatermark: 1 },
         });
     }
+    // Tokens from a fetcher are typically short-lived while the socket (and any
+    // disconnect gap) can span hours: replaying the token that was current at
+    // setAuth time guarantees an auth.error after a long sleep. authInFlight is
+    // already true here, so everything else queues behind the fetch exactly as
+    // it queues behind the server's auth reply.
+    async fetchAndSendAuth(fetcher) {
+        const generation = ++this.authFetchGeneration;
+        const socket = this.socket;
+        let token;
+        try {
+            token = await fetcher({ forceRefreshToken: false });
+        }
+        catch {
+            // A fetcher that cannot reach its identity provider (offline start)
+            // must not sign the session out — fall back to the installed token.
+            token = undefined;
+        }
+        if (generation !== this.authFetchGeneration || this.auth.fetchToken !== fetcher)
+            return;
+        if (typeof token === "string" && token) {
+            this.applyAuth({ token });
+        }
+        else if (token === null) {
+            // The fetcher is authoritative about sign-out.
+            this.applyAuth({ token: undefined });
+        }
+        // A dead socket's close handler already reset authInFlight; the next
+        // reconnect runs its own sendAuth, so this resolve has nothing to send.
+        if (this.socket !== socket || socket?.readyState !== WebSocket.OPEN)
+            return;
+        this.sendAuthFrame();
+    }
+    async refreshRejectedAuth(fetcher, rejectedToken, error) {
+        const generation = ++this.authFetchGeneration;
+        const socket = this.socket;
+        let token;
+        try {
+            token = await fetcher({ forceRefreshToken: true });
+        }
+        catch {
+            token = undefined;
+        }
+        if (generation !== this.authFetchGeneration || this.auth.fetchToken !== fetcher)
+            return;
+        if (typeof token === "string" && token && token !== rejectedToken) {
+            this.applyAuth({ token });
+            if (this.socket === socket && socket?.readyState === WebSocket.OPEN) {
+                this.sendAuthFrame();
+            }
+            return;
+        }
+        // No fresher credential exists (fetch failed, signed out, or the refresh
+        // returned the very token the server just refused): surface the rejection
+        // and degrade to the unauthenticated flow exactly like the no-fetcher path.
+        this.authInFlight = false;
+        if (this.authWatchdogTimer) {
+            clearTimeout(this.authWatchdogTimer);
+            this.authWatchdogTimer = undefined;
+        }
+        this.resetQueryCacheScope();
+        this.notifyAuthError(error);
+        this.flushPendingMessages();
+    }
+    notifyAuthError(error) {
+        for (const handler of Array.from(this.authErrorHandlers)) {
+            handler(error);
+        }
+    }
     // A lost auth reply (e.g. the server swapped its app plugin and dropped
     // in-flight responses while the socket stayed up) used to leave
     // authInFlight stuck true forever: every later mutation/subscription
@@ -1761,6 +2117,13 @@ function countPendingCalls(calls, kind) {
     }
     return count;
 }
+function isQueueableMutationError(error) {
+    return error instanceof GonvexClientError
+        && (error.code === "disconnected" || error.code === "timeout");
+}
+function mutationErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function stableStringify(value) {
     if (typeof value === "string") {
         return JSON.stringify(value)
@@ -1891,6 +2254,7 @@ function authFromOptions(options) {
         tenant: options.tenant,
         telemetry: options.telemetry,
         identity: options.identity,
+        fetchToken: options.fetchToken,
     };
 }
 function normalizeQuerySubscriptionRetentionMs(value) {