@ironflow/node 0.20.2 → 0.21.0

package/dist/client.d.ts

@@ -0,0 +1,942 @@
+/**
+ * Ironflow Node.js Client
+ *
+ * HTTP client for interacting with the Ironflow server.
+ * Provides methods for registering functions, triggering events, and managing runs.
+ */
+import { type EmitSyncResult, type RunStatus, type Trigger, type ExecutionMode, type RetryConfig, type ConcurrencyConfig, type DebounceConfig, type AppendEventInput, type AppendOptions, type AppendResult, type ReadStreamOptions, type StreamEvent, type StreamInfo, type StreamSnapshot, type CreateSQLProjectionInput, type QuerySQLProjectionOptions, type SQLProjectionQueryResult, type PublishOptions, type PublishResult, type TopicInfo, type TopicStats, type APIKey, type APIKeyWithSecret, type CreateAPIKeyInput, type Organization, type CreateOrgInput, type UpdateOrgInput, type Role, type CreateRoleInput, type UpdateRoleInput, type Policy, type CreatePolicyInput, type UpdatePolicyInput, type ProjectionStateResult, type GetProjectionOptions, type ProjectionStatusInfo, type RebuildJob, type WaitResult, type TimeTravelRunState, type TimeTravelTimelineEvent, type TimeTravelStepOutput, type AuditTrailEntry, type Secret, type SecretListEntry, type StreamListEntry, type EntityHistoryEntry, type Project, type Environment, type EventSchema, type RegisterSchemaInput, type TestUpcastInput, type UpcastResult, type WebhookSource, type CreateWebhookSourceInput, type WebhookDelivery, type ListWebhookDeliveriesOptions, type User, type CreateUserInput, type UpdateUserInput, type Tenant } from "@ironflow/core";
+import { KVClient } from "./kv.js";
+import { CommandDedup, type CommandDedupOptions } from "./command-dedup.js";
+import { ConfigClient } from "./config-client.js";
+import type { OnErrorHandler } from "./types.js";
+/**
+ * Configuration for the Ironflow client
+ */
+export interface IronflowClientConfig {
+    /** Server URL (default: http://localhost:9123 or IRONFLOW_SERVER_URL env var) */
+    serverUrl?: string;
+    /** API key for authentication (optional for local dev) */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Global error handler called on every client error (fires before re-throw) */
+    onError?: OnErrorHandler;
+}
+/**
+ * Function registration request
+ */
+export interface RegisterFunctionRequest {
+    /** Unique function identifier */
+    id: string;
+    /** Display name */
+    name?: string;
+    /** Description */
+    description?: string;
+    /** Event triggers */
+    triggers?: Trigger[];
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Concurrency configuration */
+    concurrency?: ConcurrencyConfig;
+    /** Debounce configuration — collapse rapid events (issue #545) */
+    debounce?: DebounceConfig;
+    /** Preferred execution mode */
+    preferredMode?: ExecutionMode;
+    /** Endpoint URL for push mode */
+    endpointUrl?: string;
+    /** Actor key for sticky routing */
+    actorKey?: string;
+    /** Pause behavior for scoped injection ("hold" or "release") */
+    pauseBehavior?: string;
+    /** Compensate-on-cancel flag (issue #546 P2). Pull-mode only. */
+    compensateOnCancel?: boolean;
+    /** Cancel-on-event specs (issue #546 P3 / #572). */
+    cancelOn?: {
+        event: string;
+        match: string;
+    }[];
+}
+/**
+ * Result from registering a function
+ */
+export interface RegisterFunctionResult {
+    /** Whether the function was newly created (vs updated) */
+    created: boolean;
+}
+/**
+ * Result from emitting an event
+ */
+export interface EmitResult {
+    /** IDs of runs created by this event */
+    runIds: string[];
+    /** ID of the stored event */
+    eventId: string;
+}
+/**
+ * Options for emitting an event
+ */
+export interface EmitOptions {
+    /** Event schema version (default 1) */
+    version?: number;
+    /** Idempotency key to prevent duplicate processing */
+    idempotencyKey?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Run information
+ */
+export interface Run {
+    /** Run ID */
+    id: string;
+    /** Function ID */
+    functionId: string;
+    /** Event ID that triggered this run */
+    eventId: string;
+    /** Current status */
+    status: RunStatus;
+    /** Current attempt number */
+    attempt: number;
+    /** Maximum attempts allowed */
+    maxAttempts: number;
+    /** Input data */
+    input?: unknown;
+    /** Output data (if completed) */
+    output?: unknown;
+    /** Error information (if failed) */
+    error?: {
+        message: string;
+        code: string;
+    };
+    /** When the run started */
+    startedAt?: string;
+    /** When the run ended */
+    endedAt?: string;
+    /** When the run was created */
+    createdAt: string;
+    /** When the run was last updated */
+    updatedAt: string;
+}
+/**
+ * Options for listing runs
+ */
+export interface ListRunsOptions {
+    /** Filter by function ID */
+    functionId?: string;
+    /** Filter by status */
+    status?: RunStatus;
+    /** Maximum number of results */
+    limit?: number;
+    /** Pagination cursor */
+    cursor?: string;
+}
+/**
+ * Result from listing runs
+ */
+export interface ListRunsResult {
+    /** List of runs */
+    runs: Run[];
+    /** Cursor for next page */
+    nextCursor?: string;
+    /** Total count of matching runs */
+    totalCount: number;
+}
+/**
+ * Ironflow client for server-side operations
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@ironflow/node";
+ *
+ * const client = createClient({
+ *   serverUrl: "http://localhost:9123",
+ * });
+ *
+ * // Register a function
+ * await client.registerFunction({
+ *   id: "my-function",
+ *   name: "My Function",
+ *   triggers: [{ event: "my.event" }],
+ *   endpointUrl: "http://localhost:3000/api/ironflow",
+ *   preferredMode: "push",
+ * });
+ *
+ * // Emit an event
+ * const result = await client.emit("my.event", { data: "value" });
+ * console.log("Created runs:", result.runIds);
+ * ```
+ */
+export declare class IronflowClient {
+    private readonly serverUrl;
+    private readonly apiKey?;
+    private readonly timeout;
+    private readonly onErrorHandler?;
+    constructor(config?: IronflowClientConfig);
+    /**
+     * Register a function with the Ironflow server
+     */
+    registerFunction(request: RegisterFunctionRequest): Promise<RegisterFunctionResult>;
+    /**
+     * Emit an event to trigger workflows
+     *
+     * @example
+     * ```typescript
+     * const result = await client.emit("order.placed", {
+     *   orderId: "123",
+     *   total: 99.99,
+     * });
+     * console.log("Created runs:", result.runIds);
+     * ```
+     */
+    emit(eventName: string, data: unknown, options?: EmitOptions): Promise<EmitResult>;
+    /**
+     * Emit an event synchronously — waits for the triggered run to complete and returns the result.
+     *
+     * Calls the TriggerSync endpoint, which blocks until the run finishes or the timeout elapses.
+     * Throws RunFailedError if the run fails, RunCancelledError if it is cancelled.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.emitSync("order.placed", { orderId: "123" });
+     * console.log("Output:", result.output);
+     * ```
+     */
+    emitSync(eventName: string, data: unknown, options?: {
+        timeout?: number;
+    }): Promise<EmitSyncResult>;
+    /**
+     * Publish a message to a developer pub/sub topic.
+     * Unlike emit(), this does NOT trigger workflow functions.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.publish("notifications", {
+     *   userId: "123",
+     *   message: "Hello!",
+     * });
+     * console.log("Published:", result.eventId, result.sequence);
+     * ```
+     */
+    publish(topic: string, data: unknown, options?: PublishOptions): Promise<PublishResult>;
+    /**
+     * List all active developer pub/sub topics.
+     *
+     * @example
+     * ```typescript
+     * const topics = await client.listTopics();
+     * for (const t of topics) {
+     *   console.log(t.name, t.messageCount);
+     * }
+     * ```
+     */
+    listTopics(): Promise<TopicInfo[]>;
+    /**
+     * Get detailed statistics for a topic.
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.getTopicStats("notifications");
+     * console.log("Messages:", stats.messageCount, "Lag:", stats.lag);
+     * ```
+     */
+    getTopicStats(topic: string): Promise<TopicStats>;
+    /**
+     * Get a run by ID
+     */
+    getRun(runId: string): Promise<Run>;
+    /**
+     * List runs with optional filtering
+     */
+    listRuns(options?: ListRunsOptions): Promise<ListRunsResult>;
+    /**
+     * Cancel a running workflow
+     */
+    cancelRun(runId: string, reason?: string): Promise<Run>;
+    /**
+     * Retry a failed run
+     */
+    retryRun(runId: string, fromStep?: string): Promise<Run>;
+    /**
+     * Health check
+     */
+    health(): Promise<string>;
+    /**
+     * Entity stream operations
+     *
+     * @example
+     * ```typescript
+     * // Append an event to a stream
+     * const result = await client.streams.append("order-123", {
+     *   name: "order.created",
+     *   data: { total: 100 },
+     *   entityType: "order",
+     * });
+     *
+     * // Read events from a stream
+     * const { events } = await client.streams.read("order-123", { limit: 10 });
+     *
+     * // Get stream info
+     * const info = await client.streams.getInfo("order-123");
+     * ```
+     */
+    streams: {
+        /**
+         * Append an event to an entity stream
+         */
+        append: (entityId: string, input: AppendEventInput, options?: AppendOptions) => Promise<AppendResult>;
+        /**
+         * Read events from an entity stream
+         */
+        read: (entityId: string, options?: ReadStreamOptions) => Promise<{
+            events: StreamEvent[];
+            totalCount: number;
+        }>;
+        /**
+         * Get information about an entity stream.
+         *
+         * Returns `null` if no events have been written to this stream yet — safe to
+         * pass `expectedVersion: 0` to `append()` in that case to create the first event.
+         *
+         * @example
+         * ```typescript
+         * const info = await client.streams.getInfo("order-123");
+         * await client.streams.append("order-123", event, {
+         *   expectedVersion: info ? info.version : 0,
+         * });
+         * ```
+         */
+        getInfo: (entityId: string) => Promise<StreamInfo | null>;
+        /**
+         * Create a snapshot of the materialized state at a specific stream version.
+         * Use snapshots to speed up state reconstruction for long-lived entity streams.
+         */
+        createSnapshot: (entityId: string, input: {
+            entityType: string;
+            entityVersion: number;
+            state: Record<string, unknown>;
+        }) => Promise<{
+            snapshotId: string;
+        }>;
+        /**
+         * Get the latest snapshot at or before a given version.
+         * Returns the snapshot closest to the requested version without exceeding it.
+         */
+        getSnapshot: (entityId: string, options?: {
+            beforeVersion?: number;
+        }) => Promise<StreamSnapshot>;
+        /**
+         * List all entity streams.
+         */
+        listStreams: () => Promise<StreamListEntry[]>;
+        /**
+         * Get the full event history for an entity.
+         */
+        getEntityHistory: (entityId: string) => Promise<EntityHistoryEntry[]>;
+    };
+    /**
+     * SQL-backed projections
+     *
+     * Create materialized SQL tables from event streams. Events are processed
+     * server-side using parameterized SQL handlers.
+     *
+     * @example
+     * ```typescript
+     * // Create a SQL projection
+     * await client.sqlProjections.create({
+     *   name: "board",
+     *   tableSql: "CREATE TABLE proj_board (id TEXT PRIMARY KEY, title TEXT, status TEXT)",
+     *   eventHandlers: {
+     *     "issue.created": "INSERT INTO proj_board (id, title, status) VALUES (:entity_id, :data.title, 'OPEN')",
+     *     "issue.status_changed": "UPDATE proj_board SET status = :data.to WHERE id = :entity_id",
+     *   },
+     *   events: ["issue.created", "issue.status_changed"],
+     * });
+     *
+     * // Query the projection
+     * const result = await client.sqlProjections.query("board", {
+     *   where: "status = 'OPEN'",
+     *   orderBy: "title ASC",
+     *   limit: 50,
+     * });
+     * ```
+     */
+    readonly sqlProjections: {
+        /**
+         * Create a SQL-backed projection with a materialized table and event handlers.
+         */
+        create: (input: CreateSQLProjectionInput) => Promise<{
+            name: string;
+            status: string;
+        }>;
+        /**
+         * Query a SQL-backed projection table with optional filtering, ordering, and pagination.
+         */
+        query: (name: string, options?: QuerySQLProjectionOptions) => Promise<SQLProjectionQueryResult>;
+    };
+    /**
+     * API key management
+     *
+     * @example
+     * ```typescript
+     * // Create an API key
+     * const { key } = await client.apiKeys.create({ name: "ci-key" });
+     *
+     * // List all API keys
+     * const keys = await client.apiKeys.list();
+     *
+     * // Rotate a key
+     * const rotated = await client.apiKeys.rotate(keys[0].id);
+     * ```
+     */
+    readonly apiKeys: {
+        /** Create a new API key */
+        create: (input: CreateAPIKeyInput) => Promise<APIKeyWithSecret>;
+        /** List all API keys */
+        list: () => Promise<APIKey[]>;
+        /** Get an API key by ID */
+        get: (id: string) => Promise<APIKey>;
+        /** Delete an API key */
+        delete: (id: string) => Promise<void>;
+        /** Rotate an API key (generates a new secret) */
+        rotate: (id: string) => Promise<APIKeyWithSecret>;
+    };
+    /**
+     * Organization management (enterprise)
+     *
+     * @example
+     * ```typescript
+     * const org = await client.orgs.create({ name: "Acme Corp" });
+     * const orgs = await client.orgs.list();
+     * await client.orgs.update(org.id, { name: "Acme Inc" });
+     * ```
+     */
+    readonly orgs: {
+        /** Create a new organization */
+        create: (input: CreateOrgInput) => Promise<Organization>;
+        /** List all organizations */
+        list: () => Promise<Organization[]>;
+        /** Get an organization by ID */
+        get: (id: string) => Promise<Organization>;
+        /** Update an organization */
+        update: (id: string, input: UpdateOrgInput) => Promise<Organization>;
+        /** Delete an organization */
+        delete: (id: string) => Promise<void>;
+    };
+    /**
+     * Role management (enterprise)
+     *
+     * @example
+     * ```typescript
+     * const role = await client.roles.create({ name: "deployer", org_id: orgId });
+     * await client.roles.assignPolicy(role.id, policyId);
+     * const roles = await client.roles.list(orgId);
+     * ```
+     */
+    readonly roles: {
+        /** Create a new role */
+        create: (input: CreateRoleInput) => Promise<Role>;
+        /** List roles, optionally filtered by organization */
+        list: (orgId?: string) => Promise<Role[]>;
+        /** Get a role by ID */
+        get: (id: string) => Promise<Role>;
+        /** Update a role */
+        update: (id: string, input: UpdateRoleInput) => Promise<Role>;
+        /** Delete a role */
+        delete: (id: string) => Promise<void>;
+        /** Assign a policy to a role */
+        assignPolicy: (roleId: string, policyId: string) => Promise<void>;
+        /** Remove a policy from a role */
+        removePolicy: (roleId: string, policyId: string) => Promise<void>;
+    };
+    /**
+     * Policy management (enterprise)
+     *
+     * @example
+     * ```typescript
+     * const policy = await client.policies.create({
+     *   name: "allow-emit",
+     *   effect: "allow",
+     *   actions: "emit:*",
+     *   resources: "*",
+     *   org_id: orgId,
+     * });
+     * const policies = await client.policies.list(orgId);
+     * ```
+     */
+    readonly policies: {
+        /** Create a new policy */
+        create: (input: CreatePolicyInput) => Promise<Policy>;
+        /** List policies, optionally filtered by organization */
+        list: (orgId?: string) => Promise<Policy[]>;
+        /** Get a policy by ID */
+        get: (id: string) => Promise<Policy>;
+        /** Update a policy */
+        update: (id: string, input: UpdatePolicyInput) => Promise<Policy>;
+        /** Delete a policy */
+        delete: (id: string) => Promise<void>;
+    };
+    /**
+     * Projection management
+     *
+     * @example
+     * ```typescript
+     * const state = await client.projections.get("order-summary");
+     * const statuses = await client.projections.list();
+     * await client.projections.rebuild("order-summary");
+     * ```
+     */
+    readonly projections: {
+        /**
+         * Get the current materialized state of a projection.
+         *
+         * Returns a flat `ProjectionStateResult<TState>` (see `@ironflow/core`).
+         * The server returns a wrapped envelope and this method peels it via
+         * `peelProjectionEnvelope`. See issue #610 / CHANGELOG 0.20.0.
+         *
+         * For a freshly registered projection with no events applied, returns
+         * empty `state`, `lastEventTime: undefined`, `version: 0`.
+         */
+        get: <TState = unknown>(name: string, options?: GetProjectionOptions) => Promise<ProjectionStateResult<TState>>;
+        /** List all projection statuses */
+        list: () => Promise<ProjectionStatusInfo[]>;
+        /** Get operational status for a projection */
+        getStatus: (name: string) => Promise<ProjectionStatusInfo>;
+        /** Trigger a full rebuild of a projection */
+        rebuild: (name: string) => Promise<RebuildJob>;
+        /** Get the status of an in-progress or completed rebuild job */
+        getRebuildJob: (name: string) => Promise<RebuildJob>;
+        /** Delete a projection */
+        delete: (name: string) => Promise<void>;
+        /** Pause a projection (stop consuming new events) */
+        pause: (name: string) => Promise<void>;
+        /** Resume a paused projection */
+        resume: (name: string) => Promise<void>;
+        /** Cancel an in-progress rebuild */
+        cancelRebuild: (name: string) => Promise<void>;
+        /**
+         * Wait until the named projection has processed events up to `minSeq`,
+         * or the timeout elapses. Read-your-writes primitive for CQRS: pair
+         * with `sequence` from a `streams.append` response.
+         *
+         * ```typescript
+         * const { sequence } = await client.streams.append(orderId, event);
+         * await client.projections.waitForCatchup("order-detail-view", {
+         *   minSeq: sequence,
+         *   partition: orderId,
+         *   timeoutMs: 5000,
+         * });
+         * ```
+         *
+         * Errors: 404 (projection not found), 409 (paused/rebuilding/partition
+         * unsupported for external), 429 (wait capacity exceeded).
+         *
+         * Issue #473.
+         */
+        waitForCatchup: (name: string, opts: {
+            minSeq: bigint | number;
+            timeoutMs?: number;
+            partition?: string;
+        }) => Promise<WaitResult>;
+        /**
+         * Wait on multiple projections in a single request. All items share
+         * a single timeout deadline and a single atomic slot reservation on
+         * the server — if the server's cap cannot absorb N items, the whole
+         * batch is rejected with 429. Per-item failures are returned per
+         * element via `error` fields.
+         *
+         * Max 16 items. Issue #473.
+         */
+        waitForCatchupBatch: (items: Array<{
+            name: string;
+            minSeq: bigint | number;
+            partition?: string;
+        }>, opts?: {
+            timeoutMs?: number;
+        }) => Promise<Array<{
+            result?: WaitResult;
+            error?: string;
+        }>>;
+        /**
+         * Wait for a specific event (identified by `eventId` from a
+         * `streams.append` response) to be processed by the given projection.
+         * The server resolves eventId → NATS seq internally.
+         *
+         * Errors: 404 (event not found), 409 (event predates sequence
+         * tracking — fall back to waitForCatchup with minSeq from a
+         * fresh write), plus the standard wait errors.
+         *
+         * Issue #473.
+         */
+        waitForEvent: (eventId: string, projection: string, opts?: {
+            timeoutMs?: number;
+            partition?: string;
+        }) => Promise<WaitResult>;
+    };
+    /**
+     * Secrets management
+     *
+     * @example
+     * ```typescript
+     * await client.secrets.set("stripe-key", "sk_live_...");
+     * const secret = await client.secrets.get("stripe-key");
+     * const all = await client.secrets.list();
+     * await client.secrets.delete("stripe-key");
+     * ```
+     */
+    readonly secrets: {
+        /** Get a secret by name (returns value) */
+        get: (name: string) => Promise<Secret>;
+        /** Create a new secret */
+        set: (name: string, value: string) => Promise<Secret>;
+        /** Update an existing secret's value */
+        update: (name: string, value: string) => Promise<Secret>;
+        /** List all secrets (names only, no values) */
+        list: () => Promise<SecretListEntry[]>;
+        /** Delete a secret */
+        delete: (name: string) => Promise<void>;
+    };
+    /**
+     * Project management
+     *
+     * @example
+     * ```typescript
+     * const project = await client.projects.create({ name: "my-service" });
+     * const projects = await client.projects.list();
+     * await client.projects.update(project.id, { name: "renamed-service" });
+     * await client.projects.delete(project.id);
+     * ```
+     */
+    readonly projects: {
+        /** List all projects */
+        list: () => Promise<Project[]>;
+        /** Create a new project */
+        create: (input: {
+            name: string;
+            description?: string;
+        }) => Promise<Project>;
+        /** Update a project */
+        update: (id: string, input: {
+            name?: string;
+            description?: string;
+        }) => Promise<Project>;
+        /** Delete a project */
+        delete: (id: string) => Promise<void>;
+    };
+    /**
+     * Environment management
+     *
+     * @example
+     * ```typescript
+     * const env = await client.environments.create({ name: "staging", projectId: "proj_..." });
+     * const envs = await client.environments.list();
+     * await client.environments.update(env.id, { name: "staging-v2" });
+     * await client.environments.delete(env.id);
+     * ```
+     */
+    readonly environments: {
+        /** List all environments */
+        list: () => Promise<Environment[]>;
+        /** Create a new environment */
+        create: (input: {
+            name: string;
+            project_id: string;
+        }) => Promise<Environment>;
+        /** Update an environment */
+        update: (id: string, input: {
+            name?: string;
+        }) => Promise<Environment>;
+        /** Delete an environment */
+        delete: (id: string) => Promise<void>;
+    };
+    /**
+     * Event schema registry operations
+     *
+     * @example
+     * ```typescript
+     * // Register a schema
+     * const schema = await client.schemas.register({
+     *   name: "order.placed",
+     *   version: 1,
+     *   schema: { type: "object", properties: { orderId: { type: "string" } } },
+     * });
+     *
+     * // List all schemas
+     * const schemas = await client.schemas.list();
+     *
+     * // Get latest version of a schema
+     * const latest = await client.schemas.get("order.placed");
+     *
+     * // Get a specific version
+     * const v1 = await client.schemas.getVersion("order.placed", 1);
+     *
+     * // Test an upcast transformation
+     * const result = await client.schemas.testUpcast({
+     *   eventName: "order.placed",
+     *   fromVersion: 1,
+     *   toVersion: 2,
+     *   data: { orderId: "123" },
+     * });
+     * ```
+     */
+    readonly schemas: {
+        /** Register a new event schema (or a new version of an existing schema) */
+        register: (input: RegisterSchemaInput) => Promise<EventSchema>;
+        /** List all registered event schemas */
+        list: () => Promise<EventSchema[]>;
+        /** Get the latest version of an event schema by name */
+        get: (name: string) => Promise<EventSchema>;
+        /** Get a specific version of an event schema */
+        getVersion: (name: string, version: number) => Promise<EventSchema>;
+        /** Delete a specific version of an event schema */
+        delete: (name: string, version: number) => Promise<void>;
+        /** Test an upcast transformation between two schema versions */
+        testUpcast: (input: TestUpcastInput) => Promise<UpcastResult>;
+    };
+    /**
+     * Get the reconstructed state of a run at a specific point in time.
+     *
+     * @param runId The run ID to query
+     * @param timestamp The point in time to reconstruct state at
+     */
+    getRunStateAt(runId: string, timestamp: Date): Promise<TimeTravelRunState>;
+    /**
+     * Get the timeline of events for a run (for time-travel debugging).
+     *
+     * @param runId The run ID to query
+     */
+    getRunTimeline(runId: string): Promise<TimeTravelTimelineEvent[]>;
+    /**
+     * Get the output of a specific step at a point in time.
+     *
+     * @param runId The run ID
+     * @param stepId The step ID
+     * @param timestamp The point in time to query
+     */
+    getStepOutputAt(runId: string, stepId: string, timestamp: Date): Promise<TimeTravelStepOutput>;
+    /**
+     * Get the audit trail for a run.
+     *
+     * @param runId The run ID to retrieve the audit trail for
+     */
+    getAuditTrail(runId: string): Promise<AuditTrailEntry[]>;
+    /**
+     * Webhook management operations
+     *
+     * @example
+     * ```typescript
+     * // List all webhook sources
+     * const sources = await client.webhooks.listSources();
+     *
+     * // Delete a webhook source
+     * await client.webhooks.deleteSource("my-webhook");
+     *
+     * // List deliveries for a source
+     * const { deliveries } = await client.webhooks.listDeliveries({ sourceId: "my-webhook" });
+     * ```
+     */
+    readonly webhooks: {
+        /** Create a new webhook source */
+        create: (input: CreateWebhookSourceInput) => Promise<WebhookSource>;
+        /** List all registered webhook sources */
+        listSources: () => Promise<WebhookSource[]>;
+        /** Delete a webhook source by ID */
+        deleteSource: (id: string) => Promise<void>;
+        /** List webhook deliveries with optional filtering */
+        listDeliveries: (opts?: ListWebhookDeliveriesOptions) => Promise<{
+            deliveries: WebhookDelivery[];
+            totalCount: number;
+        }>;
+    };
+    /**
+     * User management operations
+     *
+     * @example
+     * ```typescript
+     * // Create a user
+     * const user = await client.users.create({ email: "alice@example.com", password: "secret", roles: ["admin"] });
+     *
+     * // List users
+     * const users = await client.users.list();
+     *
+     * // Update a user
+     * await client.users.update(user.id, { name: "Alice" });
+     *
+     * // Delete a user
+     * await client.users.delete(user.id);
+     * ```
+     */
+    readonly users: {
+        /** Create a new user (admin only) */
+        create: (input: CreateUserInput) => Promise<User>;
+        /** List all users in the current organization (admin only) */
+        list: () => Promise<User[]>;
+        /** Get a user by ID */
+        get: (id: string) => Promise<User>;
+        /** Update a user's profile (admin only) */
+        update: (id: string, input: UpdateUserInput) => Promise<User>;
+        /** Delete a user (admin only) */
+        delete: (id: string) => Promise<void>;
+    };
+    /**
+     * Tenant management operations (enterprise-only)
+     *
+     * @example
+     * ```typescript
+     * // List all tenants
+     * const tenants = await client.tenants.list();
+     * console.log(tenants.map(t => t.name));
+     * ```
+     */
+    readonly tenants: {
+        /** List all tenants (enterprise-only) */
+        list: () => Promise<Tenant[]>;
+    };
+    /**
+     * KV store operations
+     *
+     * @example
+     * ```typescript
+     * const kv = client.kv();
+     * const bucket = await kv.createBucket({ name: "sessions", ttlSeconds: 3600 });
+     * const handle = kv.bucket("sessions");
+     * const { revision } = await handle.put("user.123", { token: "abc" });
+     * const entry = await handle.get("user.123");
+     * ```
+     */
+    kv(): KVClient;
+    /**
+     * Create a CommandDedup instance for atomic command-level idempotency.
+     *
+     * Uses the claim-first pattern backed by NATS KV. The KV bucket is created
+     * lazily on the first operation. Store the returned instance and reuse it
+     * across requests — do not call commandDedup() per request.
+     *
+     * @example
+     * ```typescript
+     * const dedup = client.commandDedup<OrderResult>("order-commands");
+     * const prior = await dedup.tryClaim(commandId, { orderId, claimedAt: new Date().toISOString() });
+     * if (prior !== null) return prior;
+     * try {
+     *   const result = await runOrderHandler();
+     *   await dedup.finalize(commandId, result);
+     *   return result;
+     * } catch (err) {
+     *   await dedup.release(commandId).catch(() => {}); // swallow — don't mask the original error
+     *   throw err;
+     * }
+     * ```
+     */
+    commandDedup<T>(bucketName: string, options?: CommandDedupOptions): CommandDedup<T>;
+    /**
+     * Config management operations
+     *
+     * @example
+     * ```typescript
+     * const config = client.config();
+     * await config.set("app", { featureX: true });
+     * const { data } = await config.get("app");
+     * await config.patch("app", { maxRetries: 5 });
+     * const configs = await config.list();
+     * await config.delete("app");
+     * ```
+     */
+    config(): ConfigClient;
+    /**
+     * Patch a step's output (hot patching)
+     */
+    patchStep(stepId: string, output: Record<string, unknown>, reason?: string): Promise<void>;
+    /**
+     * Resume a paused or failed run
+     */
+    resumeRun(runId: string, fromStep?: string): Promise<Run>;
+    /**
+     * Pause a running workflow run (scoped injection).
+     *
+     * @example
+     * ```typescript
+     * const result = await client.pauseRun("run_abc123");
+     * console.log(result.status); // "paused"
+     * ```
+     */
+    pauseRun(runId: string): Promise<{
+        status: string;
+    }>;
+    /**
+     * Get the paused state of a run, including completed steps and next step hint.
+     *
+     * @example
+     * ```typescript
+     * const state = await client.getPausedState("run_abc123");
+     * for (const step of state.steps) {
+     *   console.log(step.name, step.output, step.injected);
+     * }
+     * console.log("Next step:", state.nextStepHint);
+     * ```
+     */
+    getPausedState(runId: string): Promise<{
+        steps: Array<{
+            id: string;
+            name: string;
+            output: unknown;
+            injected: boolean;
+            completedAt: string;
+        }>;
+        nextStepHint: string;
+        pauseReason: string;
+    }>;
+    /**
+     * Inject new output for a step in a paused run (scoped injection).
+     *
+     * @example
+     * ```typescript
+     * const result = await client.injectStepOutput(
+     *   "run_abc123",
+     *   "step_xyz",
+     *   { corrected: true },
+     *   "Manual correction"
+     * );
+     * console.log("Previous output:", result.previousOutput);
+     * ```
+     */
+    injectStepOutput(runId: string, stepId: string, newOutput: unknown, reason?: string): Promise<{
+        stepId: string;
+        previousOutput: unknown;
+    }>;
+    /**
+     * List registered functions
+     */
+    listFunctions(): Promise<unknown[]>;
+    /**
+     * List connected workers
+     */
+    listWorkers(): Promise<unknown[]>;
+    /**
+     * Make an HTTP request to the server
+     */
+    private request;
+    /**
+     * Throw a typed error based on HTTP status code.
+     */
+    private throwTypedError;
+    /**
+     * Make a REST HTTP request to the server (supports GET, POST, PATCH, DELETE)
+     */
+    private restRequest;
+    /**
+     * Call the global onError handler if registered.
+     * Swallows any errors thrown by the callback.
+     */
+    private callOnError;
+}
+/**
+ * Create a new Ironflow client
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({ serverUrl: "http://localhost:9123" });
+ * ```
+ */
+export declare function createClient(config?: IronflowClientConfig): IronflowClient;
+//# sourceMappingURL=client.d.ts.map