@abloatai/ablo 0.34.1 → 0.35.0

package/dist/client/Ablo.d.ts

@@ -17,289 +17,30 @@
  *     data: { status: 'ready' },
  *   });
  *   await sync.reports.delete({ id: reportId });
+ *
+ * This module is the composition root and the merge point, and only those.
+ * `Ablo` is three declarations sharing one name — the factory, the client
+ * type, and the `Ablo.*` namespace — and TypeScript merges declarations only
+ * within a single file, so the three have to sit together. Their bodies do
+ * not: the client's shape is `./abloClient`, the pass over the options bag is
+ * `./clientPrelude`, and the client this dispatches to is `./reactiveEngine`.
  */
-import type { Schema, SchemaRecord, InferModel, InferCreate, InferRow } from '../schema/schema.js';
-import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
-export type { ModelTarget, ModelClaim };
-import { InstanceCache } from '../InstanceCache.js';
-import type { SyncStoreContract } from '../react/context.js';
-import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
-import { type SyncStatus } from '../BaseSyncedStore.js';
-import type { PresenceStream, Snapshot } from '../types/streams.js';
-import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js';
+import type { SchemaRecord } from '../transaction/schema/schema.js';
+import { type AbloHttpClient, type AbloHttpClientOptions } from '../transaction/transport/httpClient.js';
+import { type AbloPlugin, type PluginById, type MergedSurface } from '../transaction/plugin.js';
+import { type AbloCoreClient } from './coreClient.js';
 import type { AbloOptions } from './options.js';
-import type { AbloSession, CommitResource, CreateAgentClientParams, CreateSessionParams } from './resourceTypes.js';
+import type { AbloClient, AbloReads } from './abloClient.js';
 export type { ApiKeySetter, AbloOptions, InternalAbloOptions } from './options.js';
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, ModelOperations, ModelOperationAction, CommitWait, IfClaimedPolicy, ClaimedOptions, ClaimWaitOptions, ModelReadOptions, ClaimCreateOptions, CommitOperationInput, CommitCreateOptions, CommitReceipt, CommitResource, ClaimResource, ModelMutationOptions, HttpClaimApi, SessionOperation, CreateUserSessionParams, CreateAgentSessionParams, CreateSessionParams, CreateAgentClientParams, AbloSession, } from './resourceTypes.js';
-export { computeFKDepthPriority } from './schemaConfig.js';
-import type { ModelOperations } from './createModelProxy.js';
+export type { AbloReads } from './abloClient.js';
+export type { ModelTarget, ModelClaim } from './resourceTypes.js';
 /**
- * The reactive-read client a `useAblo` selector receives. The same surface as
- * {@link Ablo}, except model reads are typed as reactive rows
- * ({@link InferRow}: data fields + computeds, no relation accessors, no model
- * methods) — the shape a reactive read actually delivers after
- * `toReactiveSnapshot()`. Reading `row.layers` off a reactive read is a
- * compile error here instead of a silent runtime `undefined`; compose
- * relations through selectors or hooks that resolve the pool's instance.
+ * The typed sync engine client — one property per model in the schema.
+ *
+ * The shape itself is declared in `./abloClient`; this alias is what merges
+ * with the factory and the namespace under the one `Ablo` name.
  */
-export type AbloReads<S extends SchemaRecord> = Omit<Ablo<S>, keyof S & string> & {
-    readonly [K in keyof S & string]: ModelOperations<InferRow<Schema<S>, K>, InferCreate<Schema<S>, K>>;
-};
-/** The typed sync engine client — one property per model in the schema */
-export type Ablo<S extends SchemaRecord> = {
-    readonly [K in keyof S & string]: ModelOperations<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
-} & {
-    /**
-     * Wait for the sync engine to finish its initial bootstrap.
-     * Resolves once entity data is loaded and the WebSocket is connected.
-     *
-     * ```ts
-     * const sync = Ablo({ schema, user });
-     * await sync.ready();
-     * const reports = sync.reports.findMany(); // data is available
-     * ```
-     *
-     * If bootstrap fails, this rejects with the underlying error (unreachable
-     * server, invalid API key, 500 from bootstrap endpoint, etc.).
-     *
-     * Idempotent — calling it multiple times returns the same promise.
-     */
-    ready(): Promise<void>;
-    /**
-     * Wait for all pending mutations to be confirmed by the server.
-     *
-     * Sync engine mutations (`create`/`update`/`delete`) are optimistic and
-     * resolve immediately. Use this when you need to know the server has
-     * acknowledged everything before continuing — for example, before
-     * navigating away, before triggering a server-side workflow, or in tests.
-     *
-     * Resolves when `syncStatus.pendingChanges` reaches 0. If the engine is
-     * offline, this waits until reconnect + flush completes.
-     *
-     * ```ts
-     * await sync.reports.create({ data: { title: 'A' } });
-     * await sync.reports.create({ data: { title: 'B' } });
-     * await sync.waitForFlush(); // server has both reports
-     * ```
-     *
-     * @param timeoutMs - Optional timeout. Default: no timeout (wait forever).
-     *                    Throws `Error('Flush timeout')` if reached with pending changes.
-     */
-    waitForFlush(timeoutMs?: number): Promise<void>;
-    /** Disconnect and clean up */
-    dispose(): Promise<void>;
-    /**
-     * Replace the bearer token used for the WebSocket upgrade and HTTP requests,
-     * without tearing down the engine. Use it to push a refreshed short-lived
-     * access key (an `ek_` or `rk_`) before it expires — the client's `apiKey`
-     * resolver refresh loop calls this for you. It reuses the same rotation path as
-     * the internal capability-token refresh and is safe to call before `ready()`.
-     * It also nudges a parked connection to re-probe with the new token.
-     */
-    setAuthToken(token: string): void;
-    /**
-     * Resolve the active bearer credential this engine authenticates with — the
-     * live `ek_` or `rk_` the WebSocket and HTTP transports currently carry (kept
-     * fresh by the `apiKey` resolver refresh loop), falling back to a configured
-     * API key. Returns `null` when no credential is set yet. Use it to authenticate
-     * a side-band request to the same server with the token this client already
-     * holds, avoiding an extra mint round-trip.
-     */
-    getAuthToken(): Promise<string | null>;
-    /**
-     * Register a re-mint hook for the short-lived access key. The connection layer
-     * calls it when it finds the key stale (a `credential_stale` probe) or on an
-     * external nudge; the hook mints a fresh `ek_` or `rk_` from the still-valid
-     * login. It follows the same contract as the `apiKey` resolver: resolve a
-     * token, resolve `null` when the login itself is gone (which signs the user
-     * out), or throw on a transient failure (which backs off without signing out).
-     * The client wires this automatically from a function `apiKey`. Safe to call
-     * before `ready()`.
-     */
-    setCredentialRefresher(refresher: (() => Promise<string | null>) | null): void;
-    /**
-     * Ask the connection layer to re-probe and reconnect now, using the current
-     * credential. Idempotent and safe in any state (a no-op while connected).
-     * Call after an OS-wake signal (Electron `powerMonitor` 'resume') so a
-     * connection parked since sleep recovers immediately instead of waiting for
-     * the watchdog.
-     */
-    nudgeReconnect(): void;
-    /**
-     * Mint a short-lived, scoped session token for one end user. Call this on your
-     * backend, where the `sk_` secret key lives, then hand the returned `token` to
-     * that user's browser — typically through a token route the browser's `apiKey`
-     * resolver fetches. The browser presents the token as its bearer, and the
-     * server verifies it. The browser must never see the `sk_` key, only the
-     * per-user session token.
-     *
-     * Pass `{ user: { id } }` for a full-authority end-user session, which mints an
-     * `ek_` and attributes writes to a user (recorded as `actor_kind` on the delta
-     * row). Pass `{ agent: { id }, can: { tasks: ['update'] } }` for a scoped agent
-     * session, which mints an `rk_`; `can` is typed against your schema's model
-     * names. This always authenticates with the original `sk_`, never the client's
-     * exchanged sync credential.
-     */
-    sessions: {
-        create(params: CreateSessionParams<S>): Promise<AbloSession>;
-    };
-    /**
-     * Mint a scoped **agent identity** and return a ready-to-use client bound to
-     * it — the `ablo.<resource>.<verb>` shape for the agent use case. One call
-     * replaces `sessions.create({ agent })` + constructing a second
-     * `Ablo({ apiKey: token })`:
-     *
-     * ```ts
-     * const agent = await ablo.agents.create({
-     *   name: 'researcher',                  // readable label (optional)
-     *   can: { documents: ['read', 'update'] },
-     *   // id omitted → a fresh uuid: a distinct, independent participant
-     * });
-     * await agent.documents.update({ id, data, claim });
-     * await agent.dispose(); // when the agent is done
-     * ```
-     *
-     * Server-side only: it requires the `sk_` secret key (like `sessions.create`)
-     * and throws `AbloAuthenticationError` in the browser. The returned client
-     * holds its own auto-refreshing `rk_`, so a long run never hits token expiry,
-     * and the `sk_` never leaves this process. Each call is a distinct participant
-     * by default (omit `id` for a fresh uuid), so even two agents sharing a `name`
-     * queue behind one another on a contended row — `name` is display only and
-     * never collapses identity. Humans don't get a server-built client; ship them a
-     * token via `sessions.create({ user })`. If you need the raw token for
-     * revocation, or a stable re-attachable id, use `sessions.create({ agent })`
-     * or pass `id`.
-     */
-    agents: {
-        create(params: CreateAgentClientParams<S>): Promise<Ablo<S>>;
-    };
-    /**
-     * The organization this client resolved to — `null` until `ready()`
-     * completes. Use it instead of scraping CLI output or hardcoding env vars:
-     *
-     * ```ts
-     * await ablo.ready();
-     * const org = ablo.organizationId; // 'org_…'
-     * ```
-     */
-    readonly organizationId: string | null;
-    /**
-     * Destroy every IndexedDB database owned by this engine. Disconnects
-     * the WebSocket, releases timers, and deletes all `ablo_*` / `ablo-*`
-     * databases. Use on session expiry or explicit logout. Best-effort.
-     */
-    purge(): Promise<void>;
-    /**
-     * Subscribe to session-error events (server rejected the session).
-     * Returns an unsubscribe function. Multiple subscribers supported.
-     * Typically called by `<AbloProvider>`, which calls `purge()` on fire
-     * and forwards to the consumer's `onSessionExpired` callback.
-     */
-    onSessionError(listener: (error: Error) => void): () => void;
-    /**
-     * Subscribe to mutation failures with the full payload (transaction,
-     * error, permanent flag). Use this for user-visible failure surfaces —
-     * toasts keyed by `AbloError.type`, route-level "this entity reverted"
-     * boundaries, telemetry. Fires for both permanent rejections and
-     * `max_retries_exhausted` rollbacks.
-     *
-     * Distinct from `onSessionError` (server killed the session, requires
-     * re-auth) and from the `tx.isPersisted` per-call promise (call-site
-     * await, single transaction). This is the app-wide fan-in.
-     */
-    onMutationFailure(listener: (payload: {
-        transaction: import('../transactions/TransactionQueue.js').Transaction;
-        error: Error;
-        permanent?: boolean;
-    }) => void): () => void;
-    /**
-     * Wait for the most-recent in-flight transaction for (modelName, modelId)
-     * to be confirmed by the server. Rejects with the same error that the
-     * queue's `transaction:failed` event would carry if the mutation is
-     * permanently rolled back. Resolves immediately when no transaction is
-     * in flight (already-confirmed or never-staged).
-     *
-     * Matches the queue's `'confirmed'` status vocabulary (see also
-     * `commits.create({wait:'confirmed'})`). Use this for the routing-
-     * grace-window pattern: stage a write, then
-     * `Promise.race([ablo.waitForConfirmation(...), gracePromise])` before
-     * navigating to a route whose URL depends on the optimistic id.
-     */
-    waitForConfirmation(modelName: string, modelId: string): Promise<void>;
-    /**
-     * Reactive sync status — a MobX observable.
-     *
-     * Single source of truth for "what's the sync engine doing?" Contains:
-     * - `state`: `'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting'`
-     * - `progress`: 0-100 for bootstrap progress
-     * - `error?`: Error object when `state === 'error'`
-     * - `pendingChanges`: Number of unconfirmed mutations in the queue
-     * - `lastSyncAt?`: Timestamp of the last successful delta processing
-     * - `offlineSince?`: When the connection dropped
-     * - `isSessionError`: True when the error requires re-authentication
-     *
-     * React components using `observer()` re-render automatically when
-     * any field changes — no manual subscription or polling needed.
-     *
-     * ```tsx
-     * import { observer } from 'mobx-react-lite';
-     *
-     * const SyncIndicator = observer(() => {
-     *   if (sync.syncStatus.state === 'syncing') return <Spinner />;
-     *   if (sync.syncStatus.state === 'error') return <Error msg={sync.syncStatus.error} />;
-     *   if (sync.syncStatus.state === 'offline') return <OfflineBadge />;
-     *   return null;
-     * });
-     * ```
-     */
-    readonly syncStatus: SyncStatus;
-    /** The underlying schema */
-    readonly schema: Schema<S>;
-    /**
-     * A real-time presence livestream — who else is connected on this engine's
-     * sync groups, what they're doing, and a write surface for announcing this
-     * user's own activity. It rides the engine's existing WebSocket; opening a
-     * participant for presence does not open a second socket. See
-     * {@link PresenceStream}.
-     *
-     * The reference is stable for the engine's lifetime — the underlying connection
-     * is rotated on `dispose()`, but this object stays the same.
-     */
-    readonly presence: PresenceStream;
-    /**
-     * Canonical low-level mutation API. Every untyped model write compiles
-     * down to `commits.create(...)`.
-     */
-    readonly commits: CommitResource;
-    /**
-     * Capture a context-staleness watermark over a set of entities.
-     * Returns a flat snapshot with `stamp` (thread into writes as
-     * `readAt`), `signal` (aborts on any captured-entity delta), and
-     * `onChange` (callback form). Reads from the engine's InstanceCache;
-     * subscription is on the engine's existing transport.
-     *
-     * Use before an LLM call to prevent the model from completing
-     * against now-stale data:
-     * ```ts
-     * const snap = engine.snapshot({ slides: deck.slideIds });
-     * await streamText({ messages, signal: snap.signal });
-     * ```
-     */
-    snapshot<ModelName extends keyof S & string>(entities: Readonly<Record<ModelName, string | readonly string[]>>): Snapshot<Schema<S>, ModelName>;
-    /**
-     * The internal store. It implements {@link SyncStoreContract} — pass it to
-     * `SyncContext.Provider` so the SDK's `useModel` / `useModels` / `useMutations`
-     * hooks can reach it.
-     */
-    readonly _store: SyncStoreContract;
-    /** The InstanceCache — for demand loaders and direct pool operations. */
-    readonly _pool: InstanceCache;
-    /**
-     * The SyncWebSocket handle — for collaboration events (slide selection,
-     * cursor broadcast). Null until the engine connects.
-     */
-    readonly _ws: SyncWebSocket | null;
-};
+export type Ablo<S extends SchemaRecord> = AbloClient<S>;
 /**
  * Create a sync engine client in one call.
  *
@@ -325,19 +66,33 @@ export type Ablo<S extends SchemaRecord> = {
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
  * await ablo.tasks.update({ id, data: { status: 'done' } });
  * ```
+ *
+ * Pass `plugins: []` for the core client — the same stateless surface plus
+ * the live feed (pushed deltas, presence, claim grants and losses), and no
+ * local copy of anything:
+ *
+ * ```ts
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, plugins: [] });
+ * await ablo.connect();
+ * ablo.subscribe('claim_granted', (grant) => { ... });
+ * ```
  */
-export declare function Ablo<const S extends SchemaRecord>(options: AbloHttpClientOptions<S> & {
+export declare function Ablo<const S extends SchemaRecord, const P extends readonly AbloPlugin[] = readonly []>(options: AbloHttpClientOptions<S> & {
     transport: 'http';
-}): AbloHttpClient<S>;
+    plugins?: P;
+}): AbloHttpClient<S> & MergedSurface<P>;
+export declare function Ablo<const S extends SchemaRecord, const P extends readonly AbloPlugin[]>(options: AbloOptions<S> & {
+    plugins: P;
+}): PluginById<P, 'humans'> extends never ? AbloCoreClient<S> & MergedSurface<P> : Ablo<S>;
 export declare function Ablo<const S extends SchemaRecord>(options: AbloOptions<S>): Ablo<S>;
-import type * as _Streams from '../types/streams.js';
+import type * as _Streams from '../transaction/types/streams.js';
 import type * as _Participants from '../sync/participants.js';
-import type * as _Policy from '../policy/types.js';
+import type * as _Policy from '../transaction/policy/types.js';
 import type * as _Mutators from '../mutators/defineMutators.js';
 import type * as _Tx from '../mutators/Transaction.js';
 import type * as _Undo from '../mutators/UndoManager.js';
-import type * as _SchemaTypes from '../schema/schema.js';
-import type * as _Global from '../types/global.js';
+import type * as _SchemaTypes from '../transaction/schema/schema.js';
+import type * as _Global from '../transaction/types/global.js';
 /**
  * The canonical type namespace.
  *
@@ -408,10 +163,10 @@ export declare namespace Ablo {
      */
     type RegisteredSchema = _Global.ResolveSchema extends _SchemaTypes.Schema ? _Global.ResolveSchema : _SchemaTypes.Schema;
     namespace Schema {
-        type InferModel<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferModel<S, K>;
+        type Model<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.Model<S, K>;
         type InferCreate<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferCreate<S, K>;
         /**
-         * The reactive-row companion to {@link InferModel}: data fields + computed
+         * The reactive-row companion to {@link Model}: data fields + computed
          * getters, no relation accessors, no model methods — the shape `useAblo`
          * reads return.
          */
@@ -436,7 +191,7 @@ export declare namespace Ablo {
     }
     namespace Claim {
         type Handle = import('./resourceTypes.js').Claim;
-        type Held<T = Record<string, unknown>> = import('../types/streams.js').HeldClaim<T>;
+        type Held<T = Record<string, unknown>> = import('../transaction/types/streams.js').HeldClaim<T>;
         type CreateOptions = import('./resourceTypes.js').ClaimCreateOptions;
         type WaitOptions = import('./resourceTypes.js').ClaimWaitOptions;
         type Client = import('./resourceTypes.js').ClaimResource;