@abloatai/ablo 0.8.0 → 0.9.0

package/dist/client/auth.d.ts

@@ -43,13 +43,22 @@ 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).
+ * Resolve the direct-URL connector's Postgres connection string.
+ *
+ * The default Data Source path should not call this: the customer keeps
+ * `DATABASE_URL` in their app and exposes `dataSource(...)`. This helper exists
+ * only for the opt-in direct connector where Ablo registers a dedicated tenant
+ * database. Returns null for Ablo-managed storage.
  */
 export declare function resolveDatabaseUrl(input: AuthResolveInput): string | null;
-export declare const ABLO_DEFAULT_BASE_URL = "wss://mesh.ablo.finance";
+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 = "wss://api.abloatai.com";
+/**
+ * Normalize old hosted aliases to the public API domain. Self-hosted/custom
+ * URLs pass through unchanged; only first-party legacy hosts are rewritten.
+ */
+export declare function normalizeAbloHostedBaseUrl(rawUrl: string): string;
 export declare function resolveBaseURL(input: AuthResolveInput): string;
 /**
  * Browser guard — apiKey is server-side-only by default. Same check

package/dist/client/auth.js

@@ -28,17 +28,58 @@ 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).
+ * Resolve the direct-URL connector's Postgres connection string.
+ *
+ * The default Data Source path should not call this: the customer keeps
+ * `DATABASE_URL` in their app and exposes `dataSource(...)`. This helper exists
+ * only for the opt-in direct connector where Ablo registers a dedicated tenant
+ * database. Returns null for Ablo-managed storage.
  */
 export function resolveDatabaseUrl(input) {
     return input.options.databaseUrl ?? input.env.DATABASE_URL ?? null;
 }
-export const ABLO_DEFAULT_BASE_URL = 'wss://mesh.ablo.finance';
+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 = `wss://${ABLO_HOSTED_API_DOMAIN}`;
+const LEGACY_HOSTED_API_HOSTS = new Set([
+    'mesh.ablo.finance',
+    'mesh-staging.ablo.finance',
+    'api.ablo.finance',
+    'sync-staging.ablo.finance',
+]);
+/**
+ * Normalize old hosted aliases to the public API domain. Self-hosted/custom
+ * URLs pass through unchanged; only first-party legacy hosts are rewritten.
+ */
+export function normalizeAbloHostedBaseUrl(rawUrl) {
+    const trimmed = rawUrl.trim();
+    if (!trimmed)
+        return trimmed;
+    // A scheme-less value (e.g. `api-staging.abloatai.com`) is a RELATIVE URL:
+    // `new URL()` throws on it, and downstream `fetch` then resolves it against
+    // the current page — producing `https://<app-host>/<route>/api-staging…/api/
+    // auth/identity`, a 404 from the app's own origin. Prepend a scheme so the
+    // base is absolute. `https` mirrors `ABLO_HOSTED_HTTP_BASE_URL`; the socket
+    // layer derives `wss` from it. An existing scheme (ws/wss/http/https) is
+    // preserved untouched.
+    const schemed = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+    try {
+        const url = new URL(schemed);
+        if (!LEGACY_HOSTED_API_HOSTS.has(url.hostname))
+            return schemed.replace(/\/+$/, '');
+        url.hostname = ABLO_HOSTED_API_DOMAIN;
+        if (url.protocol === 'http:')
+            url.protocol = 'https:';
+        if (url.protocol === 'ws:')
+            url.protocol = 'wss:';
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        return schemed;
+    }
+}
 export function resolveBaseURL(input) {
-    return input.options.baseURL ?? ABLO_DEFAULT_BASE_URL;
+    return normalizeAbloHostedBaseUrl(input.options.baseURL ?? ABLO_DEFAULT_BASE_URL);
 }
 /**
  * Browser guard — apiKey is server-side-only by default. Same check
@@ -96,5 +137,17 @@ export async function resolveApiKeyValue(apiKey) {
  * preserves the protocol family (ws → http, wss → https).
  */
 export function resolveBootstrapBaseUrl(input) {
-    return input.bootstrapBaseUrl ?? `${input.url.replace(/^ws/, 'http')}/api`;
+    if (input.bootstrapBaseUrl) {
+        // Coerce ws/wss → http/https on the override path too. This base URL is
+        // used for HTTP fetches (identity resolve, apiKey exchange, bootstrap) and
+        // the browser `fetch` rejects ws/wss schemes outright ("URL scheme \"wss\"
+        // is not supported"). apps/web derives this override as `${baseUrl}/api`
+        // where `baseUrl` may carry a WebSocket scheme, so the override can
+        // legitimately arrive as `wss://…` — normalize it here rather than
+        // faceplanting at fetch time. The derive branch below already does this;
+        // the override branch silently skipped it.
+        return normalizeAbloHostedBaseUrl(input.bootstrapBaseUrl).replace(/^ws/, 'http');
+    }
+    const url = normalizeAbloHostedBaseUrl(input.url);
+    return `${url.replace(/^ws/, 'http')}/api`;
 }

package/dist/client/createInternalComponents.d.ts

@@ -16,6 +16,7 @@ import { ObjectPool } from '../ObjectPool.js';
 import { SyncClient } from '../SyncClient.js';
 import { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
 import { BootstrapHelper } from '../sync/BootstrapHelper.js';
+import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { Schema, SchemaRecord } from '../schema/schema.js';
 import { type AbloPersistence } from './persistence.js';
 export interface InternalComponentsInput<S extends SchemaRecord> {
@@ -31,6 +32,7 @@ export interface InternalComponentsInput<S extends SchemaRecord> {
         readonly offline?: boolean;
         readonly inMemory?: boolean;
     };
+    readonly auth?: AuthCredentialSource;
 }
 export interface InternalComponents {
     readonly modelRegistry: ModelRegistry;

package/dist/client/createInternalComponents.js

@@ -19,7 +19,7 @@ import { BootstrapHelper } from '../sync/BootstrapHelper.js';
 import { resolveBootstrapBaseUrl } from './auth.js';
 import { shouldUseInMemoryPersistence } from './persistence.js';
 export function createInternalComponents(input) {
-    const { schema, url, options } = input;
+    const { schema, url, options, auth } = input;
     // The registry is created here but model registration happens in
     // the caller (Ablo.ts owns `registerModelsFromSchema` since the
     // schema-to-class translation depends on private helpers there).
@@ -37,6 +37,7 @@ export function createInternalComponents(input) {
         baseUrl: bootstrapBaseUrl,
         syncGroups: options.syncGroups,
         instantModels: deriveInstantModels(schema),
+        getAuthToken: auth?.getAuthToken,
     });
     const database = new Database(modelRegistry, bootstrapHelper, {
         // Point-solution default: no browser-local durable store unless the
@@ -55,7 +56,13 @@ export function createInternalComponents(input) {
         registry: modelRegistry,
         schema,
         baseUrl: bootstrapBaseUrl,
+        getAuthToken: auth?.getAuthToken,
     });
+    // Drop the lazy-lane hydration ledger on reconnect. While connected, the
+    // 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());
     return {
         modelRegistry,
         objectPool,

package/dist/client/createModelProxy.d.ts

@@ -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.
  */
@@ -21,7 +21,7 @@ import type { SyncClient } from '../SyncClient.js';
 import type { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
 import type { LoadWhere } from '../query/types.js';
 import { ModelScope } from '../types/index.js';
-import type { Duration, Intent, IntentWaitOptions, Snapshot } from '../types/streams.js';
+import type { Duration, Intent, IntentWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
 export interface ModelClientMeta {
     readonly key: string;
     readonly typename: string;
@@ -70,7 +70,7 @@ export interface ModelLoadOptions<T> {
      */
     expand?: readonly string[];
 }
-/** Options for the single-row async server read `retrieve(id)`. A subset of
+/** Options for the single-row async server read `retrieve({ id })`. A subset of
  *  {@link ModelLoadOptions} — `where`/`limit`/`orderBy` are fixed by the id. */
 export type ModelRetrieveOptions = Pick<ModelLoadOptions<unknown>, 'type' | 'expand'>;
 export interface IntentLeaseHandle {
@@ -84,6 +84,9 @@ export interface ModelCollaboration<T> {
             model: string;
             id: string;
             field?: string;
+            path?: string;
+            range?: TargetRange;
+            meta?: Record<string, unknown>;
         };
         action: string;
         ttl?: Duration;
@@ -139,12 +142,19 @@ export interface ModelCollaboration<T> {
      */
     readonly selfParticipantId: string;
 }
-/** Options for `claim(id, …)`. */
-export interface ClaimOptions {
+export interface ClaimTargetOptions<T = Record<string, unknown>> {
     /** Phase shown to observers while held. Defaults to `'editing'`. */
     action?: string;
+    /** Peer-visible explanation of the work being performed. */
+    description?: string;
     /** Field-level target, for fine-grained claimed-state badges. */
     field?: string;
+    /** Optional path for document/file-like targets. */
+    path?: string;
+    /** Optional range for document/file-like targets. */
+    range?: TargetRange;
+    /** App-defined structured metadata. */
+    meta?: Record<string, unknown>;
     /** Crash-cleanup TTL — the claim auto-releases if the holder dies. */
     ttl?: Duration;
     /**
@@ -164,73 +174,120 @@ export interface ClaimOptions {
      */
     maxQueueDepth?: number;
 }
+/** Options for `claim({ id, ... })`. */
+export interface ClaimParams<T = Record<string, unknown>> extends ClaimTargetOptions<T> {
+    readonly id: string;
+}
+export interface ClaimLookupParams<T = Record<string, unknown>> {
+    readonly id: string;
+    readonly field?: string;
+}
+export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLookupParams<T> {
+    readonly order: readonly Intent[];
+}
 /**
- * A claimed row: the entity's data plus an async-dispose hook, so
+ * A claim handle: the held entity data plus an explicit release hook, so
  *
  * ```ts
- * await ablo.weatherReports.claim('report_stockholm', async (report) => {
- *   await ablo.weatherReports.update(report.id, { status: 'ready' });
+ * const claim = await ablo.weatherReports.claim({
+ *   id: 'report_stockholm',
+ *   action: 'forecasting',
+ *   description: 'Fetching current weather before writing the forecast.',
  * });
+ * try {
+ *   await ablo.weatherReports.update({
+ *     id: claim.target.id,
+ *     data: { status: 'ready' },
+ *     claim,
+ *   });
+ * } finally {
+ *   await claim.release();
+ * }
  * ```
  *
- * releases the claim when the callback returns or throws. Read it like any row
- * (`report.location`); write it through the flat `ablo.<model>.update(report.id, …)`
- * verb — there is no method chaining on the claim.
+ * `data` is a snapshot taken after the lease is held. Write through the flat
+ * `ablo.<model>.update({ id, data, claim })` verb — the handle carries the
+ * lease id and snapshot watermark for attribution + stale protection.
  */
-export type ClaimedRow<T> = T & AsyncDisposable;
+export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposable {
+    readonly object: 'claim';
+    readonly claimId: string;
+    readonly target: {
+        readonly model: string;
+        readonly id: string;
+        readonly field?: string;
+        readonly path?: string;
+        readonly range?: TargetRange;
+        readonly meta?: Record<string, unknown>;
+    };
+    readonly action: string;
+    readonly description?: string;
+    readonly data: T;
+    release(): Promise<void>;
+    revoke(): void;
+}
+export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
 /**
  * The coordination surface for a model, exposed as a callable namespace.
  *
- * Calling it takes a claim — either the callback form (`claim(id, work)`, which
- * releases when `work` settles) or the bare lease form (`claim(id)`). Its
- * members read and steer the same coordination plane: `state` (current holder),
- * `queue` (the wait line), `release` (drop a held claim), `reorder` (re-rank the
- * line). All four stay on the ephemeral coordination plane — never persisted,
- * never a `SyncDelta`.
+ * Most callers do not need this namespace directly. Put `claim: { ... }` on a
+ * write and the SDK acquires/releases around that one mutation:
+ *
+ * ```ts
+ * await ablo.tasks.update({
+ *   id,
+ *   data: { title },
+ *   claim: {
+ *     field: 'title',
+ *     action: 'renaming',
+ *     description: 'Renaming the task to match the project brief.',
+ *   },
+ * });
+ * ```
+ *
+ * Use `claim({ id, ... })` when a tool spans multiple writes and needs one
+ * handle. `state`, `queue`, and `reorder` are coordination reads/scheduler
+ * controls for UI and operators.
  */
 export interface ClaimApi<T> {
-    /** Take a claim and get the held row back (bare lease form). */
-    (id: string, options?: ClaimOptions): Promise<ClaimedRow<T>>;
-    /**
-     * Take a claim, run `work` with the held row, release when it settles. The
-     * preferred form for ordinary held work.
-     */
-    <R>(id: string, work: (row: ClaimedRow<T>) => Promise<R> | R, options?: ClaimOptions): Promise<R>;
+    /** Take a claim and get an explicit held-work handle back. */
+    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
     /**
-     * Who's coordinating on a row — the current holder (who, phase, until when),
-     * or `null` when free. Synchronous and reactive; for observers/UI. Never
-     * blocks.
+     * Current holder for a row, or `null` when free. Use this for UI badges and
+     * preflight checks, not for the normal write path.
      */
-    state(id: string): Intent | null;
+    state(params: ClaimLookupParams<T>): Intent | null;
     /**
-     * The wait queue on a row — who's lined up behind the holder and what each
-     * intends. Reactive snapshot (synced from the server, like `activity`);
-     * returns a Stripe-style list envelope, FIFO order, empty when no one waits.
-     *
-     * ```ts
-     * const { data } = ablo.decks.claim.queue('deck_1');
-     * // → [{ heldBy: 'agent:summarizer', action: 'editing', position: 0 }, …]
-     * ```
+     * FIFO wait line behind the current holder. Advanced: useful for operator
+     * UIs and schedulers.
      */
-    queue(id: string): {
+    queue(params: ClaimLookupParams<T>): {
         readonly object: 'list';
         readonly data: readonly Intent[];
     };
     /**
-     * Re-rank the wait queue on a record — move waiters to the front in the given
-     * order. Pass the `Intent[]` from `claim.queue(id).data`, reordered. A
-     * privileged operation: the server gates it (the caller needs the
-     * `intent.reorder` capability), so it's fire-and-forget — the new order
-     * arrives reactively through `claim.queue(id)`.
-     *
-     * ```ts
-     * const { data } = ablo.decks.claim.queue('deck_1');
-     * ablo.decks.claim.reorder('deck_1', [data[2], data[0], data[1]]); // promote #2
-     * ```
+     * Re-rank the wait line. Advanced and permission-gated.
      */
-    reorder(id: string, order: readonly Intent[]): void;
-    /** Release a claim you hold early. Usually implicit (scope exit). */
-    release(id: string): Promise<void>;
+    reorder(params: ClaimReorderParams<T>): void;
+    /** Release a manual claim handle early. Single-write claims auto-release. */
+    release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
+}
+export interface ModelRetrieveParams extends ModelRetrieveOptions {
+    readonly id: string;
+}
+export interface ModelCreateParams<T, CreateInput> extends MutationOptions {
+    readonly data: CreateInput;
+    readonly id?: string | null;
+    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+}
+export interface ModelUpdateParams<T> extends MutationOptions {
+    readonly id: string;
+    readonly data: Partial<T>;
+    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+}
+export interface ModelDeleteParams<T> extends MutationOptions {
+    readonly id: string;
+    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
 }
 export interface ModelOperations<T, CreateInput> {
     /**
@@ -244,9 +301,9 @@ export interface ModelOperations<T, CreateInput> {
      * synchronous read of an already-warm graph (a React selector) use
      * `get(id)`.
      *
-     * Mirrors `stripe.customers.retrieve(id)` — network-backed.
+     * Mirrors `stripe.customers.retrieve({ id })` — network-backed.
      */
-    retrieve(id: string, options?: ModelRetrieveOptions): Promise<T | undefined>;
+    retrieve(params: ModelRetrieveParams): Promise<T | undefined>;
     /**
      * List entities matching a filter from the **server** — async. Same 3-tier
      * lookup + graph hydration as `retrieve`; single-flight deduped. Returns the
@@ -276,29 +333,36 @@ export interface ModelOperations<T, CreateInput> {
      * the mutation is queued locally, not when the server confirms.
      * Server rejection rolls back automatically; watch `sync.syncStatus`.
      */
-    create(data: CreateInput, options?: MutationOptions): Promise<T>;
+    create(params: ModelCreateParams<T, CreateInput>): Promise<T>;
     /** Update an entity by id — optimistic, offline-first (see `create`). */
-    update(id: string, data: Partial<T>, options?: MutationOptions): Promise<T>;
+    update(params: ModelUpdateParams<T>): Promise<T>;
     /** Delete an entity by id — optimistic, offline-first (see `create`). */
-    delete(id: string, options?: MutationOptions): Promise<void>;
+    delete(params: ModelDeleteParams<T>): Promise<void>;
     /**
      * Claim a row so other writers wait or are rejected until you're done, and
      * inspect or manage that coordination through the same namespace. Call it to
-     * take a claim (the callback form releases when the callback returns or
-     * throws); reach for its members to observe and steer the wait line:
+     * take a claim handle; reach for its members to observe and steer the wait line:
      *
-     * - `claim.state(id)` — who holds the row now, or `null` when free
-     * - `claim.queue(id)` — who's lined up behind the holder
-     * - `claim.release(id)` — drop a claim early (usually implicit on scope exit)
-     * - `claim.reorder(id, order)` — re-rank the wait line
+     * - `claim.state({ id })` — who holds the row now, or `null` when free
+     * - `claim.queue({ id })` — who's lined up behind the holder
+     * - `claim.release({ id })` — drop a claim early (usually implicit on scope exit)
+     * - `claim.reorder({ id, order })` — re-rank the wait line
      *
      * ```ts
-     * await ablo.weatherReports.claim('report_stockholm', async (report) => {
-     *   const weather = await getWeather(report.location);
-     *   await ablo.weatherReports.update(report.id, { forecast: weather });
+     * const claim = await ablo.weatherReports.claim({
+     *   id: 'report_stockholm',
+     *   action: 'forecasting',
+     *   description: 'Fetching fresh weather before updating the report.',
+     * });
+     * const weather = await getWeather(claim.data.location);
+     * await ablo.weatherReports.update({
+     *   id: claim.target.id,
+     *   data: { forecast: weather },
+     *   claim,
      * });
+     * await claim.release();
      *
-     * const holder = ablo.weatherReports.claim.state('report_stockholm');
+     * const holder = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
      * ```
      */
     claim: ClaimApi<T>;