@abloatai/ablo 0.3.0

package/dist/client/ApiClient.d.ts

@@ -0,0 +1,200 @@
+/**
+ * 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 Resource / Intent / Commit
+ * nouns directly to HTTP routes on sync-server.
+ */
+import type { AbloOptions, CommitReceipt, CommitResource, IntentCreateOptions, IntentHandle, IntentWaitOptions, ResourceClient, ResourceIntent, ResourceMutationOptions, ResourceReadOptions, ResourceRead, ResourceTarget, Turn } from './Ablo.js';
+import type { Duration } from '../utils/duration.js';
+export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
+    readonly schema?: null | undefined;
+    readonly bootstrapBaseUrl?: string | undefined;
+};
+export interface AbloApiIntents {
+    create(options: IntentCreateOptions): Promise<IntentHandle>;
+    list(target?: Partial<ResourceTarget>): Promise<readonly ResourceIntent[]>;
+    waitFor(target: Partial<ResourceTarget>, options?: IntentWaitOptions): Promise<void>;
+}
+export type CapabilityParticipantKind = 'agent' | 'system';
+export interface CapabilityCreateBaseOptions {
+    readonly participantKind?: CapabilityParticipantKind;
+    readonly participantId?: string;
+    readonly syncGroups: readonly string[];
+    readonly operations: readonly string[];
+    readonly label?: string;
+    readonly wideScope?: boolean;
+    readonly userMeta?: Record<string, unknown>;
+}
+export interface CapabilityCreateOptions extends CapabilityCreateBaseOptions {
+    /**
+     * Preferred public name. A capability is a lease; the SDK and server
+     * clean it up when the run finishes or when the lease expires.
+     */
+    readonly lease?: Duration;
+    readonly leaseSeconds?: number;
+    /** @deprecated Use `lease`. */
+    readonly ttl?: Duration;
+    /** @deprecated Use `leaseSeconds`. */
+    readonly ttlSeconds?: number;
+}
+export interface CapabilityScope {
+    readonly organizationId: string;
+    readonly syncGroups: readonly string[];
+    readonly operations: readonly string[];
+    readonly participantKind: CapabilityParticipantKind;
+    readonly participantId: string;
+}
+export interface Capability {
+    readonly id: string;
+    readonly token: string;
+    readonly expiresAt: string;
+    readonly organizationId: string;
+    readonly scope: CapabilityScope;
+    readonly userMeta?: Record<string, unknown>;
+    client(): AbloApi;
+}
+export interface CapabilityRecord {
+    readonly id: string;
+    readonly organizationId: string;
+    readonly participantKind: CapabilityParticipantKind;
+    readonly participantId: string;
+    readonly label: string | null;
+    readonly status: 'active' | 'expired' | 'revoked';
+    readonly issuedAt: string;
+    readonly expiresAt: string;
+    readonly revokedAt: string | null;
+    readonly lastUsedAt: string | null;
+    readonly operations: readonly string[];
+    readonly syncGroups: readonly string[];
+}
+export interface CapabilityRevocation {
+    readonly id: string;
+    readonly deleted: boolean;
+    readonly activeSessionsClosed?: number;
+}
+export interface CapabilityResource {
+    create(options: CapabilityCreateOptions): Promise<Capability>;
+    retrieve(id: string): Promise<CapabilityRecord>;
+    revoke(id: string): Promise<CapabilityRevocation>;
+    /**
+     * Alias for `create`. Kept because "mint" is common capability-token
+     * language, but `create` is the canonical SDK verb.
+     */
+    mint(options: CapabilityCreateOptions): Promise<Capability>;
+}
+export interface TaskCreateOptions {
+    readonly prompt: string;
+    readonly parentTaskId?: string;
+    readonly surface?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface TaskCloseOptions {
+    readonly costInputTokens?: number;
+    readonly costOutputTokens?: number;
+    readonly costComputeMs?: number;
+}
+export interface Task {
+    readonly id: string;
+    readonly turnId: string;
+    readonly promptHash?: string;
+    readonly openedAt?: string;
+    close(stats?: TaskCloseOptions): Promise<TaskCloseResult>;
+}
+export interface TaskCloseResult {
+    readonly id: string;
+    readonly turnId: string;
+    readonly closed: boolean;
+    readonly alreadyClosed?: boolean;
+    readonly endedAt?: string;
+}
+export interface TaskResource {
+    create(options: TaskCreateOptions): Promise<Task>;
+    close(id: string, stats?: TaskCloseOptions): Promise<TaskCloseResult>;
+    /**
+     * Alias for `create`. Kept for the agent-run vocabulary; `create` is
+     * the canonical SDK verb.
+     */
+    open(options: TaskCreateOptions): Promise<Task>;
+}
+export interface AgentOptions {
+    readonly can: readonly string[];
+    readonly syncGroups?: readonly string[];
+    readonly label?: string;
+    readonly userMeta?: Record<string, unknown>;
+    /**
+     * Internal lease for the run capability. Most callers should omit it.
+     * The SDK revokes the capability when `run` finishes; the lease exists
+     * to clean up crashed or abandoned runs.
+     */
+    readonly lease?: Duration;
+    readonly leaseSeconds?: number;
+}
+export interface AgentRunOptions extends TaskCreateOptions {
+    readonly signal?: AbortSignal;
+    readonly costInputTokens?: number;
+    readonly costOutputTokens?: number;
+    readonly costComputeMs?: number;
+}
+export type AgentRunStatus = 'done' | 'failed' | 'cancelled';
+export interface AgentRunDone<T> {
+    readonly status: 'done';
+    readonly task: Task;
+    readonly value: T;
+}
+export interface AgentRunFailed {
+    readonly status: 'failed';
+    readonly task?: Task;
+    readonly error: unknown;
+}
+export interface AgentRunCancelled {
+    readonly status: 'cancelled';
+    readonly task?: Task;
+    readonly error?: unknown;
+}
+export type AgentRunResult<T> = AgentRunDone<T> | AgentRunFailed | AgentRunCancelled;
+export interface AgentIntentOptions {
+    readonly action: string;
+    readonly field?: string;
+    readonly ttl?: Duration;
+    readonly target?: Partial<ResourceTarget>;
+}
+export type AgentIntentInput = string | AgentIntentOptions;
+export interface AgentResourceReadOptions extends ResourceReadOptions {
+}
+export interface AgentResourceMutationOptions extends Omit<ResourceMutationOptions, 'intent'> {
+    readonly intent?: AgentIntentInput | {
+        readonly id: string;
+    } | null;
+}
+export interface AgentResourceClient<T = Record<string, unknown>> {
+    retrieve(id: string, options?: AgentResourceReadOptions): Promise<ResourceRead<T>>;
+    create(data: Record<string, unknown>, options?: AgentResourceMutationOptions & {
+        readonly id?: string | null;
+    }): Promise<CommitReceipt>;
+    update(id: string, data: Record<string, unknown>, options?: AgentResourceMutationOptions): Promise<CommitReceipt>;
+    delete(id: string, options?: AgentResourceMutationOptions): Promise<CommitReceipt>;
+}
+export interface AgentRunContext {
+    readonly task: Task;
+    readonly ablo: AbloApi;
+    resource<T = Record<string, unknown>>(name: string): AgentResourceClient<T>;
+}
+export interface Agent {
+    readonly id: string;
+    run<T>(options: AgentRunOptions, handler: (context: AgentRunContext) => Promise<T> | T): Promise<AgentRunResult<T>>;
+}
+export interface AbloApi {
+    ready(): Promise<void>;
+    waitForFlush(): Promise<void>;
+    dispose(): Promise<void>;
+    purge(): Promise<void>;
+    readonly capabilities: CapabilityResource;
+    readonly tasks: TaskResource;
+    readonly intents: AbloApiIntents;
+    readonly commits: CommitResource;
+    agent(id: string, options: AgentOptions): Agent;
+    resource<T = Record<string, unknown>>(name: string): ResourceClient<T>;
+    beginTurn(options: TaskCreateOptions): Promise<Turn>;
+}
+export declare function createProtocolClient(options: AbloApiClientOptions): AbloApi;