@abloatai/ablo 0.24.0 → 0.26.0

package/dist/client/ApiClient.d.ts

@@ -5,7 +5,8 @@
  * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget, CreateSessionParams, AbloSession } from './Ablo.js';
+import type { AbloOptions } from './options.js';
+import type { CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget, CreateSessionParams, AbloSession } from './resourceTypes.js';
 import type { SchemaRecord } from '../schema/schema.js';
 import type { Duration } from '../utils/duration.js';
 import type { Claim } from '../types/streams.js';
@@ -19,7 +20,19 @@ export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
      * `ClaimLog` works identically for headless (server-agent) evals.
      */
     readonly observability?: SyncObservabilityProvider;
+    /**
+     * Per-request deadline in milliseconds for the stateless HTTP transport.
+     * Every request this client issues is aborted after this long and surfaces
+     * as a retryable connection error — without it a black-holed server hangs
+     * a headless agent forever (browsers never time fetch out on their own).
+     * Pass `0` to disable the deadline.
+     *
+     * @default 30_000
+     */
+    readonly timeoutMs?: number;
 };
+/** Default per-request deadline for the stateless HTTP transport. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 export interface AbloApiClaims {
     create(options: ClaimCreateOptions): Promise<Claim>;
     list(target?: Partial<ModelTarget>): Promise<readonly ModelClaim[]>;

package/dist/client/ApiClient.js

@@ -9,9 +9,12 @@ import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloVal
 import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
+import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
 import { toSeconds } from '../utils/duration.js';
 import { mintSession } from './sessionMint.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
+/** Default per-request deadline for the stateless HTTP transport. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_AGENT_LEASE = '10m';
 export function createProtocolClient(options) {
     const env = readProcessEnv();
@@ -101,6 +104,9 @@ export function createProtocolClient(options) {
         const headers = {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${token}`,
+            // Protocol handshake for the HTTP transport (wire/protocolVersion.ts):
+            // the server answers an out-of-range version with a typed 426.
+            [PROTOCOL_VERSION_HEADER]: String(PROTOCOL_VERSION),
         };
         for (const [key, value] of Object.entries(options.defaultHeaders ?? {})) {
             if (value == null) {
@@ -120,20 +126,66 @@ export function createProtocolClient(options) {
         }
         return target.toString();
     }
+    const requestTimeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     async function requestJson(path, init) {
         await ready();
         const { idempotencyKey, ...requestInit } = init;
         const headers = await authHeaders();
         if (idempotencyKey)
             headers['Idempotency-Key'] = idempotencyKey;
-        const res = await fetchImpl(endpoint(path), {
-            ...requestInit,
-            headers: {
-                ...headers,
-                ...requestInit.headers,
-            },
-        });
-        const bodyText = await res.text();
+        // Deadline: abort the request after `timeoutMs` so a black-holed server
+        // can't hang the caller forever (fetch has NO default timeout in browsers,
+        // and only undici's generous defaults in Node). A caller-supplied signal
+        // is combined with the deadline via a shared controller — the portable
+        // equivalent of `AbortSignal.any([caller, AbortSignal.timeout(t)])`,
+        // which older runtimes (and the jsdom test env) don't implement. The
+        // same pattern already guards `query/client.ts` and `BootstrapHelper`.
+        const callerSignal = requestInit.signal ?? undefined;
+        const controller = new AbortController();
+        const onCallerAbort = () => { controller.abort(callerSignal?.reason); };
+        if (callerSignal) {
+            if (callerSignal.aborted)
+                onCallerAbort();
+            else
+                callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+        }
+        let timedOut = false;
+        const deadline = requestTimeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, requestTimeoutMs)
+            : null;
+        let res;
+        let bodyText;
+        try {
+            res = await fetchImpl(endpoint(path), {
+                ...requestInit,
+                signal: controller.signal,
+                headers: {
+                    ...headers,
+                    ...requestInit.headers,
+                },
+            });
+            // Keep the deadline armed while the body streams — a server that sends
+            // headers then stalls the body is the same hang with better manners.
+            bodyText = await res.text();
+        }
+        catch (error) {
+            if (timedOut) {
+                // Retryable by contract: `wait_for_timeout` is a registered transient
+                // transport code, so `isRetryableCode` steers callers to retry.
+                throw new AbloConnectionError(`The Ablo API did not respond within ${requestTimeoutMs}ms ` +
+                    `(${requestInit.method ?? 'GET'} ${path}). The request was aborted; ` +
+                    'it is safe to retry.', { code: 'wait_for_timeout', cause: error });
+            }
+            throw error;
+        }
+        finally {
+            if (deadline)
+                clearTimeout(deadline);
+            callerSignal?.removeEventListener('abort', onCallerAbort);
+        }
         const body = parseBody(bodyText);
         if (!res.ok) {
             throw translateHttpError(res.status, body ?? `Ablo API request failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
@@ -617,7 +669,9 @@ export function createProtocolClient(options) {
                 throw new AbloClaimedError(`Target ${name}/${params.id} is held; queued at position ${body.position ?? 0}. ` +
                     `The HTTP client cannot await the grant without a WebSocket.`, { code: 'claim_queued' });
             }
-            return body.claim?.id ?? body.id ?? body.id ?? createClaimId();
+            // `claimId` is the queued-response field name (routes/claims.ts) — a
+            // pre-rename regression duplicated the `body.id` arm and dropped it.
+            return body.claim?.id ?? body.id ?? body.claimId ?? createClaimId();
         };
         const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
         async function claimImpl(params) {

package/dist/client/auth.d.ts

@@ -12,20 +12,13 @@
  * explicit options so generated apps do not accrete hidden env knobs.
  */
 /**
- * Async callable that resolves the current credential. Mirrors the shape
- * Anthropic / OpenAI / Stripe ship — used for credential rotation
- * (e.g. AWS STS, GCP IAM, Vault) AND the short-lived per-user browser
- * path (mint a fresh `ek_`/`rk_` from the signed-in session). Re-exported
- * from `./Ablo` so existing import paths work; defined here so this module
- * has no circular dependency back to `Ablo.ts`.
- *
- * Contract: resolve a token; resolve `null` when the login itself is gone
- * (terminal → the credential lifecycle treats this as `session_expired` and
- * signs out); or THROW on a transient failure (→ back off and retry, never
- * sign out). A long-lived static `apiKey` string needs none of this — it is
- * used as-is. This is the single credential resolver the SDK supports.
+ * The credential-resolver callable contract. Defined in the `credentialEndpoint`
+ * leaf (which produces one) and re-exported here — the historical home — so
+ * `./auth` importers keep working while the module graph stays one-directional
+ * (`auth → credentialEndpoint`, never back). See there for the full contract.
  */
-export type ApiKeySetter = () => Promise<string | null>;
+import type { ApiKeySetter } from './credentialEndpoint.js';
+export type { ApiKeySetter };
 export interface AuthResolveInput {
     /**
      * The full options bag the caller passed to `Ablo()`. Resolvers
@@ -34,6 +27,7 @@ export interface AuthResolveInput {
      */
     readonly options: {
         readonly apiKey?: string | ApiKeySetter | null;
+        readonly authEndpoint?: string | ApiKeySetter | null;
         readonly authToken?: string | null;
         readonly baseURL?: string | null;
         readonly databaseUrl?: string | null;
@@ -88,9 +82,7 @@ export declare function resolveDatabaseUrl(input: AuthResolveInput): string | nu
 export declare function warnIfDatabaseUrlEnvIgnored(input: AuthResolveInput, warn?: (message: string) => void): void;
 export declare function warnIfDatabaseUrlDeprecated(input: AuthResolveInput, warn?: (message: string) => void): void;
 export declare function warnIfCliKeyMismatch(input: AuthResolveInput, warn?: (message: string) => void): Promise<void>;
-export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
-export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
-export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";
+export { ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, ABLO_DEFAULT_BASE_URL } from './hostedEndpoints.js';
 /**
  * Normalize old hosted aliases to the public API domain. Self-hosted/custom
  * URLs pass through unchanged; only first-party legacy hosts are rewritten.
@@ -133,4 +125,3 @@ export declare function resolveBootstrapBaseUrl(input: {
     readonly url: string;
     readonly bootstrapBaseUrl?: string;
 }): string;
-export {};

package/dist/client/auth.js

@@ -11,8 +11,10 @@
  * is the only environment fallback. Other routing/auth overrides are
  * explicit options so generated apps do not accrete hidden env knobs.
  */
-import { AbloAuthenticationError } from '../errors.js';
+import { AbloAuthenticationError, AbloValidationError } from '../errors.js';
 import { classifyCredentialKind } from '../auth/credentialPolicy.js';
+import { ABLO_HOSTED_API_DOMAIN, ABLO_DEFAULT_BASE_URL } from './hostedEndpoints.js';
+import { isCredentialEndpoint, createEndpointCredentialResolver } from './credentialEndpoint.js';
 /**
  * Read `process.env` defensively. Works in browser (where `process`
  * is undefined), Node, and edge runtimes that expose a partial
@@ -23,7 +25,37 @@ export function readProcessEnv() {
     return maybeGlobal.process?.env ?? {};
 }
 export function resolveApiKey(input) {
-    return input.options.apiKey ?? input.env.ABLO_API_KEY ?? null;
+    // `authEndpoint` — the NAMED session-mint field (Liveblocks `authEndpoint` /
+    // Ably `authUrl`): a route string the SDK exchanges for a short-lived token,
+    // or an async resolver for custom exchanges. Resolved HERE — the one
+    // resolution point all three factory branches (WS, `transport: 'http'`,
+    // protocol client) share — into an `ApiKeySetter`, so every downstream
+    // consumer sees the familiar resolver and the credential lifecycle drives
+    // renewal off it.
+    const endpoint = input.options.authEndpoint;
+    const configured = input.options.apiKey;
+    if (endpoint != null) {
+        if (configured != null) {
+            throw new AbloValidationError('Ablo: pass either `apiKey` (a key the process holds) or `authEndpoint` ' +
+                '(a route that mints the token) — not both; the client cannot know ' +
+                'which credential to use.', { code: 'invalid_options', param: 'authEndpoint' });
+        }
+        if (typeof endpoint === 'function')
+            return endpoint;
+        if (!isCredentialEndpoint(endpoint)) {
+            throw new AbloValidationError('`authEndpoint` expects a URL or path (e.g. \'/api/ablo-session\') or an ' +
+                'async resolver — a key string belongs in `apiKey`.', { code: 'invalid_options', param: 'authEndpoint' });
+        }
+        return createEndpointCredentialResolver(endpoint);
+    }
+    // `apiKey` also accepts the endpoint-string shape directly (same detection —
+    // key strings are `sk_`/`ek_`/`rk_`-prefixed so the shapes can't collide).
+    // Deliberately only the EXPLICIT option: an `ABLO_API_KEY` env value is
+    // always a literal key, never endpoint-detected.
+    if (typeof configured === 'string' && isCredentialEndpoint(configured)) {
+        return createEndpointCredentialResolver(configured);
+    }
+    return configured ?? input.env.ABLO_API_KEY ?? null;
 }
 export function resolveAuthToken(input) {
     return input.options.authToken ?? null;
@@ -41,6 +73,10 @@ export function modeFromApiKey(key) {
 }
 function resolveStaticApiKey(input) {
     if (typeof input.options.apiKey === 'string') {
+        // An endpoint-string `apiKey` is not a key — it never participates in
+        // CLI-mode mismatch checks (its minted tokens carry the mode instead).
+        if (isCredentialEndpoint(input.options.apiKey))
+            return null;
         return { key: input.options.apiKey, source: 'option' };
     }
     if (input.options.apiKey !== undefined && input.options.apiKey !== null) {
@@ -299,9 +335,9 @@ export async function warnIfCliKeyMismatch(input, warn) {
     else if (typeof console !== 'undefined')
         console.warn('[Ablo]', mismatch.message);
 }
-export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
-export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
-export const ABLO_DEFAULT_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
+// Declared in the dependency-free `hostedEndpoints.ts` leaf (single source of
+// the hosted domain); re-exported here so existing import paths keep working.
+export { ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, ABLO_DEFAULT_BASE_URL } from './hostedEndpoints.js';
 const LEGACY_HOSTED_API_HOSTS = new Set([
     'mesh.ablo.finance',
     'mesh-staging.ablo.finance',
@@ -448,6 +484,6 @@ function ensureApiSuffix(httpBase) {
     catch {
         // Should be unreachable post-`normalizeAbloHostedBaseUrl` (which yields an
         // absolute URL), but fall back to a string check rather than throwing.
-        return /\/api$/.test(trimmed) ? trimmed : `${trimmed}/api`;
+        return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
     }
 }

package/dist/client/consoleLogger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The default `[Ablo]` console logger + its level resolution.
+ *
+ * Extracted from `Ablo.ts`; exported so other entry points that build a
+ * default logger (e.g. the agent runtime) can reuse the same gating instead
+ * of hand-rolling a console shim.
+ */
+import type { SyncLogger } from '../interfaces/index.js';
+/**
+ * Level threshold for the default console logger.
+ *
+ * The SDK emits a `debug` line per model and per property during schema
+ * registration (see `ModelRegistry`), plus assorted lifecycle chatter. That
+ * is verbose by design but carries no actionable signal for app consumers, so
+ * the default threshold is `warn` — `debug`/`info` are dropped unless a
+ * consumer opts in.
+ *
+ * Opt back in with `ABLO_LOG_LEVEL=debug` (or `info`/`warn`/`error`/`silent`).
+ * Passing a custom `logger` to `Ablo({ logger })` bypasses this entirely.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Resolve the effective level. Precedence: explicit `logLevel` option →
+ * `debug: true` (⇒ debug) → `ABLO_LOG_LEVEL` env → default `warn`. `debug: false`
+ * / omitted just means "don't raise the level" — it falls through to env/default
+ * rather than force-silencing an ops-set env override.
+ */
+export declare function resolveLogLevel(opts?: {
+    debug?: boolean;
+    logLevel?: LogLevel;
+}): LogLevel;
+/**
+ * Build the default logger, gated at `level` and prefixed `[Ablo]` so a creator
+ * with a console full of other tools' logs can see at a glance what's ours.
+ */
+export declare function createConsoleLogger(level: LogLevel): SyncLogger;

package/dist/client/consoleLogger.js

@@ -0,0 +1,45 @@
+/**
+ * The default `[Ablo]` console logger + its level resolution.
+ *
+ * Extracted from `Ablo.ts`; exported so other entry points that build a
+ * default logger (e.g. the agent runtime) can reuse the same gating instead
+ * of hand-rolling a console shim.
+ */
+const LOG_LEVEL_RANK = { debug: 10, info: 20, warn: 30, error: 40, silent: 99 };
+/**
+ * Resolve the effective level. Precedence: explicit `logLevel` option →
+ * `debug: true` (⇒ debug) → `ABLO_LOG_LEVEL` env → default `warn`. `debug: false`
+ * / omitted just means "don't raise the level" — it falls through to env/default
+ * rather than force-silencing an ops-set env override.
+ */
+export function resolveLogLevel(opts) {
+    if (opts?.logLevel && opts.logLevel in LOG_LEVEL_RANK)
+        return opts.logLevel;
+    if (opts?.debug === true)
+        return 'debug';
+    // `globalThis.process` guard keeps this safe in browser/edge runtimes that
+    // have no `process` binding — there we fall through to the default.
+    const raw = globalThis.process?.env?.ABLO_LOG_LEVEL;
+    const normalized = raw?.toLowerCase();
+    if (normalized && normalized in LOG_LEVEL_RANK)
+        return normalized;
+    return 'warn';
+}
+/**
+ * Build the default logger, gated at `level` and prefixed `[Ablo]` so a creator
+ * with a console full of other tools' logs can see at a glance what's ours.
+ */
+export function createConsoleLogger(level) {
+    const threshold = LOG_LEVEL_RANK[level];
+    const emit = (lvl, fn, args) => {
+        if (typeof console === 'undefined' || LOG_LEVEL_RANK[lvl] < threshold)
+            return;
+        fn('[Ablo]', ...args);
+    };
+    return {
+        debug: (...args) => { emit('debug', console.debug, args); },
+        info: (...args) => { emit('info', console.info, args); },
+        warn: (...args) => { emit('warn', console.warn, args); },
+        error: (...args) => { emit('error', console.error, args); },
+    };
+}

package/dist/client/createInternalComponents.js

@@ -62,7 +62,7 @@ export function createInternalComponents(input) {
     // WebSocket delta stream keeps hydrated rows fresh so repeat reads serve
     // pure-local with no network; after a drop, deltas may have been missed, so
     // the next read of each query must re-confirm with the server once.
-    syncClient.on('sync:reconnecting', () => hydration.invalidate());
+    syncClient.on('sync:reconnecting', () => { hydration.invalidate(); });
     return {
         modelRegistry,
         objectPool,

package/dist/client/createModelProxy.js

@@ -15,11 +15,12 @@
  * client assembles the `ablo.<model>` lookup table from these.
  */
 import { autorun } from 'mobx';
-import { AbloClaimedError, AbloValidationError, formatClaimedErrorMessage, toAbloError, } from '../errors.js';
+import { AbloClaimedError, AbloStaleContextError, AbloValidationError, formatClaimedErrorMessage, toAbloError, } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
 import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { Model, modelAsRow } from '../Model.js';
 import { toMs } from '../utils/duration.js';
+import { LEASE_TTL_MS } from '../wire/protocol.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
 import { ModelScope } from '../types/index.js';
 const modelClientMeta = new WeakMap();
@@ -85,9 +86,11 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // TTL (a genuine epoch-ms expiry, not a fabricated watermark), defaulting to
     // the server's keepalive lease window when no TTL was requested.
     const activeClaims = new Map();
-    // Server keepalive lease window (Hub `LEASE_RENEW_TTL_MS`). The fallback
-    // expiry estimate when a claim is taken without an explicit TTL.
-    const DEFAULT_LEASE_TTL_MS = 90_000;
+    // Server keepalive lease window (Hub `LEASE_RENEW_TTL_MS` — the same
+    // `LEASE_TTL_MS` from wire/protocol.ts, so client estimate and server
+    // lease can't drift). The fallback expiry estimate when a claim is
+    // taken without an explicit TTL.
+    const DEFAULT_LEASE_TTL_MS = LEASE_TTL_MS;
     const isClaimHandle = (value) => typeof value === 'object' &&
         value !== null &&
         value.object === 'claim' &&
@@ -338,8 +341,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             if (options?.filter) {
                 result = result.filter(options.filter);
             }
-            if (options?.orderBy) {
-                const [field, dir] = Object.entries(options.orderBy)[0];
+            const orderEntry = options?.orderBy ? Object.entries(options.orderBy)[0] : undefined;
+            if (orderEntry) {
+                const [field, dir] = orderEntry;
                 result = [...result].sort((a, b) => {
                     const av = a[field];
                     const bv = b[field];

package/dist/client/credentialEndpoint.d.ts

@@ -0,0 +1,63 @@
+/**
+ * credentialEndpoint — the endpoint-string shape of `apiKey`.
+ *
+ * `Ablo({ schema, apiKey: '/api/ablo-session' })` — point the client at your
+ * session-mint route and the SDK owns the exchange: it POSTs the endpoint,
+ * parses the minted token, keeps it fresh (the credential lifecycle), and
+ * classifies failures onto the resolver tri-state. This is the Ably `authUrl`
+ * / Liveblocks `authEndpoint` model — the string form is the 95% case; the
+ * function form of `apiKey` remains the escape hatch for custom headers,
+ * bodies, or non-HTTP mints.
+ *
+ * Detection is by prefix: a string starting with `/`, `http://`, or
+ * `https://` is an endpoint; anything else is a literal key. Real Ablo keys
+ * are `sk_`/`pk_`/`ek_`/`rk_`-prefixed, so the two shapes cannot collide.
+ * (`ABLO_API_KEY` env values are NEVER endpoint-detected — the env var is
+ * always a literal key; see `resolveApiKey`.)
+ *
+ * Wire contract — matches the `ablo init` scaffold route exactly:
+ *   POST <endpoint>  (same-origin, `credentials: 'include'` so cookies flow)
+ *   → 200 `{ token, expiresAt? }`      fresh short-lived `ek_`/`rk_`
+ *   → 200 `{ token: null }` or 401/403 the login itself is gone (sign out)
+ *   → anything else                    transient — retry, NEVER sign out
+ *
+ * The tri-state mapping is the whole point of building this in: hand-written
+ * thunks routinely get it wrong (mapping any `!res.ok` to `null` signs the
+ * user out on a 500). Encoded here once, every consumer inherits the correct
+ * terminal-vs-transient split (the Liveblocks `{ error: "forbidden" }` vs
+ * retry contract, translated to HTTP statuses).
+ */
+/**
+ * Async callable that resolves the current credential. Mirrors the shape
+ * Anthropic / OpenAI / Stripe ship — used for credential rotation
+ * (e.g. AWS STS, GCP IAM, Vault) AND the short-lived per-user browser
+ * path (mint a fresh `ek_`/`rk_` from the signed-in session). Re-exported
+ * from `./auth` (and thence `./Ablo`) so existing import paths work; defined
+ * in this leaf so the credential resolver it types has no import cycle.
+ *
+ * Contract: resolve a token; resolve `null` when the login itself is gone
+ * (terminal → the credential lifecycle treats this as `session_expired` and
+ * signs out); or THROW on a transient failure (→ back off and retry, never
+ * sign out). A long-lived static `apiKey` string needs none of this — it is
+ * used as-is. This is the single credential resolver the SDK supports.
+ */
+export type ApiKeySetter = () => Promise<string | null>;
+/**
+ * Is this `apiKey` string a session-mint endpoint rather than a literal key?
+ * Prefix rule: `/relative/path`, `http://…`, or `https://…`.
+ */
+export declare function isCredentialEndpoint(value: string): boolean;
+/**
+ * Build the resolver behind an endpoint-string `apiKey`. Conforms to the
+ * `ApiKeySetter` contract end-to-end:
+ *   - resolves the minted token string on success,
+ *   - resolves `null` when the login is gone (401/403, or an explicit
+ *     `{ token: null }`) → terminal, the client signs out,
+ *   - THROWS on anything transient (network failure, 5xx/429, malformed
+ *     response) → the lifecycle backs off and retries, never signs out.
+ *
+ * A relative endpoint invoked server-side (Node fetch has no origin) throws —
+ * transient by contract, and `credentialLifecycle` already translates that
+ * exact failure into an actionable "use an absolute URL server-side" warning.
+ */
+export declare function createEndpointCredentialResolver(endpoint: string): ApiKeySetter;

package/dist/client/credentialEndpoint.js

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

package/dist/client/hostedEndpoints.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The canonical Ablo Cloud endpoint constants — a ZERO-dependency leaf.
+ *
+ * This is the single place the hosted API host is declared. Everything else
+ * (`client/auth.ts` URL resolution, the CLI's `DEFAULT_URL`, the Data Source
+ * connector's dial-out base, the generated OpenAPI `servers` entry, the
+ * network probe's default) imports from here, so the next API-domain
+ * migration is ONE edit — the `LEGACY_HOSTED_API_HOSTS` rewrite list in
+ * `client/auth.ts` (four retired ablo.finance hosts) is proof such
+ * migrations happen.
+ *
+ * Kept dependency-free on purpose: `schema/openapi.ts` and `source/connector.ts`
+ * consume it, and routing them through `client/auth.ts` would drag the error
+ * registry + credential policy (and a `schema → client → errors →
+ * coordination → schema` cycle) into subpaths that are otherwise clean.
+ */
+/** The hosted API domain (no scheme). */
+export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
+/** The hosted HTTP origin — `https://` + {@link ABLO_HOSTED_API_DOMAIN}. */
+export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
+/** Default `baseURL` when the caller passes none. Same value as
+ *  {@link ABLO_HOSTED_HTTP_BASE_URL}; kept as a distinct name because it is
+ *  the documented client-options default. */
+export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";

package/dist/client/hostedEndpoints.js

@@ -0,0 +1,24 @@
+/**
+ * The canonical Ablo Cloud endpoint constants — a ZERO-dependency leaf.
+ *
+ * This is the single place the hosted API host is declared. Everything else
+ * (`client/auth.ts` URL resolution, the CLI's `DEFAULT_URL`, the Data Source
+ * connector's dial-out base, the generated OpenAPI `servers` entry, the
+ * network probe's default) imports from here, so the next API-domain
+ * migration is ONE edit — the `LEGACY_HOSTED_API_HOSTS` rewrite list in
+ * `client/auth.ts` (four retired ablo.finance hosts) is proof such
+ * migrations happen.
+ *
+ * Kept dependency-free on purpose: `schema/openapi.ts` and `source/connector.ts`
+ * consume it, and routing them through `client/auth.ts` would drag the error
+ * registry + credential policy (and a `schema → client → errors →
+ * coordination → schema` cycle) into subpaths that are otherwise clean.
+ */
+/** The hosted API domain (no scheme). */
+export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
+/** The hosted HTTP origin — `https://` + {@link ABLO_HOSTED_API_DOMAIN}. */
+export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
+/** Default `baseURL` when the caller passes none. Same value as
+ *  {@link ABLO_HOSTED_HTTP_BASE_URL}; kept as a distinct name because it is
+ *  the documented client-options default. */
+export const ABLO_DEFAULT_BASE_URL = ABLO_HOSTED_HTTP_BASE_URL;

package/dist/client/httpClient.d.ts

@@ -23,7 +23,7 @@
  * surface as the browser client — typed proxies, stateless transport.
  */
 import { type AbloApiClientOptions } from './ApiClient.js';
-import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions, CreateSessionParams, AbloSession } from './Ablo.js';
+import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions, CreateSessionParams, AbloSession } from './resourceTypes.js';
 import type { ModelCreateParams, ModelDeleteParams, ServerReadOptions, ModelRetrieveParams, ModelUpdateParams } from './createModelProxy.js';
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
 import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';

package/dist/client/identity.js

@@ -168,9 +168,10 @@ async function resolveHosted(input) {
     const baseUrl = input.baseUrl;
     // The refresh path re-runs `exchangeApiKey` with a freshly-resolved apiKey, so
     // it needs the same argument bag the policy used for the initial exchange.
+    const participantKind = input.kind === 'agent' ? 'agent' : 'system';
     const exchangeArgs = {
         baseUrl,
-        participantKind: (input.kind === 'agent' ? 'agent' : 'system'),
+        participantKind,
         participantId: input.options.agentId ?? input.options.user?.id,
         wideScope: true,
         ttlSeconds: 3600,