@abloatai/ablo 0.8.0 → 0.9.0

package/dist/client/createModelProxy.js

@@ -10,7 +10,7 @@
  * exposes the async server reads `retrieve` / `list`, the synchronous
  * local-graph snapshots `get` / `getAll` / `getCount`, the writes
  * `create` / `update` / `delete`, the coordination namespace `claim`
- * (`claim(id, work)` plus `claim.state` / `claim.queue` / `claim.release` /
+ * (`claim({ id })` plus `claim.state` / `claim.queue` / `claim.release` /
  * `claim.reorder`), and `onChange`. The factory returns a plain object; the
  * client assembles the `ablo.<model>` lookup table from these.
  */
@@ -61,9 +61,23 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         await syncClient.waitForConfirmation(model.getModelName(), model.id);
     };
     // Claims this proxy currently holds, keyed by entity id. Lets the flat
-    // `release(id)` and `update(id)` find the lease + snapshot a `claim(id)`
+    // `release({ id })` and `update({ id, data })` find the lease + snapshot a `claim({ id })`
     // took — no per-call handle. Released on dispose, explicit release, or TTL.
     const activeClaims = new Map();
+    const isClaimHandle = (value) => typeof value === 'object' &&
+        value !== null &&
+        value.object === 'claim' &&
+        typeof value.claimId === 'string' &&
+        typeof value.release === 'function';
+    const claimMeta = (options) => {
+        if (!options?.description)
+            return options?.meta;
+        return { ...(options.meta ?? {}), description: options.description };
+    };
+    const mutationOptions = (params) => {
+        const { id: _id, data: _data, claim: _claim, ...rest } = params;
+        return rest;
+    };
     const releaseClaim = async (id) => {
         const held = activeClaims.get(id);
         if (!held)
@@ -71,10 +85,11 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         activeClaims.delete(id);
         await held.lease.release();
     };
-    const takeClaim = async (id, options) => {
+    const takeClaim = async (params) => {
         if (!collaboration) {
             throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
         }
+        const { id, ...options } = params;
         // Is someone ELSE already on this target? Read the local coordination
         // snapshot up front — it decides whether we'll need to re-read after the
         // claim (a free / already-mine target can't have changed under us).
@@ -109,6 +124,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 model: schemaKey,
                 id,
                 ...(options?.field ? { field: options.field } : {}),
+                ...(options?.path ? { path: options.path } : {}),
+                ...(options?.range ? { range: options.range } : {}),
+                ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
             },
             action: options?.action ?? 'editing',
             ttl: options?.ttl,
@@ -124,53 +142,54 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
         activeClaims.set(id, { lease, snapshot });
-        const row = modelAsRow(model);
-        // `await using` calls this on scope exit; releases the claim.
-        Object.defineProperty(row, Symbol.asyncDispose, {
-            value: () => releaseClaim(id),
-            enumerable: false,
-            configurable: true,
-        });
-        return row;
+        const target = {
+            model: schemaKey,
+            id,
+            ...(options?.field ? { field: options.field } : {}),
+            ...(options?.path ? { path: options.path } : {}),
+            ...(options?.range ? { range: options.range } : {}),
+            ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
+        };
+        const release = () => releaseClaim(id);
+        return {
+            object: 'claim',
+            claimId: lease.id,
+            target,
+            action: options?.action ?? 'editing',
+            ...(options?.description ? { description: options.description } : {}),
+            data: modelAsRow(model),
+            release,
+            revoke: () => {
+                void release();
+            },
+            [Symbol.asyncDispose]: release,
+        };
     };
-    function claim(id, a, b) {
-        if (typeof a === 'function') {
-            return (async () => {
-                const row = await takeClaim(id, b);
-                try {
-                    return await a(row);
-                }
-                finally {
-                    await releaseClaim(id);
-                }
-            })();
-        }
-        return takeClaim(id, a);
-    }
+    const claim = (params) => takeClaim(params);
     // `claim` is a callable namespace: invoke it to take a claim, reach its
     // members to read/steer the coordination plane. Attach the readers to the
     // guarded callable so `ablo.<model>.claim(...)` and `ablo.<model>.claim.state(...)`
     // are the same object.
     const claimApi = Object.assign(guard(claim), {
-        state(id) {
-            return collaboration?.observe({ model: schemaKey, id }) ?? null;
+        state(params) {
+            return collaboration?.observe({ model: schemaKey, id: params.id }) ?? null;
         },
-        queue(id) {
+        queue(params) {
             return {
                 object: 'list',
-                data: collaboration?.queue({ model: schemaKey, id }) ?? [],
+                data: collaboration?.queue({ model: schemaKey, id: params.id }) ?? [],
             };
         },
-        reorder(id, order) {
-            collaboration?.reorder({ model: schemaKey, id }, order);
+        reorder(params) {
+            collaboration?.reorder({ model: schemaKey, id: params.id }, params.order);
         },
-        release: guard((id) => releaseClaim(id)),
+        release: guard((params) => releaseClaim(isClaimHandle(params) ? params.target.id : params.id)),
     });
     const operations = {
-        retrieve: guard(async (id, options) => {
+        retrieve: guard(async (params) => {
             const rows = await load({
-                ...options,
-                where: { id },
+                ...params,
+                where: { id: params.id },
                 limit: 1,
             });
             return rows[0];
@@ -215,46 +234,130 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         getCount(options) {
             return this.getAll(options).length;
         },
-        create: guard(async (data, options) => {
-            // TODO(options-persistence): stash `options` alongside the
+        create: guard(async (params) => {
+            // TODO(options-persistence): stash `params` alongside the
             // queued transaction so idempotencyKey survives offline flush.
+            const id = params.id ?? Model.generateId();
+            const opts = mutationOptions(params);
+            const claim = params.claim;
+            let autoLease;
+            if (claim && !isClaimHandle(claim)) {
+                if (!collaboration) {
+                    throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
+                }
+                autoLease = await collaboration.createIntent({
+                    target: {
+                        model: schemaKey,
+                        id,
+                        ...(claim.field ? { field: claim.field } : {}),
+                        ...(claim.path ? { path: claim.path } : {}),
+                        ...(claim.range ? { range: claim.range } : {}),
+                        ...(claimMeta(claim) ? { meta: claimMeta(claim) } : {}),
+                    },
+                    action: claim.action ?? 'creating',
+                    ttl: claim.ttl,
+                    queue: claim.wait !== false,
+                    maxQueueDepth: claim.maxQueueDepth,
+                });
+            }
             const model = new ModelClass({
-                id: Model.generateId(),
-                ...data,
+                id,
+                ...params.data,
                 createdAt: new Date(),
                 updatedAt: new Date(),
             });
-            syncClient.add(model, options);
-            await waitForMutation(model, options);
-            return modelAsRow(model);
+            const effective = {
+                ...opts,
+                ...(autoLease ? { intent: autoLease } : {}),
+                ...(isClaimHandle(claim) ? { intent: { id: claim.claimId } } : {}),
+            };
+            try {
+                syncClient.add(model, effective);
+                await waitForMutation(model, effective);
+                return modelAsRow(model);
+            }
+            finally {
+                await autoLease?.release().catch(() => { });
+            }
         }),
-        update: guard(async (id, data, options) => {
+        update: guard(async (params) => {
+            const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
+            if (autoClaim) {
+                const handle = await takeClaim({ ...autoClaim, id: params.id });
+                try {
+                    return await operations.update({ ...params, claim: handle });
+                }
+                finally {
+                    await handle.release();
+                }
+            }
+            const { id } = params;
             const model = objectPool.get(id);
             if (!model)
                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
             // If we hold a claim on this row, guard the write with its snapshot
             // watermark + lease so it's stale-rejected and attributed to the claim.
             const claimed = activeClaims.get(id);
+            const opts = mutationOptions(params);
+            const handleIntent = isClaimHandle(params.claim)
+                ? { id: params.claim.claimId }
+                : undefined;
             const effective = claimed
                 ? {
                     wait: 'confirmed',
                     readAt: claimed.snapshot.stamp,
                     onStale: 'reject',
                     intent: claimed.lease,
-                    ...options,
+                    ...opts,
                 }
-                : options;
-            model.updateFromData(data);
+                : {
+                    ...opts,
+                    ...(handleIntent ? { intent: handleIntent } : {}),
+                };
+            // Local user update: `applyChanges` keeps change tracking ON so
+            // the edited fields land in `modifiedProperties` and actually get
+            // sent to the server. (`updateFromData` is the hydration path and
+            // would discard the tracking → empty `input: {}` no-op mutation.)
+            model.applyChanges(params.data);
             syncClient.update(model, effective);
             await waitForMutation(model, effective);
             return modelAsRow(model);
         }),
-        delete: guard(async (id, options) => {
+        delete: guard(async (params) => {
+            const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
+            if (autoClaim) {
+                const handle = await takeClaim({ ...autoClaim, id: params.id });
+                try {
+                    await operations.delete({ ...params, claim: handle });
+                }
+                finally {
+                    await handle.release();
+                }
+                return;
+            }
+            const { id } = params;
             const model = objectPool.get(id);
             if (!model)
                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
-            syncClient.delete(model, options);
-            await waitForMutation(model, options);
+            const claimed = activeClaims.get(id);
+            const opts = mutationOptions(params);
+            const handleIntent = isClaimHandle(params.claim)
+                ? { id: params.claim.claimId }
+                : undefined;
+            const effective = claimed
+                ? {
+                    wait: 'confirmed',
+                    readAt: claimed.snapshot.stamp,
+                    onStale: 'reject',
+                    intent: claimed.lease,
+                    ...opts,
+                }
+                : {
+                    ...opts,
+                    ...(handleIntent ? { intent: handleIntent } : {}),
+                };
+            syncClient.delete(model, effective);
+            await waitForMutation(model, effective);
         }),
         // `claim` is a callable namespace (take a claim) carrying the coordination
         // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).

package/dist/client/httpClient.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `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**.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { type AbloApiClientOptions, type TaskCreateOptions } from './ApiClient.js';
+import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions, Turn } from './Ablo.js';
+import type { ModelCreateParams, ModelDeleteParams, ModelLoadOptions, ModelRetrieveParams, ModelUpdateParams } from './createModelProxy.js';
+import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.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. */
+    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.
+ */
+export interface HttpModelClient<T, C = T> {
+    retrieve(params: ModelRetrieveParams & ModelReadOptions): Promise<ModelRead<T>>;
+    list(options?: ModelLoadOptions<T>): Promise<T[]>;
+    create(params: ModelCreateParams<T, C>): Promise<CommitReceipt>;
+    update(params: ModelUpdateParams<C>): Promise<CommitReceipt>;
+    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` + `beginTurn` + `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.
+ */
+export type AbloHttpClient<S extends SchemaRecord> = {
+    readonly [K in keyof S & string]: HttpModelClient<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
+} & {
+    readonly commits: CommitResource;
+    beginTurn(options: TaskCreateOptions): Promise<Turn>;
+    dispose(): Promise<void>;
+    /** Resolve the bearer credential this client authenticates with (see `AbloApi.getAuthToken`). */
+    getAuthToken(): Promise<string | null>;
+    /** String-keyed model accessor (for dynamic model names). */
+    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`, `beginTurn`, `tasks`, `dispose`, etc. pass
+ * through. No socket is ever opened; identity is the Bearer credential.
+ */
+export declare function createAbloHttpClient<S extends SchemaRecord>(options: AbloHttpClientOptions<S>): AbloHttpClient<S>;

package/dist/client/httpClient.js

@@ -0,0 +1,69 @@
+/**
+ * `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**.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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`, `intents`, `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.
+ */
+const PROTOCOL_MEMBERS = new Set([
+    'ready',
+    'waitForFlush',
+    'dispose',
+    'purge',
+    'commits',
+    'beginTurn',
+    'model',
+    'getAuthToken',
+]);
+/**
+ * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol
+ * client's `model(name)`; `commits`, `beginTurn`, `tasks`, `dispose`, etc. pass
+ * through. No socket is ever opened; identity is the Bearer credential.
+ */
+export function createAbloHttpClient(options) {
+    // The schema is type-level only; the protocol client is schema-agnostic.
+    const { schema: _schema, ...rest } = options;
+    const api = createProtocolClient({ ...rest, schema: null });
+    const facade = new Proxy(api, {
+        get(target, prop) {
+            if (typeof prop !== 'string')
+                return Reflect.get(target, prop);
+            // Real protocol members pass through unchanged.
+            if (PROTOCOL_MEMBERS.has(prop) && prop in target)
+                return Reflect.get(target, prop);
+            // Anything else is a typed model accessor → the string-keyed protocol model
+            // (which implements retrieve/list/create/update/delete/claim — every method
+            // `HttpModelClient` declares).
+            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.
+    return facade;
+}

package/dist/client/identity.d.ts

@@ -22,6 +22,7 @@
 import { type RefreshScheduler } from '../auth/index.js';
 import type { BootstrapHelper } from '../sync/BootstrapHelper.js';
 import type { SyncLogger } from '../interfaces/index.js';
+import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { ApiKeySetter } from './auth.js';
 export interface IdentityResolveInput {
     readonly options: {
@@ -42,13 +43,8 @@ export interface IdentityResolveInput {
     readonly configuredApiKey: string | ApiKeySetter | null;
     readonly configuredAuthToken: string | null;
     readonly bootstrapHelper: BootstrapHelper;
+    readonly auth: AuthCredentialSource;
     readonly logger: SyncLogger;
-    /**
-     * Called when the hosted-cloud refresh scheduler rotates the
-     * capability token — caller forwards the new token to the live
-     * WebSocket via `ws.setCapabilityToken(...)`.
-     */
-    readonly applyRotatedToken: (token: string) => void;
 }
 export interface ResolvedIdentity {
     readonly userId: string;

package/dist/client/identity.js

@@ -23,11 +23,43 @@ import { AbloAuthenticationError } from '../errors.js';
 import { exchangeApiKey } from '../auth/index.js';
 import { resolveIdentity } from '../auth/index.js';
 import { createRefreshScheduler, } from '../auth/index.js';
-import { resolveApiKeyValue } from './auth.js';
+import { resolveApiKeyValue, resolveBootstrapBaseUrl } from './auth.js';
 export async function resolveParticipantIdentity(input) {
-    const { options, internalOptions, url, kind, configuredApiKey, configuredAuthToken, bootstrapHelper, logger, applyRotatedToken, } = input;
+    const { options, internalOptions, url, kind, configuredApiKey, configuredAuthToken, bootstrapHelper, auth, logger, } = input;
     const apiKeyValue = await resolveApiKeyValue(configuredApiKey);
     const initialCapToken = options.capabilityToken ?? configuredAuthToken ?? undefined;
+    // Branch 0: publishable key (`pk_`) — a long-lived, browser-safe, READ-ONLY
+    // project key. Unlike a secret `sk_` (Branch 1), it is used DIRECTLY as the
+    // bearer and is NEVER exchanged for a short-lived capability — so it never
+    // expires and there is nothing to refresh (no `credential_stale`, no
+    // wake-from-sleep re-mint). The sync-server's `apiKeyProvider` resolves the
+    // org + read-only scope from the key itself; we still call `/auth/identity`
+    // (authenticated by the `pk_` bearer) to learn the account scope + syncGroups
+    // for the bootstrap cache. Plain `startsWith` check because the `keys` module
+    // is node-only (`node:crypto`) and must not enter the browser bundle.
+    if (apiKeyValue && apiKeyValue.startsWith('pk_') && !options.capabilityToken) {
+        const baseUrl = resolveBootstrapBaseUrl({
+            url,
+            bootstrapBaseUrl: options.bootstrapBaseUrl,
+        });
+        const identity = await resolveIdentity({ baseUrl, authToken: apiKeyValue });
+        const callerGroups = options.syncGroups ?? [];
+        const mergedSyncGroups = callerGroups.length > 0
+            ? [...new Set([...callerGroups, ...identity.syncGroups])]
+            : identity.syncGroups;
+        bootstrapHelper.setCacheScope(identity.accountScope);
+        bootstrapHelper.setSyncGroups(mergedSyncGroups);
+        auth.setAuthToken(apiKeyValue);
+        return {
+            userId: identity.participantId,
+            accountScope: identity.accountScope,
+            teamIds: undefined,
+            capabilityToken: apiKeyValue,
+            syncGroups: mergedSyncGroups,
+            participantKind: identity.participantKind,
+            refreshScheduler: null,
+        };
+    }
     // Branch 1: hosted-cloud (apiKey only, no caller-supplied capability token)
     if (apiKeyValue && !options.capabilityToken) {
         return resolveHosted({
@@ -37,8 +69,8 @@ export async function resolveParticipantIdentity(input) {
             kind,
             options,
             bootstrapHelper,
+            auth,
             logger,
-            applyRotatedToken,
         });
     }
     // Branch 2: self-derived (capability token present, identity unknown)
@@ -58,7 +90,12 @@ export async function resolveParticipantIdentity(input) {
                 'missing or expired. Ensure `getToken()` returns a valid token, or ' +
                 'pass `apiKey` / `capabilityToken`.', { code: 'session_expired' });
         }
-        const baseUrl = options.bootstrapBaseUrl ?? `${url.replace(/^ws/, 'http')}/api`;
+        // Single source of truth for the http(s) base — coerces ws/wss → http/https
+        // even when `bootstrapBaseUrl` is an explicit override (see auth.ts).
+        const baseUrl = resolveBootstrapBaseUrl({
+            url,
+            bootstrapBaseUrl: options.bootstrapBaseUrl,
+        });
         const identity = await resolveIdentity({
             baseUrl,
             authToken: initialCapToken,
@@ -80,7 +117,7 @@ export async function resolveParticipantIdentity(input) {
             : identity.syncGroups;
         bootstrapHelper.setCacheScope(identity.accountScope);
         bootstrapHelper.setSyncGroups(mergedSyncGroups);
-        bootstrapHelper.setAuthToken(initialCapToken);
+        auth.setAuthToken(initialCapToken);
         return {
             userId: identity.participantId,
             accountScope: identity.accountScope,
@@ -97,7 +134,7 @@ export async function resolveParticipantIdentity(input) {
     const accountScope = internalOptions.organizationId;
     bootstrapHelper.setCacheScope(accountScope);
     bootstrapHelper.setSyncGroups(options.syncGroups);
-    bootstrapHelper.setAuthToken(initialCapToken);
+    auth.setAuthToken(initialCapToken);
     return {
         userId,
         accountScope,
@@ -111,8 +148,10 @@ export async function resolveParticipantIdentity(input) {
 async function resolveHosted(input) {
     // Pure managed-cloud shape: `Ablo({schema, apiKey})`. Server returns
     // scope + userMeta; SDK populates internals.
-    const baseUrl = input.options.bootstrapBaseUrl ??
-        `${input.url.replace(/^ws/, 'http')}/api`;
+    const baseUrl = resolveBootstrapBaseUrl({
+        url: input.url,
+        bootstrapBaseUrl: input.options.bootstrapBaseUrl,
+    });
     const exchangeArgs = {
         baseUrl,
         participantKind: (input.kind === 'agent' ? 'agent' : 'system'),
@@ -126,7 +165,7 @@ async function resolveHosted(input) {
     });
     input.bootstrapHelper.setCacheScope(exchange.scope.organizationId);
     input.bootstrapHelper.setSyncGroups(exchange.scope.syncGroups);
-    input.bootstrapHelper.setAuthToken(exchange.token);
+    input.auth.setAuthToken(exchange.token);
     // Cap tokens have a server-set TTL (3600s by default). Without
     // proactive refresh the WS would either get force-closed at expiry
     // or fail its next reconnect with 401. The scheduler re-mints
@@ -146,8 +185,7 @@ async function resolveHosted(input) {
                 ...exchangeArgs,
                 apiKey: freshApiKey,
             });
-            input.bootstrapHelper.setAuthToken(next.token);
-            input.applyRotatedToken(next.token);
+            input.auth.setAuthToken(next.token);
             return { expiresAtMs: Date.parse(next.expiresAt) };
         },
         onError: (err) => {

package/dist/client/index.d.ts

@@ -30,6 +30,7 @@
  * ```
  */
 export { Ablo, computeFKDepthPriority, type AbloOptions, type InternalAbloOptions, type ClaimedOptions, type IfClaimedPolicy, type IntentWaitOptions, type ModelCountOptions, type ModelListOptions, type ModelListScope, type ModelLoadOptions, type ModelOperations, type ModelReadOptions, } from './Ablo.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './auth.js';
 export type { AbloPersistence } from './persistence.js';
 export type { AbloApi, AbloApiClientOptions, AbloApiIntents, Agent, AgentIntentInput, AgentIntentOptions, AgentOptions, AgentModelClient, AgentModelReadOptions, AgentModelMutationOptions, AgentRunContext, AgentRunDone, AgentRunFailed, AgentRunCancelled, AgentRunOptions, AgentRunResult, AgentRunStatus, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, Task, TaskCloseOptions, TaskCloseResult, TaskCreateOptions, TaskResource, } from './ApiClient.js';
 export type { EngineParticipant, JoinedParticipant, ParticipantJoinOptions, ParticipantManager, ParticipantScope, ParticipantStatus, ScopedIntents, ScopedPresence, } from '../sync/participants.js';

package/dist/client/index.js

@@ -30,3 +30,4 @@
  * ```
  */
 export { Ablo, computeFKDepthPriority, } from './Ablo.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './auth.js';

package/dist/client/registerDataSource.d.ts

@@ -3,7 +3,7 @@ export interface RegisterDataSourceInput {
     readonly baseUrl: string;
     /** Secret key (`sk_…`) used to authenticate + derive the org. */
     readonly apiKey: string | null;
-    /** The customer's own Postgres connection string. */
+    /** Postgres connection string for the direct connector. */
     readonly databaseUrl: string;
     /** Optional Postgres schema (defaults server-side to `public`). */
     readonly schema?: string;
@@ -11,8 +11,8 @@ export interface RegisterDataSourceInput {
     readonly fetchImpl?: typeof fetch;
 }
 /**
- * POST the connection string to the self-serve datasource route. Resolves on
- * success (the org is now a dedicated tenant pointed at this DB); throws an
+ * POST the connection string to the self-serve direct connector route. Resolves
+ * on success (the org is now a dedicated tenant pointed at this DB); throws an
  * `AbloError` with `datasource_registration_failed` otherwise so `ready()`
  * surfaces it instead of silently bootstrapping against the wrong store.
  */

package/dist/client/registerDataSource.js

@@ -1,10 +1,12 @@
 /**
- * Self-serve data-source registration.
+ * Self-serve direct-Postgres connector registration.
+ *
+ * Historical note: this module name says "DataSource", but this path registers
+ * a direct database URL. It is not the signed `dataSource(...)` endpoint path.
  *
  * When a client is constructed with `databaseUrl`, the SDK registers that
- * connection string as the project's own-Postgres data store BEFORE bootstrap,
- * so the server resolves the org's data plane to the customer's DB and writes
- * synced rows back into it (dedicated/BYO tenant).
+ * connection string BEFORE bootstrap so the server resolves the org's data plane
+ * to that direct connector.
  *
  * The org is derived server-side from the API key — the caller never sends an
  * organization id. The connection string is sent once over TLS and is never
@@ -13,14 +15,14 @@
  */
 import { AbloError } from '../errors.js';
 /**
- * POST the connection string to the self-serve datasource route. Resolves on
- * success (the org is now a dedicated tenant pointed at this DB); throws an
+ * POST the connection string to the self-serve direct connector route. Resolves
+ * on success (the org is now a dedicated tenant pointed at this DB); throws an
  * `AbloError` with `datasource_registration_failed` otherwise so `ready()`
  * surfaces it instead of silently bootstrapping against the wrong store.
  */
 export async function registerDataSource(input) {
     if (!input.apiKey) {
-        throw new AbloError('databaseUrl requires an apiKey to register the data source (the org is derived from the key).', { code: 'datasource_registration_failed' });
+        throw new AbloError('databaseUrl requires an apiKey to register the direct Postgres connector (the org is derived from the key).', { code: 'datasource_registration_failed' });
     }
     const doFetch = input.fetchImpl ?? fetch;
     const endpoint = `${input.baseUrl.replace(/\/+$/, '')}/v1/datasource`;
@@ -39,7 +41,7 @@ export async function registerDataSource(input) {
         });
     }
     catch (cause) {
-        throw new AbloError('Could not reach the Ablo API to register databaseUrl.', {
+        throw new AbloError('Could not reach the Ablo API to register the direct Postgres connector.', {
             code: 'datasource_registration_failed',
             cause,
         });
@@ -52,6 +54,6 @@ export async function registerDataSource(input) {
         catch {
             // ignore body read failures — the status alone is enough to fail loud
         }
-        throw new AbloError(`databaseUrl registration failed (HTTP ${response.status}). ${detail}`, { code: 'datasource_registration_failed', httpStatus: response.status });
+        throw new AbloError(`Direct Postgres connector registration failed (HTTP ${response.status}). ${detail}`, { code: 'datasource_registration_failed', httpStatus: response.status });
     }
 }