@abloatai/ablo 0.26.0 → 0.27.0

package/dist/client/ApiClient.js

@@ -1,17 +1,33 @@
 /**
- * Stateless API client for `Ablo({ apiKey })`.
- *
- * This is the hosted-API product surface: no schema, no object pool, no
- * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
- * nouns directly to HTTP routes on sync-server.
+ * The stateless API client behind `Ablo({ apiKey })`. It carries no schema,
+ * object pool, local database, or WebSocket, and maps the public Model, Claim,
+ * and Commit nouns directly to HTTP routes on the server. This is the transport
+ * used for server-side agents, workers, and serverless code.
  */
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, claimedError, translateHttpError, } from '../errors.js';
 import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
-import { toSeconds } from '../utils/duration.js';
+import { toMs, toSeconds } from '../utils/duration.js';
+import { heartbeatCadenceMs, resolveHeartbeatOptions, startClaimHeartbeatLoop, } from './claimHeartbeatLoop.js';
 import { mintSession } from './sessionMint.js';
+/**
+ * Interpret a heartbeat reply for a lease this handle HOLDS: anything other
+ * than `held` means the lease is no longer ours (a holder cannot be `queued`;
+ * `lost` rides a 409 that the wire error mapping already surfaces as
+ * AbloClaimedError before reaching here). The thrown loss is the definitive
+ * signal that stops the auto-heartbeat loop.
+ */
+function heldHeartbeatReply(reply, label) {
+    if (reply.status === 'held' && typeof reply.expiresAt === 'number') {
+        return {
+            expiresAt: reply.expiresAt,
+            ...(reply.queueDepth !== undefined ? { queueDepth: reply.queueDepth } : {}),
+        };
+    }
+    throw new AbloClaimedError(`The lease behind ${label} is no longer held — it expired or was granted onward. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`, { code: 'claim_lost' });
+}
 import { assertWriteOptions } from './writeOptionsSchema.js';
 /** Default per-request deadline for the stateless HTTP transport. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
@@ -32,11 +48,12 @@ export function createProtocolClient(options) {
         databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
-    // Observability seam for the STATELESS HTTP transport. The WS transport emits
-    // claim/conflict events from SyncWebSocket; the HTTP path (server-side agents,
+    // Observability hook for the stateless HTTP transport. The WebSocket transport
+    // emits claim and conflict events; the HTTP path (server-side agents,
     // `transport: 'http'`) emitted nothing, so a `ClaimLog` handed to a headless
-    // agent eval stayed empty. Mirror the two WS seams here: claim acquired +
-    // coordination-conflict rejection. No-op when no provider is configured.
+    // agent evaluation stayed empty. This mirrors the two WebSocket events here:
+    // claim acquired and coordination-conflict rejection. A no-op when no provider
+    // is configured.
     const observability = options.observability;
     // Shared by the two HTTP write doors (`commits.create` + per-model
     // `mutateModel`): a rejected write whose code is a coordination conflict is
@@ -139,7 +156,7 @@ export function createProtocolClient(options) {
         // is combined with the deadline via a shared controller — the portable
         // equivalent of `AbortSignal.any([caller, AbortSignal.timeout(t)])`,
         // which older runtimes (and the jsdom test env) don't implement. The
-        // same pattern already guards `query/client.ts` and `BootstrapHelper`.
+        // same pattern already guards `query/client.ts` and `BootstrapFetcher`.
         const callerSignal = requestInit.signal ?? undefined;
         const controller = new AbortController();
         const onCallerAbort = () => { controller.abort(callerSignal?.reason); };
@@ -482,11 +499,11 @@ export function createProtocolClient(options) {
                     queue: claimOptions.queue,
                 }),
             });
-            // The fair-queue grant is PUSHED over a WebSocket (`claim_granted`),
-            // which this stateless HTTP client doesn't hold. Returning a handle here
-            // would be a phantom holder — a lease we can't confirm is ours. So a
-            // queued response is surfaced as a typed claimed signal; callers that need
-            // to *wait* in line use the realtime (WS-backed) `ablo.<model>.claim`.
+            // The fair-queue grant is pushed over a WebSocket (`claim_granted`), which
+            // this stateless HTTP client doesn't hold. Returning a handle here would be
+            // a phantom holder — a lease we can't confirm is ours. So a queued response
+            // is surfaced as a typed claimed signal; callers that need to wait in line
+            // use the realtime (WebSocket-backed) `ablo.<model>.claim`.
             if (body.status === 'queued') {
                 throw new AbloClaimedError(`Target ${claimOptions.target.model}/${claimOptions.target.id} is held; ` +
                     `queued at position ${body.position ?? 0}. The HTTP client can't await ` +
@@ -500,9 +517,24 @@ export function createProtocolClient(options) {
                 released = true;
                 await requestJson(`/v1/claims/${encodeURIComponent(id)}`, { method: 'DELETE' });
             };
+            // The by-id twin of the model-scoped heartbeat — same reply contract.
+            const heartbeat = async (beatOptions) => {
+                const resolved = resolveHeartbeatOptions(beatOptions);
+                const reply = await requestJson(`/v1/claims/${encodeURIComponent(id)}/heartbeat`, {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        ...(resolved.ttl !== undefined ? { ttl: resolved.ttl } : {}),
+                        ...(resolved.details !== undefined
+                            ? { details: resolved.details }
+                            : {}),
+                    }),
+                });
+                return heldHeartbeatReply(reply, `claim ${id}`);
+            };
             return {
                 object: 'claim',
                 id,
+                heartbeat,
                 reason: claimOptions.reason,
                 target: {
                     type: claimOptions.target.model,
@@ -523,6 +555,23 @@ export function createProtocolClient(options) {
         waitFor(target, options) {
             return waitForNoClaims(target, options);
         },
+        async heartbeatAll(options) {
+            const reply = await requestJson('/v1/claims/heartbeat', {
+                method: 'POST',
+                body: JSON.stringify(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
+            });
+            return (reply.results ?? []).flatMap((entry) => typeof entry.claimId === 'string' && typeof entry.expiresAt === 'number'
+                ? [
+                    {
+                        claimId: entry.claimId,
+                        expiresAt: entry.expiresAt,
+                        ...(entry.queueDepth !== undefined
+                            ? { queueDepth: entry.queueDepth }
+                            : {}),
+                    },
+                ]
+                : []);
+        },
     };
     async function listModel(modelName, options) {
         const params = new URLSearchParams();
@@ -554,11 +603,11 @@ export function createProtocolClient(options) {
         const query = await requestJson(`/v1/models/${encodeURIComponent(modelName)}/${encodeURIComponent(params.id)}`, {
             method: 'GET',
         });
-        // Miss = `data: undefined`, NOT a thrown error. The WebSocket client's
+        // A miss is `data: undefined`, not a thrown error. The WebSocket client's
         // `retrieve` returns `T | undefined` for a missing row; throwing only here
         // made the obvious read ("does this row exist?") a hard edge that an agent
-        // had to wrap in try/catch. Both transports now agree: absent row → absent
-        // data. Callers branch on `.data` (already the documented `.data?.x` usage).
+        // had to wrap in try/catch. Both transports agree: an absent row means absent
+        // data. Callers branch on `.data` (the documented `.data?.x` usage).
         // Normalize a miss to `undefined` (the server may send `null` or omit it).
         const data = (query.data ?? undefined);
         return {
@@ -568,16 +617,16 @@ export function createProtocolClient(options) {
         };
     }
     /**
-     * Single-op mutation over the model-scoped routes — the canonical surface
-     * that mirrors `ablo.<model>.create/update/delete`:
+     * A single-operation mutation over the model-scoped routes — the canonical
+     * surface that mirrors `ablo.<model>.create/update/delete`:
      *
      *   POST   /v1/models/:model        create
      *   PATCH  /v1/models/:model/:id     update
      *   DELETE /v1/models/:model/:id     delete
      *
-     * This replaces the previous indirection through `POST /v1/commits`. The raw
-     * `commits.create(...)` resource is still the path for ATOMIC MULTI-OP
-     * envelopes — this helper is the one-op, one-record path only.
+     * The `commits.create(...)` resource remains the path for atomic
+     * multi-operation envelopes; this helper handles the one-operation,
+     * one-record case.
      */
     async function mutateModel(action, modelName, id, data, options) {
         assertWriteOptions(options && {
@@ -621,9 +670,8 @@ export function createProtocolClient(options) {
             });
         }
         catch (error) {
-            // Per-model write door (`ablo.<model>.update/create/delete`) — the path
-            // the demo editor + server agents actually take. Capture coordination
-            // collisions here too; this single row IS the fallback target.
+            // The per-model write door (`ablo.<model>.update/create/delete`). Capture
+            // coordination collisions here too; this single row is the fallback target.
             recordCoordinationConflict(error, clientTxId, [{ model: modelName, id }]);
             throw error;
         }
@@ -669,11 +717,25 @@ export function createProtocolClient(options) {
                 throw new AbloClaimedError(`Target ${name}/${params.id} is held; queued at position ${body.position ?? 0}. ` +
                     `The HTTP client cannot await the grant without a WebSocket.`, { code: 'claim_queued' });
             }
-            // `claimId` is the queued-response field name (routes/claims.ts) — a
-            // pre-rename regression duplicated the `body.id` arm and dropped it.
+            // `claimId` is the field name the queued response uses; check it alongside
+            // the other id shapes the response may carry.
             return body.claim?.id ?? body.id ?? body.claimId ?? createClaimId();
         };
         const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
+        // One beat on the held lease. A lapsed lease answers `claim_lost`
+        // (409), which the wire error mapping surfaces as AbloClaimedError —
+        // the definitive signal that stops the auto-heartbeat loop.
+        const heartbeatClaim = async (id, claimId, options) => {
+            const reply = await requestJson(`${claimPath(id)}/heartbeat`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    claimId,
+                    ...(options.ttl !== undefined ? { ttl: options.ttl } : {}),
+                    ...(options.details !== undefined ? { details: options.details } : {}),
+                }),
+            });
+            return heldHeartbeatReply(reply, `claim ${claimId} on ${name}/${id}`);
+        };
         async function claimImpl(params) {
             const claimId = await acquireClaim(params);
             observability?.captureClaim({
@@ -691,7 +753,33 @@ export function createProtocolClient(options) {
             if (data === undefined) {
                 throw new AbloNotFoundError(`Cannot claim ${name}/${params.id}: it does not exist (or is outside this credential's scope).`, [params.id]);
             }
-            const release = () => releaseClaim(params);
+            const heartbeat = async (beatOptions) => {
+                const resolved = resolveHeartbeatOptions(beatOptions);
+                const beat = await heartbeatClaim(params.id, claimId, {
+                    ttl: resolved.ttl ?? params.ttl,
+                    ...(resolved.details !== undefined
+                        ? { details: resolved.details }
+                        : {}),
+                });
+                params.onHeartbeat?.(beat);
+                return beat;
+            };
+            // Opt-in auto-heartbeat — the background-worker cadence. The stateless
+            // HTTP claim defaults to the server's 60s acquire window when no TTL
+            // was requested, so the default cadence lands at 20s beats.
+            const stopHeartbeatLoop = params.heartbeat
+                ? startClaimHeartbeatLoop({
+                    beat: () => heartbeat(),
+                    intervalMs: heartbeatCadenceMs(params.ttl !== undefined ? toMs(params.ttl) : 60_000, params.heartbeat),
+                    ...(params.onHeartbeatLost
+                        ? { onLost: params.onHeartbeatLost }
+                        : {}),
+                })
+                : undefined;
+            const release = () => {
+                stopHeartbeatLoop?.();
+                return releaseClaim(params);
+            };
             return {
                 object: 'claim',
                 id: claimId,
@@ -711,6 +799,7 @@ export function createProtocolClient(options) {
                 revoke: () => {
                     void release().catch(() => { });
                 },
+                heartbeat,
                 [Symbol.asyncDispose]: release,
             };
         }
@@ -729,8 +818,8 @@ export function createProtocolClient(options) {
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {
                     method: 'POST',
-                    // The reorder route's payload is `{ heldBy, claimId }[]` — Claim's id
-                    // IS the claimId.
+                    // The reorder route's payload is `{ heldBy, claimId }[]` — a Claim's id
+                    // is the claimId.
                     body: JSON.stringify({ order: params.order.map((i) => ({ heldBy: i.heldBy, claimId: i.id })) }),
                 });
             },
@@ -742,7 +831,13 @@ export function createProtocolClient(options) {
             if (isClaimHandle(claimInput)) {
                 return run({ ...input, claimRef: { id: claimInput.id }, claim: undefined });
             }
-            const claimId = await acquireClaim({ id, ...claimInput });
+            // `isClaimHandle` ruled out the handle form above; the generic mismatch
+            // (the union carries `Claim`, the guard narrows `Claim<T>`) keeps the
+            // compiler from subtracting it, so narrow to the inline-options form.
+            const claimId = await acquireClaim({
+                id,
+                ...claimInput,
+            });
             try {
                 return await run({ ...input, claimRef: { id: claimId }, claim: undefined });
             }
@@ -796,8 +891,8 @@ export function createProtocolClient(options) {
                     // Confirm the write, then return the row — the obvious expectation of
                     // "create" (the WebSocket client already returns the row). The read-
                     // back is the authoritative server row, so it carries the framework
-                    // defaults (createdAt/createdBy/…) AND, for an idempotent re-create of
-                    // an existing id, the EXISTING row rather than the caller's input.
+                    // defaults (createdAt, createdBy, …) and, for an idempotent re-create of
+                    // an existing id, the existing row rather than the caller's input.
                     await mutateModel('create', name, id, params.data, {
                         ...options,
                         wait: options?.wait ?? 'confirmed',
@@ -829,9 +924,9 @@ export function createProtocolClient(options) {
         model,
         sessions: {
             async create(params) {
-                // Stateless mint: the configured key IS the control-plane credential here
-                // (no startup `rk_` exchange runs on this client). Reuse the resolved base
-                // URL + fetch; the shared `mintSession` owns the two server doors.
+                // Stateless mint: the configured key is the control-plane credential here
+                // (no startup `rk_` exchange runs on this client). It reuses the resolved
+                // base URL and fetch; the shared `mintSession` handles the two server routes.
                 const apiKey = await resolveApiKeyValue(configuredApiKey);
                 if (!apiKey) {
                     throw new AbloAuthenticationError('sessions.create requires a secret (sk_) API key — call it from your backend, not the browser.', { code: 'apikey_missing' });

package/dist/client/auth.d.ts

@@ -1,29 +1,29 @@
 /**
- * Auth + URL resolution for `Ablo()`.
+ * Authentication and URL resolution for the `Ablo()` client.
  *
- * Mirrors the small, focused helpers Anthropic ships in `client.ts`
- * (`apiKeyAuth`, `bearerAuth`, `validateHeaders`). Each function does
- * one thing — resolve a value with the right precedence, or fail
- * with an actionable message — so the constructor reads as a
- * sequence of named decisions rather than a stream of `??`-chains.
+ * Each function here makes one decision: it resolves a configuration value with
+ * the right precedence, or fails with an actionable message. Together they let
+ * the client constructor read as a sequence of named steps rather than a chain
+ * of fallbacks.
  *
- * Customer-facing env surface is intentionally small: `ABLO_API_KEY`
- * is the only environment fallback. Other routing/auth overrides are
- * explicit options so generated apps do not accrete hidden env knobs.
+ * The environment surface is deliberately small: `ABLO_API_KEY` is the only
+ * value read from the environment. Every other routing or authentication
+ * override is an explicit option, so an app never picks up hidden behavior from
+ * a stray environment variable.
  */
 /**
- * The credential-resolver callable contract. Defined in the `credentialEndpoint`
- * leaf (which produces one) and re-exported here — the historical home — so
- * `./auth` importers keep working while the module graph stays one-directional
- * (`auth → credentialEndpoint`, never back). See there for the full contract.
+ * The credential-resolver callable type. It is defined alongside
+ * {@link createEndpointCredentialResolver} in `./credentialEndpoint` and
+ * re-exported here so importers of this module keep working. See that module
+ * for the full contract.
  */
 import type { ApiKeySetter } from './credentialEndpoint.js';
 export type { ApiKeySetter };
 export interface AuthResolveInput {
     /**
-     * The full options bag the caller passed to `Ablo()`. Resolvers
-     * read only the fields they care about; the wide shape avoids
-     * passing N parameters into each helper.
+     * The full set of options the caller passed to the client constructor. Each
+     * resolver reads only the fields it needs; passing the whole object avoids
+     * threading many separate parameters through every helper.
      */
     readonly options: {
         readonly apiKey?: string | ApiKeySetter | null;
@@ -63,20 +63,21 @@ export interface CliKeyMismatch {
     readonly kind: 'mode_mismatch' | 'key_override';
     readonly message: string;
 }
-/** Infer sandbox/production from Ablo key prefixes without importing CLI code. */
+/** Infer the sandbox or production mode from an Ablo key's prefix. */
 export declare function modeFromApiKey(key: string): CliMode | undefined;
 export declare function describeCliKeyMismatch(configured: StaticApiKey, cli: CliCredentialSnapshot): CliKeyMismatch | null;
 /**
- * Resolve the direct-URL connector's Postgres connection string.
+ * Resolves the Postgres connection string for the direct-connection option, or
+ * `null` when none was given.
  *
- * `databaseUrl` is an EXPLICIT, opt-in option: Ablo registers a dedicated
- * tenant database only when the caller passes it to `Ablo(...)`. It is NOT
- * read from `process.env.DATABASE_URL` — per this module's invariant
- * (`ABLO_API_KEY` is the only environment fallback), an app's `DATABASE_URL`
- * (commonly set for Prisma/Drizzle/docker) must never silently flip the client
- * into connection-string mode. The default Data Source path keeps `DATABASE_URL`
- * in the app and exposes `dataSource(...)`; that path leaves this null.
- * `warnIfDatabaseUrlEnvIgnored` nudges callers who set the env but omitted the option.
+ * `databaseUrl` is opt-in: the client registers a dedicated database only when
+ * the caller passes it explicitly. It is never read from
+ * `process.env.DATABASE_URL`, because this module treats `ABLO_API_KEY` as the
+ * one environment fallback — an app's `DATABASE_URL`, commonly set for other
+ * tools, must not silently switch the client into connection-string mode. The
+ * default path leaves `DATABASE_URL` untouched and reads through `dataSource(...)`
+ * instead, so this returns `null`. {@link warnIfDatabaseUrlEnvIgnored} nudges a
+ * caller who set the environment variable but omitted the option.
  */
 export declare function resolveDatabaseUrl(input: AuthResolveInput): string | null;
 export declare function warnIfDatabaseUrlEnvIgnored(input: AuthResolveInput, warn?: (message: string) => void): void;
@@ -84,17 +85,19 @@ export declare function warnIfDatabaseUrlDeprecated(input: AuthResolveInput, war
 export declare function warnIfCliKeyMismatch(input: AuthResolveInput, warn?: (message: string) => void): Promise<void>;
 export { ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, ABLO_DEFAULT_BASE_URL } from './hostedEndpoints.js';
 /**
- * Normalize old hosted aliases to the public API domain. Self-hosted/custom
- * URLs pass through unchanged; only first-party legacy hosts are rewritten.
+ * Normalizes older hosted host names to the current public API domain.
+ * Self-hosted or custom URLs pass through unchanged; only the retired
+ * first-party host names are rewritten.
  */
 export declare function normalizeAbloHostedBaseUrl(rawUrl: string): string;
 export declare function resolveBaseURL(input: AuthResolveInput): string;
 /**
- * Browser guard — apiKey is server-side-only by default. Same check
- * Anthropic, OpenAI, and Stripe ship: shipping `sk_live_...` to a
- * browser exposes it in every visitor's network tab. Consumers opt
- * in explicitly when the browser holds a minted session token
- * (`ek_`/`rk_`) or routes through a server proxy.
+ * Guards against using a secret `apiKey` in a browser. A secret key is
+ * server-side only by default: shipping an `sk_live_...` key to a browser would
+ * expose it in every visitor's network tab. Callers opt in explicitly when the
+ * browser instead holds a minted session token (`ek_`/`rk_`) or routes through a
+ * server proxy. Throws {@link AbloAuthenticationError} when a secret key is
+ * detected in a browser without opt-in.
  */
 export declare function assertBrowserSafety(input: {
     apiKey: string | ApiKeySetter | null;
@@ -102,24 +105,21 @@ export declare function assertBrowserSafety(input: {
     dangerouslyAllowBrowser: boolean | undefined;
 }): void;
 /**
- * Resolve an `ApiKeySetter` callable to its current string value.
- * Used at request time so a rotating credential picks up rotations
- * between requests. Returns `null` when no key was configured.
- *
- * Mirrors Anthropic's pattern of supporting both a static string and
- * a callable for credential rotation.
+ * Resolves an {@link ApiKeySetter} callable to its current string value, or
+ * returns a plain string key as-is. Called at request time so a rotating
+ * credential picks up new values between requests. Returns `null` when no key
+ * was configured.
  */
 export declare function resolveApiKeyValue(apiKey: string | ApiKeySetter | null): Promise<string | null>;
 /**
- * Translate a sync-engine WebSocket URL to the matching HTTP API
- * base URL, defaulting to `${url}/api` when the caller hasn't
- * overridden `bootstrapBaseUrl`. Used by `BootstrapHelper`,
- * `HydrationCoordinator`, the apiKey-exchange flow, and the
- * self-derived identity flow — same derivation in all four spots,
- * so it lives here as a single source of truth.
+ * Translates a WebSocket URL into the matching HTTP API base URL, defaulting to
+ * `${url}/api` when the caller has not overridden `bootstrapBaseUrl`. The
+ * bootstrap helper, the hydration coordinator, the credential-exchange flow, and
+ * the identity flow all derive their base URL through this one function, so the
+ * derivation stays consistent across them.
  *
- * Note: when both `wss://` and `https://` are valid, `replace(/^ws/, 'http')`
- * preserves the protocol family (ws → http, wss → https).
+ * When both `wss://` and `https://` are valid, the ws-to-http rewrite preserves
+ * the protocol family: ws becomes http and wss becomes https.
  */
 export declare function resolveBootstrapBaseUrl(input: {
     readonly url: string;