@abloatai/ablo 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.8.0
+
+A callable `claim` coordination namespace and bring-your-own-database support
+via a new `databaseUrl` option.
+
+### Minor Changes
+
+- **Callable `claim` coordination namespace.** Taking a claim and inspecting its
+  state now live under one accessor: `claim(id, work)` acquires a claim and runs
+  `work` while it's held, and `claim.state(id)`, `claim.queue(id)`,
+  `claim.release(id)`, and `claim.reorder(id, order)` cover the surrounding
+  lifecycle. The README leads with the problem (who is allowed to act, and in
+  what order) and the Quick Start now demonstrates `claim` directly.
+
+- **Bring-your-own-database via `databaseUrl`.** Point a project at your own
+  Postgres with `Ablo({ schema, apiKey, databaseUrl })`. Ablo writes synced rows
+  back into your database, so your data stays canonical. Server-side only;
+  defaults to `process.env.DATABASE_URL`. See the data-sources guide for setup
+  and role requirements.
+
+### Breaking
+
+- The flat coordination methods `claimState`, `queue`, `release`, and `reorder`
+  are removed in favor of the `claim` namespace above.
+
+  ```diff
+  - await ablo.task.claimState(id)
+  - await ablo.task.release(id)
+  + await ablo.task.claim.state(id)
+  + await ablo.task.claim.release(id)
+  ```
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -5,35 +5,40 @@
 [![types](https://img.shields.io/badge/types-included-blue.svg)](#)
 [![runtime](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](#keys--runtime)
 
-Ablo is a typed sync engine for shared app state — the kind that humans,
-server code, and AI agents all edit at once.
+**Let people and AI agents work on the same data without overwriting each other.**
 
-Reach for it when those edits need to show up everywhere in real time, not
-silently overwrite each other, expose who's working on what, and leave a record
-of who changed what.
+When an agent and a person change the same thing at once, work gets lost: one
+edit silently clobbers another, or the agent acts on data that already moved.
+Ablo gives them one shared, typed write path so people, server actions, and
+agents can all work on the same rows without working blind.
+
+The core idea is a **claim**. An agent's work is rarely one instant write; it
+reads something, thinks, calls an LLM or tool, then writes back. While that is
+happening, the row can change underneath it. So before slow work starts, the
+agent claims the row. If someone else is already working on it, `claim` waits,
+re-reads the fresh row, then hands it over. No stale overwrite, no separate
+agent mutation path.
+
+Under the hood, you define a Zod schema once and get typed model clients for
+every actor:
 
 ```txt
 schema -> ablo.<model>.create/retrieve/update/claim(...)
 ```
 
-## Why Ablo
-
-- **Real-time by default.** Every `create` / `update` / `delete` fans out
-  confirmed deltas to all subscribers — humans and agents — with no separate
-  "multiplayer mode" to switch on.
-- **No silent clobbers.** Writes are guarded against stale reads, and `claim`
-  holds a row across a slow read → LLM → write gap so concurrent edits queue
-  instead of overwriting.
-- **Built for agents.** See who's mid-edit (`claimState` / `queue`), coordinate a
-  fair line, and ship an `llms.txt` so coding agents integrate from the real API.
-- **Typed end to end.** Your Zod schema produces typed model proxies
-  (`ablo.<model>.update(...)`), optimistic local reads, and reactive React hooks.
-- **Bring your own auth and database.** Ablo scopes realtime data to *sync
-  groups* from your existing identity, and can leave your database as the source
-  of truth via a Data Source.
-
-**Built for:** collaborative editors, AI agent workflows, internal tools, and any
-app where multiple actors mutate shared state and everyone must see it live.
+The schema is the public contract. It gives you typed model methods, realtime
+fanout, React selectors, agent writes, and the HTTP/Data Source shape for
+non-JavaScript services. Every confirmed change shows up everywhere, and active
+claims are visible while the work is still in progress.
+
+[Get started ↓](#quick-start) · point your coding agent at the shipped `llms.txt`
+
+It works with the auth and database you already have: realtime data is scoped to
+*sync groups* from your own identity, and your database can stay the source of
+truth via a Data Source.
+
+**Built for** collaborative editors, AI agent workflows, and internal tools —
+anywhere people and agents change shared state and everyone has to see it live.
 
 ## Set up
 
@@ -83,12 +88,16 @@ const created = await ablo.weatherReports.create({
   status: 'pending',
 });
 
-const updated = await ablo.weatherReports.update(created.id, {
-  status: 'ready',
-  forecast: 'Light rain, 13C',
+// An agent claims the row, does its slow work, then writes back. While the
+// claim is held nobody else can overwrite it; anyone else who tries waits in
+// line and re-reads the result. This is the whole point of Ablo.
+await ablo.weatherReports.claim(created.id, async (report) => {
+  const forecast = await fetchForecast(report.location); // slow: API or LLM call
+  await ablo.weatherReports.update(report.id, { status: 'ready', forecast });
 });
 
-console.log({ id: updated.id, status: updated.status });
+const ready = ablo.weatherReports.get(created.id);
+console.log({ id: ready.id, status: ready.status });
 
 await ablo.dispose();
 ```
@@ -99,31 +108,30 @@ Expected output:
 { id: '...', status: 'ready' }
 ```
 
-Pass `schema` to get typed models like `ablo.weatherReports.update(...)`.
-
 ## Reading
 
-`retrieve(id)` returns one row from the local cache — synchronous, no round-trip.
-`list(...)` filters and sorts what's already synced; it's also synchronous, and
-reactive under `useAblo`/`subscribe`. `load(...)` fetches from the server when a
-row may not be local yet.
+Two ways to read, depending on whether you can wait. `get(id)` / `getAll({ where })`
+/ `getCount({ where })` are instant — they read what's already local and re-render
+on their own when it changes, so they're what your UI uses. `retrieve(id)` /
+`list({ where })` go ask the server and return a `Promise`, for when you need the
+authoritative answer right now.
 
 ```ts
-ablo.weatherReports.retrieve('report_stockholm');
+ablo.weatherReports.get('report_stockholm');
 
-const pending = ablo.weatherReports.list({
+const pending = ablo.weatherReports.getAll({
   where: { status: 'pending' },
   orderBy: { location: 'asc' },
   limit: 20,
 });
 
-const ready = await ablo.weatherReports.load({
+const ready = await ablo.weatherReports.list({
   where: { status: 'ready' },
   type: 'complete',
 });
 ```
 
-An array value in `where` means `IN`. On `load`, `type: 'complete'` waits for
+An array value in `where` means `IN`. On `list`, `type: 'complete'` waits for
 the server; `'unknown'` returns what's local now and refreshes in the background.
 
 ## Writing
@@ -163,8 +171,8 @@ returns or throws.
 See who's mid-edit before you act — decide to wait, or skip:
 
 ```ts
-ablo.weatherReports.claimState('report_stockholm');
-ablo.weatherReports.queue('report_stockholm');
+ablo.weatherReports.claim.state('report_stockholm');
+ablo.weatherReports.claim.queue('report_stockholm');
 
 await ablo.weatherReports.claim(id, async (report) => {
   /* do the held work */
@@ -175,7 +183,7 @@ await ablo.weatherReports.claim(id, async (report) => {
 }, { maxQueueDepth: 2 });
 ```
 
-`claimState` returns the holder (or `null`); `queue` returns the line waiting
+`claim.state` returns the holder (or `null`); `claim.queue` returns the line waiting
 behind it. `wait: false` skips rather than waiting when the row is held;
 `maxQueueDepth: 2` bails when two or more are already ahead.
 
@@ -195,8 +203,8 @@ try {
 > Prefer the callback form for ordinary held work. Manual scoped claims are
 > available for wider lifetimes, but callback claims are the docs default.
 
-See [Coordination](./docs/coordination.md) for the full `claim` / `claimState` /
-`queue` / `release` reference.
+See [Coordination](./docs/coordination.md) for the full `claim` / `claim.state` /
+`claim.queue` / `claim.release` reference.
 
 ## React
 
@@ -217,7 +225,7 @@ function App() {
 }
 
 function Report({ id }: { id: string }) {
-  const report = useAblo((ablo) => ablo.weatherReports.retrieve(id));
+  const report = useAblo((ablo) => ablo.weatherReports.get(id));
   const ablo = useAblo();
 
   if (!report) return null;
@@ -277,7 +285,7 @@ each other's changes in real time — that's the default, not a feature you turn
 
 - `ablo.<model>.create/update/delete` fan out confirmed deltas to subscribers.
 - `useAblo(...)` gives React clients the live row, kept current automatically.
-- `ablo.<model>.claim(id)` / `claimState(id)` / `queue(id)` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
+- `ablo.<model>.claim(id)` / `claim.state(id)` / `queue(id)` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
 
 Always write through Ablo — either the SDK model methods
 (`ablo.<model>.create/update/delete`) or the HTTP write endpoint below. If you
@@ -372,10 +380,11 @@ contract; there are no retry or timeout knobs to tune.
 ## Production Reference
 
 - [Identity & Sync Groups](./docs/identity.md) — bring your own auth; tell Ablo who's connecting and how org / team / user map to sync-group scope.
+- [Schema Contract](./docs/schema-contract.md) — one schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
 - [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
-- [Coordination](./docs/coordination.md) — `claim` / `claimState` / `queue` / `release` reference: hold a row across slow agent work, and observe the line waiting behind it.
+- [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
 - [Connect Your Database](./docs/data-sources.md) — keep canonical rows in your app database without giving Ablo database credentials.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.

package/dist/BaseSyncedStore.js

@@ -12,7 +12,7 @@
  * pull generic methods into this base class.
  */
 import { makeObservable, observable, computed, runInAction } from 'mobx';
-import { AbloConnectionError, AbloValidationError } from './errors.js';
+import { AbloConnectionError, AbloValidationError, toAbloError } from './errors.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
 import { PropertyType } from './types/index.js';
 import { SyncWebSocket, } from './sync/SyncWebSocket.js';
@@ -447,14 +447,18 @@ export class BaseSyncedStore {
                 }
             }
         }
-        throw lastError || new Error('Bootstrap failed after all retry attempts');
+        throw lastError
+            ? toAbloError(lastError)
+            : new AbloConnectionError('Bootstrap failed after all retry attempts', {
+                code: 'bootstrap_fetch_timeout',
+            });
     }
     /** Create a timeout promise for bootstrap attempts */
     createBootstrapTimeout(attempt) {
         const timeoutMs = BOOTSTRAP_CONFIG.OVERALL_TIMEOUT_MS + (attempt - 1) * 3_000;
         return new Promise((_, reject) => {
             setTimeout(() => {
-                reject(new Error(`Bootstrap timed out after ${timeoutMs}ms (attempt ${attempt})`));
+                reject(new AbloConnectionError(`Bootstrap timed out after ${timeoutMs}ms (attempt ${attempt})`, { code: 'bootstrap_fetch_timeout' }));
             }, timeoutMs);
         });
     }

package/dist/SyncEngineContext.d.ts

@@ -33,7 +33,8 @@ export declare const noopObservability: SyncObservabilityProvider;
 export declare const noopAnalytics: SyncAnalytics;
 /** Browser-native online status provider */
 export declare const browserOnlineStatus: OnlineStatusProvider;
-/** Permissive session error detector — treats 401/403 as session errors */
+/** Session error detector — delegates to SyncSessionError so detection is
+ *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
 export declare const defaultSessionErrorDetector: SessionErrorDetector;
 /**
  * Fallback config used when the context is read before

package/dist/SyncEngineContext.js

@@ -4,6 +4,7 @@
  * All SDK classes receive this context at construction time.
  * It bundles every injectable dependency so constructors stay clean.
  */
+import { SyncSessionError } from './errors.js';
 // ─────────────────────────────────────────────
 // No-op defaults for optional dependencies
 // ─────────────────────────────────────────────
@@ -45,7 +46,8 @@ export const browserOnlineStatus = {
         return typeof navigator !== 'undefined' ? navigator.onLine : true;
     },
 };
-/** Permissive session error detector — treats 401/403 as session errors */
+/** Session error detector — delegates to SyncSessionError so detection is
+ *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
 export const defaultSessionErrorDetector = {
     isSessionError(error) {
         if (error && typeof error === 'object' && 'isSessionError' in error) {
@@ -53,8 +55,8 @@ export const defaultSessionErrorDetector = {
         }
         return false;
     },
-    isSessionErrorResponse(status) {
-        return status === 401 || status === 403;
+    isSessionErrorResponse(status, body) {
+        return SyncSessionError.isSessionErrorResponse(status, body);
     },
 };
 /**

package/dist/agent/session.js

@@ -20,6 +20,7 @@
  * The helper itself imports nothing app-specific. Open-source-clean.
  */
 import { Ablo } from '../client/Ablo.js';
+import { AbloConnectionError } from '../errors.js';
 /**
  * Returns a session whose `getAgent` method handles cache, mint,
  * sync_groups alignment, and lifecycle. Call `disposeAll()` from
@@ -113,8 +114,8 @@ export function createAgentSession(options) {
                 causeMsg,
                 err,
             });
-            throw new Error(`ws bootstrap ${wsUrl} failed: ${e.message ?? 'bootstrap failed'}` +
-                (code ? ` (${code})` : ''));
+            throw new AbloConnectionError(`ws bootstrap ${wsUrl} failed: ${e.message ?? 'bootstrap failed'}` +
+                (code ? ` (${code})` : ''), { code: 'bootstrap_fetch_timeout', cause: err });
         }
         cacheByKey.set(key, { agent, expiresAtMs: minted.expiresAtMs });
         return agent;

package/dist/auth/index.js

@@ -11,7 +11,25 @@
  * SDKs hide their internal auth-handshake — the apiKey is the only
  * credential the consumer touches.
  */
-import { AbloAuthenticationError } from '../errors.js';
+import { AbloAuthenticationError, translateHttpError } from '../errors.js';
+/**
+ * Whether an HTTP error body carries a code `translateHttpError` can read —
+ * a top-level `code`, a nested `error.code`, or a string `error`. When it
+ * doesn't (empty body, non-JSON, or a non-Ablo proxy 401), the caller falls
+ * back to its own default code rather than emitting a code-less error.
+ */
+function hasWireCode(body) {
+    if (typeof body !== 'object' || body === null)
+        return false;
+    const b = body;
+    if (typeof b.code === 'string')
+        return true;
+    if (typeof b.error === 'string')
+        return true;
+    return (typeof b.error === 'object' &&
+        b.error !== null &&
+        typeof b.error.code === 'string');
+}
 export async function exchangeApiKey(options) {
     if (!options.apiKey) {
         throw new AbloAuthenticationError('apiKey is required for capability exchange', { code: 'apikey_missing' });
@@ -59,11 +77,16 @@ export async function exchangeApiKey(options) {
         catch {
             // ignore — server returned non-JSON error
         }
-        const errBody = body;
-        throw new AbloAuthenticationError(`apiKey exchange rejected (${response.status}): ${errBody?.reason ?? response.statusText}`, {
-            code: errBody?.error ?? 'exchange_failed',
-            httpStatus: response.status,
-        });
+        // Route through the canonical wire-error translator so the server's
+        // envelope (`code` + `message` + `doc_url`) propagates verbatim and maps to
+        // the right AbloError subclass — instead of the legacy `error`/`reason`
+        // shape this used to read (which the server no longer emits, collapsing
+        // every failure to a generic code with an empty message). Fall back to
+        // `exchange_failed` only when the body carried no recognizable code.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`apiKey exchange rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
     }
     const raw = (await response.json());
     if (!isCapabilityExchangeResponse(raw)) {
@@ -130,11 +153,16 @@ export async function resolveIdentity(options) {
         catch {
             // ignore non-JSON auth errors
         }
-        const errBody = body;
-        throw new AbloAuthenticationError(`identity resolve rejected (${response.status}): ${errBody?.reason ?? response.statusText}`, {
-            code: errBody?.error ?? 'identity_resolve_failed',
-            httpStatus: response.status,
-        });
+        // Canonical envelope translation (see `exchangeApiKey` above). This is what
+        // surfaces the sync-server's precise auth diagnosis — e.g.
+        // `jwt_issuer_untrusted` with its full message — to the SDK consumer,
+        // instead of collapsing every 401 to `identity_resolve_failed` with an
+        // empty reason because the old parser looked for `error`/`reason` keys the
+        // server doesn't emit.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`identity resolve rejected (${response.status})`, { code: 'identity_resolve_failed', httpStatus: response.status });
     }
     return (await response.json());
 }

package/dist/client/Ablo.d.ts

@@ -88,6 +88,21 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * usually don't pass this explicitly server-side.
      */
     apiKey?: string | ApiKeySetter | null | undefined;
+    /**
+     * Connection string to YOUR OWN Postgres. When set, Ablo registers this
+     * database as your project's data store and writes synced rows back into it
+     * (dedicated/BYO tenant), so your data stays canonical in your DB while Ablo
+     * runs the sync/coordination plane. Defaults to `process.env['DATABASE_URL']`.
+     *
+     * SERVER-ONLY: this carries credentials, so it is never sent from the browser
+     * — constructing a client with `databaseUrl` and `dangerouslyAllowBrowser`
+     * throws. Provide Ablo a NON-superuser, non-`BYPASSRLS` role: the server runs
+     * the tenant plane with row-level security forced, and rejects a privileged
+     * role that couldn't enforce isolation.
+     *
+     * Omit it to use Ablo-managed storage (the hosted default).
+     */
+    databaseUrl?: string | null | undefined;
     /**
      * Local persistence mode. Pass `indexeddb` only when you want offline
      * queueing and a reload-surviving browser cache.
@@ -112,8 +127,8 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
     defaultQuery?: Record<string, string | undefined> | undefined;
     /**
      * Client-side use is disabled by default because private API keys should
-     * not ship to browsers. Set this only when using a publishable/browser-safe
-     * key or a controlled server proxy.
+     * not ship to browsers. Set this only when the browser holds a minted
+     * session token (`ek_`/`rk_`) or you route through a controlled server proxy.
      */
     dangerouslyAllowBrowser?: boolean | undefined;
 }
@@ -168,7 +183,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Client-side use of this SDK is disabled by default — your apiKey
      * would ship to every visitor's network tab. Only set this to
      * `true` if you've understood the risk and have appropriate
-     * mitigations (a publishable key, a server-side proxy, etc).
+     * mitigations (a minted session token, a server-side proxy, etc).
      */
     dangerouslyAllowBrowser?: boolean | undefined;
     /**
@@ -459,6 +474,72 @@ export interface ModelClient<T = Record<string, unknown>> {
     update(id: string, data: Record<string, unknown>, options?: ModelMutationOptions): Promise<CommitReceipt>;
     delete(id: string, options?: ModelMutationOptions): Promise<CommitReceipt>;
 }
+/** A single data operation a scoped **agent** session may perform on a model. */
+export type SessionOperation = 'read' | 'create' | 'update' | 'delete';
+/** Mint params for an **end-user** session — full data authority within the
+ *  org (the Stripe `ephemeralKeys.create` / Supabase session shape). Mints an
+ *  `ek_` token. `user.id` is your end user's external IdP id (becomes the
+ *  session's `participantId`); Ablo does not model your users, so it's an
+ *  honest string at the trust boundary. */
+export interface CreateUserSessionParams {
+    /** Your end user. `id` becomes the token's `participantId`. */
+    user: {
+        id: string;
+    };
+    /** Sync groups this session may subscribe to. Omit to inherit the key's scope. */
+    syncGroups?: readonly string[];
+    /** Token lifetime in seconds. Defaults to 900 (15m, the Stripe ephemeral default). */
+    ttlSeconds?: number;
+    /** Opaque identity blob echoed back to the client as `ablo.user`. */
+    userMeta?: Record<string, unknown>;
+    agent?: never;
+    can?: never;
+}
+/** Mint params for a scoped **agent** session — mints a restricted `rk_` token
+ *  gated to exactly the operations named in `can`. `can` is typed off your
+ *  schema (no magic `'task.update'` strings): `{ Task: ['update'], Deck: ['read'] }`
+ *  — the SDK serializes each entry to the wire allowlist (`task.update`). */
+export interface CreateAgentSessionParams<S extends SchemaRecord> {
+    /** Your agent. `id` becomes the token's `participantId`. */
+    agent: {
+        id: string;
+    };
+    /** Per-model operation allowlist, typed against the schema's model names. */
+    can: {
+        [M in keyof S & string]?: readonly SessionOperation[];
+    };
+    /** Sync groups this session may subscribe to. Omit to inherit the key's scope. */
+    syncGroups?: readonly string[];
+    /** Token lifetime in seconds. Defaults to 900 (15m, the Stripe ephemeral default). */
+    ttlSeconds?: number;
+    /** Opaque identity blob echoed back to the client as `ablo.agent`. */
+    userMeta?: Record<string, unknown>;
+    user?: never;
+}
+/** Params for {@link Ablo.sessions}.create — a discriminated union: pass
+ *  `{ user }` for a full-authority end-user session (`ek_`) or `{ agent, can }`
+ *  for a scoped agent session (`rk_`). */
+export type CreateSessionParams<S extends SchemaRecord> = CreateUserSessionParams | CreateAgentSessionParams<S>;
+/** A minted end-user session token — the Stripe ephemeral-key / Supabase
+ *  session resource. `token` is the secret the browser presents as its bearer. */
+export interface AbloSession {
+    object: 'session';
+    /** Stable id of the minted credential (for revocation). */
+    id: string;
+    /** The short-lived `rk_` session token. Hand this to the user's browser. */
+    token: string;
+    /** ISO-8601 expiry. */
+    expiresAt: string;
+    organizationId: string;
+    scope: {
+        organizationId: string;
+        syncGroups: readonly string[];
+        operations: readonly string[];
+        participantKind: 'user' | 'agent' | 'system';
+        participantId: string;
+    };
+    userMeta: Record<string, unknown>;
+}
 /** 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>>;
@@ -502,6 +583,31 @@ export type Ablo<S extends SchemaRecord> = {
     waitForFlush(timeoutMs?: number): Promise<void>;
     /** Disconnect and clean up */
     dispose(): Promise<void>;
+    /**
+     * Replace the bearer auth token used for the WebSocket upgrade and HTTP
+     * requests, WITHOUT tearing down the engine. Use to push a refreshed
+     * short-lived token (e.g. a 15m JWT) before it expires — `<AbloProvider>`'s
+     * `getToken` refresh loop calls this. Reuses the same rotation path as the
+     * internal capability-token refresh; safe to call before `ready()`.
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Mint a short-lived, scoped **session token** for one end user — the
+     * Stripe `ephemeralKeys.create` / Supabase session shape. Call this on YOUR
+     * BACKEND (where the `sk_` secret key lives), then hand the returned
+     * `token` to that user's browser (typically via an authEndpoint the client
+     * fetches). The browser presents it as the bearer; the sync-server verifies
+     * the scoped `rk_` token via `apiKeyProvider`.
+     *
+     * The browser must NEVER see the `sk_` key — only the per-user session token.
+     *
+     * Pass `{ user: { id } }` for a full-authority end-user session (mints `ek_`),
+     * or `{ agent: { id }, can: { Task: ['update'] } }` for a scoped agent
+     * session (mints `rk_`); `can` is typed against your schema's model names.
+     */
+    sessions: {
+        create(params: CreateSessionParams<S>): Promise<AbloSession>;
+    };
     /**
      * Destroy every IndexedDB database owned by this engine. Disconnects
      * the WebSocket, releases timers, and deletes all `ablo_*` / `ablo-*`
@@ -766,6 +872,8 @@ export declare namespace Ablo {
     type CapabilityRecord = import('./ApiClient.js').CapabilityRecord;
     type CapabilityResource = import('./ApiClient.js').CapabilityResource;
     type CapabilityRevocation = import('./ApiClient.js').CapabilityRevocation;
+    type CapabilityRotateOptions = import('./ApiClient.js').CapabilityRotateOptions;
+    type RotatedCapability = import('./ApiClient.js').RotatedCapability;
     type Task = import('./ApiClient.js').Task;
     type TaskCreateOptions = import('./ApiClient.js').TaskCreateOptions;
     type TaskCloseOptions = import('./ApiClient.js').TaskCloseOptions;