@ironflow/browser 0.1.0-test.2 → 0.2.0

package/dist/client.js

@@ -3,11 +3,13 @@
  *
  * Singleton client for browser-based real-time interactions with Ironflow.
  */
-import { NotConfiguredError, IronflowError, ValidationError, createLogger, createNoopLogger, DEFAULT_TIMEOUTS, TriggerResponseSchema, RunResponseSchema, ListRunsResponseSchema, RunStatusSchema, ErrorResponseSchema, safeJsonParse, patterns, } from "@ironflow/core";
+import { NotConfiguredError, IronflowError, ValidationError, createLogger, createNoopLogger, DEFAULT_TIMEOUTS, HEADERS, TriggerResponseSchema, RunResponseSchema, ListRunsResponseSchema, RunStatusSchema, ErrorResponseSchema, safeJsonParse, patterns, } from "@ironflow/core";
 import { mergeConfig } from "./config.js";
 import { SubscriptionManager, } from "./subscription.js";
 import { createWebSocketTransport } from "./transport/websocket.js";
 import { createConnectRPCTransport } from "./transport/connectrpc.js";
+import { BrowserKVClient } from "./kv.js";
+import { BrowserConfigClient } from "./config-client.js";
 /**
  * Ironflow browser client singleton
  */
@@ -43,6 +45,7 @@ class IronflowClient {
             reconnectDelay: this.config.reconnect.backoff.initial,
             maxReconnectDelay: this.config.reconnect.backoff.max,
             reconnectBackoff: this.config.reconnect.backoff.multiplier,
+            environment: this.config.environment,
         };
         // Create transport based on config (ConnectRPC by default)
         if (this.config.transport === "websocket") {
@@ -85,11 +88,15 @@ class IronflowClient {
         const serverUrl = this.config?.serverUrl ?? "http://localhost:9123";
         try {
             // Try to get server capabilities via ConnectRPC endpoint
+            const detectHeaders = {
+                "Content-Type": "application/json",
+            };
+            if (this.config?.environment) {
+                detectHeaders[HEADERS.ENVIRONMENT] = this.config.environment;
+            }
             const response = await fetch(`${serverUrl}/ironflow.v1.IronflowService/GetCapabilities`, {
                 method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                },
+                headers: detectHeaders,
                 body: "{}",
             });
             if (response.ok) {
@@ -263,6 +270,187 @@ class IronflowClient {
         const response = await this.request(RunResponseSchema, "POST", "/ironflow.v1.IronflowService/CancelRun", { id: runId, reason });
         return this.mapRunResponse(response);
     }
+    /**
+     * Retry a failed run
+     */
+    async retryRun(runId, fromStep) {
+        this.ensureConfigured();
+        const response = await this.request(RunResponseSchema, "POST", "/ironflow.v1.IronflowService/RetryRun", { id: runId, fromStep });
+        return this.mapRunResponse(response);
+    }
+    /**
+     * Patch a step's output (hot patching)
+     */
+    async patchStep(stepId, output, reason) {
+        this.ensureConfigured();
+        const url = `${this.config.serverUrl}/api/v1/steps/patch`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                "Content-Type": "application/json",
+                [HEADERS.ENVIRONMENT]: this.config.environment,
+            };
+            if (this.config.auth?.apiKey) {
+                headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
+            }
+            const response = await fetch(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ step_id: stepId, output, reason: reason || "" }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const error = safeJsonParse(await response.text());
+                throw new IronflowError(error?.message || `Patch step failed: ${response.status}`, { code: error?.code || "PATCH_FAILED" });
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Resume a paused or failed run
+     */
+    async resumeRun(runId, fromStep) {
+        this.ensureConfigured();
+        const url = `${this.config.serverUrl}/api/v1/runs/resume`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                "Content-Type": "application/json",
+                [HEADERS.ENVIRONMENT]: this.config.environment,
+            };
+            if (this.config.auth?.apiKey) {
+                headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
+            }
+            const response = await fetch(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ run_id: runId, from_step: fromStep || "" }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const error = safeJsonParse(await response.text());
+                throw new IronflowError(error?.message || `Resume run failed: ${response.status}`, { code: error?.code || "RESUME_FAILED" });
+            }
+            return response.json();
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * List registered functions
+     */
+    async listFunctions() {
+        this.ensureConfigured();
+        const url = `${this.config.serverUrl}/api/v1/functions`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                [HEADERS.ENVIRONMENT]: this.config.environment,
+            };
+            if (this.config.auth?.apiKey) {
+                headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
+            }
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new IronflowError(`List functions failed: ${response.status}`, { code: "LIST_FUNCTIONS_FAILED" });
+            }
+            const data = await response.json();
+            return data.functions || [];
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * List connected workers
+     */
+    async listWorkers() {
+        this.ensureConfigured();
+        const url = `${this.config.serverUrl}/api/v1/workers`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                [HEADERS.ENVIRONMENT]: this.config.environment,
+            };
+            if (this.config.auth?.apiKey) {
+                headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
+            }
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new IronflowError(`List workers failed: ${response.status}`, { code: "LIST_WORKERS_FAILED" });
+            }
+            const data = await response.json();
+            return data.workers || [];
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Health check
+     */
+    async health() {
+        this.ensureConfigured();
+        const url = `${this.config.serverUrl}/health`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new IronflowError(`Health check failed: ${response.status}`, { code: "HEALTH_FAILED" });
+            }
+            return response.json();
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Get server capabilities
+     */
+    async getCapabilities() {
+        this.ensureConfigured();
+        const url = `${this.config.serverUrl}/api/v1/capabilities`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new IronflowError(`Get capabilities failed: ${response.status}`, { code: "CAPABILITIES_FAILED" });
+            }
+            return response.json();
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
     // ============================================================================
     // Event Emission
     // ============================================================================
@@ -282,6 +470,7 @@ class IronflowClient {
         const response = await this.request(TriggerResponseSchema, "POST", "/ironflow.v1.PubSubService/Emit", {
             event: eventName,
             data,
+            ...(options?.version ? { version: options.version } : {}),
             idempotency_key: options?.idempotencyKey,
             metadata: options?.metadata,
             namespace: options?.namespace,
@@ -307,6 +496,417 @@ class IronflowClient {
         return sub;
     }
     // ============================================================================
+    // Entity Streams
+    // ============================================================================
+    /**
+     * Entity stream operations
+     *
+     * @example
+     * ```typescript
+     * // Append an event to a stream
+     * const result = await ironflow.streams.append("order-123", {
+     *   name: "order.created",
+     *   data: { total: 100 },
+     *   entityType: "order",
+     * });
+     *
+     * // Read events from a stream
+     * const { events } = await ironflow.streams.read("order-123", { limit: 10 });
+     *
+     * // Get stream info
+     * const info = await ironflow.streams.getInfo("order-123");
+     * ```
+     */
+    streams = {
+        /**
+         * Append an event to an entity stream
+         */
+        append: async (entityId, input, options) => {
+            this.ensureConfigured();
+            const response = await this.streamRequest("/ironflow.v1.EntityStreamService/AppendEvent", {
+                entity_id: entityId,
+                entity_type: input.entityType,
+                event_name: input.name,
+                data: input.data,
+                expected_version: options?.expectedVersion ?? -1,
+                idempotency_key: options?.idempotencyKey ?? "",
+                version: options?.version ?? 1,
+            });
+            return {
+                entityVersion: Number(response.entityVersion ?? 0),
+                eventId: response.eventId ?? "",
+            };
+        },
+        /**
+         * Read events from an entity stream
+         */
+        read: async (entityId, options) => {
+            this.ensureConfigured();
+            const response = await this.streamRequest("/ironflow.v1.EntityStreamService/ReadStream", {
+                entity_id: entityId,
+                from_version: options?.fromVersion ?? 0,
+                limit: options?.limit ?? 0,
+                direction: options?.direction ?? "forward",
+            });
+            return {
+                events: (response.events ?? []).map((e) => ({
+                    id: e.id,
+                    name: e.name,
+                    data: e.data ?? {},
+                    entityVersion: Number(e.entityVersion ?? 0),
+                    version: e.version,
+                    timestamp: e.timestamp,
+                    source: e.source,
+                    metadata: e.metadata,
+                })),
+                totalCount: Number(response.totalCount ?? 0),
+            };
+        },
+        /**
+         * Get information about an entity stream
+         */
+        getInfo: async (entityId) => {
+            this.ensureConfigured();
+            const response = await this.streamRequest("/ironflow.v1.EntityStreamService/GetStreamInfo", {
+                entity_id: entityId,
+            });
+            return {
+                entityId: response.entityId ?? "",
+                entityType: response.entityType ?? "",
+                version: Number(response.version ?? 0),
+                eventCount: Number(response.eventCount ?? 0),
+                createdAt: response.createdAt ?? "",
+                updatedAt: response.updatedAt ?? "",
+            };
+        },
+        /**
+         * Subscribe to real-time events for an entity stream
+         *
+         * @example
+         * ```typescript
+         * const sub = await ironflow.streams.subscribe("order-123", {
+         *   entityType: "order",
+         *   onEvent: (event) => console.log(event),
+         *   replay: 100,
+         * });
+         *
+         * // Cleanup
+         * sub.unsubscribe();
+         * ```
+         */
+        subscribe: async (entityId, options) => {
+            this.ensureConfigured();
+            const pattern = `entity:${options.entityType}.${entityId}.>`;
+            const sub = await this.subscribe(pattern, {
+                onEvent: (event) => {
+                    const data = event.data;
+                    const streamEvent = {
+                        id: data.id ?? "",
+                        name: data.name ?? "",
+                        data: data.data ?? {},
+                        entityVersion: data.entityVersion ?? 0,
+                        version: data.version ?? 0,
+                        timestamp: data.timestamp ?? "",
+                        source: data.source,
+                        metadata: data.metadata,
+                    };
+                    options.onEvent(streamEvent);
+                },
+                onError: options.onError
+                    ? (info) => options.onError(new Error(info.message))
+                    : undefined,
+                replay: options.replay,
+            });
+            return sub;
+        },
+    };
+    // ============================================================================
+    // Projections
+    // ============================================================================
+    /**
+     * Get the current state of a projection
+     *
+     * @example
+     * ```typescript
+     * const result = await ironflow.getProjection<OrderStats>('order-stats');
+     * console.log(result.state); // { totalOrders: 42, ... }
+     *
+     * // With partition
+     * const result = await ironflow.getProjection('order-stats', { partition: 'customer-123' });
+     * ```
+     */
+    async getProjection(name, options) {
+        this.ensureConfigured();
+        let url = `${this.config.serverUrl}/api/v1/projections/${encodeURIComponent(name)}`;
+        if (options?.partition) {
+            url += `?partition=${encodeURIComponent(options.partition)}`;
+        }
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                [HEADERS.ENVIRONMENT]: this.config.environment,
+            };
+            if (this.config.auth?.apiKey) {
+                headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
+            }
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const error = safeJsonParse(await response.text());
+                throw new IronflowError(error?.message || `Get projection failed: ${response.status}`, { code: error?.code || "GET_PROJECTION_FAILED" });
+            }
+            const data = await response.json();
+            return {
+                name: data.name,
+                partition: data.state?.partition_key ?? "__global__",
+                state: data.state?.state ?? {},
+                lastEventId: data.state?.last_event_id ?? "",
+                lastEventTime: data.state?.last_event_time
+                    ? new Date(data.state.last_event_time)
+                    : new Date(0),
+                version: data.state?.version ?? 0,
+                mode: data.mode,
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Get the status of a projection
+     *
+     * @example
+     * ```typescript
+     * const status = await ironflow.getProjectionStatus('order-stats');
+     * console.log(status.status); // 'active' | 'rebuilding' | 'paused' | 'error'
+     * ```
+     */
+    async getProjectionStatus(name) {
+        this.ensureConfigured();
+        const url = `${this.config.serverUrl}/api/v1/projections/${encodeURIComponent(name)}/status`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                [HEADERS.ENVIRONMENT]: this.config.environment,
+            };
+            if (this.config.auth?.apiKey) {
+                headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
+            }
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const error = safeJsonParse(await response.text());
+                throw new IronflowError(error?.message || `Get projection status failed: ${response.status}`, { code: error?.code || "GET_PROJECTION_STATUS_FAILED" });
+            }
+            const data = await response.json();
+            return {
+                name: data.name,
+                status: data.status,
+                mode: data.mode,
+                lastEventSeq: data.last_event_seq ?? 0,
+                lag: data.lag ?? 0,
+                errorMessage: data.error_message || undefined,
+                updatedAt: data.updated_at ? new Date(data.updated_at) : new Date(),
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Trigger a rebuild of a projection
+     *
+     * @example
+     * ```typescript
+     * const result = await ironflow.rebuildProjection('order-stats');
+     * ```
+     */
+    async rebuildProjection(name, options) {
+        this.ensureConfigured();
+        const url = `${this.config.serverUrl}/api/v1/projections/${encodeURIComponent(name)}/rebuild`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                "Content-Type": "application/json",
+                [HEADERS.ENVIRONMENT]: this.config.environment,
+            };
+            if (this.config.auth?.apiKey) {
+                headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
+            }
+            const response = await fetch(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    partition: options?.partition,
+                    from_event_id: options?.fromEventId,
+                    dry_run: options?.dryRun,
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const error = safeJsonParse(await response.text());
+                throw new IronflowError(error?.message || `Rebuild projection failed: ${response.status}`, { code: error?.code || "REBUILD_PROJECTION_FAILED" });
+            }
+            return response.json();
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * List all registered projections
+     *
+     * @example
+     * ```typescript
+     * const projections = await ironflow.listProjections();
+     * projections.forEach(p => console.log(p.name, p.status));
+     * ```
+     */
+    async listProjections() {
+        this.ensureConfigured();
+        const url = `${this.config.serverUrl}/api/v1/projections`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                [HEADERS.ENVIRONMENT]: this.config.environment,
+            };
+            if (this.config.auth?.apiKey) {
+                headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
+            }
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new IronflowError(`List projections failed: ${response.status}`, { code: "LIST_PROJECTIONS_FAILED" });
+            }
+            const data = await response.json();
+            const projections = data.projections || [];
+            return projections.map((p) => ({
+                name: p.name,
+                status: p.status,
+                mode: p.mode,
+                lastEventSeq: p.last_event_seq ?? 0,
+                lag: 0,
+                errorMessage: p.error_message || undefined,
+                updatedAt: p.updated_at ? new Date(p.updated_at) : new Date(),
+            }));
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Subscribe to real-time updates for a projection
+     *
+     * @example
+     * ```typescript
+     * const sub = await ironflow.subscribeToProjection<OrderStats>('order-stats', {
+     *   onUpdate: (state, event) => console.log('Updated:', state),
+     *   onError: (error) => console.error(error),
+     * });
+     *
+     * // With partition
+     * const sub = await ironflow.subscribeToProjection('order-stats', {
+     *   onUpdate: (state, event) => console.log('Updated:', state),
+     * }, { partition: 'customer-123' });
+     *
+     * // Cleanup
+     * sub.unsubscribe();
+     * ```
+     */
+    async subscribeToProjection(name, callbacks, options) {
+        this.ensureConfigured();
+        // Build the subscription pattern
+        let pattern;
+        if (options?.partition) {
+            pattern = `system.projection.${name}.${options.partition}.updated`;
+        }
+        else {
+            pattern = `system.projection.${name}.>`;
+        }
+        const sub = await this.subscribe(pattern, {
+            onEvent: (event) => {
+                const payload = event.data;
+                const state = payload.state ?? {};
+                callbacks.onUpdate(state, {
+                    id: payload.last_event_id ?? "",
+                    name: payload.last_event_name ?? "",
+                });
+            },
+            onError: callbacks.onError
+                ? (info) => callbacks.onError(new Error(info.message))
+                : undefined,
+            replay: options?.replay,
+        });
+        return sub;
+    }
+    // ============================================================================
+    // KV Store
+    // ============================================================================
+    /**
+     * KV store operations
+     *
+     * @example
+     * ```typescript
+     * const kv = ironflow.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");
+     *
+     * // Watch for changes
+     * const watcher = handle.watch({
+     *   onUpdate: (event) => console.log(event),
+     * }, { key: "user.*" });
+     * ```
+     */
+    kv() {
+        this.ensureConfigured();
+        return new BrowserKVClient(this.config);
+    }
+    // ============================================================================
+    // Config Management
+    // ============================================================================
+    /**
+     * Config management operations
+     *
+     * @example
+     * ```typescript
+     * const cfg = ironflow.configManager();
+     * await cfg.set("app", { featureX: true, maxRetries: 3 });
+     * const { data, revision } = await cfg.get("app");
+     * await cfg.patch("app", { maxRetries: 5 });
+     * const configs = await cfg.list();
+     * await cfg.delete("app");
+     *
+     * // Watch for changes
+     * const sub = await cfg.watch("app", {
+     *   onEvent: (config) => console.log(config),
+     * });
+     * sub.unsubscribe();
+     * ```
+     */
+    configManager() {
+        this.ensureConfigured();
+        return new BrowserConfigClient(this.config, (pattern, callbacks) => this.subscribe(pattern, callbacks));
+    }
+    // ============================================================================
     // Pattern Helpers (static)
     // ============================================================================
     /**
@@ -332,6 +932,15 @@ class IronflowClient {
         }
         this.transport = null;
     }
+    /**
+     * Reset client state for testing. Not intended for production use.
+     * @internal
+     */
+    _resetForTesting() {
+        this.cleanup();
+        this.config = null;
+        this.logger = createNoopLogger();
+    }
     setupVisibilityHandling() {
         this.visibilityHandler = () => {
             if (document.hidden) {
@@ -355,6 +964,7 @@ class IronflowClient {
         try {
             const headers = {
                 "Content-Type": "application/json",
+                [HEADERS.ENVIRONMENT]: this.config.environment,
             };
             if (this.config.auth?.apiKey) {
                 headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
@@ -397,12 +1007,64 @@ class IronflowClient {
                 throw error;
             }
             if (error instanceof Error && error.name === "AbortError") {
-                throw new IronflowError(`Request timeout after ${timeout}ms`, {
+                throw new IronflowError(`Request timeout after ${timeout}ms for ${method} ${path}`, {
                     code: "TIMEOUT",
                     retryable: true,
                 });
             }
-            throw new IronflowError(error instanceof Error ? error.message : "Request failed", {
+            throw new IronflowError(error instanceof Error
+                ? `${method} ${path} failed: ${error.message}`
+                : `${method} ${path} failed`, {
+                code: "REQUEST_FAILED",
+                retryable: true,
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    async streamRequest(path, body) {
+        const url = `${this.config.serverUrl}${path}`;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                "Content-Type": "application/json",
+                [HEADERS.ENVIRONMENT]: this.config.environment,
+            };
+            if (this.config.auth?.apiKey) {
+                headers["Authorization"] = `Bearer ${this.config.auth.apiKey}`;
+            }
+            else if (this.config.auth?.token) {
+                headers["Authorization"] = `Bearer ${this.config.auth.token}`;
+            }
+            const response = await fetch(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorBody = safeJsonParse(await response.text());
+                throw new IronflowError(errorBody?.message ?? `Request failed: ${response.status}`, {
+                    code: errorBody?.code ?? `HTTP_${response.status}`,
+                    retryable: response.status >= 500,
+                });
+            }
+            return response.json();
+        }
+        catch (error) {
+            if (error instanceof IronflowError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new IronflowError(`Request timeout after ${timeout}ms for POST ${path}`, { code: "TIMEOUT", retryable: true });
+            }
+            throw new IronflowError(error instanceof Error
+                ? `POST ${path} failed: ${error.message}`
+                : `POST ${path} failed`, {
                 code: "REQUEST_FAILED",
                 retryable: true,
                 cause: error instanceof Error ? error : undefined,
@@ -413,7 +1075,9 @@ class IronflowClient {
         }
     }
     mapRunResponse(response) {
-        const statusResult = RunStatusSchema.safeParse(response.status.toLowerCase());
+        // ConnectRPC returns proto enum strings like "RUN_STATUS_COMPLETED" — normalize to "completed"
+        const rawStatus = response.status.toLowerCase().replace(/^run_status_/, "");
+        const statusResult = RunStatusSchema.safeParse(rawStatus);
         const status = statusResult.success ? statusResult.data : "failed";
         return {
             id: response.id,