@abloatai/ablo 0.7.0 → 0.8.0

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;
             }
         })();
@@ -1384,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;
@@ -1491,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;
@@ -1515,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;
 /**

package/dist/client/auth.js

@@ -27,6 +27,15 @@ export function resolveApiKey(input) {
 export function resolveAuthToken(input) {
     return input.options.authToken ?? 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 function resolveDatabaseUrl(input) {
+    return input.options.databaseUrl ?? input.env.DATABASE_URL ?? null;
+}
 export const ABLO_DEFAULT_BASE_URL = 'wss://mesh.ablo.finance';
 export function resolveBaseURL(input) {
     return input.options.baseURL ?? ABLO_DEFAULT_BASE_URL;
@@ -35,11 +44,13 @@ export function resolveBaseURL(input) {
  * 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 function assertBrowserSafety(input) {
+    const inBrowser = typeof window !== 'undefined';
     if (!input.dangerouslyAllowBrowser &&
-        typeof window !== 'undefined' &&
+        inBrowser &&
         typeof input.apiKey === 'string' &&
         input.apiKey.startsWith('sk_')) {
         throw new AbloAuthenticationError("It looks like you're running in a browser-like environment.\n\n" +
@@ -49,6 +60,14 @@ export function assertBrowserSafety(input) {
             '`dangerouslyAllowBrowser` option to `true`, e.g.,\n\n' +
             '    Ablo({ schema, apiKey, dangerouslyAllowBrowser: true });\n', { code: 'browser_apikey_blocked' });
     }
+    // `databaseUrl` carries DB credentials and is NEVER browser-safe, so
+    // `dangerouslyAllowBrowser` does not override it. Register your database from
+    // a server-side runtime.
+    if (inBrowser && typeof input.databaseUrl === 'string' && input.databaseUrl.length > 0) {
+        throw new AbloAuthenticationError('Ablo `databaseUrl` cannot be used in a browser-like environment — it ' +
+            'carries your database credentials. Initialize the client with ' +
+            '`databaseUrl` from a server-side runtime only.', { code: 'browser_database_url_blocked' });
+    }
 }
 /**
  * Resolve an `ApiKeySetter` callable to its current string value.