@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/resources/httpResources.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Shared resource types for the typed clients and private HTTP transport.
+ * the commit and claim shapes, the session-mint params and resource, and the
+ * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
+ * imports.
+ */
+import type { ClaimHeartbeatAckPayload, OnStaleMode, ReadDependency, TrackDependency } from '../coordination/schema.js';
+import type { ClaimHeartbeatReply, ClaimState } from '../wire/claims.js';
+import type { ClientCommitReceipt, CommitWait } from '../wire/commit.js';
+export type { CommitWait };
+import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
+export type { ModelTarget, ModelClaim };
+import type { ResolveClaimMeta } from '../types/global.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import type { SyncGroupInput } from '../schema/roles.js';
+import type { CapabilityCan, CapabilityOperation, CapabilityScope } from '../auth/capability.js';
+import type { Claim, ClaimStream, ClaimWaitOptions, Duration, HeldClaim } from '../types/streams.js';
+import type { ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod } from './modelOperations.js';
+/**
+ * The operations available on each model in the sync engine:
+ *   `retrieve({ id })` — an async single-row server read
+ *   `list({ where })` — an async collection server read
+ *   `local.retrieve(id)` / `local.list(...)` / `local.count(...)` — synchronous local reads
+ *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
+ *   `claim({ id })` — a durable claim handle for coordinated writes
+ */
+export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+export type IfClaimedPolicy = 'return' | 'fail';
+export interface ClaimedOptions {
+    /**
+     * What to do when another participant has claimed the target: `return` lets
+     * the read proceed; `fail` throws `AbloClaimedError`. Inspect claim state via
+     * `ablo.<model>.claim.state({ id })`. Waiting is a claim-side concern — take
+     * `ablo.<model>.claim({ id })` (it queues fairly); reads never block.
+     */
+    readonly ifClaimed?: IfClaimedPolicy;
+}
+export type { ClaimWaitOptions } from '../types/streams.js';
+export interface ModelReadOptions extends ClaimedOptions {
+}
+/**
+ * The target a caller names when creating a claim: {@link ModelTarget} with its
+ * one caller-authored member typed — `meta` is the shape declared on
+ * `Register`'s `ClaimMeta` slot, the same declaration every reader of the claim
+ * is given back.
+ *
+ * Derived rather than restated, and narrowed only here: `modelTargetSchema`
+ * keeps parsing `meta` as an open record, because a peer on a newer build must
+ * still be understood. The wire stays permissive; the DTO the caller writes
+ * does not.
+ */
+export type ModelTargetInput = Omit<ModelTarget, 'meta'> & {
+    readonly meta?: ResolveClaimMeta;
+};
+export interface ClaimCreateOptions {
+    readonly target: ModelTargetInput;
+    /** Peer-visible description of the work — the same field on every claim
+     *  surface. Defaults to `'editing'` when omitted. */
+    readonly description?: 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 `claim_acquired` if the target
+     * was free, or `claim_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;
+    /** Abort a pending wait from outside — rejects with `claim_wait_aborted`.
+     *  Ignored once the grant has arrived. */
+    readonly signal?: AbortSignal;
+    /**
+     * Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of
+     * waiting if the queue is already `>= maxQueueDepth` when we join.
+     */
+    readonly maxQueueDepth?: number;
+}
+export interface CommitOperationInput {
+    readonly action: ModelOperationAction;
+    /** The model name — matches `ablo.<model>` and the schema's `model()`. */
+    readonly model: string;
+    readonly id?: string | null;
+    readonly data?: Record<string, unknown> | null;
+    readonly transactionId?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: OnStaleMode | null;
+    /** Fencing token (Option B) from the batch's claim handle; server-validated. */
+    readonly fenceToken?: number | null;
+}
+export interface CommitCreateOptions {
+    readonly idempotencyKey?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: OnStaleMode | null;
+    /**
+     * A claim handle from `ablo.<model>.claim({ id })` (or the HTTP claim
+     * surface). Same vocabulary as the per-model writes: the handle's
+     * snapshot watermark becomes the batch `readAt` default and `onStale`
+     * defaults to `'reject'`, so a commit that follows a claim is guarded
+     * against concurrent edits without re-stating the watermark by hand.
+     * Explicit `readAt`/`onStale` on the options win.
+     */
+    readonly claim?: Claim | null;
+    /** One atomic batch. Use a one-element array for a single operation. */
+    readonly operations: readonly CommitOperationInput[];
+    readonly wait?: CommitWait;
+    /**
+     * The batch premise — the "did anything I looked at change?" guard.
+     * Declare the rows (`{ model, id, readAt, fields? }`) or sync groups
+     * (`{ group, readAt }`, for example `report:abc`) this batch was premised on; the
+     * server checks that none moved since `readAt` and fires the entry's `onStale`
+     * over the batch. This is distinct from the write-target `readAt`: it guards what
+     * you read, not what you write.
+     */
+    readonly reads?: readonly ReadDependency[] | null;
+    /**
+     * Durable premises to register as part of this batch — the persisted
+     * sibling of `reads`. Where `reads` guards only this commit, a `track` entry
+     * (`{ model, id, readAt? }` for a row or `{ group, readAt? }` for a sync group)
+     * lives on past it: a later matching change rides back on a future receipt's
+     * `notifications`. A track-only batch (just `track`, an empty `operations`) is
+     * the batch form of `ablo.<model>.track()`.
+     */
+    readonly track?: readonly TrackDependency[] | null;
+}
+/** Public projection inferred from the canonical runtime schema. */
+export type CommitReceipt = ClientCommitReceipt;
+export interface CommitResource {
+    create(options: CommitCreateOptions): Promise<CommitReceipt>;
+}
+export interface ClaimResource extends ClaimStream {
+    create(options: ClaimCreateOptions): Promise<Claim>;
+    list(target?: Partial<ModelTarget>): readonly ModelClaim[];
+    waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
+}
+/**
+ * The claim-ticket surface of the stateless HTTP client — the operations a
+ * caller performs holding only a `claimId`, which is what a queued acquire
+ * leaves in its hand (`AbloClaimedError('claim_queued')` carries it on
+ * `error.claims`). The WebSocket client never needs these: it awaits the grant
+ * on its socket.
+ *
+ * All three shapes are the wire's own — `claimStateSchema`,
+ * `claimHeartbeatReplySchema`, and the batch ack — so this surface cannot
+ * describe a response the server does not send.
+ */
+export interface HttpClaimsResource {
+    /**
+     * The claim's current state, by its id — `GET /v1/claims/{claimId}`. The
+     * poll half of the queued-grant handover: a queued caller polls until
+     * `status` is `'active'`, at which point `fenceToken` is present and the
+     * work can begin. `position` is advisory (a privileged caller can reorder
+     * the line, so it may go up); only `status` is authoritative.
+     */
+    retrieve(params: {
+        readonly claimId: string;
+    }): Promise<ClaimState>;
+    /**
+     * One beat on the named lease — `POST /v1/claims/{claimId}/heartbeat`. On a
+     * held lease it extends the TTL; on a queued ticket it refreshes the
+     * waiter's slot in the line and reports `{ status: 'queued', position }`.
+     */
+    heartbeat(params: {
+        readonly claimId: string;
+        readonly ttl?: string | number;
+    }): Promise<ClaimHeartbeatReply>;
+    /**
+     * One beat for every lease this identity holds — `POST /v1/claims/heartbeat`,
+     * one ack per extended lease. The socketless twin of the realtime
+     * keepalive, for a stateless worker holding many rows.
+     */
+    heartbeatAll(options?: {
+        readonly ttl?: string | number;
+    }): Promise<readonly ClaimHeartbeatAckPayload[]>;
+    /**
+     * Give the ticket back — `DELETE /v1/claims/{claimId}`. On a held lease this
+     * releases it and promotes the head of the queue; on a queued ticket it
+     * leaves the line, so the waiters behind move up instead of waiting out
+     * your slot's TTL. Idempotent: releasing an already-ended claim is a no-op.
+     */
+    release(params: {
+        readonly claimId: string;
+    }): Promise<void>;
+}
+export interface ModelMutationOptions extends ClaimedOptions {
+    readonly claimRef?: string | {
+        readonly id: string;
+    } | null;
+    readonly idempotencyKey?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: OnStaleMode | null;
+    readonly wait?: CommitWait;
+    readonly claim?: Claim | ClaimOptions | null;
+    /** Fencing token (Option B) from the claim; server-validated at commit. */
+    readonly fenceToken?: number | null;
+}
+/**
+ * The stateless HTTP claim surface. Most code puts a `claim` directly on the write
+ * (`update({ id, data, claim })`) and lets the SDK release it; reach for this
+ * namespace for multi-step handles and coordination screens.
+ *
+ * It is the same surface as the reactive claim API, but because every read is a
+ * server round-trip, `state`, `queue`, and `reorder` are awaited here. The
+ * WebSocket client resolves those synchronously from its local cache, which is what
+ * lets it read a claim's state inside a React render; a stateless client has no
+ * cache to read, so the promise is unavoidable.
+ *
+ * It is derived from `ClaimReadApi` through {@link AwaitedClaimMethod} so the two
+ * transports cannot drift: the only difference is the promise wrapper that
+ * statelessness forces. `claim({ id })` is identical on both (already async);
+ * `state`, `queue`, `reorder`, and `release` are the awaited form.
+ */
+export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T> & {
+    queue: false;
+}) => Promise<HeldClaim<T> | null>) & ((params: ClaimParams<T>) => Promise<HeldClaim<T>>) & {
+    [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
+};
+/** A single data operation a scoped **agent** session may perform on a model.
+ *  The SDK-facing name for {@link CapabilityOperation}; the vocabulary itself is
+ *  declared once, as a schema, in `auth/capability.ts`. */
+export type SessionOperation = CapabilityOperation;
+/** Parameters for minting an end-user session — full data authority within the
+ *  organization. Mints an `ek_` token. `user.id` is your end user's id from your
+ *  own identity provider and becomes the session's `participantId`; Ablo does not
+ *  model your users, so it is treated as an opaque string at the trust boundary. */
+export interface CreateUserSessionParams {
+    /** Your end user. `id` becomes the token's `participantId`. */
+    user: {
+        id: string;
+    };
+    /** Mint the session into this organization instead of the key's own — for a
+     *  platform that serves many tenants from one backend. Requires the `sk_` key to
+     *  carry the `ephemeral:mint-any-org` scope; omit it for the normal
+     *  single-tenant case. */
+    organizationId?: string;
+    /** Sync groups this session may subscribe to — typed (`'default'` or
+     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
+     *  `@abloatai/ablo/schema`). Omit for the server default:
+     *  `[org:<your org>, user:<user.id>]`. */
+    syncGroups?: readonly SyncGroupInput[];
+    /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
+    ttlSeconds?: number;
+    /** Opaque identity blob echoed back to the client as `ablo.user`. */
+    userMeta?: Record<string, unknown>;
+    agent?: never;
+    can?: never;
+}
+/** Mint params for a scoped **agent** session — mints a restricted `rk_` token
+ *  gated to exactly the operations named in `can`. `can` is typed off your
+ *  schema (no magic `'task.update'` strings): `{ Task: ['update'], Report: ['read'] }`
+ *  — the SDK serializes each entry to the wire allowlist (`task.update`). */
+export interface CreateAgentSessionParams<S extends SchemaRecord> {
+    /** Your agent. `id` becomes the token's `participantId`. */
+    agent: {
+        id: string;
+    };
+    /** Per-model operation allowlist, typed against the schema's model names. */
+    can: CapabilityCan<S>;
+    /** Sync groups this session may subscribe to — typed (`'default'` or
+     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
+     *  `@abloatai/ablo/schema`). Omit for the server default: the org
+     *  anchor (`org:<your org>`) + the agent's own anchor. */
+    syncGroups?: readonly SyncGroupInput[];
+    /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
+    ttlSeconds?: number;
+    /** Opaque identity blob echoed back to the client as `ablo.agent`. */
+    userMeta?: Record<string, unknown>;
+    user?: never;
+}
+/** Params for {@link Ablo.sessions}.create — a discriminated union: pass
+ *  `{ user }` for a full-authority end-user session (`ek_`) or `{ agent, can }`
+ *  for a scoped agent session (`rk_`). */
+export type CreateSessionParams<S extends SchemaRecord> = CreateUserSessionParams | CreateAgentSessionParams<S>;
+/** Params for {@link Ablo.agents}.create — a flattened agent descriptor (no
+ *  `{ agent }` discriminator: `agents.create` only ever mints an agent). Unlike
+ *  {@link CreateSessionParams} it resolves to a connected, scoped {@link Ablo}
+ *  client rather than a raw token. */
+export interface CreateAgentClientParams<S extends SchemaRecord> {
+    /** The wire participant identity (`agent:<id>`) that claim exclusion and the
+     *  FIFO queue gate on. Omit it to get a fresh random id — a distinct, independent
+     *  participant, which is the default and what you want for concurrent agents.
+     *  Pass a stable string only when one logical agent must re-attach to its own
+     *  held claims across reconnects or restarts. */
+    id?: string;
+    /** A human-readable label for logs and attribution (carried in `userMeta.name`).
+     *  It is independent of `id`: two agents that share a `name` still receive
+     *  distinct ids and coordinate as separate participants — `name` never derives or
+     *  collapses identity. */
+    name?: string;
+    /** Per-model operation allowlist, typed against the schema's model names. */
+    can: CapabilityCan<S>;
+    /** Sync groups this agent may subscribe to — typed (`'default'` or
+     *  `<namespace>:<id>`). Omit for the server default (org anchor + the
+     *  agent's own anchor). */
+    syncGroups?: readonly SyncGroupInput[];
+    /** Token lifetime in seconds. Defaults to 900 (15 minutes); the returned client
+     *  re-mints before expiry, so a long-running agent never handles rotation
+     *  itself. */
+    ttlSeconds?: number;
+    /** Extra opaque identity blob echoed on the session scope. Merged with
+     *  `name` (the `name` param wins if you also set `userMeta.name`). */
+    userMeta?: Record<string, unknown>;
+}
+/** A minted session. `token` is the secret the holder presents as its bearer. */
+export interface AbloSession {
+    object: 'session';
+    /** Stable id of the minted credential (for revocation). */
+    id: string;
+    /** The short-lived session token — `ek_` for a `{ user }` session, `rk_`
+     *  for an `{ agent }` session. Hand this to the participant's runtime. */
+    token: string;
+    /** ISO-8601 expiry. */
+    expiresAt: string;
+    organizationId: string;
+    /** The grant this token carries, on both axes — the same shape the key row
+     *  stores and the gates enforce. */
+    scope: CapabilityScope;
+    userMeta: Record<string, unknown>;
+}

package/dist/transaction/resources/httpResources.js

@@ -0,0 +1,7 @@
+/**
+ * Shared resource types for the typed clients and private HTTP transport.
+ * the commit and claim shapes, the session-mint params and resource, and the
+ * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
+ * imports.
+ */
+export {};