@abloatai/ablo 0.26.0 → 0.28.0

package/dist/stores/SyncActionStore.d.ts

@@ -1,18 +1,14 @@
 /**
- * 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}.
  */
 import type { SyncAction } from '../types/index.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
+ * 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 declare class SyncActionStore {
     private db;

package/dist/stores/SyncActionStore.js

@@ -1,19 +1,17 @@
 /**
- * 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';
 /**
- * Zod boundary for rows read back from the sync-action store (T1.8): they
- * were written by a previous session, so their shape is not guaranteed by
- * this build. Default (strip) mode drops the storage bookkeeping fields
- * (`storedAt`/`applied`/`appliedAt`) that used to be peeled off with an
- * untyped rest-spread. Rows that don't parse are dropped + logged instead
- * of being replayed as malformed deltas.
+ * 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(),
@@ -35,13 +33,11 @@ function toSyncAction(row) {
     return parsed.data;
 }
 /**
- * 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
+ * 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;

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", "authEndpoint", "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", "commitOutbox", "commitOutboxScope", "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,14 +48,18 @@ 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',
+    'commitOutbox',
+    'commitOutboxScope',
     'transport',
     'debug',
     'logLevel',

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

@@ -1,25 +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?: 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;
 }
@@ -40,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. */
@@ -95,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
@@ -116,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>;
     /**