flowforge-client 0.3.1 → 0.3.3

package/README.md

@@ -151,6 +151,30 @@ await ff.runs.cancel('run-id');
 
 // Replay a failed run
 const { data: newRun } = await ff.runs.replay('run-id');
+
+// Stream real-time events (SSE)
+for await (const event of ff.runs.stream('run-id')) {
+  console.log(event.type, event.data);
+}
+
+// Stream with callbacks
+await ff.runs.stream('run-id', {
+  onEvent: (e) => console.log(e.type),
+  onComplete: (e) => console.log('Done:', e.data),
+  onError: (e) => console.error('Error:', e.message),
+}).drain();
+
+// Collect all events into an array
+const events = await ff.runs.stream('run-id').collect();
+
+// Cancel a stream early
+const stream = ff.runs.stream('run-id');
+for await (const event of stream) {
+  if (event.type === 'step_completed') {
+    stream.close();
+    break;
+  }
+}
 ```
 
 ### Functions
@@ -310,6 +334,12 @@ import type {
   UpdateToolInput,
   SendEventInput,
 
+  // Streaming types
+  RunEventType,
+  RunStreamEvent,
+  StreamOptions,
+  StreamConfig,
+
   // Result type
   Result,
   FlowForgeError,

package/dist/index.d.mts

@@ -15,7 +15,7 @@ declare class FlowForgeError extends Error {
     constructor(message: string, status: number, code?: string | undefined, detail?: unknown | undefined);
 }
 type RunStatus = "pending" | "running" | "completed" | "failed" | "paused" | "cancelled";
-type StepType = "run" | "sleep" | "ai" | "wait_for_event" | "invoke" | "send_event" | "agent";
+type StepType = "run" | "sleep" | "ai" | "wait_for_event" | "invoke" | "send_event" | "agent" | "sub_agent";
 type StepStatus = "pending" | "running" | "completed" | "failed" | "sleeping" | "waiting";
 type TriggerType = "event" | "cron" | "webhook";
 type ApprovalStatus = "pending" | "approved" | "rejected" | "expired";
@@ -23,6 +23,7 @@ interface Run {
     id: string;
     function_id: string;
     event_id: string | null;
+    parent_run_id: string | null;
     status: RunStatus;
     trigger_type: string;
     trigger_data: Record<string, unknown>;
@@ -68,12 +69,17 @@ interface FlowForgeFunction {
     created_at: string;
     updated_at: string;
 }
+type ToolType = "custom" | "webhook" | "builtin";
 interface Tool {
     id: string;
     name: string;
     description: string;
     parameters: Record<string, unknown>;
+    tool_type: ToolType;
     code: string | null;
+    webhook_url: string | null;
+    webhook_method: string;
+    webhook_headers: Record<string, string> | null;
     is_builtin: boolean;
     requires_approval: boolean;
     approval_timeout: string | null;
@@ -154,6 +160,20 @@ interface ToolFilters {
 interface ApprovalFilters {
     status: ApprovalStatus;
 }
+interface SubAgentConfig {
+    system_prompt: string;
+    model?: string;
+    tools?: string[];
+    max_iterations?: number;
+    max_tool_calls?: number;
+    description?: string;
+}
+interface AgentConfig {
+    model?: string;
+    max_iterations?: number;
+    max_tool_calls?: number;
+    sub_agents?: Record<string, SubAgentConfig>;
+}
 interface CreateFunctionInput {
     id: string;
     name: string;
@@ -164,7 +184,7 @@ interface CreateFunctionInput {
     is_inline?: boolean;
     system_prompt?: string;
     tools_config?: string[];
-    agent_config?: Record<string, unknown>;
+    agent_config?: AgentConfig | Record<string, unknown>;
     config?: Record<string, unknown>;
     is_active?: boolean;
 }
@@ -183,7 +203,11 @@ interface CreateToolInput {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
+    tool_type?: ToolType;
     code?: string;
+    webhook_url?: string;
+    webhook_method?: string;
+    webhook_headers?: Record<string, string>;
     requires_approval?: boolean;
     approval_timeout?: string;
     is_active?: boolean;
@@ -191,11 +215,41 @@ interface CreateToolInput {
 interface UpdateToolInput {
     description?: string;
     parameters?: Record<string, unknown>;
+    tool_type?: ToolType;
     code?: string;
+    webhook_url?: string;
+    webhook_method?: string;
+    webhook_headers?: Record<string, string>;
     requires_approval?: boolean;
     approval_timeout?: string;
     is_active?: boolean;
 }
+interface CreateCredentialInput {
+    name: string;
+    credential_type?: string;
+    value: string;
+    description?: string;
+}
+interface UpdateCredentialInput {
+    value?: string;
+    description?: string;
+    credential_type?: string;
+    is_active?: boolean;
+}
+interface Credential {
+    id: string;
+    name: string;
+    credential_type: string;
+    value_prefix: string;
+    description: string | null;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface CredentialsResponse {
+    credentials: Credential[];
+    total: number;
+}
 interface SendEventInput {
     id?: string;
     user_id?: string;
@@ -255,6 +309,32 @@ interface ApiKeysResponse {
 interface ApiKeyFilters {
     include_revoked: boolean;
 }
+type RunEventType = "step_started" | "step_completed" | "step_failed" | "thinking" | "thinking_chunk" | "tool_call_started" | "tool_call_completed" | "approval_required" | "approval_resolved" | "sub_agent_started" | "sub_agent_completed" | "run_started" | "run_paused" | "run_resumed" | "run_completed" | "run_failed";
+interface RunStreamEvent {
+    type: RunEventType;
+    data: Record<string, unknown>;
+    runId: string;
+    timestamp: string;
+}
+interface StreamOptions {
+    /** Include historical events on connect (default: true) */
+    includeHistory?: boolean;
+    /** Server-side stream timeout in seconds (default: 300, max: 600) */
+    timeout?: number;
+    /** AbortSignal to cancel the stream */
+    signal?: AbortSignal;
+    /** Callback for each event */
+    onEvent?: (event: RunStreamEvent) => void;
+    /** Callback when run completes or fails */
+    onComplete?: (event: RunStreamEvent) => void;
+    /** Callback on stream error */
+    onError?: (error: FlowForgeError) => void;
+}
+interface StreamConfig {
+    baseUrl: string;
+    apiKey?: string;
+    fetchFn: typeof fetch;
+}
 interface ClientOptions {
     /**
      * API key for authentication.
@@ -401,13 +481,44 @@ declare class EventsResource {
     select(): QueryBuilder<Event, EventFilters>;
 }
 
+/**
+ * RunStream — SSE stream wrapper for FlowForge run events.
+ */
+
+declare class RunStream {
+    private runId;
+    private config;
+    private options;
+    private abortController;
+    private iteratorStarted;
+    private closed;
+    constructor(runId: string, config: StreamConfig, options?: StreamOptions);
+    /**
+     * Async iterator — use with `for await...of`.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<RunStreamEvent>;
+    /**
+     * Consume the entire stream via callbacks. Returns the terminal event or null.
+     */
+    drain(): Promise<RunStreamEvent | null>;
+    /**
+     * Collect all events into an array.
+     */
+    collect(): Promise<RunStreamEvent[]>;
+    /**
+     * Cancel the stream.
+     */
+    close(): void;
+}
+
 /**
  * FlowForge TypeScript Client - Runs Resource
  */
 
 declare class RunsResource {
     private request;
-    constructor(request: RequestFn$2);
+    private streamConfig?;
+    constructor(request: RequestFn$2, streamConfig?: StreamConfig | undefined);
     /**
      * Get a run by ID, including its steps.
      *
@@ -455,6 +566,25 @@ declare class RunsResource {
      * ```
      */
     replay(runId: string): Promise<Result<RunWithSteps>>;
+    /**
+     * Stream real-time SSE events for a run.
+     *
+     * @example Async iterator
+     * ```ts
+     * for await (const event of ff.runs.stream('run-id')) {
+     *   console.log(event.type, event.data);
+     * }
+     * ```
+     *
+     * @example Callback-based
+     * ```ts
+     * await ff.runs.stream('run-id', {
+     *   onEvent: (e) => console.log(e.type),
+     *   onComplete: (e) => console.log('Done'),
+     * }).drain();
+     * ```
+     */
+    stream(runId: string, options?: StreamOptions): RunStream;
     /**
      * Wait for a run to complete (polling).
      *
@@ -872,6 +1002,40 @@ declare class ApiKeysResource {
     }>>;
 }
 
+/**
+ * FlowForge TypeScript Client - Credentials Resource
+ */
+
+declare class CredentialsResource {
+    private request;
+    constructor(request: RequestFn$2);
+    /**
+     * List all credentials for the tenant.
+     * Values are never returned — only masked prefixes.
+     */
+    list(): Promise<Result<CredentialsResponse>>;
+    /**
+     * Get a credential by name (metadata only, no decrypted value).
+     */
+    get(name: string): Promise<Result<Credential>>;
+    /**
+     * Create a new encrypted credential.
+     */
+    create(input: CreateCredentialInput): Promise<Result<Credential>>;
+    /**
+     * Update an existing credential.
+     * If value is provided, it will be re-encrypted.
+     */
+    update(name: string, input: UpdateCredentialInput): Promise<Result<Credential>>;
+    /**
+     * Delete a credential.
+     */
+    delete(name: string): Promise<Result<{
+        success: boolean;
+        message: string;
+    }>>;
+}
+
 /**
  * FlowForge TypeScript Client - Main Client Factory
  */
@@ -896,6 +1060,8 @@ interface FlowForgeClient {
     users: UsersResource;
     /** API Keys resource - manage API key authentication */
     apiKeys: ApiKeysResource;
+    /** Credentials resource - manage encrypted service credentials */
+    credentials: CredentialsResource;
 }
 /**
  * Create a FlowForge client instance.
@@ -931,4 +1097,4 @@ interface FlowForgeClient {
  */
 declare function createClient(baseUrl: string, options?: ClientOptions): FlowForgeClient;
 
-export { type ApiKey, type ApiKeyCreated, type ApiKeyFilters, type ApiKeyType, ApiKeysResource, type ApiKeysResponse, type Approval, type ApprovalFilters, type ApprovalStatus, ApprovalsResource, type ClientOptions, type CreateApiKeyInput, type CreateFunctionInput, type CreateToolInput, type CreateUserInput, type Event, type EventFilters, EventsResource, type FlowForgeClient, FlowForgeError, type FlowForgeFunction, type FunctionFilters, FunctionsResource, HealthResource, type HealthStatus, type OrderDirection, QueryBuilder, type QueryParams, type Result, type Run, type RunFilters, type RunStatus, type RunWithSteps, RunsResource, type SendEventInput, type SendEventResponse, type Stats, type Step, type StepStatus, type StepType, type Tool, type ToolFilters, ToolsResource, type TriggerType, type UpdateFunctionInput, type UpdateToolInput, type UpdateUserInput, type User, type UserRole, UsersResource, type UsersResponse, createClient };
+export { type AgentConfig, type ApiKey, type ApiKeyCreated, type ApiKeyFilters, type ApiKeyType, ApiKeysResource, type ApiKeysResponse, type Approval, type ApprovalFilters, type ApprovalStatus, ApprovalsResource, type ClientOptions, type CreateApiKeyInput, type CreateCredentialInput, type CreateFunctionInput, type CreateToolInput, type CreateUserInput, type Credential, CredentialsResource, type CredentialsResponse, type Event, type EventFilters, EventsResource, type FlowForgeClient, FlowForgeError, type FlowForgeFunction, type FunctionFilters, FunctionsResource, HealthResource, type HealthStatus, type OrderDirection, QueryBuilder, type QueryParams, type Result, type Run, type RunEventType, type RunFilters, type RunStatus, RunStream, type RunStreamEvent, type RunWithSteps, RunsResource, type SendEventInput, type SendEventResponse, type Stats, type Step, type StepStatus, type StepType, type StreamConfig, type StreamOptions, type SubAgentConfig, type Tool, type ToolFilters, type ToolType, ToolsResource, type TriggerType, type UpdateCredentialInput, type UpdateFunctionInput, type UpdateToolInput, type UpdateUserInput, type User, type UserRole, UsersResource, type UsersResponse, createClient };

package/dist/index.d.ts

@@ -15,7 +15,7 @@ declare class FlowForgeError extends Error {
     constructor(message: string, status: number, code?: string | undefined, detail?: unknown | undefined);
 }
 type RunStatus = "pending" | "running" | "completed" | "failed" | "paused" | "cancelled";
-type StepType = "run" | "sleep" | "ai" | "wait_for_event" | "invoke" | "send_event" | "agent";
+type StepType = "run" | "sleep" | "ai" | "wait_for_event" | "invoke" | "send_event" | "agent" | "sub_agent";
 type StepStatus = "pending" | "running" | "completed" | "failed" | "sleeping" | "waiting";
 type TriggerType = "event" | "cron" | "webhook";
 type ApprovalStatus = "pending" | "approved" | "rejected" | "expired";
@@ -23,6 +23,7 @@ interface Run {
     id: string;
     function_id: string;
     event_id: string | null;
+    parent_run_id: string | null;
     status: RunStatus;
     trigger_type: string;
     trigger_data: Record<string, unknown>;
@@ -68,12 +69,17 @@ interface FlowForgeFunction {
     created_at: string;
     updated_at: string;
 }
+type ToolType = "custom" | "webhook" | "builtin";
 interface Tool {
     id: string;
     name: string;
     description: string;
     parameters: Record<string, unknown>;
+    tool_type: ToolType;
     code: string | null;
+    webhook_url: string | null;
+    webhook_method: string;
+    webhook_headers: Record<string, string> | null;
     is_builtin: boolean;
     requires_approval: boolean;
     approval_timeout: string | null;
@@ -154,6 +160,20 @@ interface ToolFilters {
 interface ApprovalFilters {
     status: ApprovalStatus;
 }
+interface SubAgentConfig {
+    system_prompt: string;
+    model?: string;
+    tools?: string[];
+    max_iterations?: number;
+    max_tool_calls?: number;
+    description?: string;
+}
+interface AgentConfig {
+    model?: string;
+    max_iterations?: number;
+    max_tool_calls?: number;
+    sub_agents?: Record<string, SubAgentConfig>;
+}
 interface CreateFunctionInput {
     id: string;
     name: string;
@@ -164,7 +184,7 @@ interface CreateFunctionInput {
     is_inline?: boolean;
     system_prompt?: string;
     tools_config?: string[];
-    agent_config?: Record<string, unknown>;
+    agent_config?: AgentConfig | Record<string, unknown>;
     config?: Record<string, unknown>;
     is_active?: boolean;
 }
@@ -183,7 +203,11 @@ interface CreateToolInput {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
+    tool_type?: ToolType;
     code?: string;
+    webhook_url?: string;
+    webhook_method?: string;
+    webhook_headers?: Record<string, string>;
     requires_approval?: boolean;
     approval_timeout?: string;
     is_active?: boolean;
@@ -191,11 +215,41 @@ interface CreateToolInput {
 interface UpdateToolInput {
     description?: string;
     parameters?: Record<string, unknown>;
+    tool_type?: ToolType;
     code?: string;
+    webhook_url?: string;
+    webhook_method?: string;
+    webhook_headers?: Record<string, string>;
     requires_approval?: boolean;
     approval_timeout?: string;
     is_active?: boolean;
 }
+interface CreateCredentialInput {
+    name: string;
+    credential_type?: string;
+    value: string;
+    description?: string;
+}
+interface UpdateCredentialInput {
+    value?: string;
+    description?: string;
+    credential_type?: string;
+    is_active?: boolean;
+}
+interface Credential {
+    id: string;
+    name: string;
+    credential_type: string;
+    value_prefix: string;
+    description: string | null;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface CredentialsResponse {
+    credentials: Credential[];
+    total: number;
+}
 interface SendEventInput {
     id?: string;
     user_id?: string;
@@ -255,6 +309,32 @@ interface ApiKeysResponse {
 interface ApiKeyFilters {
     include_revoked: boolean;
 }
+type RunEventType = "step_started" | "step_completed" | "step_failed" | "thinking" | "thinking_chunk" | "tool_call_started" | "tool_call_completed" | "approval_required" | "approval_resolved" | "sub_agent_started" | "sub_agent_completed" | "run_started" | "run_paused" | "run_resumed" | "run_completed" | "run_failed";
+interface RunStreamEvent {
+    type: RunEventType;
+    data: Record<string, unknown>;
+    runId: string;
+    timestamp: string;
+}
+interface StreamOptions {
+    /** Include historical events on connect (default: true) */
+    includeHistory?: boolean;
+    /** Server-side stream timeout in seconds (default: 300, max: 600) */
+    timeout?: number;
+    /** AbortSignal to cancel the stream */
+    signal?: AbortSignal;
+    /** Callback for each event */
+    onEvent?: (event: RunStreamEvent) => void;
+    /** Callback when run completes or fails */
+    onComplete?: (event: RunStreamEvent) => void;
+    /** Callback on stream error */
+    onError?: (error: FlowForgeError) => void;
+}
+interface StreamConfig {
+    baseUrl: string;
+    apiKey?: string;
+    fetchFn: typeof fetch;
+}
 interface ClientOptions {
     /**
      * API key for authentication.
@@ -401,13 +481,44 @@ declare class EventsResource {
     select(): QueryBuilder<Event, EventFilters>;
 }
 
+/**
+ * RunStream — SSE stream wrapper for FlowForge run events.
+ */
+
+declare class RunStream {
+    private runId;
+    private config;
+    private options;
+    private abortController;
+    private iteratorStarted;
+    private closed;
+    constructor(runId: string, config: StreamConfig, options?: StreamOptions);
+    /**
+     * Async iterator — use with `for await...of`.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<RunStreamEvent>;
+    /**
+     * Consume the entire stream via callbacks. Returns the terminal event or null.
+     */
+    drain(): Promise<RunStreamEvent | null>;
+    /**
+     * Collect all events into an array.
+     */
+    collect(): Promise<RunStreamEvent[]>;
+    /**
+     * Cancel the stream.
+     */
+    close(): void;
+}
+
 /**
  * FlowForge TypeScript Client - Runs Resource
  */
 
 declare class RunsResource {
     private request;
-    constructor(request: RequestFn$2);
+    private streamConfig?;
+    constructor(request: RequestFn$2, streamConfig?: StreamConfig | undefined);
     /**
      * Get a run by ID, including its steps.
      *
@@ -455,6 +566,25 @@ declare class RunsResource {
      * ```
      */
     replay(runId: string): Promise<Result<RunWithSteps>>;
+    /**
+     * Stream real-time SSE events for a run.
+     *
+     * @example Async iterator
+     * ```ts
+     * for await (const event of ff.runs.stream('run-id')) {
+     *   console.log(event.type, event.data);
+     * }
+     * ```
+     *
+     * @example Callback-based
+     * ```ts
+     * await ff.runs.stream('run-id', {
+     *   onEvent: (e) => console.log(e.type),
+     *   onComplete: (e) => console.log('Done'),
+     * }).drain();
+     * ```
+     */
+    stream(runId: string, options?: StreamOptions): RunStream;
     /**
      * Wait for a run to complete (polling).
      *
@@ -872,6 +1002,40 @@ declare class ApiKeysResource {
     }>>;
 }
 
+/**
+ * FlowForge TypeScript Client - Credentials Resource
+ */
+
+declare class CredentialsResource {
+    private request;
+    constructor(request: RequestFn$2);
+    /**
+     * List all credentials for the tenant.
+     * Values are never returned — only masked prefixes.
+     */
+    list(): Promise<Result<CredentialsResponse>>;
+    /**
+     * Get a credential by name (metadata only, no decrypted value).
+     */
+    get(name: string): Promise<Result<Credential>>;
+    /**
+     * Create a new encrypted credential.
+     */
+    create(input: CreateCredentialInput): Promise<Result<Credential>>;
+    /**
+     * Update an existing credential.
+     * If value is provided, it will be re-encrypted.
+     */
+    update(name: string, input: UpdateCredentialInput): Promise<Result<Credential>>;
+    /**
+     * Delete a credential.
+     */
+    delete(name: string): Promise<Result<{
+        success: boolean;
+        message: string;
+    }>>;
+}
+
 /**
  * FlowForge TypeScript Client - Main Client Factory
  */
@@ -896,6 +1060,8 @@ interface FlowForgeClient {
     users: UsersResource;
     /** API Keys resource - manage API key authentication */
     apiKeys: ApiKeysResource;
+    /** Credentials resource - manage encrypted service credentials */
+    credentials: CredentialsResource;
 }
 /**
  * Create a FlowForge client instance.
@@ -931,4 +1097,4 @@ interface FlowForgeClient {
  */
 declare function createClient(baseUrl: string, options?: ClientOptions): FlowForgeClient;
 
-export { type ApiKey, type ApiKeyCreated, type ApiKeyFilters, type ApiKeyType, ApiKeysResource, type ApiKeysResponse, type Approval, type ApprovalFilters, type ApprovalStatus, ApprovalsResource, type ClientOptions, type CreateApiKeyInput, type CreateFunctionInput, type CreateToolInput, type CreateUserInput, type Event, type EventFilters, EventsResource, type FlowForgeClient, FlowForgeError, type FlowForgeFunction, type FunctionFilters, FunctionsResource, HealthResource, type HealthStatus, type OrderDirection, QueryBuilder, type QueryParams, type Result, type Run, type RunFilters, type RunStatus, type RunWithSteps, RunsResource, type SendEventInput, type SendEventResponse, type Stats, type Step, type StepStatus, type StepType, type Tool, type ToolFilters, ToolsResource, type TriggerType, type UpdateFunctionInput, type UpdateToolInput, type UpdateUserInput, type User, type UserRole, UsersResource, type UsersResponse, createClient };
+export { type AgentConfig, type ApiKey, type ApiKeyCreated, type ApiKeyFilters, type ApiKeyType, ApiKeysResource, type ApiKeysResponse, type Approval, type ApprovalFilters, type ApprovalStatus, ApprovalsResource, type ClientOptions, type CreateApiKeyInput, type CreateCredentialInput, type CreateFunctionInput, type CreateToolInput, type CreateUserInput, type Credential, CredentialsResource, type CredentialsResponse, type Event, type EventFilters, EventsResource, type FlowForgeClient, FlowForgeError, type FlowForgeFunction, type FunctionFilters, FunctionsResource, HealthResource, type HealthStatus, type OrderDirection, QueryBuilder, type QueryParams, type Result, type Run, type RunEventType, type RunFilters, type RunStatus, RunStream, type RunStreamEvent, type RunWithSteps, RunsResource, type SendEventInput, type SendEventResponse, type Stats, type Step, type StepStatus, type StepType, type StreamConfig, type StreamOptions, type SubAgentConfig, type Tool, type ToolFilters, type ToolType, ToolsResource, type TriggerType, type UpdateCredentialInput, type UpdateFunctionInput, type UpdateToolInput, type UpdateUserInput, type User, type UserRole, UsersResource, type UsersResponse, createClient };

package/dist/index.js

@@ -22,11 +22,13 @@ var index_exports = {};
 __export(index_exports, {
   ApiKeysResource: () => ApiKeysResource,
   ApprovalsResource: () => ApprovalsResource,
+  CredentialsResource: () => CredentialsResource,
   EventsResource: () => EventsResource,
   FlowForgeError: () => FlowForgeError,
   FunctionsResource: () => FunctionsResource,
   HealthResource: () => HealthResource,
   QueryBuilder: () => QueryBuilder,
+  RunStream: () => RunStream,
   RunsResource: () => RunsResource,
   ToolsResource: () => ToolsResource,
   UsersResource: () => UsersResource,
@@ -186,10 +188,212 @@ var EventsResource = class {
   }
 };
 
+// src/sse-parser.ts
+async function* parseSSEStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let eventType = "";
+  const dataLines = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.startsWith(":")) {
+          continue;
+        }
+        if (line === "") {
+          if (eventType && dataLines.length > 0) {
+            yield { event: eventType, data: dataLines.join("\n") };
+          }
+          eventType = "";
+          dataLines.length = 0;
+          continue;
+        }
+        if (line.startsWith("event:")) {
+          eventType = line.slice(6).trim();
+        } else if (line.startsWith("data:")) {
+          dataLines.push(line.slice(5).trim());
+        }
+      }
+    }
+    if (eventType && dataLines.length > 0) {
+      yield { event: eventType, data: dataLines.join("\n") };
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/types.ts
+var FlowForgeError = class extends Error {
+  constructor(message, status, code, detail) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.detail = detail;
+    this.name = "FlowForgeError";
+  }
+};
+
+// src/stream.ts
+var TERMINAL_EVENTS = /* @__PURE__ */ new Set([
+  "run_completed",
+  "run_failed"
+]);
+var RunStream = class {
+  constructor(runId, config, options = {}) {
+    this.runId = runId;
+    this.config = config;
+    this.options = options;
+    this.iteratorStarted = false;
+    this.closed = false;
+    this.abortController = new AbortController();
+  }
+  /**
+   * Async iterator — use with `for await...of`.
+   */
+  async *[Symbol.asyncIterator]() {
+    if (this.iteratorStarted) {
+      throw new FlowForgeError("Stream already consumed", 0, "STREAM_CONSUMED");
+    }
+    this.iteratorStarted = true;
+    const includeHistory = this.options.includeHistory ?? true;
+    const timeout = this.options.timeout ?? 300;
+    const params = new URLSearchParams({
+      include_history: String(includeHistory),
+      timeout: String(timeout)
+    });
+    const url = `${this.config.baseUrl}/api/v1/runs/${this.runId}/stream?${params}`;
+    const headers = {
+      Accept: "text/event-stream"
+    };
+    if (this.config.apiKey) {
+      headers["X-FlowForge-API-Key"] = this.config.apiKey;
+    }
+    const signals = [this.abortController.signal];
+    if (this.options.signal) {
+      signals.push(this.options.signal);
+    }
+    let response;
+    try {
+      response = await this.config.fetchFn(url, {
+        method: "GET",
+        headers,
+        signal: signals.length === 1 ? signals[0] : anySignal(signals)
+      });
+    } catch (err) {
+      const error = new FlowForgeError(
+        err instanceof Error ? err.message : "Stream connection failed",
+        0,
+        "STREAM_ERROR"
+      );
+      this.options.onError?.(error);
+      throw error;
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      const error = new FlowForgeError(
+        body || `HTTP ${response.status}`,
+        response.status,
+        "STREAM_HTTP_ERROR"
+      );
+      this.options.onError?.(error);
+      throw error;
+    }
+    if (!response.body) {
+      const error = new FlowForgeError(
+        "Response body is empty",
+        0,
+        "STREAM_EMPTY"
+      );
+      this.options.onError?.(error);
+      throw error;
+    }
+    try {
+      for await (const sse of parseSSEStream(response.body)) {
+        if (this.closed) return;
+        let data;
+        try {
+          data = JSON.parse(sse.data);
+        } catch {
+          continue;
+        }
+        const event = {
+          type: sse.event,
+          data,
+          runId: this.runId,
+          timestamp: data.timestamp ?? data.ts ?? (/* @__PURE__ */ new Date()).toISOString()
+        };
+        this.options.onEvent?.(event);
+        yield event;
+        if (TERMINAL_EVENTS.has(event.type)) {
+          this.options.onComplete?.(event);
+          return;
+        }
+      }
+    } catch (err) {
+      if (this.closed) return;
+      const error = new FlowForgeError(
+        err instanceof Error ? err.message : "Stream error",
+        0,
+        "STREAM_ERROR"
+      );
+      this.options.onError?.(error);
+      throw error;
+    }
+  }
+  /**
+   * Consume the entire stream via callbacks. Returns the terminal event or null.
+   */
+  async drain() {
+    let last = null;
+    for await (const event of this) {
+      last = event;
+    }
+    return last;
+  }
+  /**
+   * Collect all events into an array.
+   */
+  async collect() {
+    const events = [];
+    for await (const event of this) {
+      events.push(event);
+    }
+    return events;
+  }
+  /**
+   * Cancel the stream.
+   */
+  close() {
+    this.closed = true;
+    this.abortController.abort();
+  }
+};
+function anySignal(signals) {
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller.signal;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), {
+      once: true
+    });
+  }
+  return controller.signal;
+}
+
 // src/resources/runs.ts
 var RunsResource = class {
-  constructor(request) {
+  constructor(request, streamConfig) {
     this.request = request;
+    this.streamConfig = streamConfig;
   }
   /**
    * Get a run by ID, including its steps.
@@ -246,6 +450,30 @@ var RunsResource = class {
   async replay(runId) {
     return this.request("POST", `/runs/${runId}/replay`);
   }
+  /**
+   * Stream real-time SSE events for a run.
+   *
+   * @example Async iterator
+   * ```ts
+   * for await (const event of ff.runs.stream('run-id')) {
+   *   console.log(event.type, event.data);
+   * }
+   * ```
+   *
+   * @example Callback-based
+   * ```ts
+   * await ff.runs.stream('run-id', {
+   *   onEvent: (e) => console.log(e.type),
+   *   onComplete: (e) => console.log('Done'),
+   * }).drain();
+   * ```
+   */
+  stream(runId, options) {
+    if (!this.streamConfig) {
+      throw new Error("Stream config not available");
+    }
+    return new RunStream(runId, this.streamConfig, options);
+  }
   /**
    * Wait for a run to complete (polling).
    *
@@ -732,9 +960,51 @@ var ApiKeysResource = class {
   }
 };
 
+// src/resources/credentials.ts
+var CredentialsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * List all credentials for the tenant.
+   * Values are never returned — only masked prefixes.
+   */
+  async list() {
+    return this.request("GET", "/credentials");
+  }
+  /**
+   * Get a credential by name (metadata only, no decrypted value).
+   */
+  async get(name) {
+    return this.request("GET", `/credentials/${name}`);
+  }
+  /**
+   * Create a new encrypted credential.
+   */
+  async create(input) {
+    return this.request("POST", "/credentials", input);
+  }
+  /**
+   * Update an existing credential.
+   * If value is provided, it will be re-encrypted.
+   */
+  async update(name, input) {
+    return this.request("PATCH", `/credentials/${name}`, input);
+  }
+  /**
+   * Delete a credential.
+   */
+  async delete(name) {
+    return this.request(
+      "DELETE",
+      `/credentials/${name}`
+    );
+  }
+};
+
 // src/client.ts
 var DEFAULT_TIMEOUT = 3e4;
-function anySignal(signals) {
+function anySignal2(signals) {
   const controller = new AbortController();
   for (const signal of signals) {
     if (signal.aborted) {
@@ -778,7 +1048,7 @@ function createClient(baseUrl, options = {}) {
     }
     const timeoutController = new AbortController();
     const timeoutId = setTimeout(() => timeoutController.abort(), timeout);
-    const combinedSignal = signal ? anySignal([signal, timeoutController.signal]) : timeoutController.signal;
+    const combinedSignal = signal ? anySignal2([signal, timeoutController.signal]) : timeoutController.signal;
     try {
       const response = await fetchFn(`${normalizedBaseUrl}/api/v1${path}`, {
         method,
@@ -874,35 +1144,31 @@ function createClient(baseUrl, options = {}) {
   }
   return {
     events: new EventsResource(request),
-    runs: new RunsResource(request),
+    runs: new RunsResource(request, {
+      baseUrl: normalizedBaseUrl,
+      apiKey: options.apiKey,
+      fetchFn
+    }),
     functions: new FunctionsResource(request),
     tools: new ToolsResource(request),
     approvals: new ApprovalsResource(request),
     health: new HealthResource(request),
     users: new UsersResource(request),
-    apiKeys: new ApiKeysResource(request)
+    apiKeys: new ApiKeysResource(request),
+    credentials: new CredentialsResource(request)
   };
 }
-
-// src/types.ts
-var FlowForgeError = class extends Error {
-  constructor(message, status, code, detail) {
-    super(message);
-    this.status = status;
-    this.code = code;
-    this.detail = detail;
-    this.name = "FlowForgeError";
-  }
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiKeysResource,
   ApprovalsResource,
+  CredentialsResource,
   EventsResource,
   FlowForgeError,
   FunctionsResource,
   HealthResource,
   QueryBuilder,
+  RunStream,
   RunsResource,
   ToolsResource,
   UsersResource,

package/dist/index.mjs

@@ -150,10 +150,212 @@ var EventsResource = class {
   }
 };
 
+// src/sse-parser.ts
+async function* parseSSEStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let eventType = "";
+  const dataLines = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.startsWith(":")) {
+          continue;
+        }
+        if (line === "") {
+          if (eventType && dataLines.length > 0) {
+            yield { event: eventType, data: dataLines.join("\n") };
+          }
+          eventType = "";
+          dataLines.length = 0;
+          continue;
+        }
+        if (line.startsWith("event:")) {
+          eventType = line.slice(6).trim();
+        } else if (line.startsWith("data:")) {
+          dataLines.push(line.slice(5).trim());
+        }
+      }
+    }
+    if (eventType && dataLines.length > 0) {
+      yield { event: eventType, data: dataLines.join("\n") };
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/types.ts
+var FlowForgeError = class extends Error {
+  constructor(message, status, code, detail) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.detail = detail;
+    this.name = "FlowForgeError";
+  }
+};
+
+// src/stream.ts
+var TERMINAL_EVENTS = /* @__PURE__ */ new Set([
+  "run_completed",
+  "run_failed"
+]);
+var RunStream = class {
+  constructor(runId, config, options = {}) {
+    this.runId = runId;
+    this.config = config;
+    this.options = options;
+    this.iteratorStarted = false;
+    this.closed = false;
+    this.abortController = new AbortController();
+  }
+  /**
+   * Async iterator — use with `for await...of`.
+   */
+  async *[Symbol.asyncIterator]() {
+    if (this.iteratorStarted) {
+      throw new FlowForgeError("Stream already consumed", 0, "STREAM_CONSUMED");
+    }
+    this.iteratorStarted = true;
+    const includeHistory = this.options.includeHistory ?? true;
+    const timeout = this.options.timeout ?? 300;
+    const params = new URLSearchParams({
+      include_history: String(includeHistory),
+      timeout: String(timeout)
+    });
+    const url = `${this.config.baseUrl}/api/v1/runs/${this.runId}/stream?${params}`;
+    const headers = {
+      Accept: "text/event-stream"
+    };
+    if (this.config.apiKey) {
+      headers["X-FlowForge-API-Key"] = this.config.apiKey;
+    }
+    const signals = [this.abortController.signal];
+    if (this.options.signal) {
+      signals.push(this.options.signal);
+    }
+    let response;
+    try {
+      response = await this.config.fetchFn(url, {
+        method: "GET",
+        headers,
+        signal: signals.length === 1 ? signals[0] : anySignal(signals)
+      });
+    } catch (err) {
+      const error = new FlowForgeError(
+        err instanceof Error ? err.message : "Stream connection failed",
+        0,
+        "STREAM_ERROR"
+      );
+      this.options.onError?.(error);
+      throw error;
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      const error = new FlowForgeError(
+        body || `HTTP ${response.status}`,
+        response.status,
+        "STREAM_HTTP_ERROR"
+      );
+      this.options.onError?.(error);
+      throw error;
+    }
+    if (!response.body) {
+      const error = new FlowForgeError(
+        "Response body is empty",
+        0,
+        "STREAM_EMPTY"
+      );
+      this.options.onError?.(error);
+      throw error;
+    }
+    try {
+      for await (const sse of parseSSEStream(response.body)) {
+        if (this.closed) return;
+        let data;
+        try {
+          data = JSON.parse(sse.data);
+        } catch {
+          continue;
+        }
+        const event = {
+          type: sse.event,
+          data,
+          runId: this.runId,
+          timestamp: data.timestamp ?? data.ts ?? (/* @__PURE__ */ new Date()).toISOString()
+        };
+        this.options.onEvent?.(event);
+        yield event;
+        if (TERMINAL_EVENTS.has(event.type)) {
+          this.options.onComplete?.(event);
+          return;
+        }
+      }
+    } catch (err) {
+      if (this.closed) return;
+      const error = new FlowForgeError(
+        err instanceof Error ? err.message : "Stream error",
+        0,
+        "STREAM_ERROR"
+      );
+      this.options.onError?.(error);
+      throw error;
+    }
+  }
+  /**
+   * Consume the entire stream via callbacks. Returns the terminal event or null.
+   */
+  async drain() {
+    let last = null;
+    for await (const event of this) {
+      last = event;
+    }
+    return last;
+  }
+  /**
+   * Collect all events into an array.
+   */
+  async collect() {
+    const events = [];
+    for await (const event of this) {
+      events.push(event);
+    }
+    return events;
+  }
+  /**
+   * Cancel the stream.
+   */
+  close() {
+    this.closed = true;
+    this.abortController.abort();
+  }
+};
+function anySignal(signals) {
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller.signal;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), {
+      once: true
+    });
+  }
+  return controller.signal;
+}
+
 // src/resources/runs.ts
 var RunsResource = class {
-  constructor(request) {
+  constructor(request, streamConfig) {
     this.request = request;
+    this.streamConfig = streamConfig;
   }
   /**
    * Get a run by ID, including its steps.
@@ -210,6 +412,30 @@ var RunsResource = class {
   async replay(runId) {
     return this.request("POST", `/runs/${runId}/replay`);
   }
+  /**
+   * Stream real-time SSE events for a run.
+   *
+   * @example Async iterator
+   * ```ts
+   * for await (const event of ff.runs.stream('run-id')) {
+   *   console.log(event.type, event.data);
+   * }
+   * ```
+   *
+   * @example Callback-based
+   * ```ts
+   * await ff.runs.stream('run-id', {
+   *   onEvent: (e) => console.log(e.type),
+   *   onComplete: (e) => console.log('Done'),
+   * }).drain();
+   * ```
+   */
+  stream(runId, options) {
+    if (!this.streamConfig) {
+      throw new Error("Stream config not available");
+    }
+    return new RunStream(runId, this.streamConfig, options);
+  }
   /**
    * Wait for a run to complete (polling).
    *
@@ -696,9 +922,51 @@ var ApiKeysResource = class {
   }
 };
 
+// src/resources/credentials.ts
+var CredentialsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * List all credentials for the tenant.
+   * Values are never returned — only masked prefixes.
+   */
+  async list() {
+    return this.request("GET", "/credentials");
+  }
+  /**
+   * Get a credential by name (metadata only, no decrypted value).
+   */
+  async get(name) {
+    return this.request("GET", `/credentials/${name}`);
+  }
+  /**
+   * Create a new encrypted credential.
+   */
+  async create(input) {
+    return this.request("POST", "/credentials", input);
+  }
+  /**
+   * Update an existing credential.
+   * If value is provided, it will be re-encrypted.
+   */
+  async update(name, input) {
+    return this.request("PATCH", `/credentials/${name}`, input);
+  }
+  /**
+   * Delete a credential.
+   */
+  async delete(name) {
+    return this.request(
+      "DELETE",
+      `/credentials/${name}`
+    );
+  }
+};
+
 // src/client.ts
 var DEFAULT_TIMEOUT = 3e4;
-function anySignal(signals) {
+function anySignal2(signals) {
   const controller = new AbortController();
   for (const signal of signals) {
     if (signal.aborted) {
@@ -742,7 +1010,7 @@ function createClient(baseUrl, options = {}) {
     }
     const timeoutController = new AbortController();
     const timeoutId = setTimeout(() => timeoutController.abort(), timeout);
-    const combinedSignal = signal ? anySignal([signal, timeoutController.signal]) : timeoutController.signal;
+    const combinedSignal = signal ? anySignal2([signal, timeoutController.signal]) : timeoutController.signal;
     try {
       const response = await fetchFn(`${normalizedBaseUrl}/api/v1${path}`, {
         method,
@@ -838,34 +1106,30 @@ function createClient(baseUrl, options = {}) {
   }
   return {
     events: new EventsResource(request),
-    runs: new RunsResource(request),
+    runs: new RunsResource(request, {
+      baseUrl: normalizedBaseUrl,
+      apiKey: options.apiKey,
+      fetchFn
+    }),
     functions: new FunctionsResource(request),
     tools: new ToolsResource(request),
     approvals: new ApprovalsResource(request),
     health: new HealthResource(request),
     users: new UsersResource(request),
-    apiKeys: new ApiKeysResource(request)
+    apiKeys: new ApiKeysResource(request),
+    credentials: new CredentialsResource(request)
   };
 }
-
-// src/types.ts
-var FlowForgeError = class extends Error {
-  constructor(message, status, code, detail) {
-    super(message);
-    this.status = status;
-    this.code = code;
-    this.detail = detail;
-    this.name = "FlowForgeError";
-  }
-};
 export {
   ApiKeysResource,
   ApprovalsResource,
+  CredentialsResource,
   EventsResource,
   FlowForgeError,
   FunctionsResource,
   HealthResource,
   QueryBuilder,
+  RunStream,
   RunsResource,
   ToolsResource,
   UsersResource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowforge-client",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "TypeScript client for FlowForge workflow orchestration",
   "main": "dist/index.js",
   "module": "dist/index.mjs",