@abloatai/ablo 0.6.0 → 0.8.0

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;
@@ -784,6 +892,7 @@ export declare namespace Ablo {
     type ActiveIntent = _Streams.ActiveIntent;
     type Claim = _Streams.Claim;
     type IntentRejection = _Streams.IntentRejection;
+    type IntentLost = _Streams.IntentLost;
     type Snapshot<TSchema extends _SchemaTypes.Schema = _SchemaTypes.Schema, K extends keyof TSchema['models'] = keyof TSchema['models']> = _Streams.Snapshot<TSchema, K>;
     type Turn = import('./Ablo.js').Turn;
     namespace Auth {

package/dist/client/Ablo.js

@@ -16,12 +16,13 @@
  *   await sync.reports.delete(reportId);
  */
 import { z } from 'zod';
-import { AbloClaimedError, AbloError, AbloConnectionError, AbloValidationError, translateHttpError } from '../errors.js';
+import { AbloClaimedError, AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, hasWireCode, toAbloError } from '../errors.js';
 import { LoadStrategy, PropertyType } from '../types/index.js';
 import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
 import { alwaysOnline } from '../adapters/alwaysOnline.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
+import { exchangeApiKey } from '../auth/index.js';
 import { createInternalComponents } from './createInternalComponents.js';
 import { resolveParticipantIdentity } from './identity.js';
 import { Model } from '../Model.js';
@@ -32,7 +33,8 @@ import { awaitIntentGrant } from '../sync/awaitIntentGrant.js';
 import { createSnapshot } from '../sync/createSnapshot.js';
 import { createParticipantManager } from '../sync/participants.js';
 import { createProtocolClient, } from './ApiClient.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveAuthToken, resolveBaseURL, } from './auth.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, } from './auth.js';
+import { registerDataSource } from './registerDataSource.js';
 import { shouldUseInMemoryPersistence, } from './persistence.js';
 import { createModelProxy } from './createModelProxy.js';
 // ── Config derivation from schema ─────────────────────────────────────────
@@ -653,8 +655,10 @@ export function Ablo(options) {
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);
+    const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
     assertBrowserSafety({
         apiKey: configuredApiKey,
+        databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
     const { logger = consoleLogger } = internalOptions;
@@ -827,6 +831,19 @@ export function Ablo(options) {
         }
         _readyPromise = (async () => {
             try {
+                // Register the caller's own database for write-back BEFORE bootstrap, so
+                // the server resolves this org's data plane to the customer's DB rather
+                // than serving an empty/wrong store. The org is derived server-side from
+                // the API key. Idempotent server-side (register-or-update). Skipped when
+                // no `databaseUrl` was configured (Ablo-managed storage).
+                if (configuredDatabaseUrl) {
+                    await registerDataSource({
+                        baseUrl: resolveBootstrapBaseUrl({ url }),
+                        apiKey: await resolveApiKeyValue(configuredApiKey),
+                        databaseUrl: configuredDatabaseUrl,
+                        ...(internalOptions.fetch ? { fetchImpl: internalOptions.fetch } : {}),
+                    });
+                }
                 // Resolve participant identity + scope. Three branches —
                 // hosted-cloud apiKey exchange, self-derived from capability
                 // token, or legacy explicit options. See `./identity.ts`.
@@ -836,7 +853,15 @@ export function Ablo(options) {
                     url,
                     kind,
                     configuredApiKey,
-                    configuredAuthToken,
+                    // Resolve identity against the LIVE token, not the construction-time
+                    // `configuredAuthToken`. Consumers using `getToken` (apps/web) never
+                    // pass `authToken` at construction — they call `setAuthToken()` before
+                    // `ready()`, which updates `currentCapabilityToken`. Reading the frozen
+                    // `configuredAuthToken` here made `/auth/identity` fire with no Bearer
+                    // (→ `no_matching_provider` / `session_expired`) even though the JWT
+                    // was present. Mirrors `authHeaders()`'s `currentCapabilityToken ??
+                    // configuredAuthToken` precedence.
+                    configuredAuthToken: currentCapabilityToken ?? configuredAuthToken,
                     bootstrapHelper,
                     logger,
                     applyRotatedToken: (token) => {
@@ -902,7 +927,11 @@ export function Ablo(options) {
                 }
                 const result = current.value;
                 if (!result.success) {
-                    throw result.error ?? new Error('Sync engine initialization failed');
+                    throw result.error
+                        ? toAbloError(result.error)
+                        : new AbloConnectionError('Sync engine initialization failed', {
+                            code: 'bootstrap_fetch_timeout',
+                        });
                 }
                 // Wire presence + intents to the now-open transport.
                 // `getSyncWebSocket()` returns non-null after a successful
@@ -916,11 +945,23 @@ export function Ablo(options) {
                 logger.info('Sync engine ready', { models: Object.keys(schema.models).length });
             }
             catch (err) {
-                const error = err instanceof Error ? err : new Error(String(err));
+                // Coerce so the rejection a consumer awaiting `ready()` catches is
+                // always an AbloError — connection setup is held to the same
+                // never-leak-untagged contract as the model operations.
+                const error = toAbloError(err);
                 // Make sure syncStatus reflects the failure for observer() components
                 store.syncStatus.state = 'error';
                 store.syncStatus.error = error;
-                logger.error('Sync engine failed to initialize', { error: error.message });
+                // Log the typed envelope (type + code + status), not just the bare
+                // message — so the console line names it as an Ablo error and carries
+                // the code (e.g. AbloAuthenticationError/identity_resolve_failed on a
+                // 401) instead of reading like an untagged failure.
+                logger.error('Sync engine failed to initialize', {
+                    type: error.type,
+                    code: error.code,
+                    httpStatus: error.httpStatus,
+                    error: error.message,
+                });
                 throw error;
             }
         })();
@@ -1211,6 +1252,7 @@ export function Ablo(options) {
                 entities: { [modelKey]: id },
             }),
             queue: (target) => publicIntents.queueFor({ type: target.model, id: target.id }),
+            reorder: (target, order) => publicIntents.reorder({ type: target.model, id: target.id }, order),
             observe: (target) => {
                 // The live intent stream only tracks *open* (active) claims;
                 // terminal states (committed / expired / canceled) drop out of
@@ -1383,6 +1425,68 @@ export function Ablo(options) {
         ...modelProxies,
         ready,
         waitForFlush,
+        setAuthToken(token) {
+            // Same rotation path as the internal capability-token refresh
+            // (`applyRotatedToken` in `ready()`): update the closure binding the
+            // HTTP hydration provider reads, push to the bootstrap helper's header,
+            // and swap it on the live WebSocket. Decoupled from `ready()` so a
+            // refreshed JWT can be pushed at any point in the engine's lifetime.
+            currentCapabilityToken = token;
+            bootstrapHelper.setAuthToken(token);
+            store.getSyncWebSocket()?.setCapabilityToken(token);
+        },
+        sessions: {
+            // Stripe `ephemeralKeys.create` shape: a BACKEND (holding `sk_`) mints a
+            // short-lived scoped token for one end user OR one agent. Thin wrapper over
+            // the `/auth/capability` exchange, reshaped to a Stripe-style resource.
+            async create(params) {
+                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' });
+                }
+                const baseUrl = resolveBootstrapBaseUrl({
+                    url,
+                    bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
+                });
+                // Discriminate the union: `{ user }` → full-authority `ek_` (no op
+                // allowlist); `{ agent, can }` → scoped `rk_`. `can: { Task: ['update'] }`
+                // serializes to the wire allowlist `['task.update']` — the Hub matches
+                // `${model.toLowerCase()}.${op}` (Hub.ts handleCommit).
+                let participantKind;
+                let participantId;
+                let operations;
+                if (params.user) {
+                    participantKind = 'user';
+                    participantId = params.user.id;
+                    operations = undefined;
+                }
+                else {
+                    participantKind = 'agent';
+                    participantId = params.agent.id;
+                    operations = Object.entries(params.can).flatMap(([model, ops]) => (ops ?? []).map((op) => `${model.toLowerCase()}.${op}`));
+                }
+                const res = await exchangeApiKey({
+                    apiKey,
+                    baseUrl,
+                    participantKind,
+                    participantId,
+                    ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+                    ...(operations ? { operations } : {}),
+                    ttlSeconds: params.ttlSeconds ?? 900,
+                    ...(params.userMeta ? { userMeta: params.userMeta } : {}),
+                    ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
+                });
+                return {
+                    object: 'session',
+                    id: res.capabilityId,
+                    token: res.token,
+                    expiresAt: res.expiresAt,
+                    organizationId: res.organizationId,
+                    scope: res.scope,
+                    userMeta: res.userMeta,
+                };
+            },
+        },
         async dispose() {
             _refreshScheduler?.dispose();
             _refreshScheduler = null;
@@ -1490,8 +1594,24 @@ export function Ablo(options) {
                 }),
             });
             if (!res.ok) {
-                const body = await res.text().catch(() => '<no body>');
-                throw new AbloError(`beginTurn failed: ${res.status} ${body}`, { code: 'turn_open_failed', httpStatus: res.status });
+                const text = await res.text().catch(() => '');
+                let parsed = text;
+                if (text) {
+                    try {
+                        parsed = JSON.parse(text);
+                    }
+                    catch {
+                        /* keep raw text */
+                    }
+                }
+                // Preserve the server's structured envelope (code/message/doc_url) when
+                // present; fall back to turn_open_failed for a bare/non-Ablo body.
+                throw hasWireCode(parsed)
+                    ? translateHttpError(res.status, parsed, res.headers.get('x-request-id') ?? undefined)
+                    : new AbloError(`beginTurn failed: ${res.status} ${text}`, {
+                        code: 'turn_open_failed',
+                        httpStatus: res.status,
+                    });
             }
             const json = (await res.json());
             const turnId = json.turnId;
@@ -1514,8 +1634,22 @@ export function Ablo(options) {
                     }),
                 });
                 if (!closeRes.ok) {
-                    const body = await closeRes.text().catch(() => '<no body>');
-                    throw new AbloError(`closeTurn failed: ${closeRes.status} ${body}`, { code: 'turn_close_failed', httpStatus: closeRes.status });
+                    const text = await closeRes.text().catch(() => '');
+                    let parsed = text;
+                    if (text) {
+                        try {
+                            parsed = JSON.parse(text);
+                        }
+                        catch {
+                            /* keep raw text */
+                        }
+                    }
+                    throw hasWireCode(parsed)
+                        ? translateHttpError(closeRes.status, parsed, closeRes.headers.get('x-request-id') ?? undefined)
+                        : new AbloError(`closeTurn failed: ${closeRes.status} ${text}`, {
+                            code: 'turn_close_failed',
+                            httpStatus: closeRes.status,
+                        });
                 }
             };
             const dispose = () => {

package/dist/client/ApiClient.d.ts

@@ -73,10 +73,42 @@ export interface CapabilityRevocation {
     readonly deleted: boolean;
     readonly activeSessionsClosed?: number;
 }
+export interface CapabilityRotateOptions {
+    /**
+     * Overlap window — the OLD token keeps authenticating for this long after
+     * rotation, so you can deploy the replacement with zero downtime. Default
+     * 24h server-side.
+     */
+    readonly grace?: Duration;
+    readonly graceSeconds?: number;
+    /**
+     * Lifetime of the REPLACEMENT capability. Omit to inherit the original's
+     * lifetime.
+     */
+    readonly lease?: Duration;
+    readonly leaseSeconds?: number;
+}
+/** The fresh capability returned by `rotate`, plus a pointer to the old one. */
+export interface RotatedCapability extends Capability {
+    /**
+     * The capability that was rotated out. Its token keeps working until
+     * `expiresAt` (the end of the grace window), then expires.
+     */
+    readonly rotatedFrom: {
+        readonly id: string;
+        readonly expiresAt: string;
+    };
+}
 export interface CapabilityResource {
     create(options: CapabilityCreateOptions): Promise<Capability>;
     retrieve(id: string): Promise<CapabilityRecord>;
     revoke(id: string): Promise<CapabilityRevocation>;
+    /**
+     * Rotate with overlap (Stripe's "roll" model): mint a fresh capability
+     * carrying the SAME scope, and keep the old token working for a grace
+     * window so you can roll out the replacement without downtime.
+     */
+    rotate(id: string, options?: CapabilityRotateOptions): Promise<RotatedCapability>;
     /**
      * Alias for `create`. Kept because "mint" is common capability-token
      * language, but `create` is the canonical SDK verb.

package/dist/client/ApiClient.js

@@ -439,6 +439,35 @@ export function createProtocolClient(options) {
                 activeSessionsClosed: body.activeSessionsClosed,
             };
         },
+        async rotate(id, rotateOptions = {}) {
+            const graceSeconds = rotateOptions.graceSeconds ??
+                (rotateOptions.grace !== undefined ? toSeconds(rotateOptions.grace) : undefined);
+            const leaseSeconds = rotateOptions.leaseSeconds ??
+                (rotateOptions.lease !== undefined ? toSeconds(rotateOptions.lease) : undefined);
+            const body = await requestJson(`/v1/capabilities/${encodeURIComponent(id)}/rotate`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    ...(graceSeconds !== undefined ? { graceSeconds } : {}),
+                    ...(leaseSeconds !== undefined ? { ttlSeconds: leaseSeconds } : {}),
+                }),
+            });
+            const newId = body.capabilityId ?? body.id;
+            if (!newId) {
+                throw new AbloValidationError('Capability rotate response did not include an id.', { code: 'capability_id_missing' });
+            }
+            return {
+                id: newId,
+                token: body.token,
+                expiresAt: body.expiresAt,
+                organizationId: body.organizationId,
+                scope: body.scope,
+                rotatedFrom: {
+                    id: body.rotatedFrom.capabilityId ?? body.rotatedFrom.id ?? id,
+                    expiresAt: body.rotatedFrom.expiresAt,
+                },
+                client: () => childClient(body.token),
+            };
+        },
         mint(options) {
             return capabilities.create(options);
         },
@@ -548,6 +577,50 @@ export function createProtocolClient(options) {
             claims: query.claims ?? [],
         };
     }
+    /**
+     * Single-op 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.
+     */
+    async function mutateModel(action, modelName, id, data, options) {
+        const clientTxId = createClientTxId(options?.idempotencyKey);
+        const encModel = encodeURIComponent(modelName);
+        const path = action === 'create'
+            ? `/v1/models/${encModel}`
+            : `/v1/models/${encModel}/${encodeURIComponent(id)}`;
+        const method = action === 'create' ? 'POST' : action === 'update' ? 'PATCH' : 'DELETE';
+        const requestBody = {
+            idempotencyKey: clientTxId,
+            intent: normalizeIntentId(options?.intent),
+            onStale: options?.onStale,
+            readAt: options?.readAt,
+        };
+        if (action === 'create')
+            requestBody.id = id;
+        if (data !== undefined)
+            requestBody.data = data;
+        const body = await requestJson(path, {
+            method,
+            idempotencyKey: clientTxId,
+            body: JSON.stringify(requestBody),
+        });
+        // `requestJson` throws via `translateHttpError` on any non-2xx, so reaching
+        // here implies success. Narrow `status` to the `CommitWait`-compatible
+        // subset; `'rejected'` only appears on a thrown rejection body.
+        const status = body.status === 'queued' ? 'queued' : 'confirmed';
+        return {
+            id: body.serverTxId ?? body.id ?? body.clientTxId ?? clientTxId,
+            status,
+            lastSyncId: body.lastSyncId,
+        };
+    }
     function model(name) {
         return {
             retrieve(id, options) {
@@ -556,56 +629,15 @@ export function createProtocolClient(options) {
             async create(data, mutationOptions) {
                 const id = mutationOptions?.id ?? createModelId();
                 await applyClaimedPolicy({ model: name, id }, mutationOptions);
-                return commits.create({
-                    intent: mutationOptions?.intent,
-                    idempotencyKey: mutationOptions?.idempotencyKey,
-                    readAt: mutationOptions?.readAt,
-                    onStale: mutationOptions?.onStale,
-                    wait: mutationOptions?.wait,
-                    operations: [
-                        {
-                            action: 'create',
-                            model: name,
-                            id,
-                            data,
-                        },
-                    ],
-                });
+                return mutateModel('create', name, id, data, mutationOptions);
             },
             async update(id, data, mutationOptions) {
                 await applyClaimedPolicy({ model: name, id }, mutationOptions);
-                return commits.create({
-                    intent: mutationOptions?.intent,
-                    idempotencyKey: mutationOptions?.idempotencyKey,
-                    readAt: mutationOptions?.readAt,
-                    onStale: mutationOptions?.onStale,
-                    wait: mutationOptions?.wait,
-                    operations: [
-                        {
-                            action: 'update',
-                            model: name,
-                            id,
-                            data,
-                        },
-                    ],
-                });
+                return mutateModel('update', name, id, data, mutationOptions);
             },
             async delete(id, mutationOptions) {
                 await applyClaimedPolicy({ model: name, id }, mutationOptions);
-                return commits.create({
-                    intent: mutationOptions?.intent,
-                    idempotencyKey: mutationOptions?.idempotencyKey,
-                    readAt: mutationOptions?.readAt,
-                    onStale: mutationOptions?.onStale,
-                    wait: mutationOptions?.wait,
-                    operations: [
-                        {
-                            action: 'delete',
-                            model: name,
-                            id,
-                        },
-                    ],
-                });
+                return mutateModel('delete', name, id, undefined, mutationOptions);
             },
         };
     }

package/dist/client/auth.d.ts

@@ -29,6 +29,7 @@ export interface AuthResolveInput {
         readonly apiKey?: string | ApiKeySetter | null;
         readonly authToken?: string | null;
         readonly baseURL?: string | null;
+        readonly databaseUrl?: string | null;
         readonly dangerouslyAllowBrowser?: boolean;
     };
     readonly env: Record<string, string | undefined>;
@@ -41,16 +42,25 @@ export interface AuthResolveInput {
 export declare function readProcessEnv(): Record<string, string | undefined>;
 export declare function resolveApiKey(input: AuthResolveInput): string | ApiKeySetter | null;
 export declare function resolveAuthToken(input: AuthResolveInput): string | null;
+/**
+ * Resolve the customer's own-Postgres connection string for write-back
+ * (dedicated/BYO tenant). Falls back to `DATABASE_URL` — the Prisma-style
+ * convention — so a server-side app that already exports it needs no extra
+ * config. Returns null for Ablo-managed storage (the hosted default).
+ */
+export declare function resolveDatabaseUrl(input: AuthResolveInput): string | null;
 export declare const ABLO_DEFAULT_BASE_URL = "wss://mesh.ablo.finance";
 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 they have a publishable key or a server proxy.
+ * in explicitly when the browser holds a minted session token
+ * (`ek_`/`rk_`) or routes through a server proxy.
  */
 export declare function assertBrowserSafety(input: {
     apiKey: string | ApiKeySetter | null;
+    databaseUrl?: string | null;
     dangerouslyAllowBrowser: boolean | undefined;
 }): void;
 /**