@abloatai/ablo 0.5.1 → 0.6.0

package/dist/client/Ablo.d.ts

@@ -10,10 +10,10 @@
  *
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
  *
- *   const tasks = sync.tasks.list({ where: { status: 'todo' } });
- *   await sync.tasks.create({ title: 'Fix bug' });
- *   await sync.tasks.update(taskId, { status: 'done' });
- *   await sync.tasks.delete(taskId);
+ *   const reports = sync.reports.list({ where: { status: 'todo' } });
+ *   await sync.reports.create({ title: 'Fix bug' });
+ *   await sync.reports.update(reportId, { status: 'ready' });
+ *   await sync.reports.delete(reportId);
  */
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
 import type { SyncEngineConfig, SyncLogger, MutationExecutor, MutationDispatcher, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
@@ -76,7 +76,7 @@ import { type AbloPersistence } from './persistence.js';
 export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
      * TypeScript schema defined with `defineSchema()`. Required — it's what
-     * makes `ablo.tasks.update(...)` typed. This is the one field you must
+     * makes `ablo.weatherReports.update(...)` typed. This is the one field you must
      * pass; start here.
      */
     schema: Schema<S>;
@@ -104,20 +104,6 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Override the Ablo API base URL. Defaults to hosted production.
      */
     baseURL?: string | null | undefined;
-    /**
-     * Maximum time (ms) to wait for a single request before timing out.
-     * Timed-out requests are retried, so worst-case wait can exceed this.
-     *
-     * @default 600_000
-     */
-    timeout?: number | undefined;
-    /**
-     * Maximum retries on transient failure (network error / 5xx / 429).
-     * Honors `Retry-After`.
-     *
-     * @default 2
-     */
-    maxRetries?: number | undefined;
     /** Custom fetch implementation for tests, proxies, or non-standard runtimes. */
     fetch?: typeof fetch | undefined;
     /** Default headers sent with every API request. */
@@ -162,18 +148,6 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * URL for self-hosted or staging (e.g. `wss://mesh-staging.ablo.finance`).
      */
     baseURL?: string | null | undefined;
-    /**
-     * Maximum amount of time (ms) the client waits for a response
-     * before timing out a single request. Defaults to 10 minutes
-     * (600_000ms). Retried requests can wait longer in worst case.
-     */
-    timeout?: number | undefined;
-    /**
-     * Maximum number of times the client will retry a request on
-     * transient failure (5xx / 429 / network error). Defaults to 2.
-     * Honors `Retry-After` and `retry-after-ms` response headers.
-     */
-    maxRetries?: number | undefined;
     /**
      * Custom `fetch` implementation. Defaults to `globalThis.fetch`.
      * Override for testing, custom transports, or runtime shims.
@@ -201,8 +175,8 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * TypeScript schema defined with `defineSchema()`.
      *
      * The root `Ablo(...)` client is schema-first so consumers get typed
-     * model resources such as `ablo.tasks.update(...)`. Omit `schema`
-     * only for the advanced Resource / Intent / Commit client.
+     * model clients such as `ablo.weatherReports.update(...)`. Omit `schema`
+     * only for the advanced Model / Claim / Commit client.
      */
     schema: Schema<S>;
     /**
@@ -253,7 +227,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     inMemory?: boolean;
     /**
      * If true, initialization starts immediately in the background so
-     * `sync.tasks.findMany()` works after `await sync.ready()`.
+     * `sync.reports.findMany()` works after `await sync.ready()`.
      *
      * If false (default), the consumer MUST call `await sync.ready()` before
      * using the engine — any query before that returns empty results.
@@ -268,7 +242,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      *  - `'full'`: pull every delta in the configured sync groups before
      *    `ready()` resolves. Default for `kind: 'user'`.
      *  - `'none'`: open the WS and process live deltas only — no baseline
-     *    fetch. Reads round-trip via `resource.retrieve()`; subscriptions
+     *    fetch. Reads round-trip via `model.retrieve()`; subscriptions
      *    populate the pool lazily via covering deltas. Default for
      *    `kind: 'agent'` because agent-worker / routine runners don't
      *    need (or want) a local replica of the org's tenant plane.
@@ -357,52 +331,76 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
  * deprecated aliases for one release cycle so consumers can migrate
  * without a flag day.
  */
-export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelIntentAcquireOptions, ModelIntentHandle, ModelOperations, } from './createModelProxy.js';
+export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ClaimOptions, ClaimedRow, ModelOperations, } from './createModelProxy.js';
 import type { ModelOperations } from './createModelProxy.js';
-export type ResourceOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
-export interface ResourceTarget {
-    readonly resource: string;
+export interface ModelTarget {
+    /** The model name — matches `ablo.<model>` and the schema's `model()`. */
+    readonly model: string;
     readonly id: string;
     readonly path?: string;
     readonly range?: TargetRange;
     readonly field?: string;
     readonly meta?: Record<string, unknown>;
 }
-export interface ResourceIntent {
+export interface ModelClaim {
     readonly id: string;
     readonly actor: string;
     readonly participantKind: ActiveIntent['participantKind'];
     readonly action: string;
     readonly field?: string;
+    readonly status?: 'active' | 'queued';
+    readonly position?: number;
     readonly expiresAt: string;
-    readonly target: ResourceTarget;
+    readonly target: ModelTarget;
 }
-export interface ResourceRead<T = Record<string, unknown>> {
+export interface ModelRead<T = Record<string, unknown>> {
     readonly data: T;
     readonly stamp: number;
-    readonly intents: readonly ResourceIntent[];
+    readonly claims: readonly ModelClaim[];
 }
-export type BusyPolicy = 'return' | 'wait' | 'fail';
-export interface BusyOptions {
+export type IfClaimedPolicy = 'return' | 'wait' | 'fail';
+export interface ClaimedOptions {
     /**
-     * What to do when another participant has an active intent on the
-     * target. `return` includes the intents in the response, `wait`
-     * resolves after they clear, and `fail` throws `AbloBusyError`.
+     * What to do when another participant has claimed the target. `return`
+     * includes active claim metadata in the response, `wait` resolves after the
+     * claim clears, and `fail` throws `AbloClaimedError`.
      */
-    readonly ifBusy?: BusyPolicy;
-    /** Max time to wait for peer intents to clear, in milliseconds. */
-    readonly busyTimeout?: number;
+    readonly ifClaimed?: IfClaimedPolicy;
+    /** Max time to wait for peer claims to clear, in milliseconds. */
+    readonly claimedTimeout?: number;
     /** HTTP API polling interval while waiting. WebSocket clients ignore it. */
-    readonly busyPollInterval?: number;
+    readonly claimedPollInterval?: number;
+    /**
+     * Backpressure for `ifClaimed: 'wait'`: reject instead of waiting if the
+     * row's FIFO line is already `>= maxQueueDepth` deep.
+     */
+    readonly maxQueueDepth?: number;
 }
 export type { IntentWaitOptions } from '../types/streams.js';
-export interface ResourceReadOptions extends BusyOptions {
+export interface ModelReadOptions extends ClaimedOptions {
 }
 export interface IntentCreateOptions {
-    readonly target: ResourceTarget;
+    readonly target: ModelTarget;
     readonly action: string;
     readonly ttl?: Duration;
+    /**
+     * Join the server's fair FIFO queue when the target is already claimed,
+     * rather than failing immediately. `create` then resolves only once the
+     * lease is actually ours (the server pushes `intent_acquired` if the target
+     * was free, or `intent_granted` when we reach the head of the line). Without
+     * this, a contended claim throws. Used by `ablo.<model>.claim` so writers
+     * serialize instead of racing.
+     */
+    readonly queue?: boolean;
+    /** Cap on how long to wait for a queued grant before rejecting. */
+    readonly waitTimeoutMs?: number;
+    /**
+     * Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of
+     * waiting if the queue is already `>= maxQueueDepth` when we join.
+     */
+    readonly maxQueueDepth?: number;
 }
 export interface IntentHandle extends AsyncDisposable {
     readonly id: string;
@@ -410,9 +408,10 @@ export interface IntentHandle extends AsyncDisposable {
     revoke(): void;
 }
 export interface CommitOperationInput {
-    readonly action: ResourceOperationAction;
-    readonly resource?: string;
-    readonly target?: ResourceTarget;
+    readonly action: ModelOperationAction;
+    /** The model name — matches `ablo.<model>` and the schema's `model()`. */
+    readonly model?: string;
+    readonly target?: ModelTarget;
     readonly id?: string | null;
     readonly data?: Record<string, unknown> | null;
     readonly transactionId?: string | null;
@@ -429,7 +428,6 @@ export interface CommitCreateOptions {
     readonly operation?: CommitOperationInput;
     readonly operations?: readonly CommitOperationInput[];
     readonly wait?: CommitWait;
-    readonly timeout?: number;
 }
 export interface CommitReceipt {
     readonly id: string;
@@ -441,10 +439,10 @@ export interface CommitResource {
 }
 export interface IntentResource extends IntentStream {
     create(options: IntentCreateOptions): Promise<IntentHandle>;
-    list(target?: Partial<ResourceTarget>): readonly ResourceIntent[];
-    waitFor(target: Partial<ResourceTarget>, options?: IntentWaitOptions): Promise<void>;
+    list(target?: Partial<ModelTarget>): readonly ModelClaim[];
+    waitFor(target: Partial<ModelTarget>, options?: IntentWaitOptions): Promise<void>;
 }
-export interface ResourceMutationOptions extends BusyOptions {
+export interface ModelMutationOptions extends ClaimedOptions {
     readonly intent?: string | {
         readonly id: string;
     } | null;
@@ -452,15 +450,14 @@ export interface ResourceMutationOptions extends BusyOptions {
     readonly readAt?: number | null;
     readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
     readonly wait?: CommitWait;
-    readonly timeout?: number;
 }
-export interface ResourceClient<T = Record<string, unknown>> {
-    retrieve(id: string, options?: ResourceReadOptions): Promise<ResourceRead<T>>;
-    create(data: Record<string, unknown>, options?: ResourceMutationOptions & {
+export interface ModelClient<T = Record<string, unknown>> {
+    retrieve(id: string, options?: ModelReadOptions): Promise<ModelRead<T>>;
+    create(data: Record<string, unknown>, options?: ModelMutationOptions & {
         readonly id?: string | null;
     }): Promise<CommitReceipt>;
-    update(id: string, data: Record<string, unknown>, options?: ResourceMutationOptions): Promise<CommitReceipt>;
-    delete(id: string, options?: ResourceMutationOptions): Promise<CommitReceipt>;
+    update(id: string, data: Record<string, unknown>, options?: ModelMutationOptions): Promise<CommitReceipt>;
+    delete(id: string, options?: ModelMutationOptions): Promise<CommitReceipt>;
 }
 /** The typed sync engine client — one property per model in the schema */
 export type Ablo<S extends SchemaRecord> = {
@@ -473,7 +470,7 @@ export type Ablo<S extends SchemaRecord> = {
      * ```ts
      * const sync = Ablo({ schema, user });
      * await sync.ready();
-     * const tasks = sync.tasks.findMany(); // data is available
+     * const reports = sync.reports.findMany(); // data is available
      * ```
      *
      * If bootstrap fails, this rejects with the underlying error (unreachable
@@ -494,9 +491,9 @@ export type Ablo<S extends SchemaRecord> = {
      * offline, this waits until reconnect + flush completes.
      *
      * ```ts
-     * await sync.tasks.create({ title: 'A' });
-     * await sync.tasks.create({ title: 'B' });
-     * await sync.waitForFlush(); // server has both tasks
+     * await sync.reports.create({ title: 'A' });
+     * await sync.reports.create({ title: 'B' });
+     * await sync.waitForFlush(); // server has both reports
      * ```
      *
      * @param timeoutMs - Optional timeout. Default: no timeout (wait forever).
@@ -596,16 +593,16 @@ export type Ablo<S extends SchemaRecord> = {
      */
     readonly intents: IntentResource;
     /**
-     * Canonical low-level mutation API. Every resource convenience write
-     * compiles down to `commits.create(...)`.
+     * Canonical low-level mutation API. Every untyped model write compiles
+     * down to `commits.create(...)`.
      */
     readonly commits: CommitResource;
     /**
-     * Canonical untyped resource API. This is the portable API shape that maps
+     * Canonical untyped model API. This is the portable API shape that maps
      * cleanly to HTTP/Python/Ruby/Go clients. Typed `ablo.<model>` properties
-     * are schema-powered sugar over the same resource model.
+     * are schema-powered sugar over the same model write/read path.
      */
-    resource<T = Record<string, unknown>>(name: string): ResourceClient<T>;
+    model<T = Record<string, unknown>>(name: string): ModelClient<T>;
     /**
      * Canonical multiplayer participant surface. Joins a structured app
      * target, derives the transport scope internally, opens a scoped
@@ -718,8 +715,8 @@ export declare function computeFKDepthPriority(schema: Schema): ReadonlyMap<stri
  * ```ts
  * const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
  *
- * const tasks = sync.tasks.list({ where: { status: 'todo' } });
- * await sync.tasks.create({ title: 'New task' });
+ * const reports = sync.weatherReports.list({ where: { status: 'pending' } });
+ * await sync.weatherReports.create({ location: 'Stockholm', status: 'pending' });
  * ```
  */
 export declare function Ablo<const S extends SchemaRecord>(options: AbloOptions<S>): Ablo<S>;
@@ -759,9 +756,9 @@ export declare namespace Ablo {
     type AgentRunStatus = import('./ApiClient.js').AgentRunStatus;
     type AgentRunResult<T> = import('./ApiClient.js').AgentRunResult<T>;
     type AgentRunContext = import('./ApiClient.js').AgentRunContext;
-    type AgentResourceClient<T = Record<string, unknown>> = import('./ApiClient.js').AgentResourceClient<T>;
-    type AgentResourceReadOptions = import('./ApiClient.js').AgentResourceReadOptions;
-    type AgentResourceMutationOptions = import('./ApiClient.js').AgentResourceMutationOptions;
+    type AgentModelClient<T = Record<string, unknown>> = import('./ApiClient.js').AgentModelClient<T>;
+    type AgentModelReadOptions = import('./ApiClient.js').AgentModelReadOptions;
+    type AgentModelMutationOptions = import('./ApiClient.js').AgentModelMutationOptions;
     type AgentIntentOptions = import('./ApiClient.js').AgentIntentOptions;
     type AgentIntentInput = import('./ApiClient.js').AgentIntentInput;
     type Capability = import('./ApiClient.js').Capability;
@@ -774,8 +771,8 @@ export declare namespace Ablo {
     type TaskCloseOptions = import('./ApiClient.js').TaskCloseOptions;
     type TaskCloseResult = import('./ApiClient.js').TaskCloseResult;
     type TaskResource = import('./ApiClient.js').TaskResource;
-    type BusyPolicy = import('./Ablo.js').BusyPolicy;
-    type BusyOptions = import('./Ablo.js').BusyOptions;
+    type IfClaimedPolicy = import('./Ablo.js').IfClaimedPolicy;
+    type ClaimedOptions = import('./Ablo.js').ClaimedOptions;
     type EntityRef = _Streams.EntityRef;
     type PresenceTarget = _Streams.PresenceTarget;
     type TargetRange = _Streams.TargetRange;
@@ -817,25 +814,25 @@ export declare namespace Ablo {
     }
     namespace Commit {
         type Wait = import('./Ablo.js').CommitWait;
-        type OperationAction = import('./Ablo.js').ResourceOperationAction;
+        type OperationAction = import('./Ablo.js').ModelOperationAction;
         type OperationInput = import('./Ablo.js').CommitOperationInput;
         type CreateOptions = import('./Ablo.js').CommitCreateOptions;
         type Receipt = import('./Ablo.js').CommitReceipt;
-        type Resource = import('./Ablo.js').CommitResource;
+        type Client = import('./Ablo.js').CommitResource;
     }
     namespace Intent {
         type Handle = import('./Ablo.js').IntentHandle;
         type CreateOptions = import('./Ablo.js').IntentCreateOptions;
         type WaitOptions = import('./Ablo.js').IntentWaitOptions;
-        type Resource = import('./Ablo.js').IntentResource;
+        type Client = import('./Ablo.js').IntentResource;
     }
-    namespace Resource {
-        type Target = import('./Ablo.js').ResourceTarget;
-        type Intent = import('./Ablo.js').ResourceIntent;
-        type Read<T = Record<string, unknown>> = import('./Ablo.js').ResourceRead<T>;
-        type Client<T = Record<string, unknown>> = import('./Ablo.js').ResourceClient<T>;
-        type ReadOptions = import('./Ablo.js').ResourceReadOptions;
-        type MutationOptions = import('./Ablo.js').ResourceMutationOptions;
+    namespace Model {
+        type Target = import('./Ablo.js').ModelTarget;
+        type Claim = import('./Ablo.js').ModelClaim;
+        type Read<T = Record<string, unknown>> = import('./Ablo.js').ModelRead<T>;
+        type Client<T = Record<string, unknown>> = import('./Ablo.js').ModelClient<T>;
+        type ReadOptions = import('./Ablo.js').ModelReadOptions;
+        type MutationOptions = import('./Ablo.js').ModelMutationOptions;
     }
     namespace Source {
         type Operation = import('../source/index.js').SourceOperation;