@abloatai/ablo 0.26.0 → 0.27.0

package/dist/client/credentialEndpoint.js

@@ -1,31 +1,29 @@
 /**
- * credentialEndpoint — the endpoint-string shape of `apiKey`.
+ * Support for the endpoint-string form of `apiKey`.
  *
- * `Ablo({ schema, apiKey: '/api/ablo-session' })` — point the client at your
- * session-mint route and the SDK owns the exchange: it POSTs the endpoint,
- * parses the minted token, keeps it fresh (the credential lifecycle), and
- * classifies failures onto the resolver tri-state. This is the Ably `authUrl`
- * / Liveblocks `authEndpoint` model — the string form is the 95% case; the
- * function form of `apiKey` remains the escape hatch for custom headers,
+ * With `Ablo({ schema, apiKey: '/api/ablo-session' })`, you point the client at
+ * your own session-mint route and the client owns the exchange: it POSTs to the
+ * endpoint, parses the minted token, keeps it fresh, and classifies failures
+ * onto the resolver's three outcomes. The string form covers the common case;
+ * the function form of `apiKey` remains the escape hatch for custom headers,
  * bodies, or non-HTTP mints.
  *
- * Detection is by prefix: a string starting with `/`, `http://`, or
- * `https://` is an endpoint; anything else is a literal key. Real Ablo keys
- * are `sk_`/`pk_`/`ek_`/`rk_`-prefixed, so the two shapes cannot collide.
- * (`ABLO_API_KEY` env values are NEVER endpoint-detected — the env var is
- * always a literal key; see `resolveApiKey`.)
+ * The form is detected by prefix: a string starting with `/`, `http://`, or
+ * `https://` is an endpoint, and anything else is a literal key. Ablo keys are
+ * prefixed (`sk_`/`pk_`/`ek_`/`rk_`), so the two shapes cannot collide. An
+ * `ABLO_API_KEY` environment value is never treated as an endpoint — it is
+ * always a literal key (see `resolveApiKey`).
  *
- * Wire contract — matches the `ablo init` scaffold route exactly:
+ * Wire contract:
  *   POST <endpoint>  (same-origin, `credentials: 'include'` so cookies flow)
- *   → 200 `{ token, expiresAt? }`      fresh short-lived `ek_`/`rk_`
- *   → 200 `{ token: null }` or 401/403 the login itself is gone (sign out)
- *   → anything else                    transient — retry, NEVER sign out
+ *   → 200 `{ token, expiresAt? }`       a fresh short-lived `ek_`/`rk_`
+ *   → 200 `{ token: null }` or 401/403  the login itself is gone (sign out)
+ *   → anything else                     transient — retry, do not sign out
  *
- * The tri-state mapping is the whole point of building this in: hand-written
- * thunks routinely get it wrong (mapping any `!res.ok` to `null` signs the
- * user out on a 500). Encoded here once, every consumer inherits the correct
- * terminal-vs-transient split (the Liveblocks `{ error: "forbidden" }` vs
- * retry contract, translated to HTTP statuses).
+ * The three-way mapping is the reason to build this in. Hand-written token
+ * fetchers routinely get it wrong — mapping any non-OK response to `null` signs
+ * the user out on a 500. Encoded here once, every consumer inherits the correct
+ * split between a terminal sign-out and a transient retry.
  */
 /**
  * Is this `apiKey` string a session-mint endpoint rather than a literal key?
@@ -35,22 +33,23 @@ export function isCredentialEndpoint(value) {
     return value.startsWith('/') || /^https?:\/\//i.test(value);
 }
 /**
- * Build the resolver behind an endpoint-string `apiKey`. Conforms to the
- * `ApiKeySetter` contract end-to-end:
- *   - resolves the minted token string on success,
- *   - resolves `null` when the login is gone (401/403, or an explicit
- *     `{ token: null }`) → terminal, the client signs out,
- *   - THROWS on anything transient (network failure, 5xx/429, malformed
- *     response) → the lifecycle backs off and retries, never signs out.
+ * Builds the resolver behind an endpoint-string `apiKey`. It follows the
+ * {@link ApiKeySetter} contract end to end:
+ *   - resolves the minted token string on success;
+ *   - resolves `null` when the login is gone (a 401 or 403, or an explicit
+ *     `{ token: null }`) — terminal, so the client signs out;
+ *   - throws on anything transient (a network failure, a 5xx or 429, or a
+ *     malformed response) — so the lifecycle backs off and retries without
+ *     signing out.
  *
- * A relative endpoint invoked server-side (Node fetch has no origin) throws —
- * transient by contract, and `credentialLifecycle` already translates that
- * exact failure into an actionable "use an absolute URL server-side" warning.
+ * A relative endpoint invoked on a server (where `fetch` has no origin) throws,
+ * which is transient by contract; the credential lifecycle translates that exact
+ * failure into an actionable "use an absolute URL server-side" warning.
  */
 export function createEndpointCredentialResolver(endpoint) {
     return async () => {
-        // fetch() rejections (offline, DNS, relative URL in Node) propagate as-is:
-        // a throw IS the transient signal in the resolver contract.
+        // `fetch()` rejections (offline, DNS, a relative URL on a server) propagate
+        // as-is: a throw is the transient signal in the resolver contract.
         const res = await fetch(endpoint, {
             method: 'POST',
             credentials: 'include',
@@ -70,9 +69,9 @@ export function createEndpointCredentialResolver(endpoint) {
         catch {
             throw new Error(`credential endpoint ${endpoint} returned non-JSON — expected { token }`);
         }
-        // Distinguish "explicitly signed out" ({ token: null }) from "not a mint
-        // endpoint at all" (no `token` key — misconfiguration must be LOUD and
-        // transient, never a silent sign-out).
+        // Distinguish "explicitly signed out" (`{ token: null }`) from "not a mint
+        // endpoint at all" (no `token` key). A misconfiguration must fail loudly and
+        // transiently, never as a silent sign-out.
         if (typeof body !== 'object' || body === null || !('token' in body)) {
             throw new Error(`credential endpoint ${endpoint} returned no \`token\` field — expected { token }`);
         }

package/dist/client/functionalUpdate.d.ts

@@ -1,30 +1,30 @@
 /**
  * The functional update — `ablo.<model>.update(id, current => next)`.
  *
- * This is the "just works under contention" surface. The developer expresses
- * ONLY their intent — "given the latest row, here is the next state" — and the
- * SDK owns everything else: read the fresh row + its watermark, run the updater,
- * write it as a compare-and-swap against that watermark, and on any concurrent
- * write re-read → recompute → retry. No claim, no identity, no transport
- * awareness, and no `stale_context` / `claim_*` error codes ever reach the
+ * This is the surface that just works under contention. You express only your
+ * intent — given the latest row, here is the next state — and the client does
+ * the rest: it reads the fresh row and its watermark, runs your updater, writes
+ * the result as a compare-and-swap against that watermark, and on any concurrent
+ * write it re-reads, recomputes, and retries. No claim, no identity, no transport
+ * awareness, and no `stale_context` or `claim_*` error codes ever reach the
  * caller. The write either lands or, at the extreme, throws a single
- * {@link AbloContentionError} after the reconcile budget is spent.
+ * {@link AbloContentionError} once the reconcile budget is spent.
  *
- * Correctness comes from the `readAt` watermark + `onStale: 'reject'`
- * (optimistic concurrency / compare-and-swap), NOT from participant identity —
- * which is why it is immune to the shared-credential silent-clobber footgun and
- * behaves identically on both transports. The HTTP and WebSocket clients inject
- * the same two thunks ({@link ReconcileTransport}); the loop below is shared, so
- * the guarantee can never drift between them — only the mechanism differs.
+ * Correctness comes from the `readAt` watermark plus `onStale: 'reject'`
+ * (optimistic concurrency, or compare-and-swap), not from participant identity.
+ * That is why it is immune to the shared-credential silent-overwrite hazard and
+ * behaves identically on both transports: the HTTP and WebSocket clients inject
+ * the same two functions ({@link ReconcileTransport}) into the shared loop below,
+ * so the guarantee cannot drift between them — only the mechanism differs.
  *
  * The mental model is React's `setState(prev => next)`: pass a function of the
- * current state, the runtime owns reconciliation.
+ * current state and the runtime owns reconciliation.
  */
 import { AbloContentionError } from '../errors.js';
 /**
  * The functional form of an update: given the freshly-read row, return the
- * fields to write. Return `null` / `undefined` to make NO write — a no-op the
- * caller decided on after seeing the latest state (e.g. "already done").
+ * fields to write. Return `null` or `undefined` to make no write — a no-op the
+ * caller chose after seeing the latest state (for example, "already done").
  */
 export type ModelUpdater<T> = (current: T) => Partial<T> | null | undefined | Promise<Partial<T> | null | undefined>;
 /** Tuning for the functional update's internal reconcile loop. */
@@ -41,30 +41,32 @@ export interface ContentionOptions {
 /** Reconcile rounds before a hot row is declared permanently contended. */
 export declare const DEFAULT_CONTENTION_RETRIES = 16;
 /**
- * Does this thrown error mean "another writer moved the row — re-read and
- * retry" rather than a genuine failure to surface? These are the optimistic-
- * concurrency signals the functional update reconciles against:
- *   - `stale_context` — our `readAt` watermark was overtaken by a concurrent write
- *   - `claim_lost`    — a holder preempted us (e.g. a human under `humansOverwrite`)
+ * Reports whether a thrown error means "another writer moved the row — re-read
+ * and retry" rather than a genuine failure to surface. These are the
+ * optimistic-concurrency signals the functional update reconciles against:
+ *   - `stale_context` — the `readAt` watermark was overtaken by a concurrent write
+ *   - `claim_lost`    — a holder preempted the write (for example a human under `humansOverwrite`)
  *   - `claim_queued`  — a holder is actively editing the row right now
  */
 export declare function isReconcilableConflict(err: unknown): boolean;
 /**
- * Transport-specific read/write the shared loop drives. Each client injects its
- * own pair — that's the ONLY thing that differs between HTTP and WebSocket.
+ * The transport-specific read and write that the shared loop drives. Each client
+ * injects its own pair — the one thing that differs between the HTTP and
+ * WebSocket transports.
  */
 export interface ReconcileTransport<T, R> {
     readonly model: string;
     readonly id: string;
-    /** Read the latest row + its watermark from the authoritative store. */
+    /** Read the latest row and its watermark from the authoritative store. */
     readFresh: () => Promise<{
         readonly data: T | null | undefined;
         readonly stamp: number;
     }>;
     /**
-     * Write the computed patch as a compare-and-swap against `readAt`. MUST throw
-     * a reconcilable conflict (`stale_context` / `claim_*`) when the watermark was
-     * overtaken — that rejection is what drives the next reconcile round.
+     * Write the computed patch as a compare-and-swap against `readAt`. It must
+     * throw a reconcilable conflict (`stale_context` or `claim_*`) when the
+     * watermark was overtaken — that rejection is what drives the next reconcile
+     * round.
      */
     writeNext: (patch: Partial<T>, readAt: number) => Promise<R>;
 }

package/dist/client/functionalUpdate.js

@@ -1,34 +1,34 @@
 /**
  * The functional update — `ablo.<model>.update(id, current => next)`.
  *
- * This is the "just works under contention" surface. The developer expresses
- * ONLY their intent — "given the latest row, here is the next state" — and the
- * SDK owns everything else: read the fresh row + its watermark, run the updater,
- * write it as a compare-and-swap against that watermark, and on any concurrent
- * write re-read → recompute → retry. No claim, no identity, no transport
- * awareness, and no `stale_context` / `claim_*` error codes ever reach the
+ * This is the surface that just works under contention. You express only your
+ * intent — given the latest row, here is the next state — and the client does
+ * the rest: it reads the fresh row and its watermark, runs your updater, writes
+ * the result as a compare-and-swap against that watermark, and on any concurrent
+ * write it re-reads, recomputes, and retries. No claim, no identity, no transport
+ * awareness, and no `stale_context` or `claim_*` error codes ever reach the
  * caller. The write either lands or, at the extreme, throws a single
- * {@link AbloContentionError} after the reconcile budget is spent.
+ * {@link AbloContentionError} once the reconcile budget is spent.
  *
- * Correctness comes from the `readAt` watermark + `onStale: 'reject'`
- * (optimistic concurrency / compare-and-swap), NOT from participant identity —
- * which is why it is immune to the shared-credential silent-clobber footgun and
- * behaves identically on both transports. The HTTP and WebSocket clients inject
- * the same two thunks ({@link ReconcileTransport}); the loop below is shared, so
- * the guarantee can never drift between them — only the mechanism differs.
+ * Correctness comes from the `readAt` watermark plus `onStale: 'reject'`
+ * (optimistic concurrency, or compare-and-swap), not from participant identity.
+ * That is why it is immune to the shared-credential silent-overwrite hazard and
+ * behaves identically on both transports: the HTTP and WebSocket clients inject
+ * the same two functions ({@link ReconcileTransport}) into the shared loop below,
+ * so the guarantee cannot drift between them — only the mechanism differs.
  *
  * The mental model is React's `setState(prev => next)`: pass a function of the
- * current state, the runtime owns reconciliation.
+ * current state and the runtime owns reconciliation.
  */
 import { AbloError, AbloNotFoundError, AbloStaleContextError, AbloClaimedError, AbloContentionError, } from '../errors.js';
 /** Reconcile rounds before a hot row is declared permanently contended. */
 export const DEFAULT_CONTENTION_RETRIES = 16;
 /**
- * Does this thrown error mean "another writer moved the row — re-read and
- * retry" rather than a genuine failure to surface? These are the optimistic-
- * concurrency signals the functional update reconciles against:
- *   - `stale_context` — our `readAt` watermark was overtaken by a concurrent write
- *   - `claim_lost`    — a holder preempted us (e.g. a human under `humansOverwrite`)
+ * Reports whether a thrown error means "another writer moved the row — re-read
+ * and retry" rather than a genuine failure to surface. These are the
+ * optimistic-concurrency signals the functional update reconciles against:
+ *   - `stale_context` — the `readAt` watermark was overtaken by a concurrent write
+ *   - `claim_lost`    — a holder preempted the write (for example a human under `humansOverwrite`)
  *   - `claim_queued`  — a holder is actively editing the row right now
  */
 export function isReconcilableConflict(err) {
@@ -82,6 +82,6 @@ export async function reconcileFunctionalUpdate(updater, options, transport) {
         cause: lastConflict,
     });
 }
-// Re-exported so call sites import the loop + its terminal error from one place;
-// the class itself lives with the rest of the hierarchy in `errors.ts`.
+// Re-exported so call sites import the loop and its terminal error from one
+// place; the class itself lives with the rest of the error hierarchy.
 export { AbloContentionError };

package/dist/client/hostedEndpoints.d.ts

@@ -1,18 +1,15 @@
 /**
- * The canonical Ablo Cloud endpoint constants — a ZERO-dependency leaf.
+ * The hosted Ablo Cloud endpoint constants, with no dependencies of their own.
  *
- * This is the single place the hosted API host is declared. Everything else
- * (`client/auth.ts` URL resolution, the CLI's `DEFAULT_URL`, the Data Source
- * connector's dial-out base, the generated OpenAPI `servers` entry, the
- * network probe's default) imports from here, so the next API-domain
- * migration is ONE edit — the `LEGACY_HOSTED_API_HOSTS` rewrite list in
- * `client/auth.ts` (four retired ablo.finance hosts) is proof such
- * migrations happen.
+ * This is the single place the hosted API host is declared. URL resolution, the
+ * CLI's default URL, the data-source connector's base, the generated OpenAPI
+ * server entry, and the network probe's default all import from here, so
+ * changing the API domain is a one-line edit.
  *
- * Kept dependency-free on purpose: `schema/openapi.ts` and `source/connector.ts`
- * consume it, and routing them through `client/auth.ts` would drag the error
- * registry + credential policy (and a `schema → client → errors →
- * coordination → schema` cycle) into subpaths that are otherwise clean.
+ * These constants are kept dependency-free deliberately: several low-level
+ * modules consume them, and routing those modules through the auth layer would
+ * pull the error registry and credential policy into otherwise-clean paths and
+ * risk an import cycle.
  */
 /** The hosted API domain (no scheme). */
 export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";

package/dist/client/hostedEndpoints.js

@@ -1,18 +1,15 @@
 /**
- * The canonical Ablo Cloud endpoint constants — a ZERO-dependency leaf.
+ * The hosted Ablo Cloud endpoint constants, with no dependencies of their own.
  *
- * This is the single place the hosted API host is declared. Everything else
- * (`client/auth.ts` URL resolution, the CLI's `DEFAULT_URL`, the Data Source
- * connector's dial-out base, the generated OpenAPI `servers` entry, the
- * network probe's default) imports from here, so the next API-domain
- * migration is ONE edit — the `LEGACY_HOSTED_API_HOSTS` rewrite list in
- * `client/auth.ts` (four retired ablo.finance hosts) is proof such
- * migrations happen.
+ * This is the single place the hosted API host is declared. URL resolution, the
+ * CLI's default URL, the data-source connector's base, the generated OpenAPI
+ * server entry, and the network probe's default all import from here, so
+ * changing the API domain is a one-line edit.
  *
- * Kept dependency-free on purpose: `schema/openapi.ts` and `source/connector.ts`
- * consume it, and routing them through `client/auth.ts` would drag the error
- * registry + credential policy (and a `schema → client → errors →
- * coordination → schema` cycle) into subpaths that are otherwise clean.
+ * These constants are kept dependency-free deliberately: several low-level
+ * modules consume them, and routing those modules through the auth layer would
+ * pull the error registry and credential policy into otherwise-clean paths and
+ * risk an import cycle.
  */
 /** The hosted API domain (no scheme). */
 export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';

package/dist/client/httpClient.d.ts

@@ -1,26 +1,23 @@
 /**
- * `createAbloHttpClient` — a STATELESS, typed HTTP client for server-side actors
- * (agents, workers, serverless), modelled on `@liveblocks/node` / the Stripe
- * server SDK / Netflix Conductor workers: it talks to Ablo over plain HTTP with
- * the credential as identity, and holds **no WebSocket and no connection state**.
+ * Creates a stateless, typed HTTP client for server-side actors — agents,
+ * workers, and serverless handlers. It talks to Ablo over plain request/response
+ * HTTP, uses the bearer credential as its identity, and holds no WebSocket and no
+ * connection state.
  *
- * Why this exists (docs/plans/agent-transport-event-driven.md): the stateful
- * `Ablo({ schema })` client is for INTERACTIVE participants — it opens a
- * WebSocket and seeds its identity (userId/orgId) during the connect/bootstrap
- * step, then routes writes through a `TransactionQueue` that drops mutations
- * until that identity exists. A reactive agent has no socket, so that identity is
- * never seeded and writes drop. The proven fix (unanimous across Liveblocks,
- * Stripe, PlanetScale, Conductor, Better Auth) is NOT to de-socket the stateful
- * client — it's a separate stateless client where the credential carries identity
- * and the SERVER resolves it per request.
+ * This is the counterpart to the stateful {@link Ablo} client. The stateful
+ * client is for interactive participants: it opens a WebSocket, learns its
+ * identity (user id and organization id) during the connect-and-bootstrap step,
+ * and routes writes through a queue that waits for that identity. A server-side
+ * actor has no socket, so instead of reusing that machinery it uses this client,
+ * where the credential itself carries identity and the server resolves it on
+ * every request.
  *
- * Ablo already has that stateless surface: `Ablo({ schema: null })` returns the
- * protocol client (`createProtocolClient` → `AbloApi`), which commits via
- * `POST /v1/commits` and reads via the HTTP `ApiClient`, authenticating with the
- * Bearer token on every request. Its only ergonomic gap is that model access is
- * string-keyed (`api.model('slides')`) rather than typed (`api.slides`). This
- * wraps it in a typed proxy facade so server code gets the SAME `client.<model>`
- * surface as the browser client — typed proxies, stateless transport.
+ * Under the hood this wraps the schema-agnostic protocol client that
+ * {@link createProtocolClient} returns in a typed proxy. The protocol client
+ * commits over `POST /v1/commits` and reads over HTTP, authenticating with the
+ * bearer token each time; its model access is string-keyed (`api.model('slides')`).
+ * The proxy gives server code the same typed `client.<model>` surface the
+ * stateful client offers, over stateless transport.
  */
 import { type AbloApiClientOptions } from './ApiClient.js';
 import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions, CreateSessionParams, AbloSession } from './resourceTypes.js';
@@ -28,73 +25,80 @@ import type { ModelCreateParams, ModelDeleteParams, ServerReadOptions, ModelRetr
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
 import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
 export interface AbloHttpClientOptions<S extends SchemaRecord> extends Omit<AbloApiClientOptions, 'schema'> {
-    /** The schema — used for TYPING only (typed model proxies); never sent or used at runtime. */
+    /** The schema. Used only to type the model proxies; it is never sent over the wire or read at runtime. */
     readonly schema: Schema<S>;
 }
 /**
- * The per-model HTTP surface — exactly what a stateless client can do over
- * request/response: reads (`retrieve`/`list`), writes (`create`/`update`/`delete`),
- * and the durable-lease claim plane (`claim` — acquire/hold/release). It does NOT
- * include `get`/`getAll`/`getCount` (local synced-pool reads) or `onChange` (live
- * subscription); those need the stateful plane and are absent BY TYPE here.
+ * The per-model surface of the stateless HTTP client — everything reachable over
+ * request/response: reads (`retrieve` and `list`), writes (`create`, `update`,
+ * and `delete`), and the durable-lease {@link HttpClaimApi | claim} plane for
+ * coordinated writes. It deliberately omits the stateful client's local-cache
+ * reads (`get`, `getAll`, `getCount`) and live subscriptions (`onChange`), which
+ * need a persistent socket; those are absent from the type, so reaching for one
+ * is a compile error rather than a runtime gap.
  *
- * Read-shape asymmetry (by design, not a gap): `retrieve(...)` returns a
- * `ModelRead<T>` envelope `{ data, stamp, claims }` — the stateless client has no
- * local graph, so the watermark/claims the stateful client reads from its pool
- * must ride inline on the read (an agent needs the `stamp` to do a stale-guarded
- * write; there is no `snapshot()` to fetch it from). `list(...)` returns a bare `T[]`.
+ * The read shapes differ on purpose. `retrieve` returns a {@link ModelRead}
+ * envelope of `{ data, stamp, claims }`, because a stateless client keeps no local
+ * copy of the data: the watermark (`stamp`) and any active claims must travel
+ * inline on the read so a caller can follow it with a stale-guarded write. `list`
+ * returns a plain array.
  */
 export interface HttpModelClient<T, C = T> {
     retrieve(params: ModelRetrieveParams & ModelReadOptions): Promise<ModelRead<T>>;
     list(options?: ServerReadOptions<T>): Promise<T[]>;
     /**
-     * Create a row and return it — the confirmed, authoritative server row (with
-     * framework defaults), mirroring the WebSocket client's `create`. A re-create
-     * of an existing caller-supplied id is idempotent and returns the EXISTING row.
+     * Creates a row and returns the confirmed server row, including any
+     * framework-applied defaults. Matches the stateful client's `create`. Passing an
+     * id that already exists is idempotent: the existing row is returned unchanged.
      */
     create(params: ModelCreateParams<T, C>): Promise<T>;
     update(params: ModelUpdateParams<C>): Promise<CommitReceipt>;
     /**
-     * Functional update under contention — `update(id, current => next)`, the
-     * `setState(prev => next)` of the data layer. The SDK reads the freshest row,
-     * runs your updater, writes it as a compare-and-swap, and re-reads + re-runs on
-     * any concurrent write. No claim, no identity, no conflict codes: the write
-     * lands or throws `AbloContentionError`. Return `null`/`undefined` to skip.
+     * Updates a row with a function of its latest value — `update(id, current =>
+     * next)`, the data-layer equivalent of a `setState(prev => next)` reducer. The
+     * client reads the freshest row, runs your updater, and writes the result as a
+     * compare-and-swap against the row's watermark; if another write landed first it
+     * re-reads and re-runs. No claim or conflict handling is needed: the write either
+     * lands or throws `AbloContentionError` once its retry budget is spent. Return
+     * `null` or `undefined` from the updater to skip the write.
      */
     update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<CommitReceipt | undefined>;
     delete(params: ModelDeleteParams<T>): Promise<CommitReceipt>;
     claim: HttpClaimApi<T>;
 }
 /**
- * The honest type of the stateless HTTP client: typed model proxies (the
- * request/response subset) + `commits` + `dispose`. Reaching for a
- * stateful-only capability (`get`/`getAll`/`getCount`, `onChange`,
- * `claim.state`/`queue`/`reorder`) is a COMPILE error here, not a latent runtime
- * `undefined` — the type matches what the transport can actually do.
+ * The type of the stateless HTTP client: a typed {@link HttpModelClient} per
+ * schema model, plus `commits`, `dispose`, and the session-mint surface. It
+ * exposes only what request/response transport can do, so reaching for a
+ * stateful-only capability — `get`, `getAll`, `getCount`, `onChange`, or the
+ * synchronous `claim.state`/`queue`/`reorder` reads — is a compile error rather
+ * than a value that is `undefined` at runtime.
  */
 export type AbloHttpClient<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: HttpModelClient<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
 } & {
-    /** Register `databaseUrl` when configured. Also runs lazily before the first request. */
+    /** Runs one-time setup, such as registering a configured `databaseUrl` data source, before the client is used. It also runs lazily ahead of the first request, so calling it yourself is optional. */
     ready(): Promise<void>;
     readonly commits: CommitResource;
     dispose(): Promise<void>;
-    /** Resolve the bearer credential this client authenticates with (see `AbloApi.getAuthToken`). */
+    /** Resolves the bearer credential this client authenticates with, or `null` if none is set. */
     getAuthToken(): Promise<string | null>;
     /**
-     * Mint a short-lived scoped session (Stripe ephemeral-key shape). Minting is a
-     * stateless control-plane call, so — unlike `get`/`getAll`/`onChange` — it IS
-     * available on the HTTP client. `{ user }` → `ek_`, `{ agent, can }` → `rk_`.
+     * Mints a short-lived, scoped session token. Minting is itself a stateless
+     * request, so it is available here even though the local-cache reads are not.
+     * Pass `{ user }` to mint an end-user key (`ek_`) or `{ agent, can }` to mint a
+     * scoped agent key (`rk_`). See {@link CreateSessionParams}.
      */
     readonly sessions: {
         create(params: CreateSessionParams<S>): Promise<AbloSession>;
     };
-    /** String-keyed model accessor (for dynamic model names). */
+    /** Looks up a model client by name, for when the model name is only known at runtime. */
     model<T = Record<string, unknown>>(name: string): HttpModelClient<T>;
 };
 /**
- * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol
- * client's `model(name)`; `commits`, `dispose`, etc. pass through. No socket is
- * ever opened; identity is the Bearer credential.
+ * Builds the stateless, typed HTTP client. Each `client.<model>` resolves to the
+ * protocol client's model accessor, while `commits`, `dispose`, and the other
+ * protocol members pass through unchanged. No socket is ever opened; the bearer
+ * credential is the identity.
  */
 export declare function createAbloHttpClient<S extends SchemaRecord>(options: AbloHttpClientOptions<S>): AbloHttpClient<S>;

package/dist/client/httpClient.js

@@ -1,34 +1,31 @@
 /**
- * `createAbloHttpClient` — a STATELESS, typed HTTP client for server-side actors
- * (agents, workers, serverless), modelled on `@liveblocks/node` / the Stripe
- * server SDK / Netflix Conductor workers: it talks to Ablo over plain HTTP with
- * the credential as identity, and holds **no WebSocket and no connection state**.
+ * Creates a stateless, typed HTTP client for server-side actors — agents,
+ * workers, and serverless handlers. It talks to Ablo over plain request/response
+ * HTTP, uses the bearer credential as its identity, and holds no WebSocket and no
+ * connection state.
  *
- * Why this exists (docs/plans/agent-transport-event-driven.md): the stateful
- * `Ablo({ schema })` client is for INTERACTIVE participants — it opens a
- * WebSocket and seeds its identity (userId/orgId) during the connect/bootstrap
- * step, then routes writes through a `TransactionQueue` that drops mutations
- * until that identity exists. A reactive agent has no socket, so that identity is
- * never seeded and writes drop. The proven fix (unanimous across Liveblocks,
- * Stripe, PlanetScale, Conductor, Better Auth) is NOT to de-socket the stateful
- * client — it's a separate stateless client where the credential carries identity
- * and the SERVER resolves it per request.
+ * This is the counterpart to the stateful {@link Ablo} client. The stateful
+ * client is for interactive participants: it opens a WebSocket, learns its
+ * identity (user id and organization id) during the connect-and-bootstrap step,
+ * and routes writes through a queue that waits for that identity. A server-side
+ * actor has no socket, so instead of reusing that machinery it uses this client,
+ * where the credential itself carries identity and the server resolves it on
+ * every request.
  *
- * Ablo already has that stateless surface: `Ablo({ schema: null })` returns the
- * protocol client (`createProtocolClient` → `AbloApi`), which commits via
- * `POST /v1/commits` and reads via the HTTP `ApiClient`, authenticating with the
- * Bearer token on every request. Its only ergonomic gap is that model access is
- * string-keyed (`api.model('slides')`) rather than typed (`api.slides`). This
- * wraps it in a typed proxy facade so server code gets the SAME `client.<model>`
- * surface as the browser client — typed proxies, stateless transport.
+ * Under the hood this wraps the schema-agnostic protocol client that
+ * {@link createProtocolClient} returns in a typed proxy. The protocol client
+ * commits over `POST /v1/commits` and reads over HTTP, authenticating with the
+ * bearer token each time; its model access is string-keyed (`api.model('slides')`).
+ * The proxy gives server code the same typed `client.<model>` surface the
+ * stateful client offers, over stateless transport.
  */
 import { createProtocolClient, } from './ApiClient.js';
 /**
- * Members of the underlying `AbloApi` that pass straight through the facade.
- * Deliberately EXCLUDES the resource names that collide with common schema model
- * names — `tasks`, `claims`, `capabilities`, `agent` — so `client.tasks` resolves
- * to the schema model `tasks`, not the protocol `TaskResource`. Only lifecycle +
- * the genuinely-protocol methods an agent uses pass through.
+ * Names on the underlying protocol client that pass straight through the proxy.
+ * This set intentionally leaves out names that collide with common schema models —
+ * `tasks`, `claims`, `capabilities`, `agent` — so that `client.tasks` resolves to
+ * the schema model named `tasks` rather than a protocol resource. Only lifecycle
+ * methods and the genuinely protocol-level members belong here.
  */
 const PROTOCOL_MEMBERS = new Set([
     'ready',
@@ -41,9 +38,10 @@ const PROTOCOL_MEMBERS = new Set([
     'sessions',
 ]);
 /**
- * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol
- * client's `model(name)`; `commits`, `dispose`, etc. pass through. No socket is
- * ever opened; identity is the Bearer credential.
+ * Builds the stateless, typed HTTP client. Each `client.<model>` resolves to the
+ * protocol client's model accessor, while `commits`, `dispose`, and the other
+ * protocol members pass through unchanged. No socket is ever opened; the bearer
+ * credential is the identity.
  */
 export function createAbloHttpClient(options) {
     // The schema is type-level only; the protocol client is schema-agnostic.
@@ -62,8 +60,8 @@ export function createAbloHttpClient(options) {
             return api.model(prop);
         },
     });
-    // One boundary cast — and now an HONEST one: `AbloHttpClient<S>` declares only
-    // what `api.model()` + the passed-through protocol members actually implement,
-    // so there is no method on this type that fails at runtime.
+    // A single boundary cast. `AbloHttpClient<S>` declares only what the model
+    // accessor and the passed-through protocol members actually implement, so no
+    // method on this type is missing at runtime.
     return facade;
 }