@koolbase/react-native 9.1.0 → 9.2.0

package/dist/offline-state.js

@@ -0,0 +1,200 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineStateTooLargeError = void 0;
+exports.recordKey = recordKey;
+exports.readOfflineState = readOfflineState;
+exports.mutateOfflineState = mutateOfflineState;
+exports.queueWrite = queueWrite;
+exports.migrateLegacyQueue = migrateLegacyQueue;
+const async_storage_1 = __importDefault(require("@react-native-async-storage/async-storage"));
+/**
+ * The offline system's correctness-critical state: writes waiting to be sent,
+ * and writes the server refused because the record moved underneath them.
+ *
+ * Both live under one key so moving between them is a single write. A conflict
+ * recorded without removing the pending write would replay and be refused
+ * forever; a pending write removed without recording the conflict would lose a
+ * change the user believes is saved. Two keys admit both outcomes.
+ *
+ * Records are cached separately, per record. Putting them here would let a
+ * growing cache push this value past a storage ceiling and make the queue
+ * unreadable — losing the correctness-critical state to something incidental.
+ */
+const VERSION = 'v1';
+function stateKey(userId) {
+    return `koolbase:${VERSION}:${userId}:offline-state`;
+}
+function recordKey(userId, collection, recordId) {
+    return `koolbase:${VERSION}:${userId}:record:${collection}:${recordId}`;
+}
+const EMPTY = { pending: [], conflicts: [] };
+/**
+ * A conservative ceiling, below the lowest per-value limit any supported
+ * AsyncStorage implementation imposes.
+ *
+ * Not a claim about a platform maximum — a boundary that leaves headroom for
+ * rewriting and migration. A queue that cannot be written is a queue that
+ * silently stops accepting work, so the limit is enforced with an error rather
+ * than discovered.
+ */
+const MAX_STATE_BYTES = 1000000;
+class OfflineStateTooLargeError extends Error {
+    constructor(bytes) {
+        super(`Offline state is ${bytes} bytes, above the ${MAX_STATE_BYTES} byte limit. ` +
+            'Sync or resolve what is queued before making more offline changes.');
+        this.name = 'OfflineStateTooLargeError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.OfflineStateTooLargeError = OfflineStateTooLargeError;
+/**
+ * Serialises access per user.
+ *
+ * A single setItem is one storage operation, but read-modify-write is not: two
+ * callers can both read, both modify, and the second write silently discards
+ * the first. Two components queueing a write in the same tick is enough. The
+ * lock is in-process — one JavaScript runtime is the assumption every React
+ * Native app satisfies, and the SDK does not promise more.
+ */
+/** UTF-8 byte length, without depending on TextEncoder being present. */
+function byteLength(s) {
+    if (typeof TextEncoder !== 'undefined') {
+        return new TextEncoder().encode(s).length;
+    }
+    let bytes = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.codePointAt(i);
+        if (c > 0xffff)
+            i++; // surrogate pair, counted once
+        bytes += c < 0x80 ? 1 : c < 0x800 ? 2 : c < 0x10000 ? 3 : 4;
+    }
+    return bytes;
+}
+const locks = new Map();
+async function withLock(userId, fn) {
+    const previous = locks.get(userId) ?? Promise.resolve();
+    let release = () => { };
+    const next = new Promise((resolve) => { release = resolve; });
+    locks.set(userId, previous.then(() => next));
+    await previous;
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        if (locks.get(userId) === next)
+            locks.delete(userId);
+    }
+}
+async function readOfflineState(userId) {
+    try {
+        const raw = await async_storage_1.default.getItem(stateKey(userId));
+        if (!raw)
+            return { ...EMPTY, pending: [], conflicts: [] };
+        const parsed = JSON.parse(raw);
+        return { pending: parsed.pending ?? [], conflicts: parsed.conflicts ?? [] };
+    }
+    catch {
+        // Unreadable state is treated as empty rather than throwing: an app that
+        // cannot start is worse than one that has lost a queue it could not read
+        // anyway. The write path's size guard is what keeps this from happening.
+        return { pending: [], conflicts: [] };
+    }
+}
+/**
+ * Reads, mutates, and writes the state under the user's lock.
+ *
+ * Every mutation goes through here. A caller that reads and writes separately
+ * reintroduces the race this exists to prevent.
+ */
+async function mutateOfflineState(userId, mutate) {
+    await withLock(userId, async () => {
+        const state = await readOfflineState(userId);
+        mutate(state);
+        const serialised = JSON.stringify(state);
+        // Bytes, not characters. String length undercounts anything outside ASCII —
+        // an accented name, any non-Latin script — so a limit measured in
+        // characters permits more than it claims, which is the wrong direction for
+        // a safety boundary. TextEncoder is not guaranteed in every React Native
+        // runtime, so fall back to a byte count computed directly.
+        const bytes = byteLength(serialised);
+        if (bytes > MAX_STATE_BYTES) {
+            throw new OfflineStateTooLargeError(bytes);
+        }
+        await async_storage_1.default.setItem(stateKey(userId), serialised);
+    });
+}
+/** Adds a write to the queue, under the user's lock. */
+async function queueWrite(userId, write) {
+    await mutateOfflineState(userId, (state) => {
+        state.pending.push({
+            ...write,
+            retries: 0,
+            enqueuedAt: new Date().toISOString(),
+        });
+    });
+}
+const LEGACY_QUEUE_VERSION = 'v1';
+function legacyQueueKey(userId) {
+    return `koolbase:${LEGACY_QUEUE_VERSION}:${userId}:write_queue`;
+}
+/**
+ * Moves writes queued by an earlier version into the current state.
+ *
+ * Runs once, before any replay, and never contacts the network. Migration that
+ * depended on connectivity would give the same input two different outcomes
+ * depending on whether the device happened to be online at startup — which is
+ * how a bug becomes unreproducible.
+ *
+ * Inserts carry everything they need and simply move across. Updates and
+ * deletes do not: they were queued before baselines were recorded, so replaying
+ * one would apply it blindly and overwrite whatever changed in the meantime.
+ * They are preserved as waiting for a decision instead — the change is not lost,
+ * and nothing is written on a guess.
+ */
+async function migrateLegacyQueue(userId) {
+    const raw = await async_storage_1.default.getItem(legacyQueueKey(userId));
+    if (!raw)
+        return;
+    let legacy = [];
+    try {
+        legacy = JSON.parse(raw);
+    }
+    catch {
+        // Unreadable: nothing recoverable, and leaving the key would retry forever.
+        await async_storage_1.default.removeItem(legacyQueueKey(userId));
+        return;
+    }
+    await mutateOfflineState(userId, (state) => {
+        for (const w of legacy) {
+            const operation = w.type;
+            if (operation === 'insert') {
+                state.pending.push({
+                    id: w.id,
+                    operation: 'insert',
+                    collection: w.collection,
+                    recordId: w.recordId,
+                    data: w.data,
+                    retries: w.retries ?? 0,
+                    enqueuedAt: w.createdAt ?? new Date().toISOString(),
+                });
+                continue;
+            }
+            if (!w.recordId)
+                continue;
+            state.conflicts.push({
+                id: w.id,
+                reason: 'baseline_unavailable',
+                operation,
+                collection: w.collection ?? '',
+                recordId: w.recordId,
+                local: w.data,
+                createdAt: w.createdAt ?? new Date().toISOString(),
+            });
+        }
+    });
+    await async_storage_1.default.removeItem(legacyQueueKey(userId));
+}

package/dist/pending-write.d.ts

@@ -0,0 +1,47 @@
+import { QueuedWrite } from './offline-state';
+/**
+ * A change made offline, waiting to be sent.
+ *
+ * The counterpart to KoolbaseConflict, one step earlier in the lifecycle: a
+ * conflict is a write the server refused; a pending write is one the server has
+ * not seen yet. Both are durable state an app should surface — a queue nobody
+ * can see accumulates invisibly, and the changes it holds feel saved to the
+ * user while existing only on this device.
+ *
+ * The case that makes this API matter: logout. Queues are per-user and survive
+ * logout by design, so a user signing out with pending writes walks away
+ * believing their edits saved — and they sync whenever that user next logs in
+ * on this device, which may be never. Warn before logout:
+ *
+ * ```ts
+ * const pending = await Koolbase.db.pendingWrites();
+ * if (pending.length > 0) {
+ *   // "You have 3 unsynced changes. Sync now, or they wait until you
+ *   //  next sign in on this device."
+ * }
+ * ```
+ *
+ * This is a snapshot, not a live handle — re-read after a sync. Per-user:
+ * another account's queue on this device is not visible here.
+ */
+export interface PendingWrite {
+    id: string;
+    operation: 'insert' | 'update' | 'delete';
+    collection: string;
+    /** Absent for an insert the server has not yet assigned. */
+    recordId?: string;
+    /** What the user changed. Absent for a delete. */
+    data?: Record<string, unknown>;
+    enqueuedAt: string;
+    /** Failed send attempts so far. A count, not a policy — nothing drops it. */
+    attempts: number;
+}
+/**
+ * Maps the stored write to its public shape, field by field.
+ *
+ * Deliberately not a spread: the stored write carries baseline and baseRevision
+ * — replay mechanics, not contract. A spread would leak whatever the storage
+ * shape grows next; naming each field means new internals stay internal until
+ * someone chooses otherwise.
+ */
+export declare function toPendingWrite(w: QueuedWrite): PendingWrite;

package/dist/pending-write.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPendingWrite = toPendingWrite;
+/**
+ * Maps the stored write to its public shape, field by field.
+ *
+ * Deliberately not a spread: the stored write carries baseline and baseRevision
+ * — replay mechanics, not contract. A spread would leak whatever the storage
+ * shape grows next; naming each field means new internals stay internal until
+ * someone chooses otherwise.
+ */
+function toPendingWrite(w) {
+    return {
+        id: w.id,
+        operation: w.operation,
+        collection: w.collection,
+        recordId: w.recordId,
+        data: w.data,
+        enqueuedAt: w.enqueuedAt,
+        attempts: w.retries,
+    };
+}

package/dist/realtime.d.ts

@@ -6,13 +6,38 @@ export declare class KoolbaseRealtime {
     private ws;
     private projectId;
     private listeners;
+    private reconnectAttempts;
     private reconnectTimer;
     private connecting;
-    constructor(config: KoolbaseConfig, getToken: TokenProvider);
+    /**
+     * Identifies whose cache a seen record belongs in.
+     *
+     * The record cache is keyed by user, so without this a watched record would
+     * be filed under the wrong key — or under 'anonymous', which is worse than
+     * not caching at all: a baseline stored where it will never be read.
+     */
+    private getUserId?;
+    constructor(config: KoolbaseConfig, getToken: TokenProvider, getUserId?: () => string | null);
+    /** Files a record seen over the socket, if we know whose it is. */
+    private cacheSeenRecord;
+    private forgetSeenRecord;
     subscribe(collection: string, callback: RealtimeCallback): () => void;
     private connect;
     private sendSubscribe;
     private sendUnsubscribe;
+    /**
+     * Reconnects with backoff, rather than every three seconds forever.
+     *
+     * A fixed interval is fine while a connection is merely interrupted and
+     * costly when it is not: a device with no network, a wrong URL, or a session
+     * the server will not accept retried indefinitely, draining battery and data
+     * the user cannot see or stop.
+     *
+     * Doubling from three seconds to a minute keeps a brief interruption
+     * recovering quickly while a lasting one settles into an interval that costs
+     * almost nothing. The counter resets when a connection opens, so a flaky link
+     * does not accumulate delay.
+     */
     private scheduleReconnect;
     disconnect(): void;
 }

package/dist/realtime.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseRealtime = void 0;
+const cache_store_1 = require("./cache-store");
 const record_1 = require("./record");
 const EVENT_TYPE_MAP = {
     'db.record.created': 'created',
@@ -32,14 +33,29 @@ function projectIdFromToken(token) {
     }
 }
 class KoolbaseRealtime {
-    constructor(config, getToken) {
+    constructor(config, getToken, getUserId) {
         this.ws = null;
         this.projectId = null;
         this.listeners = new Map();
+        this.reconnectAttempts = 0;
         this.reconnectTimer = null;
         this.connecting = false;
         this.config = config;
         this.getToken = getToken;
+        this.getUserId = getUserId;
+    }
+    /** Files a record seen over the socket, if we know whose it is. */
+    async cacheSeenRecord(collection, record) {
+        const userId = this.getUserId?.();
+        if (!userId)
+            return;
+        await (0, cache_store_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
+    }
+    async forgetSeenRecord(recordId) {
+        const userId = this.getUserId?.();
+        if (!userId)
+            return;
+        await (0, cache_store_1.removeCachedRecord)(userId, recordId);
     }
     subscribe(collection, callback) {
         if (!this.listeners.has(collection))
@@ -79,6 +95,10 @@ class KoolbaseRealtime {
         this.ws = ws;
         ws.onopen = () => {
             this.connecting = false;
+            // A connection that opened is the only proof the endpoint and the
+            // credentials are usable, so the backoff resets here rather than on a
+            // close — a flaky link should not accumulate delay.
+            this.reconnectAttempts = 0;
             for (const collection of this.listeners.keys())
                 this.sendSubscribe(collection); // (re)subscribe all
         };
@@ -99,9 +119,21 @@ class KoolbaseRealtime {
             let msg;
             if (mapped === 'deleted') {
                 msg = { type: 'deleted', collection: payload.collection, recordId: payload.record_id };
+                // Gone for everyone, so the cached copy is no longer a baseline for
+                // anything. An edit composed against it would be refused at replay
+                // regardless; removing it makes that a local refusal rather than a
+                // round trip.
+                void this.forgetSeenRecord(payload.record_id);
             }
             else if (payload.record) {
-                msg = { type: mapped, collection: payload.collection, record: (0, record_1.recordFromWire)(payload.record) };
+                const record = (0, record_1.recordFromWire)(payload.record);
+                msg = { type: mapped, collection: payload.collection, record };
+                // A record seen over the socket is as freshly seen as one fetched, and
+                // a client watching a collection would otherwise hold a stale baseline
+                // while looking at the change. Writes already queued are unaffected:
+                // their baseline was copied in when they were made, so this cannot move
+                // ground beneath them.
+                void this.cacheSeenRecord(payload.collection, record);
             }
             else {
                 return;
@@ -126,13 +158,28 @@ class KoolbaseRealtime {
             return;
         this.ws.send(JSON.stringify({ action: 'unsubscribe', project_id: this.projectId, collection }));
     }
+    /**
+     * Reconnects with backoff, rather than every three seconds forever.
+     *
+     * A fixed interval is fine while a connection is merely interrupted and
+     * costly when it is not: a device with no network, a wrong URL, or a session
+     * the server will not accept retried indefinitely, draining battery and data
+     * the user cannot see or stop.
+     *
+     * Doubling from three seconds to a minute keeps a brief interruption
+     * recovering quickly while a lasting one settles into an interval that costs
+     * almost nothing. The counter resets when a connection opens, so a flaky link
+     * does not accumulate delay.
+     */
     scheduleReconnect() {
         if (this.listeners.size === 0 || this.reconnectTimer)
             return;
+        const delay = Math.min(3000 * Math.pow(2, this.reconnectAttempts), 60000);
+        this.reconnectAttempts += 1;
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             void this.connect();
-        }, 3000);
+        }, delay);
     }
     disconnect() {
         if (this.reconnectTimer) {

package/dist/record.js

@@ -16,5 +16,8 @@ function recordFromWire(raw) {
         data,
         createdAt: raw['$createdAt'],
         updatedAt: raw['$updatedAt'],
+        revision: typeof raw['$revision'] === 'number'
+            ? raw['$revision']
+            : undefined,
     };
 }

package/dist/storage-errors.d.ts

@@ -1,10 +1,10 @@
+import { KoolbaseError } from './errors';
 /**
  * Base error type for all Koolbase storage errors. Catchable via
  * `instanceof KoolbaseStorageError` to handle any storage-related failure
  * generically; subclasses let you handle specific cases.
  */
-export declare class KoolbaseStorageError extends Error {
-    code?: string;
+export declare class KoolbaseStorageError extends KoolbaseError {
     constructor(message: string, code?: string);
 }
 /**

package/dist/storage-errors.js

@@ -3,15 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
 exports.koolbaseStorageError = koolbaseStorageError;
 exports.koolbaseStorageErrorFromResponse = koolbaseStorageErrorFromResponse;
+const errors_1 = require("./errors");
 /**
  * Base error type for all Koolbase storage errors. Catchable via
  * `instanceof KoolbaseStorageError` to handle any storage-related failure
  * generically; subclasses let you handle specific cases.
  */
-class KoolbaseStorageError extends Error {
+class KoolbaseStorageError extends errors_1.KoolbaseError {
     constructor(message, code) {
-        super(message);
-        this.code = code;
+        super(message, code);
         this.name = 'KoolbaseStorageError';
         Object.setPrototypeOf(this, KoolbaseStorageError.prototype);
     }
@@ -226,6 +226,10 @@ function koolbaseStorageError(status, body, fallbackMessage = 'Storage request f
             return new KoolbaseStorageMimeTypeError(message);
         case 404:
             return new KoolbaseStorageNotFoundError(message);
+        case 401:
+            // A rejected credential is not a storage problem: a session stops
+            // working for the whole SDK at once, so it raises the shared type.
+            return new errors_1.KoolbaseUnauthenticatedError(message);
         case 403:
             return new KoolbaseStoragePermissionError(message);
         case 400:

package/dist/storage.d.ts

@@ -10,7 +10,21 @@ import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject, KoolbaseOb
 export declare class KoolbaseStorage {
     private config;
     private getToken;
-    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>);
+    /**
+     * Called when the server rejects the caller's credentials.
+     *
+     * A session stops working for the whole SDK at once, not one subsystem at a
+     * time, so a 401 met during an upload has to clear it just as one met during a
+     * query does. Otherwise an app whose failing call happens to be a file upload
+     * keeps believing it is signed in.
+     */
+    private onSessionExpired?;
+    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
+    /**
+     * Builds the error for a failed response and clears the session when the
+     * credentials were refused, before the error reaches the caller.
+     */
+    private error;
     private buildHeaders;
     /**
      * Upload a file to a bucket. Returns the object metadata and a download URL.

package/dist/storage.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseStorage = void 0;
+const errors_1 = require("./errors");
 const storage_errors_1 = require("./storage-errors");
 // --- Cloudflare image-transform URL helpers -------------------------------
 // Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
@@ -40,9 +41,21 @@ function serializeTransform(t) {
  * `overwrite: true` is passed.
  */
 class KoolbaseStorage {
-    constructor(config, getToken) {
+    constructor(config, getToken, onSessionExpired) {
         this.config = config;
         this.getToken = getToken;
+        this.onSessionExpired = onSessionExpired;
+    }
+    /**
+     * Builds the error for a failed response and clears the session when the
+     * credentials were refused, before the error reaches the caller.
+     */
+    async error(res, fallback) {
+        const err = await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, fallback);
+        if (err instanceof errors_1.KoolbaseUnauthenticatedError) {
+            await this.onSessionExpired?.();
+        }
+        return err;
     }
     async buildHeaders() {
         const token = await this.getToken();
@@ -91,7 +104,7 @@ class KoolbaseStorage {
             }),
         });
         if (!urlRes.ok) {
-            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(urlRes, 'Failed to get upload URL');
+            throw await this.error(urlRes, 'Failed to get upload URL');
         }
         const { upload_url } = (await urlRes.json());
         // ─── Step 2: Upload directly to R2 ───
@@ -136,7 +149,7 @@ class KoolbaseStorage {
             body: JSON.stringify(confirmBody),
         });
         if (!confirmRes.ok) {
-            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(confirmRes, 'Failed to confirm upload');
+            throw await this.error(confirmRes, 'Failed to confirm upload');
         }
         const raw = await confirmRes.json();
         const object = mapObjectFromServer(raw);
@@ -187,7 +200,7 @@ class KoolbaseStorage {
             body: JSON.stringify({ bucket, path, metadata }),
         });
         if (!res.ok) {
-            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to update metadata');
+            throw await this.error(res, 'Failed to update metadata');
         }
         const raw = await res.json();
         return mapObjectFromServer(raw);
@@ -203,7 +216,7 @@ class KoolbaseStorage {
         }
         const res = await fetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
-            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to get download URL');
+            throw await this.error(res, 'Failed to get download URL');
         }
         const data = (await res.json());
         return data.url;
@@ -307,7 +320,7 @@ class KoolbaseStorage {
         if (res.status === 204)
             return;
         if (!res.ok) {
-            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to delete file');
+            throw await this.error(res, 'Failed to delete file');
         }
     }
     /**
@@ -325,7 +338,7 @@ class KoolbaseStorage {
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
         const res = await fetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
-            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to list versions');
+            throw await this.error(res, 'Failed to list versions');
         }
         const data = (await res.json());
         const list = Array.isArray(data.versions) ? data.versions : [];
@@ -341,7 +354,7 @@ class KoolbaseStorage {
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
         const res = await fetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
-            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to fetch version');
+            throw await this.error(res, 'Failed to fetch version');
         }
         return fromVersionJson((await res.json()));
     }
@@ -363,7 +376,7 @@ class KoolbaseStorage {
             headers: await this.buildHeaders(),
         });
         if (!res.ok) {
-            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to restore version');
+            throw await this.error(res, 'Failed to restore version');
         }
         return mapObjectFromServer(await res.json());
     }
@@ -383,7 +396,7 @@ class KoolbaseStorage {
         if (res.status === 204)
             return;
         if (!res.ok) {
-            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to purge version');
+            throw await this.error(res, 'Failed to purge version');
         }
     }
 }

package/dist/sync-engine.d.ts

@@ -5,12 +5,26 @@ export declare class SyncEngine {
     private getUserId;
     private getToken;
     private onSyncComplete?;
+    /**
+     * Called when the server rejects the caller's credentials during replay.
+     *
+     * Background sync is the likeliest place to meet a dead session: the queue
+     * replays writes made long before the session stopped being honoured.
+     */
+    private onSessionExpired?;
     private unsubscribe?;
     private isSyncing;
-    constructor(config: KoolbaseConfig, getUserId: () => string | null, getToken: () => Promise<string | null>, onSyncComplete?: SyncCallback);
+    constructor(config: KoolbaseConfig, getUserId: () => string | null, getToken: () => Promise<string | null>, onSyncComplete?: SyncCallback, onSessionExpired?: () => Promise<void>);
     start(): void;
     stop(): void;
     flush(): Promise<void>;
+    /**
+     * Sends one queued write, returning the revision the record now carries.
+     *
+     * The revision matters to whatever is queued behind this for the same record:
+     * those were composed against this one's result and cannot know its revision
+     * until the server assigns it.
+     */
     private executeWrite;
 }
 export {};