@ironflow/browser 0.27.0 → 0.29.0

package/dist/client.js

@@ -3,7 +3,7 @@
  *
  * Singleton client for browser-based real-time interactions with Ironflow.
  */
-import { NotConfiguredError, IronflowError, RunFailedError, RunCancelledError, UnauthenticatedError, EnterpriseRequiredError, UnauthorizedError, ValidationError, createLogger, createNoopLogger, DEFAULT_TIMEOUTS, HEADERS, TriggerResponseSchema, TriggerSyncResponseSchema, RunResponseSchema, ListRunsResponseSchema, RunStatusSchema, ErrorResponseSchema, safeJsonParse, patterns, peelProjectionEnvelope, webhookVerifyConfigToWire, webhookVerifyConfigFromWire, } from "@ironflow/core";
+import { NotConfiguredError, IronflowError, RunFailedError, RunCancelledError, UnauthenticatedError, EnterpriseRequiredError, UnauthorizedError, ValidationError, createLogger, createNoopLogger, DEFAULT_TIMEOUTS, HEADERS, TriggerResponseSchema, TriggerSyncResponseSchema, RunResponseSchema, ListRunsResponseSchema, RunStatusSchema, ErrorResponseSchema, safeJsonParse, patterns, peelProjectionEnvelope, webhookVerifyConfigToWire, webhookGraceToWire, webhookSourceFromWire, webhookDeliveryFromWire, } from "@ironflow/core";
 import { mergeConfig } from "./config.js";
 import { SubscriptionManager, } from "./subscription.js";
 import { createWebSocketTransport } from "./transport/websocket.js";
@@ -12,6 +12,28 @@ import { filterWaitStreamFrames } from "./projection-stream.js";
 import { BrowserKVClient } from "./kv.js";
 import { BrowserConfigClient } from "./config-client.js";
 import { createAgentsNamespace } from "./agents/index.js";
+/**
+ * Key for the offline queue's replay entry point.
+ *
+ * Not exported from the package root, so it is unreachable outside this module
+ * pair — the closest thing to package-private TypeScript offers.
+ */
+export const REPLAY_QUEUED_WRITE = Symbol("ironflow.replayQueuedWrite");
+/**
+ * Whether an HTTP status is worth trying again.
+ *
+ * 5xx is the obvious half. 429 is the half that is easy to miss: a rate limit
+ * is a "later", not a "never", and a caller that treats it as permanent gives
+ * up at exactly the moment backing off would have worked.
+ *
+ * This matters most for the offline write queue (ADR 0053), whose drain after
+ * a long offline stretch is a burst of writes — the single most likely way to
+ * earn a 429. Classifying it as permanent would send those writes to the dead
+ * letter store precisely when the queue was doing its job.
+ */
+function isRetryableStatus(status) {
+    return status >= 500 || status === 429;
+}
 /**
  * Ironflow browser client singleton
  */
@@ -89,6 +111,34 @@ class IronflowClient {
             transport: this.config.transport,
         });
     }
+    /**
+     * Replace the credentials without tearing anything down.
+     *
+     * `configure()` cannot be used for this: it calls `cleanup()`, which destroys
+     * the transport, every subscription, and — for an offline client — the
+     * drainer mid-flight. Refreshing an expired token must not cost you all of
+     * that.
+     *
+     * Every request path reads `config.auth` at send time (`request()`,
+     * `streamRequest()`, `restRequest()` all build their `Authorization` header
+     * per call), so the next request picks this up with no further work. An
+     * already-open subscription keeps the credentials it connected with until it
+     * reconnects.
+     */
+    setAuth(auth) {
+        this.ensureConfigured();
+        this.config.auth = auth;
+        this.logger.debug("Auth updated");
+    }
+    /**
+     * The configured logger.
+     *
+     * @internal Lets sibling modules (the offline queue) honour the app's logging
+     * configuration instead of writing straight to the console.
+     */
+    getLogger() {
+        return this.logger;
+    }
     /**
      * Check if the client is configured
      */
@@ -301,14 +351,6 @@ 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)
      */
@@ -1088,6 +1130,7 @@ class IronflowClient {
         return {
             columns: response.columns ?? [],
             rows: (response.rows ?? []).map((r) => r.values),
+            typedRows: (response.rows ?? []).map((r) => r.typedValues ?? []),
             totalCount: Number(response.totalCount ?? 0),
         };
     }
@@ -1824,47 +1867,113 @@ class IronflowClient {
      * ```
      */
     webhooks = {
-        /** Create a new webhook source */
+        /**
+         * Create a new webhook source.
+         *
+         * The returned `ingestToken` is the ONLY copy (ADR 0048) — the server
+         * keeps a hash, so a source whose token is dropped can never receive a
+         * delivery.
+         */
         create: async (input) => {
             this.ensureConfigured();
-            const response = await this.streamRequest("/ironflow.v1.WebhookService/CreateWebhookSource", {
-                id: input.id,
+            return webhookSourceFromWire(await this.streamRequest("/ironflow.v1.WebhookService/CreateWebhookSource", {
+                name: input.name,
                 event_prefix: input.eventPrefix,
                 verify_header: input.verifyHeader ?? "",
                 verify_algorithm: input.verifyAlgorithm ?? "",
                 verify_secret: input.verifySecret ?? "",
                 verify_config: webhookVerifyConfigToWire(input.verifyConfig),
                 metadata: input.metadata,
-            });
-            return {
-                id: response.id,
-                eventPrefix: response.event_prefix,
-                verifyHeader: response.verify_header,
-                verifyAlgorithm: response.verify_algorithm,
-                sourceType: response.source_type,
-                metadata: response.metadata,
-                // ADR 0048: raw token returned only here; the server keeps a hash.
-                ingestToken: response.ingest_token,
-                ingestTokenPrefix: response.ingest_token_prefix,
-                verifyConfig: webhookVerifyConfigFromWire(response.verify_config),
-                createdAt: response.created_at,
-                updatedAt: response.updated_at,
-            };
+            }));
+        },
+        /** Fetch a single webhook source by ID. */
+        getSource: async (id) => {
+            this.ensureConfigured();
+            return webhookSourceFromWire(await this.streamRequest("/ironflow.v1.WebhookService/GetWebhookSource", { id }));
+        },
+        /**
+         * Replace the editable fields on a webhook source.
+         *
+         * FULL-REPLACE, not patch — every omitted field is cleared server-side.
+         * Fetch with `getSource` first and copy across what you are not changing;
+         * see {@link UpdateWebhookSourceInput}.
+         */
+        updateSource: async (input) => {
+            this.ensureConfigured();
+            return webhookSourceFromWire(await this.streamRequest("/ironflow.v1.WebhookService/UpdateWebhookSource", {
+                id: input.id,
+                name: input.name,
+                verify_header: input.verifyHeader ?? "",
+                verify_algorithm: input.verifyAlgorithm ?? "",
+                verify_config: webhookVerifyConfigToWire(input.verifyConfig),
+                metadata: input.metadata,
+                ...(input.expectedUpdatedAt
+                    ? { expected_updated_at: input.expectedUpdatedAt }
+                    : {}),
+            }));
+        },
+        /**
+         * Rotate a source's verify secret (ADR 0024), keeping the prior secret
+         * verifying as `prev` for the grace window.
+         */
+        rotateSecret: async (input) => {
+            this.ensureConfigured();
+            return webhookSourceFromWire(await this.streamRequest("/ironflow.v1.WebhookService/RotateWebhookSecret", {
+                id: input.id,
+                verify_secret: input.verifySecret,
+                // Tri-state + range-validated; see webhookGraceToWire.
+                ...webhookGraceToWire(input.graceSeconds),
+                ...(input.expectedUpdatedAt
+                    ? { expected_updated_at: input.expectedUpdatedAt }
+                    : {}),
+            }));
+        },
+        /**
+         * Force-expire the previous secret slot, ending a rotation grace window
+         * early. Idempotent.
+         */
+        expireSecretPrev: async (id, expectedUpdatedAt) => {
+            this.ensureConfigured();
+            return webhookSourceFromWire(await this.streamRequest("/ironflow.v1.WebhookService/ExpireWebhookSecretPrev", {
+                id,
+                ...(expectedUpdatedAt ? { expected_updated_at: expectedUpdatedAt } : {}),
+            }));
+        },
+        /**
+         * Stop verifying signatures on a source. The prior secret is preserved as
+         * `prev` for the grace window; after it lapses the source ingests
+         * unsigned.
+         */
+        disableSignatureVerification: async (input) => {
+            this.ensureConfigured();
+            return webhookSourceFromWire(await this.streamRequest("/ironflow.v1.WebhookService/DisableWebhookSignatureVerification", {
+                id: input.id,
+                // Tri-state + range-validated; see webhookGraceToWire.
+                ...webhookGraceToWire(input.graceSeconds),
+                ...(input.expectedUpdatedAt
+                    ? { expected_updated_at: input.expectedUpdatedAt }
+                    : {}),
+            }));
+        },
+        /**
+         * Rotate a source's per-source ingest token (ADR 0048).
+         *
+         * No grace window — the previous token stops working immediately, so
+         * update the provider's URL as soon as this returns. `ingestToken` on the
+         * result is the only copy.
+         */
+        rotateIngestToken: async (id, expectedUpdatedAt) => {
+            this.ensureConfigured();
+            return webhookSourceFromWire(await this.streamRequest("/ironflow.v1.WebhookService/RotateWebhookIngestToken", {
+                id,
+                ...(expectedUpdatedAt ? { expected_updated_at: expectedUpdatedAt } : {}),
+            }));
         },
         /** List all registered webhook sources */
         listSources: async () => {
             this.ensureConfigured();
             const response = await this.streamRequest("/ironflow.v1.WebhookService/ListWebhookSources", { limit: 0, offset: 0 });
-            return (response.sources ?? []).map((s) => ({
-                id: s.id,
-                eventPrefix: s.event_prefix,
-                verifyHeader: s.verify_header,
-                verifyAlgorithm: s.verify_algorithm,
-                sourceType: s.source_type,
-                metadata: s.metadata,
-                createdAt: s.created_at,
-                updatedAt: s.updated_at,
-            }));
+            return (response.sources ?? []).map(webhookSourceFromWire);
         },
         /** Delete a webhook source by ID */
         deleteSource: async (id) => {
@@ -1881,15 +1990,7 @@ class IronflowClient {
                 offset: opts?.offset ?? 0,
             });
             return {
-                deliveries: (response.deliveries ?? []).map((d) => ({
-                    id: d.id,
-                    sourceId: d.source_id,
-                    externalId: d.external_id,
-                    status: d.status,
-                    eventId: d.event_id,
-                    error: d.error,
-                    createdAt: d.created_at,
-                })),
+                deliveries: (response.deliveries ?? []).map(webhookDeliveryFromWire),
                 totalCount: response.total_count ?? 0,
             };
         },
@@ -2009,28 +2110,112 @@ class IronflowClient {
         };
         document.addEventListener("visibilitychange", this.visibilityHandler);
     }
-    async request(schema, method, path, body) {
+    /**
+     * Shared HTTP shell for every REST/Connect call the client makes.
+     *
+     * `send` owns the transport concerns; `handle` owns how one response becomes
+     * a `T`. Splitting there is what lets three callers with very different
+     * response handling share one implementation:
+     *
+     *   caller ──> send(method, path, body, handle)
+     *                │
+     *                ├─ headers: Content-Type (only when a body is sent),
+     *                │           X-Ironflow-Environment,
+     *                │           Authorization (apiKey wins over token)
+     *                ├─ fetch ──> handle(response) ──> T
+     *                │               └─ may throw IronflowError ──┐
+     *                ├─ catch: AbortError -> TIMEOUT              │ rethrown
+     *                │         anything else -> REQUEST_FAILED    │  as-is
+     *                └─ finally: clearTimeout <───────────────────┘
+     *
+     * Two details are load-bearing and must not be "tidied":
+     *
+     * 1. The abort timer is cleared only *after* `handle` returns, so a slow
+     *    parse of a large body can still trip the timeout. That matches the
+     *    behaviour of the three helpers this replaces.
+     * 2. `handle` runs inside the try, so errors it throws pass through the
+     *    catch below. Every typed error in this SDK (`ValidationError`,
+     *    `UnauthenticatedError`, `EnterpriseRequiredError`, `UnauthorizedError`)
+     *    extends `IronflowError`, so the single `instanceof` guard covers all of
+     *    them and they are rethrown untouched.
+     */
+    async send(method, path, body, handle) {
         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 (body !== undefined) {
+                headers["Content-Type"] = "application/json";
+            }
             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, {
+            const fetchOptions = {
                 method,
                 headers,
-                body: JSON.stringify(body),
                 signal: controller.signal,
+            };
+            if (body !== undefined) {
+                fetchOptions.body = JSON.stringify(body);
+            }
+            const response = await fetch(url, fetchOptions);
+            try {
+                return await handle(response);
+            }
+            catch (error) {
+                if (error instanceof IronflowError)
+                    throw error;
+                if (error instanceof Error && error.name === "AbortError")
+                    throw error;
+                // The request itself succeeded; the BODY could not be understood.
+                // Retrying cannot fix a server that returns unparseable bytes, and
+                // marking it retryable would stall the offline queue at this write
+                // indefinitely (it blocks on the head of a strict FIFO).
+                throw new IronflowError(`${method} ${path} returned an unparseable response: ${error instanceof Error ? error.message : String(error)}`, {
+                    code: "RESPONSE_UNPARSEABLE",
+                    status: response.status,
+                    retryable: false,
+                    cause: error instanceof Error ? error : undefined,
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof IronflowError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new IronflowError(`Request timeout after ${timeout}ms for ${method} ${path}`, {
+                    code: "TIMEOUT",
+                    retryable: true,
+                });
+            }
+            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);
+        }
+    }
+    /**
+     * Connect-style request whose response is validated against a zod schema.
+     *
+     * Reads the body exactly once and reuses the text for both the error path
+     * and the success parse.
+     */
+    async request(schema, method, path, body) {
+        return this.send(method, path, body, async (response) => {
             const responseBody = await response.text();
             if (!response.ok) {
                 const errorResult = ErrorResponseSchema.safeParse(safeJsonParse(responseBody));
@@ -2039,7 +2224,8 @@ class IronflowClient {
                     : { message: responseBody };
                 throw new IronflowError(errorData.message ?? `Request failed: ${response.status}`, {
                     code: errorData.code ?? `HTTP_${response.status}`,
-                    retryable: response.status >= 500,
+                    status: response.status,
+                    retryable: isRetryableStatus(response.status),
                 });
             }
             const parsed = safeJsonParse(responseBody);
@@ -2054,78 +2240,61 @@ class IronflowClient {
                 throw new ValidationError(`Invalid response from server: ${issues}`);
             }
             return result.data;
+        });
+    }
+    /**
+     * Replay a write that the offline queue stored earlier (ADR 0053).
+     *
+     * Keyed by a module-private symbol rather than a name. An `@internal` JSDoc
+     * tag does nothing without `stripInternal`, which this repo does not set, so
+     * a named method would ship in the published .d.ts — and this one is an
+     * arbitrary-path authenticated POST, which is not something to hand out.
+     * `index.ts` does not re-export the symbol, so no consumer can reach it.
+     *
+     * Takes the serialised body the queue persisted and routes it through the
+     * ordinary request path, so a replayed write gets exactly the same headers,
+     * timeout and retry classification as a live one — including 429 being
+     * retryable, which the drainer depends on.
+     */
+    async [REPLAY_QUEUED_WRITE](path, body) {
+        this.ensureConfigured();
+        // Parsed here rather than inline in the call, and as a NON-retryable coded
+        // error: a bare SyntaxError is not an IronflowError, and the drainer treats
+        // anything else as a network fault worth retrying. Since the queue is strict
+        // FIFO, an unreadable record at the head would then block every write behind
+        // it until retention expired. Dead-lettering quarantines just the one.
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
         }
         catch (error) {
-            if (error instanceof IronflowError || error instanceof ValidationError) {
-                throw error;
-            }
-            if (error instanceof Error && error.name === "AbortError") {
-                throw new IronflowError(`Request timeout after ${timeout}ms for ${method} ${path}`, {
-                    code: "TIMEOUT",
-                    retryable: true,
-                });
-            }
-            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);
+            throw new IronflowError(`Queued write body is not valid JSON and can never be sent: ${error instanceof Error ? error.message : String(error)}`, { code: "QUEUE_BODY_CORRUPT", retryable: false });
         }
+        const response = await this.streamRequest(path, parsed);
+        return {
+            eventId: response.eventId,
+            entityVersion: response.entityVersion === undefined
+                ? undefined
+                : Number(response.entityVersion),
+        };
     }
+    /**
+     * Connect-style POST returning the raw decoded JSON, no schema validation.
+     *
+     * Only reads the body on the error path.
+     */
     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,
-            });
+        return this.send("POST", path, body, async (response) => {
             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,
+                    status: response.status,
+                    retryable: isRetryableStatus(response.status),
                 });
             }
             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,
-            });
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
+        });
     }
     /**
      * REST request helper for auth management endpoints.
@@ -2134,34 +2303,13 @@ class IronflowClient {
      * - 401 → UnauthenticatedError
      * - 402 → EnterpriseRequiredError
      * - 403 → UnauthorizedError
+     *
+     * Note the error message template differs from the two Connect helpers
+     * above ("Request failed with status N" vs "Request failed: N"); both are
+     * pinned by tests, so pick deliberately if you ever unify them.
      */
     async restRequest(method, 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 = {
-                [HEADERS.ENVIRONMENT]: this.config.environment,
-            };
-            if (body !== undefined) {
-                headers["Content-Type"] = "application/json";
-            }
-            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 fetchOptions = {
-                method,
-                headers,
-                signal: controller.signal,
-            };
-            if (body !== undefined) {
-                fetchOptions.body = JSON.stringify(body);
-            }
-            const response = await fetch(url, fetchOptions);
+        return this.send(method, path, body, async (response) => {
             // Handle 204 No Content
             if (response.status === 204) {
                 return undefined;
@@ -2188,33 +2336,13 @@ class IronflowClient {
                     default:
                         throw new IronflowError(errorMessage, {
                             code: `HTTP_${response.status}`,
-                            retryable: response.status >= 500,
+                            status: response.status,
+                            retryable: isRetryableStatus(response.status),
                         });
                 }
             }
             return response.json();
-        }
-        catch (error) {
-            if (error instanceof IronflowError ||
-                error instanceof UnauthenticatedError ||
-                error instanceof EnterpriseRequiredError ||
-                error instanceof UnauthorizedError) {
-                throw error;
-            }
-            if (error instanceof Error && error.name === "AbortError") {
-                throw new IronflowError(`Request timeout after ${timeout}ms for ${method} ${path}`, { code: "TIMEOUT", retryable: true });
-            }
-            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);
-        }
+        });
     }
     mapRunResponse(response) {
         // ConnectRPC returns proto enum strings like "RUN_STATUS_COMPLETED" — normalize to "completed"