@abloatai/ablo 0.26.0 → 0.28.0

package/dist/client/ApiClient.d.ts

@@ -1,23 +1,22 @@
 /**
- * Stateless API client for `Ablo({ apiKey })`.
- *
- * This is the hosted-API product surface: no schema, no object pool, no
- * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
- * nouns directly to HTTP routes on sync-server.
+ * The stateless API client behind `Ablo({ apiKey })`. It carries no schema,
+ * object pool, local database, or WebSocket, and maps the public Model, Claim,
+ * and Commit nouns directly to HTTP routes on the server. This is the transport
+ * used for server-side agents, workers, and serverless code.
  */
 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';
+import type { Claim, ClaimHeartbeat } from '../types/streams.js';
 import type { SyncObservabilityProvider } from '../interfaces/index.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
     readonly schema?: null | undefined;
     readonly bootstrapBaseUrl?: string | undefined;
     /**
-     * Observability provider forwarded from `Ablo({ observability })`. The HTTP
-     * transport emits the same claim/conflict seams as the WS transport so a
-     * `ClaimLog` works identically for headless (server-agent) evals.
+     * The observability provider forwarded from `Ablo({ observability })`. The HTTP
+     * transport emits the same claim and conflict events as the WebSocket transport,
+     * so a `ClaimLog` works identically for headless server-agent evaluations.
      */
     readonly observability?: SyncObservabilityProvider;
     /**
@@ -37,6 +36,18 @@ export interface AbloApiClaims {
     create(options: ClaimCreateOptions): Promise<Claim>;
     list(target?: Partial<ModelTarget>): Promise<readonly ModelClaim[]>;
     waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
+    /**
+     * The batched beat — extend every lease this credential holds in one
+     * request (`POST /v1/claims/heartbeat`), the stateless twin of the
+     * WebSocket keepalive. One round trip per cadence for a worker holding
+     * many rows. Returns one {@link ClaimHeartbeat} per extended lease,
+     * tagged with its claim id — no separate result type to learn.
+     */
+    heartbeatAll(options?: {
+        ttl?: Duration;
+    }): Promise<readonly (ClaimHeartbeat & {
+        readonly claimId: string;
+    })[]>;
 }
 export type CapabilityParticipantKind = 'agent' | 'system';
 export interface CapabilityCreateBaseOptions {
@@ -97,14 +108,14 @@ export interface CapabilityRevocation {
 }
 export interface CapabilityRotateOptions {
     /**
-     * Overlap window — the OLD token keeps authenticating for this long after
-     * rotation, so you can deploy the replacement with zero downtime. Default
-     * 24h server-side.
+     * The overlap window — the old token keeps authenticating for this long after
+     * rotation, so you can deploy the replacement with zero downtime. Defaults to
+     * 24h on the server.
      */
     readonly grace?: Duration;
     readonly graceSeconds?: number;
     /**
-     * Lifetime of the REPLACEMENT capability. Omit to inherit the original's
+     * The lifetime of the replacement capability. Omit to inherit the original's
      * lifetime.
      */
     readonly lease?: Duration;
@@ -126,9 +137,9 @@ export interface CapabilityResource {
     retrieve(id: string): Promise<CapabilityRecord>;
     revoke(id: string): Promise<CapabilityRevocation>;
     /**
-     * Rotate with overlap (Stripe's "roll" model): mint a fresh capability
-     * carrying the SAME scope, and keep the old token working for a grace
-     * window so you can roll out the replacement without downtime.
+     * Rotate with overlap: mint a fresh capability that carries the same scope, and
+     * keep the old token working for a grace window so you can roll out the
+     * replacement without downtime.
      */
     rotate(id: string, options?: CapabilityRotateOptions): Promise<RotatedCapability>;
     /**
@@ -155,9 +166,9 @@ export interface AbloApi {
      */
     getAuthToken(): Promise<string | null>;
     /**
-     * Mint a short-lived scoped session — the Stripe `ephemeralKeys.create` shape.
-     * Minting is a control-plane HTTP call (no socket), so it lives on this stateless
-     * client too, not only the realtime one. `{ user }` → `ek_`, `{ agent, can }` → `rk_`.
+     * Mint a short-lived scoped session. Minting is a control-plane HTTP call (no
+     * socket), so it lives on this stateless client too, not only the realtime one.
+     * `{ user }` mints an `ek_`; `{ agent, can }` mints an `rk_`.
      */
     readonly sessions: {
         create(params: CreateSessionParams<SchemaRecord>): Promise<AbloSession>;