@abloatai/ablo 0.25.0 → 0.27.0

package/dist/sync/{BootstrapHelper.js → BootstrapFetcher.js}

@@ -1,13 +1,17 @@
 /**
- * BootstrapHelper - Fixed to always fetch fresh data
- * Removed problematic caching that was serving stale data
+ * Fetches the initial snapshot the sync engine needs before it can go live: the
+ * current rows for the requested models plus the sync position from which to
+ * resume live updates. It calls the sync server's `/sync/bootstrap` HTTP
+ * endpoint, retries transient failures with backoff, and can fall back to a
+ * cached snapshot when the device is offline. {@link BootstrapData} is the
+ * shape it returns; {@link BootstrapOptions} configures it.
  */
 import { getContext } from '../context.js';
 import { SyncSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '../errors.js';
 import { withAuthHeaders } from '../auth/credentialSource.js';
 // SyncObservability replaced by getContext().observability
 import { parseBootstrapResponse } from './schemas.js';
-export class BootstrapHelper {
+export class BootstrapFetcher {
     options;
     abortController = null;
     /** Warn about schema drift at most once per helper. */
@@ -39,23 +43,20 @@ export class BootstrapHelper {
             `\`ablo push\` to deploy your schema (or update this app to match the deployed one).`, { clientSchemaHash: clientHash, serverSchemaHash: serverHash });
     }
     constructor(options) {
-        // Defaults are spread first; the explicit `baseUrl` then takes precedence
-        // and is computed from `options.baseUrl` (or the localhost fallback).
-        //
-        // Historical note: a previous version of this constructor placed
-        // `baseUrl: \`${baseUrl}/api\`` BEFORE the `...options` spread, which
-        // meant the spread silently overwrote it back to the caller's value
-        // and the `/api` suffix was dead code. Both Ablo and `createSyncEngine`
-        // already pass `${url}/api` explicitly, so removing the suffix here
-        // preserves the actual on-the-wire behavior while making the contract
-        // explicit: callers pass the full base URL including `/api`.
+        // Defaults are spread first; the explicit `baseUrl` then takes precedence,
+        // resolved from `options.baseUrl` or the localhost fallback. Callers pass
+        // the full base URL, including the `/api` prefix.
         this.options = {
             syncGroups: [],
             maxRetries: 3,
             retryDelay: 1000,
             fetchTimeout: 10_000, // 10 second timeout per request - fail fast for good UX
             ...options,
-            baseUrl: options.baseUrl || 'http://localhost:8080/api',
+            baseUrl: options.baseUrl ?? 'http://localhost:8080/api',
+            // Reading the deprecated `organizationId` is deliberate: it preserves the
+            // cache namespace for callers that still construct BootstrapFetcher
+            // directly with the old field instead of `cacheScope`.
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             cacheScope: options.cacheScope ?? options.organizationId ?? null,
         };
         // Do not clear cache here; keep offline fallback available
@@ -73,8 +74,8 @@ export class BootstrapHelper {
         this.options.syncGroups = [...(syncGroups ?? [])];
     }
     /**
-     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
-     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     * Sets a fixed credential for callers that construct the helper directly.
+     * The SDK instead supplies `getAuthToken` and never calls this.
      */
     setAuthToken(authToken) {
         if (!authToken) {
@@ -83,26 +84,6 @@ export class BootstrapHelper {
         }
         this.options.authToken = authToken;
     }
-    /**
-     * Create a promise that rejects after a timeout
-     * Used to race against fetch requests that may hang indefinitely
-     */
-    createTimeoutPromise(ms, operation) {
-        return new Promise((_, reject) => {
-            setTimeout(() => {
-                reject(new AbloConnectionError(`Bootstrap ${operation} timed out after ${ms}ms`, {
-                    code: 'bootstrap_fetch_timeout',
-                }));
-            }, ms);
-        });
-    }
-    /**
-     * Wrap a promise with a timeout - if the promise doesn't resolve within
-     * the timeout period, the AbortController is triggered and an error is thrown
-     */
-    async withTimeout(promise, timeoutMs, operation) {
-        return Promise.race([promise, this.createTimeoutPromise(timeoutMs, operation)]);
-    }
     /**
      * Fetch bootstrap data from sync engine with partial bootstrap support
      * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
@@ -110,11 +91,12 @@ export class BootstrapHelper {
      */
     async fetchBootstrap(lastSyncId, 
     /**
-     * Per-call sync-group override for SCOPED hydrate-on-enter. When provided,
-     * the request uses THESE groups instead of `this.options.syncGroups`,
-     * WITHOUT mutating the shared options (so a concurrent full bootstrap is
-     * unaffected). Also bypasses the offline full-snapshot cache below, which
-     * holds the connection's full bootstrap and would be wrong for a subset.
+     * A per-call set of sync groups for a scoped hydrate-on-enter. When given,
+     * the request uses these groups instead of the configured `syncGroups`, and
+     * does so without mutating the shared options, so a concurrent full
+     * bootstrap is unaffected. It also bypasses the offline snapshot cache,
+     * which holds the full bootstrap and would be a wrong answer to a subset
+     * request.
      */
     syncGroupsOverride) {
         // organizationId omitted — server reads it from auth identity.
@@ -135,10 +117,19 @@ export class BootstrapHelper {
             params.append('models', this.options.instantModels.join(','));
         }
         const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
-        // If offline, try cached bootstrap. Skipped for a scoped override — the
-        // cache holds the FULL snapshot, which is not a valid answer to a subset
+        // If offline, try the cached bootstrap. Skipped for a scoped override: the
+        // cache holds the full snapshot, which is not a valid answer to a subset
         // request; a scoped hydrate just soft-fails offline and retries on re-enter.
-        if (!syncGroupsOverride && typeof navigator !== 'undefined' && navigator && navigator.onLine === false) {
+        //
+        // Only an explicit `false` means offline. `navigator.onLine` is *typed*
+        // `boolean`, but at runtime it is `boolean | undefined`: Node 21+ exposes a
+        // global `navigator` whose `onLine` is `undefined`. Reading `!navigator.onLine`
+        // would treat that `undefined` as offline and falsely short-circuit to the
+        // (empty, under `persistence: 'memory'`) cache — throwing instead of fetching.
+        // Capturing it at its true runtime type keeps the `=== false` honest (and lets
+        // the boolean-literal-compare lint rule see the nullable it really is).
+        const navigatorOnline = typeof navigator !== 'undefined' ? navigator.onLine : undefined;
+        if (!syncGroupsOverride && navigatorOnline === false) {
             const cached = this.options.cacheScope
                 ? this.loadCachedBootstrap(this.options.cacheScope)
                 : null;
@@ -160,7 +151,7 @@ export class BootstrapHelper {
                     type: data.type,
                     lastSyncId: data.lastSyncId,
                     modelCount: data.models ? Object.keys(data.models).length : 0,
-                    deltaCount: data.deltaCount || 0,
+                    deltaCount: data.deltaCount ?? 0,
                     totalItems: data.models
                         ? Object.values(data.models).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0)
                         : 0,
@@ -176,7 +167,7 @@ export class BootstrapHelper {
                 // Also do NOT fallback to cache - the user must sign in again
                 if (SyncSessionError.isSessionError(error)) {
                     getContext().observability.breadcrumb('Bootstrap session error - redirecting to sign-in', 'sync.bootstrap', 'warning', {
-                        statusCode: error.statusCode,
+                        statusCode: (error).statusCode,
                     });
                     throw error;
                 }
@@ -220,13 +211,11 @@ export class BootstrapHelper {
      * Fetch bootstrap with ETag, returning 304 hints
      */
     async fetchBootstrapWithETag() {
-        // organizationId is intentionally NOT sent. Server resolves it from
-        // the authenticated identity (`c.var.identity.organizationId`) —
-        // see `apps/sync-server/src/routes/bootstrap.ts`. Sending it
-        // client-side was historical: it predated the auth-context pipeline
-        // and forced a cross-org guard to defend against the SDK lying.
+        // The organization id is intentionally not sent. The server resolves it
+        // from the authenticated identity, so the client cannot select or spoof an
+        // organization it is not scoped to.
         const params = new URLSearchParams();
-        this.options.syncGroups.forEach((g) => params.append('syncGroups', g));
+        this.options.syncGroups.forEach((g) => { params.append('syncGroups', g); });
         if (this.options.instantModels && this.options.instantModels.length > 0) {
             params.append('models', this.options.instantModels.join(','));
         }
@@ -252,7 +241,10 @@ export class BootstrapHelper {
         }
         if (!res.ok) {
             const bodyText = await res.text().catch(() => '');
-            let parsed = bodyText;
+            // Map an empty body to undefined so the `??` below falls through to the
+            // synthetic message — translateHttpError renders an empty string body as
+            // an empty error message, which is useless to the caller.
+            let parsed = bodyText || undefined;
             if (bodyText) {
                 try {
                     parsed = JSON.parse(bodyText);
@@ -261,12 +253,13 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            // Translate the canonical envelope FIRST so the server's specific code +
-            // message survive (e.g. `api_key_required`, `jwt_issuer_untrusted`).
-            const translated = translateHttpError(res.status, parsed || `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
-            // Only a genuine session/JWT EXPIRY — or a bare auth failure carrying no
-            // structured code — should drive the sign-in redirect. A specific auth
-            // code like `api_key_required` is NOT an expired session: re-logging-in
+            // Translate the canonical envelope first so the server's specific code
+            // and message survive (for example `api_key_required` or
+            // `jwt_issuer_untrusted`).
+            const translated = translateHttpError(res.status, parsed ?? `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            // Only a genuine session or JWT expiry — or a bare auth failure carrying
+            // no structured code — should drive the sign-in redirect. A specific auth
+            // code like `api_key_required` is not an expired session: signing in again
             // mints the same credential and loops. Surface it as its real typed error
             // instead of a `session_expired` wrapping the stringified body.
             if (translated.code === 'session_expired' ||
@@ -277,8 +270,7 @@ export class BootstrapHelper {
             }
             throw translated;
         }
-        const rawJson = await res.json();
-        const data = parseBootstrapResponse(rawJson);
+        const data = parseBootstrapResponse(await res.json());
         this.warnOnSchemaDrift(data.schemaHash);
         // Persist payload for offline
         try {
@@ -286,7 +278,10 @@ export class BootstrapHelper {
                 this.saveCachedBootstrap(this.options.cacheScope, data);
             }
         }
-        catch { }
+        catch {
+            // Offline persistence is best-effort; a failed cache write must not
+            // block returning the freshly fetched data.
+        }
         getContext().logger.info('[Bootstrap] 200 OK - received new data');
         return { notModified: false, data, etag };
     }
@@ -329,7 +324,9 @@ export class BootstrapHelper {
         clearTimeout(timeoutId);
         if (!response.ok) {
             const bodyText = await response.text().catch(() => '');
-            let parsed = bodyText;
+            // Map an empty body to undefined so the `??` below falls through to the
+            // synthetic message (see the note on the primary fetch path).
+            let parsed = bodyText || undefined;
             if (bodyText) {
                 try {
                     parsed = JSON.parse(bodyText);
@@ -341,7 +338,7 @@ export class BootstrapHelper {
             // Same code-aware handling as the primary bootstrap fetch: preserve the
             // server's specific code/message; only a genuine expiry (or a bare,
             // code-less auth failure) drives the sign-in redirect.
-            const translated = translateHttpError(response.status, parsed || `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            const translated = translateHttpError(response.status, parsed ?? `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
             if (translated.code === 'session_expired' ||
                 translated.code === 'jwt_expired' ||
                 ((response.status === 401 || response.status === 403) &&
@@ -350,8 +347,7 @@ export class BootstrapHelper {
             }
             throw translated;
         }
-        const rawJson = await response.json();
-        const data = parseBootstrapResponse(rawJson);
+        const data = parseBootstrapResponse(await response.json());
         this.warnOnSchemaDrift(data.schemaHash);
         // Save a copy for offline
         try {
@@ -359,7 +355,10 @@ export class BootstrapHelper {
                 this.saveCachedBootstrap(this.options.cacheScope, data);
             }
         }
-        catch { }
+        catch {
+            // Offline persistence is best-effort; a failed cache write must not
+            // block returning the freshly fetched data.
+        }
         return data;
     }
     /**
@@ -369,18 +368,40 @@ export class BootstrapHelper {
      */
     async fetchEntity(modelName, id) {
         const url = `${this.options.baseUrl}/sync/entity/${modelName}/${id}`;
-        const response = await fetch(url, {
-            method: 'GET',
-            headers: withAuthHeaders(this.options.getAuthToken, {
-                'Content-Type': 'application/json',
-            }, this.options.authToken),
-        });
+        // Uses the same `fetchTimeout` deadline as `performFetch`. A local
+        // AbortController, rather than the shared `this.abortController`, means an
+        // entity self-heal never cancels a concurrent bootstrap fetch.
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => { controller.abort(); }, this.options.fetchTimeout);
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'GET',
+                headers: withAuthHeaders(this.options.getAuthToken, {
+                    'Content-Type': 'application/json',
+                }, this.options.authToken),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            // Convert abort to the existing typed timeout error (same code as the
+            // bootstrap fetch path) so callers get a retryable connection error.
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new AbloConnectionError(`Entity fetch timed out after ${this.options.fetchTimeout}ms`, { code: 'bootstrap_fetch_timeout', cause: error });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
         if (response.status === 404) {
             return null;
         }
         if (!response.ok) {
             const bodyText = await response.text().catch(() => '');
-            let parsed = bodyText;
+            // Map an empty body to undefined so the `??` below falls through to the
+            // synthetic message (see the note on the primary fetch path).
+            let parsed = bodyText || undefined;
             if (bodyText) {
                 try {
                     parsed = JSON.parse(bodyText);
@@ -389,9 +410,9 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(response.status, parsed || `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            throw translateHttpError(response.status, parsed ?? `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
         }
-        return await response.json();
+        return (await response.json());
     }
     // ─────────────────────────────────────────────────────────────────────
     /**
@@ -405,7 +426,7 @@ export class BootstrapHelper {
             const keysToRemove = [];
             for (let i = 0; i < localStorage.length; i++) {
                 const key = localStorage.key(i);
-                if (key && key.includes('sync-bootstrap')) {
+                if (key?.includes('sync-bootstrap')) {
                     keysToRemove.push(key);
                 }
             }
@@ -474,10 +495,10 @@ export class BootstrapHelper {
             });
             if (!response.ok)
                 return false;
-            const data = await response.json();
-            return data.status === 'healthy';
+            const body = (await response.json());
+            return body.status === 'healthy';
         }
-        catch (error) {
+        catch {
             getContext().observability.breadcrumb('Health check failed', 'sync.bootstrap', 'warning');
             return false;
         }

package/dist/sync/ConnectionManager.d.ts

@@ -1,24 +1,18 @@
 /**
- * ConnectionManager — single source of truth for the sync engine's
- * connection lifecycle. Absorbs the FSM every SDK consumer used to
- * rebuild by hand (apps/web's `ConnectionStore` was the reference
- * implementation — 605 LOC of FSM + watchdog + backoff).
+ * Owns the sync engine's connection lifecycle: the state machine that carries a
+ * client from a healthy connection, through a dropout, and back to live. It
+ * watches the browser's online/offline and visibility events, probes real
+ * connectivity and session validity with {@link probeNetwork}, applies retry
+ * backoff with a ceiling and jitter, and runs a watchdog for the cases where
+ * the browser never fires an event (VPN flips, captive portals). When it
+ * decides to recover, it drives the reconnect sequence — bootstrap, then
+ * WebSocket connect — through the {@link ConnectionCallbacks.onReconnect}
+ * callback and reacts to the outcome.
  *
- * What it owns:
- *  - Browser online/offline + visibility events
- *  - Network probe orchestration (via `probeNetwork`)
- *  - Session-validity checks (HEAD /api/auth/check)
- *  - Retry backoff with ceiling, jitter, and offline-aware parking
- *  - Watchdog for browser events that never fire (VPN, captive portal)
- *  - The reconnect → bootstrap → WebSocket connect sequence
- *
- * What it DOES NOT own:
- *  - The actual bootstrap / IndexedDB / ObjectPool work — that lives in
- *    `BaseSyncedStore.performReconnect()`. This class calls it via the
- *    `onReconnect` callback and reacts to the outcome.
- *
- * Designed to be embedded by `BaseSyncedStore`: one instance per store,
- * started on first successful connect, disposed on teardown.
+ * It deliberately does not perform the bootstrap, local-storage, or object-pool
+ * work itself; that lives in the embedding store, which the manager reaches
+ * only through its callbacks. One manager is created per store, started on the
+ * first successful connect and disposed on teardown.
  *
  *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
  *        │                              │                  │
@@ -29,20 +23,15 @@
  *        ▼
  *   WAITING_FOR_NETWORK
  *
- * Includes three fixes over the original app-side FSM:
- *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
- *      probing immediately when the network comes back, without
- *      waiting for the backoff timer to elapse.
- *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
- *      `attempt`) when `navigator.onLine === false` at max retries,
- *      instead of hard-reloading an already-offline browser.
- *   3. A socket drop (`WS_DISCONNECTED`, typically code 1006) goes
- *      STRAIGHT to `probing_network`, not the passive `offline` state.
- *      1006 is browser-local and carries no connectivity signal, so on a
- *      healthy machine no `online`/`offline` event ever fires — parking in
- *      `offline` stranded recovery until the 30s watchdog, long enough for
- *      queued commits to roll back. Only a genuine OS-level `NETWORK_LOST`
- *      parks in `offline` and waits for the `online` event.
+ * Three behaviors are worth calling out. A network return or tab focus during a
+ * backoff delay jumps straight to probing instead of waiting out the full
+ * interval. Reaching the retry ceiling while the browser reports offline parks
+ * in `waiting_for_network` rather than hard-reloading a browser that has no
+ * network. And a socket drop (close code 1006) goes straight to probing rather
+ * than the passive `offline` state — 1006 is generated locally and carries no
+ * connectivity signal, so on a healthy machine no online/offline event ever
+ * fires; only a genuine operating-system network loss parks in `offline` to
+ * wait for the `online` event.
  */
 import { type ProbeResult } from './NetworkProbe.js';
 import type { AuthTokenGetter } from '../auth/credentialSource.js';
@@ -93,17 +82,18 @@ export interface ConnectionCallbacks {
     /** Run bootstrap + WebSocket reconnect. Returns the outcome. */
     onReconnect: () => Promise<'success' | 'session_error' | 'network_error'>;
     /**
-     * Re-mint the short-lived access credential (the Stripe-style `ek_`/`rk_`)
-     * and push it into the credential source, then report the outcome. Invoked
-     * on `refreshing_credential` — i.e. when a probe found the access key stale
-     * (`PROBE_CREDENTIAL_STALE`). Mirrors the `getToken` contract:
-     *   - `'refreshed'`     → a fresh credential is in place; re-probe & reconnect.
-     *   - `'session_error'` → the LONG-LIVED login is gone (mint returned null →
-     *                          401/403); terminal → sign out.
-     *   - `'network_error'` → couldn't reach the mint endpoint (offline/5xx/throw);
-     *                          transient → back off and retry, never sign out.
-     * Optional: a deployment with no re-mint path (e.g. a static `apiKey`) omits
-     * it, and the FSM falls back to a plain re-probe.
+     * Re-mints the short-lived access credential (the `ek_`/`rk_`) and pushes it
+     * into the credential source, then reports the outcome. Invoked in the
+     * `refreshing_credential` state — that is, when a probe found the access key
+     * stale (`PROBE_CREDENTIAL_STALE`). The three outcomes map onto recovery:
+     *   - `'refreshed'`     → a fresh credential is in place; re-probe and reconnect.
+     *   - `'session_error'` → the long-lived login itself is gone (the mint
+     *                          returned null, a 401/403); terminal, so sign out.
+     *   - `'network_error'` → the mint endpoint was unreachable (offline, 5xx, or
+     *                          a throw); transient, so back off and retry rather
+     *                          than sign out.
+     * Optional: a deployment with no re-mint path (for example a static `apiKey`)
+     * omits it, and the state machine falls back to a plain re-probe.
      */
     onRefreshCredential?: () => Promise<'refreshed' | 'session_error' | 'network_error'>;
     /** Called when the session is confirmed expired — route to signin. */
@@ -111,12 +101,11 @@ export interface ConnectionCallbacks {
     /** Called to tear down the WebSocket when entering a dead state. */
     onDisconnectWebSocket: () => void;
     /**
-     * Fired on every FSM state transition. Lets the embedding store
-     * mirror recovery progress into its visible `syncStatus` so the UI
-     * can show "Reconnecting…" instead of a sticky "offline" while the
-     * FSM cycles through `probing_network` → `reconnecting` → `backoff`.
-     * Optional — omitting it preserves the previous behavior where the
-     * FSM was opaque to the UI.
+     * Fires on every state transition. It lets the embedding store mirror
+     * recovery progress into its visible `syncStatus`, so the UI can show
+     * "Reconnecting…" instead of a sticky "offline" while the machine cycles
+     * through `probing_network` → `reconnecting` → `backoff`. Optional; when
+     * omitted, the state machine is simply opaque to the UI.
      */
     onStateChange?: (next: ConnectionState, prev: ConnectionState) => void;
 }
@@ -167,6 +156,14 @@ export declare class ConnectionManager {
     send(event: ConnectionEvent): void;
     private transition;
     private onEnterState;
+    /**
+     * FSM effects are fire-and-forget by design (`onEnterState` is sync). Each
+     * effect catches its own operational failures and maps them onto an FSM
+     * event, so a rejection here means the machine wedged mid-transition
+     * (`send()` or a transition listener threw) with no retry timer armed past
+     * it — capture it instead of losing the reconnect loop silently.
+     */
+    private captureEffectFailure;
     private runProbe;
     /**
      * Re-mint the short-lived access key on `refreshing_credential`. Delegates to