@ironflow/browser 0.20.2 → 0.22.0

package/dist/agents/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Public types for `ironflow.agents.{invoke, subscribe, readMemory}`.
+ *
+ * Spec: see ./spec.md
+ */
+import type { InvokeResult, ProjectionStateResult, Run, Subscription, SubscriptionCallbacks, SubscriptionErrorInfo, WaitResult } from "@ironflow/core";
+/**
+ * Options for `ironflow.agents.invoke()`.
+ */
+export interface AgentInvokeOptions {
+    /**
+     * Local timeout in milliseconds. When elapsed, throws
+     * `AgentInvokeTimeoutError` and best-effort calls
+     * `cancelRun(runId)` server-side. Default: 30000.
+     */
+    timeoutMs?: number;
+    /**
+     * Caller cancellation. When the signal aborts, throws an `AbortError`
+     * (DOMException) and best-effort calls `cancelRun(runId)`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Server-side dedup. Same key → same `runId` returned across retries.
+     * Wires to existing event-idempotency path.
+     */
+    idempotencyKey?: string;
+    /**
+     * Number of historical events to replay on subscribe. Default: 100.
+     * Replay covers the race window between Trigger return and subscribe attach.
+     */
+    replay?: number;
+    /**
+     * Called once with the runId as soon as `Trigger` returns and before
+     * the wait begins. Lets callers attach a separate progress subscription
+     * (e.g., `agents.subscribe(runId)`) without waiting for the terminal
+     * event. May return a Promise; the SDK awaits it so any async setup
+     * (subscription attach) completes before terminal events dispatch.
+     */
+    onRunStarted?: (runId: string) => void | Promise<void>;
+}
+/**
+ * Result returned from a successful `ironflow.agents.invoke()`.
+ */
+export interface AgentInvokeResult<TOutput = unknown> {
+    runId: string;
+    output: TOutput | undefined;
+    durationMs: number;
+}
+/**
+ * Callbacks for `ironflow.agents.subscribe()`.
+ */
+export interface AgentSubscribeCallbacks {
+    /** Non-terminal run lifecycle events (created, updated, resumed). */
+    onProgress?: (event: AgentProgressEvent) => void;
+    /** Step lifecycle events (created, completed, etc.). */
+    onStep?: (event: AgentStepEvent) => void;
+    /** Terminal `run.completed`. */
+    onComplete?: (result: {
+        output: unknown;
+    }) => void;
+    /** Terminal `run.failed`. */
+    onFailed?: (error: {
+        message: string;
+        code?: string;
+    }) => void;
+    /** Terminal `run.cancelled`. */
+    onCancelled?: () => void;
+    /** Transport / parse error. */
+    onError?: (err: SubscriptionErrorInfo) => void;
+}
+export interface AgentProgressEvent {
+    topic: string;
+    status?: string;
+    data?: unknown;
+}
+export interface AgentStepEvent {
+    topic: string;
+    stepId: string;
+    type: string;
+    data?: unknown;
+}
+/**
+ * Options for `ironflow.agents.readMemory()`.
+ */
+export interface AgentReadMemoryOptions {
+    /**
+     * Sequence number returned by an earlier `streams.append`. When set,
+     * `readMemory` calls `waitForProjectionCatchup` before reading state
+     * so the result reflects events up to and including `minSeq`
+     * (read-your-writes).
+     *
+     * If `minSeq` exceeds the projection's eventual `last_event_seq`, the
+     * catchup blocks until `timeoutMs` and throws
+     * `MemoryCatchupTimeoutError`.
+     */
+    minSeq?: number | bigint;
+    /**
+     * Catchup timeout in milliseconds. Default 30000. Ignored when
+     * `minSeq` is not provided.
+     */
+    timeoutMs?: number;
+    /**
+     * Caller cancellation. Throws an `AbortError` (DOMException) if the
+     * signal aborts before the call completes.
+     */
+    signal?: AbortSignal;
+    /**
+     * Partition key for partitioned projections. Passed through to both
+     * the catchup wait and the state read.
+     */
+    partition?: string;
+}
+/**
+ * Result returned from a successful `ironflow.agents.readMemory()`.
+ */
+export interface AgentMemoryResult<TState = unknown> {
+    /** Materialized projection state. */
+    state: TState;
+    /** Projection version. */
+    version: number;
+    /** Last event id applied to the state, if any. */
+    lastEventId?: string;
+    /**
+     * `true` when `minSeq` was honored or skipped (no `minSeq` provided).
+     * Always `true` on a successful return — the catchup throws on timeout.
+     */
+    caughtUp: boolean;
+}
+/**
+ * Minimum surface that `ironflow.agents.{invoke, subscribe, readMemory}`
+ * need from the client. Defining it as an interface lets the helpers be
+ * unit-tested with a mock client and keeps the public client surface
+ * tight.
+ */
+export interface AgentClientLike {
+    invoke<T = unknown>(functionId: string, options: {
+        data: T;
+        idempotencyKey?: string;
+    }): Promise<InvokeResult>;
+    subscribe<T = unknown>(pattern: string | string[], callbacks: SubscriptionCallbacks<T> & {
+        replay?: number;
+        includeMetadata?: boolean;
+    }): Promise<Subscription | {
+        unsubscribe(): void;
+    }>;
+    cancelRun(runId: string, reason?: string): Promise<Run>;
+    getProjection<TState = unknown>(name: string, options?: {
+        partition?: string;
+    }): Promise<ProjectionStateResult<TState>>;
+    waitForProjectionCatchup(name: string, opts: {
+        minSeq: number | bigint;
+        timeoutMs?: number;
+        partition?: string;
+    }): Promise<WaitResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agents/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"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"}

package/dist/agents/types.js

@@ -0,0 +1,7 @@
+/**
+ * Public types for `ironflow.agents.{invoke, subscribe, readMemory}`.
+ *
+ * Spec: see ./spec.md
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}