@ironflow/browser 0.26.0 → 0.28.0

package/dist/client.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 0052), 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)
      */
@@ -2009,28 +2051,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 +2165,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 +2181,61 @@ class IronflowClient {
                 throw new ValidationError(`Invalid response from server: ${issues}`);
             }
             return result.data;
+        });
+    }
+    /**
+     * Replay a write that the offline queue stored earlier (ADR 0052).
+     *
+     * 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 +2244,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 +2277,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"