@abloatai/ablo 0.25.0 → 0.27.0

package/dist/stores/SyncActionStore.js

@@ -1,17 +1,43 @@
 /**
- * Linear Sync Engine - Sync Action Store
- *
- * Stores and manages sync actions received from the server.
- * Critical for delta sync and maintaining sync state consistency.
+ * A local, IndexedDB-backed store for the sync actions (change deltas) the
+ * server sends. See {@link SyncActionStore}.
  */
+// Uses native IndexedDB for maximum performance
+import { z } from 'zod';
+import { getContext } from '../context.js';
 /**
- * SyncActionStore - Manages sync actions (deltas)
- *
- * Features:
- * - Stores sync actions by ID for replay
- * - Tracks applied vs pending actions
- * - Enables rewind/replay for conflict resolution
- * - Maintains sync watermark
+ * The validation boundary for rows read back from the store. A row may have
+ * been written by an earlier session, so this build cannot assume its shape.
+ * Parsing in strip mode also drops the storage bookkeeping fields
+ * (`storedAt`, `applied`, `appliedAt`) that are not part of a
+ * {@link SyncAction}. A row that fails to parse is dropped and logged rather
+ * than replayed as a malformed delta.
+ */
+const storedSyncActionSchema = z.object({
+    id: z.number(),
+    modelName: z.string(),
+    modelId: z.string(),
+    action: z.enum(['I', 'U', 'A', 'D', 'C', 'G', 'S', 'V']),
+    data: z.unknown(),
+    __class: z.literal('SyncAction').default('SyncAction'),
+});
+/** Parse one stored row into a SyncAction, or `null` (dropped + logged). */
+function toSyncAction(row) {
+    const parsed = storedSyncActionSchema.safeParse(row);
+    if (!parsed.success) {
+        getContext().logger.debug('[SyncActionStore] Dropping malformed stored sync action', {
+            issues: parsed.error.issues.map((i) => i.path.join('.')).join(', '),
+        });
+        return null;
+    }
+    return parsed.data;
+}
+/**
+ * Stores the sync actions (the change deltas) the server sends, keyed by
+ * their sync id, and tracks which ones have been applied. It keeps a
+ * watermark of the last applied id, holds not-yet-applied actions as
+ * pending, and can rewind a range of actions back to pending so they can be
+ * replayed while resolving a conflict.
  */
 export class SyncActionStore {
     db;
@@ -51,8 +77,8 @@ export class SyncActionStore {
                 }
                 resolve();
             };
-            tx.onerror = () => reject(tx.error);
-            request.onerror = () => reject(request.error);
+            tx.onerror = () => { reject(tx.error); };
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -83,10 +109,10 @@ export class SyncActionStore {
                         }
                     }
                 };
-                request.onerror = () => reject(request.error);
+                request.onerror = () => { reject(request.error); };
             }
-            tx.oncomplete = () => resolve();
-            tx.onerror = () => reject(tx.error);
+            tx.oncomplete = () => { resolve(); };
+            tx.onerror = () => { reject(tx.error); };
         });
     }
     /**
@@ -103,10 +129,9 @@ export class SyncActionStore {
                     resolve(undefined);
                     return;
                 }
-                const { storedAt, applied, ...action } = data;
-                resolve(action);
+                resolve(toSyncAction(data) ?? undefined);
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -121,10 +146,12 @@ export class SyncActionStore {
             const request = index.getAll(range);
             request.onsuccess = () => {
                 const allData = request.result;
-                const actions = allData.map(({ storedAt, applied, ...action }) => action);
+                const actions = allData
+                    .map(toSyncAction)
+                    .filter((action) => action !== null);
                 resolve(actions);
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -142,7 +169,9 @@ export class SyncActionStore {
      * Mark sync action as applied
      */
     async markAsApplied(syncId) {
-        return new Promise(async (resolve, reject) => {
+        // Plain (non-async) executor: a sync throw (e.g. transaction() on a
+        // closing DB) must reject this promise, not vanish into an ignored one.
+        return new Promise((resolve, reject) => {
             const tx = this.db.transaction([this.storeName], 'readwrite');
             const store = tx.objectStore(this.storeName);
             const getRequest = store.get(syncId);
@@ -152,10 +181,10 @@ export class SyncActionStore {
                     existing.applied = true;
                     existing.appliedAt = Date.now();
                     const putRequest = store.put(existing);
-                    putRequest.onerror = () => reject(putRequest.error);
+                    putRequest.onerror = () => { reject(putRequest.error); };
                 }
             };
-            getRequest.onerror = () => reject(getRequest.error);
+            getRequest.onerror = () => { reject(getRequest.error); };
             tx.oncomplete = async () => {
                 // Update tracking
                 if (syncId > this.lastAppliedSyncId) {
@@ -172,7 +201,7 @@ export class SyncActionStore {
                     reject(error);
                 }
             };
-            tx.onerror = () => reject(tx.error);
+            tx.onerror = () => { reject(tx.error); };
         });
     }
     /**
@@ -181,7 +210,7 @@ export class SyncActionStore {
     async markManyAsApplied(syncIds) {
         if (syncIds.length === 0)
             return;
-        return new Promise(async (resolve, reject) => {
+        return new Promise((resolve, reject) => {
             const tx = this.db.transaction([this.storeName], 'readwrite');
             const store = tx.objectStore(this.storeName);
             let processed = 0;
@@ -206,14 +235,14 @@ export class SyncActionStore {
                                 }
                             }
                         };
-                        putRequest.onerror = () => reject(putRequest.error);
+                        putRequest.onerror = () => { reject(putRequest.error); };
                     }
                     else {
                         processed++;
                         this.pendingActions.delete(syncId);
                     }
                 };
-                getRequest.onerror = () => reject(getRequest.error);
+                getRequest.onerror = () => { reject(getRequest.error); };
             }
             tx.oncomplete = async () => {
                 // Update metadata with the highest sync ID
@@ -231,7 +260,7 @@ export class SyncActionStore {
                     resolve();
                 }
             };
-            tx.onerror = () => reject(tx.error);
+            tx.onerror = () => { reject(tx.error); };
         });
     }
     /**
@@ -265,7 +294,7 @@ export class SyncActionStore {
                     currentId++;
                     checkNext();
                 };
-                request.onerror = () => reject(request.error);
+                request.onerror = () => { reject(request.error); };
             };
             checkNext();
         });
@@ -293,7 +322,7 @@ export class SyncActionStore {
                     currentId++;
                     checkNext();
                 };
-                request.onerror = () => reject(request.error);
+                request.onerror = () => { reject(request.error); };
             };
             checkNext();
         });
@@ -317,7 +346,7 @@ export class SyncActionStore {
                             cleaned++;
                             cursor.continue();
                         };
-                        deleteRequest.onerror = () => reject(deleteRequest.error);
+                        deleteRequest.onerror = () => { reject(deleteRequest.error); };
                     }
                     else {
                         cursor.continue();
@@ -328,7 +357,7 @@ export class SyncActionStore {
                     resolve(cleaned);
                 }
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -344,8 +373,8 @@ export class SyncActionStore {
                 this.lastAppliedSyncId = 0;
                 resolve();
             };
-            tx.onerror = () => reject(tx.error);
-            request.onerror = () => reject(request.error);
+            tx.onerror = () => { reject(tx.error); };
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -373,7 +402,7 @@ export class SyncActionStore {
                     newestAction: timestamps.length > 0 ? new Date(timestamps[timestamps.length - 1]) : null,
                 });
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -389,11 +418,11 @@ export class SyncActionStore {
                 metadata.lastSyncId = syncId;
                 metadata.updatedAt = new Date();
                 const putRequest = store.put(metadata, 'metadata');
-                putRequest.onerror = () => reject(putRequest.error);
+                putRequest.onerror = () => { reject(putRequest.error); };
             };
-            getRequest.onerror = () => reject(getRequest.error);
-            tx.oncomplete = () => resolve();
-            tx.onerror = () => reject(tx.error);
+            getRequest.onerror = () => { reject(getRequest.error); };
+            tx.oncomplete = () => { resolve(); };
+            tx.onerror = () => { reject(tx.error); };
         });
     }
     /**
@@ -416,14 +445,14 @@ export class SyncActionStore {
                     resolve(undefined);
                 }
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
      * Rewind to a specific sync ID (for conflict resolution)
      */
     async rewindTo(syncId) {
-        return new Promise(async (resolve, reject) => {
+        return new Promise((resolve, reject) => {
             // Get all actions after this sync ID
             const tx = this.db.transaction([this.storeName], 'readonly');
             const store = tx.objectStore(this.storeName);
@@ -461,21 +490,23 @@ export class SyncActionStore {
                             this.lastAppliedSyncId = syncId - 1;
                         }
                     };
-                    putRequest.onerror = () => reject(putRequest.error);
+                    putRequest.onerror = () => { reject(putRequest.error); };
                 }
                 writeTx.oncomplete = async () => {
                     try {
                         await this.updateLastSyncId(this.lastAppliedSyncId);
-                        const result = actionsToRewind.map(({ storedAt, applied, ...action }) => action);
+                        const result = actionsToRewind
+                            .map(toSyncAction)
+                            .filter((action) => action !== null);
                         resolve(result);
                     }
                     catch (error) {
                         reject(error);
                     }
                 };
-                writeTx.onerror = () => reject(writeTx.error);
+                writeTx.onerror = () => { reject(writeTx.error); };
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
 }

package/dist/surface.d.ts

@@ -1,29 +1,36 @@
 /**
- * Machine-checked public API-surface manifest — the SDK owns the description of
- * its OWN surface, bound to the real exported types at COMPILE TIME so the MCP
- * `get_api_surface` / docs can never drift from reality.
+ * A machine-checked manifest of this package's public API surface. It lists,
+ * as string tuples, the method names on `ablo.<model>`, the keys accepted by
+ * the list-style read options, and the keys of the client constructor
+ * options. Each tuple is proven equal to the keys of its source interface at
+ * compile time, so the lists cannot drift from the real types: add or remove
+ * a name on either side without updating the matching tuple and this file
+ * fails to compile, in both directions — no name the interface lacks, and no
+ * interface key the tuple omits.
  *
- * This exists because the hand-authored surface (apps/sync-web/.../api-surface.ts)
- * once named `load` / `count` / `scope` — verbs/options that don't exist — with no
- * coupling to the code. The fix: the name lists live HERE, next to the types, and
- * each is proven EXACTLY equal to the keys of its source interface via
- * `Expect<Equal<…>>`. Add or remove a verb/option without updating the matching
- * tuple and THIS FILE FAILS TO COMPILE (the `Equal` constraint is checked eagerly
- * at the alias declaration — both directions: no phantom name, no missing name).
- *
- * Consumers (the MCP `get_api_surface`) import these NAME tuples and build their
- * prose from them, so a summary can never reference a verb that doesn't exist.
- * NAMES are guaranteed; descriptions stay hand-written (prose can't be type-checked).
+ * Documentation tooling reads these tuples to describe the surface, which
+ * guarantees a generated summary never names a method or option that does
+ * not exist. The names are verified here; their prose descriptions are
+ * written by hand, since prose cannot be type-checked.
+ */
+/**
+ * The names of every method available on `ablo.<model>`, matching the keys of
+ * the {@link ModelOperations} interface. Documentation tooling reads this
+ * tuple, so it is the one list of model-verb names a generated summary can
+ * describe.
  */
-/** Every method on `ablo.<model>` (the stateful `ModelOperations`). The single
- *  source of truth for the model-verb names the docs/MCP may describe. */
 export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "get", "getAll", "getCount", "create", "update", "delete", "claim", "watch", "onChange"];
-/** Keys accepted by `list`/`getAll`/`onChange` options (`LocalReadOptions`).
- *  Note `state` (lifecycle filter) — NOT `scope` (a historic doc drift). */
+/**
+ * The option keys accepted by `list`, `getAll`, and `onChange`, matching the
+ * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
+ * `state`, not `scope`.
+ */
 export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orderBy", "limit", "offset", "state"];
-/** Public keys of `AbloOptions`. `schema` is required; the rest are optional
- *  (the locked happy path is `Ablo({ schema, apiKey, databaseUrl, transport })`). */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "databaseUrl", "persistence", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
+/**
+ * The keys of the client constructor options, {@link AbloOptions}. Only
+ * `schema` is required; every other key is optional.
+ */
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "databaseUrl", "persistence", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -1,23 +1,25 @@
 /**
- * Machine-checked public API-surface manifest — the SDK owns the description of
- * its OWN surface, bound to the real exported types at COMPILE TIME so the MCP
- * `get_api_surface` / docs can never drift from reality.
+ * A machine-checked manifest of this package's public API surface. It lists,
+ * as string tuples, the method names on `ablo.<model>`, the keys accepted by
+ * the list-style read options, and the keys of the client constructor
+ * options. Each tuple is proven equal to the keys of its source interface at
+ * compile time, so the lists cannot drift from the real types: add or remove
+ * a name on either side without updating the matching tuple and this file
+ * fails to compile, in both directions — no name the interface lacks, and no
+ * interface key the tuple omits.
  *
- * This exists because the hand-authored surface (apps/sync-web/.../api-surface.ts)
- * once named `load` / `count` / `scope` — verbs/options that don't exist — with no
- * coupling to the code. The fix: the name lists live HERE, next to the types, and
- * each is proven EXACTLY equal to the keys of its source interface via
- * `Expect<Equal<…>>`. Add or remove a verb/option without updating the matching
- * tuple and THIS FILE FAILS TO COMPILE (the `Equal` constraint is checked eagerly
- * at the alias declaration — both directions: no phantom name, no missing name).
- *
- * Consumers (the MCP `get_api_surface`) import these NAME tuples and build their
- * prose from them, so a summary can never reference a verb that doesn't exist.
- * NAMES are guaranteed; descriptions stay hand-written (prose can't be type-checked).
+ * Documentation tooling reads these tuples to describe the surface, which
+ * guarantees a generated summary never names a method or option that does
+ * not exist. The names are verified here; their prose descriptions are
+ * written by hand, since prose cannot be type-checked.
  */
 // ── the per-`ablo.<model>` verb surface ────────────────────────────────────
-/** Every method on `ablo.<model>` (the stateful `ModelOperations`). The single
- *  source of truth for the model-verb names the docs/MCP may describe. */
+/**
+ * The names of every method available on `ablo.<model>`, matching the keys of
+ * the {@link ModelOperations} interface. Documentation tooling reads this
+ * tuple, so it is the one list of model-verb names a generated summary can
+ * describe.
+ */
 export const PUBLIC_MODEL_VERBS = [
     'retrieve',
     'list',
@@ -32,8 +34,11 @@ export const PUBLIC_MODEL_VERBS = [
     'onChange',
 ];
 // ── the read/list query option surface ─────────────────────────────────────
-/** Keys accepted by `list`/`getAll`/`onChange` options (`LocalReadOptions`).
- *  Note `state` (lifecycle filter) — NOT `scope` (a historic doc drift). */
+/**
+ * The option keys accepted by `list`, `getAll`, and `onChange`, matching the
+ * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
+ * `state`, not `scope`.
+ */
 export const PUBLIC_LIST_OPTION_KEYS = [
     'where',
     'filter',
@@ -43,11 +48,14 @@ export const PUBLIC_LIST_OPTION_KEYS = [
     'state',
 ];
 // ── the `Ablo({ … })` constructor option surface ───────────────────────────
-/** Public keys of `AbloOptions`. `schema` is required; the rest are optional
- *  (the locked happy path is `Ablo({ schema, apiKey, databaseUrl, transport })`). */
+/**
+ * The keys of the client constructor options, {@link AbloOptions}. Only
+ * `schema` is required; every other key is optional.
+ */
 export const PUBLIC_ABLO_OPTION_KEYS = [
     'schema',
     'apiKey',
+    'authEndpoint',
     'databaseUrl',
     'persistence',
     'transport',

package/dist/sync/{BootstrapHelper.d.ts → BootstrapFetcher.d.ts}

@@ -1,27 +1,30 @@
 /**
- * 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.
  */
 export interface BootstrapData {
     type: 'full' | 'partial';
     lastSyncId: number;
     /**
-     * Model rows keyed by typename. Each row is opaque to the SDK at this
-     * boundary — the per-model shape is asserted by the consumer (sync
-     * engine reduce + IDB write) using the registered schema.
+     * Model rows keyed by type name. Each row is opaque at this boundary; the
+     * engine asserts the per-model shape against the registered schema when it
+     * reduces the rows and writes them to local storage.
      */
-    models?: {
-        [typename: string]: unknown[];
-    };
+    models?: Record<string, unknown[]>;
     deltas?: ValidatedServerDelta[];
     deltaCount?: number;
-    /** Model types whose server-side query failed (timeout, RLS error, etc.) */
+    /** Model types whose server-side query failed (timeout, RLS error, and the like). */
     failedModels?: string[];
     timestamp: number;
     /**
-     * The server's ACTIVE schema content hash for this tenant (same `schemaHash`
-     * the CLI push computes). Present once the tenant has pushed a schema; the
-     * client compares it to its own `config.expectedSchemaHash` to warn on drift.
+     * The content hash of the schema the server currently has active for this
+     * tenant — the same hash `ablo push` computes. Present once a schema has been
+     * pushed. The client compares it against its own `expectedSchemaHash` to warn
+     * when the app's schema and the deployed schema have drifted apart.
      */
     schemaHash?: string;
 }
@@ -42,40 +45,38 @@ export interface BootstrapOptions {
      */
     baseUrl?: string;
     /**
-     * Private cache namespace for offline bootstrap fallback. Hosted SDK
-     * callers do not pass this; Ablo sets it after auth resolves the
-     * account scope.
+     * Namespace for the offline bootstrap cache. Most callers leave this unset;
+     * the SDK fills it in once authentication has resolved the account scope, so
+     * the fallback cache is partitioned per account.
      */
     cacheScope?: string | null;
     /**
-     * @deprecated Use `cacheScope`. Kept so older self-hosted code that
-     * still constructs BootstrapHelper directly keeps its cache namespace.
+     * @deprecated Use `cacheScope`. Retained so code that constructs
+     * {@link BootstrapFetcher} directly keeps its cache namespace.
      */
     organizationId?: string;
     syncGroups?: string[];
     maxRetries?: number;
     retryDelay?: number;
-    /** Timeout for individual fetch requests in ms (default: 30000) */
+    /** How long to wait for a single fetch before timing out, in milliseconds. Default 10000 (10 seconds). */
     fetchTimeout?: number;
     /**
-     * Model names to request in bootstrap. When set, the server only returns
-     * these models — everything else is skipped. Derived from the schema's
-     * `load` strategy: only models with `load: 'instant'` (or unset, which
-     * defaults to instant) are included.
-     *
-     * When absent, the server returns all models (backward compatible with
-     * old clients that don't send a models param).
+     * The model names to request. When set, the server returns only these models
+     * and skips the rest. This is derived from each model's `load` strategy: only
+     * models loaded instantly (the default) are included. When unset, the server
+     * returns every model.
      */
     instantModels?: string[];
     /**
-     * Shared SDK credential getter. Preferred over `setAuthToken`; read at
-     * request time so token refreshes apply without recreating BootstrapHelper.
+     * Getter for the current credential, read at request time so a refreshed
+     * token takes effect without recreating the helper. Preferred over
+     * {@link BootstrapFetcher.setAuthToken}.
      */
     getAuthToken?: AuthTokenGetter;
 }
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
 import { type ValidatedServerDelta } from './schemas.js';
-export declare class BootstrapHelper {
+export declare class BootstrapFetcher {
     private options;
     private abortController;
     /** Warn about schema drift at most once per helper. */
@@ -97,20 +98,10 @@ export declare class BootstrapHelper {
     setCacheScope(cacheScope: string): void;
     setSyncGroups(syncGroups: readonly string[] | undefined): void;
     /**
-     * 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: string | undefined): void;
-    /**
-     * Create a promise that rejects after a timeout
-     * Used to race against fetch requests that may hang indefinitely
-     */
-    private createTimeoutPromise;
-    /**
-     * 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
-     */
-    private withTimeout;
     /**
      * Fetch bootstrap data from sync engine with partial bootstrap support
      * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
@@ -118,11 +109,12 @@ export declare class BootstrapHelper {
      */
     fetchBootstrap(lastSyncId?: number, 
     /**
-     * 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?: readonly string[]): Promise<BootstrapData>;
     /**