@reliantlabs/forge-web-runtime 0.6.0 → 0.8.0

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import { Code } from "@connectrpc/connect";
+import { Code, ConnectError } from "@connectrpc/connect";
 /**
  * FORGE_ERROR_REASON_HEADER is the Connect trailer/metadata key carrying a
  * stable, machine-readable reason code (snake_case) the backend sets for
@@ -33,15 +33,42 @@ export declare function stripServerFraming(message: string): string;
  */
 export declare function userMessage(err: unknown, fallback?: string): string;
 /**
- * ConnectClientError is the single typed error shape the app catches. It is
- * a plain Error subclass so it works with React Query, error boundaries, and
- * `instanceof` alike.
+ * codeName — the canonical wire name of a Connect code: `Code.NotFound` →
+ * "not_found", `Code.DeadlineExceeded` → "deadline_exceeded". The spelling
+ * the Connect protocol puts on the wire and in the "[code] " message prefix.
+ *
+ * (An earlier version lower-cased the enum key, which produced "notfound" —
+ * a name that matches nothing the server or the docs spell.)
+ */
+export declare function codeName(code: Code): string;
+/** Detail types a ConnectError carries; spelled off the base class's field. */
+type ConnectErrorDetails = ConnectError["details"];
+/**
+ * ConnectClientError is the single typed error shape the app catches.
+ *
+ * It IS a ConnectError — a subclass — so the error the runtime's
+ * errorNormalizeInterceptor throws still satisfies every consumer written
+ * against connect-es: `err instanceof ConnectError` holds, `err.code` is the
+ * numeric `Code`, and `metadata`, `details`, `findDetails()` and `rawMessage`
+ * are the original error's. What it adds is the normalized view: `codeName`,
+ * `status`, `retryable`, `reason` and `traceId`. An app that already branches
+ * on ConnectError can therefore adopt the runtime chain one call site at a
+ * time; nothing downgrades to `Code.Unknown` because a catch block met a type
+ * it did not expect.
+ *
+ * `name` stays "ConnectError". That is load-bearing: connect-es's
+ * `ConnectError[Symbol.hasInstance]` accepts an object whose prototype is
+ * exactly `ConnectError.prototype`, or one NAMED "ConnectError" with the
+ * right fields — a subclass instance is the second case, so any other name
+ * fails `instanceof ConnectError`.
+ *
+ * `message` is the server's text WITHOUT the "[code] " framing (the same as
+ * `rawMessage`), so it is presentable at every layer; connect-es's own
+ * `message` carries the prefix. Render with {@link userMessage} regardless.
  */
-export declare class ConnectClientError extends Error {
+export declare class ConnectClientError extends ConnectError {
     /** Canonical Connect code name, e.g. "unavailable", "not_found". */
-    readonly code: string;
-    /** Numeric Connect code (Code enum), or undefined for non-Connect errors. */
-    readonly connectCode?: Code;
+    readonly codeName: string;
     /** Approximate HTTP status, for telemetry and generic UI. */
     readonly status: number;
     /** True when a transparent retry is reasonable (transient failures). */
@@ -60,12 +87,18 @@ export declare class ConnectClientError extends Error {
      * key to every server span and log line of that request.
      */
     readonly traceId: string | null;
+    /**
+     * `status` and `retryable` default from `code`; `reason` defaults to the
+     * x-forge-error-reason entry in `metadata`.
+     */
     constructor(args: {
+        /** The server's message, without "[code] " framing. */
         message: string;
-        code: string;
-        connectCode?: Code;
-        status: number;
-        retryable: boolean;
+        code: Code;
+        metadata?: HeadersInit;
+        details?: ConnectErrorDetails;
+        status?: number;
+        retryable?: boolean;
         reason?: string | null;
         traceId?: string | null;
         cause?: unknown;
@@ -76,11 +109,8 @@ export declare class ConnectClientError extends Error {
      * working when two copies of this package end up in one bundle (see
      * {@link isConnectClientErrorShape}). Without it, normalizeError's
      * pass-through guard misses an already-normalized error from the other
-     * copy; that error's `name` is "ConnectClientError" rather than
-     * "ConnectError", so it misses the ConnectError branch too and is re-wrapped
-     * through the generic Error branch — silently downgrading every error in the
-     * app to code "unknown", status 500, no connectCode and no reason.
-     * @connectrpc/connect does the same on ConnectError, for the same reason.
+     * copy and re-wraps it as a fresh error. @connectrpc/connect does the same
+     * on ConnectError, for the same reason.
      */
     static [Symbol.hasInstance](v: unknown): boolean;
 }
@@ -95,6 +125,8 @@ export declare function isRetryableCode(code: Code): boolean;
  * Both `instanceof` checks below match on SHAPE rather than class identity —
  * ours via ConnectClientError's Symbol.hasInstance, ConnectError's via the one
  * @connectrpc/connect ships — so neither branch is missed when a second copy
- * of either package lands in the bundle.
+ * of either package lands in the bundle. The ConnectClientError check comes
+ * first because every ConnectClientError is also a ConnectError.
  */
 export declare function normalizeError(err: unknown, requestTraceId?: string | null): ConnectClientError;
+export {};

package/dist/errors.js

@@ -3,8 +3,9 @@
 // Typed client errors. Connect surfaces failures as ConnectError with a
 // numeric Code; the rest of the app should reason about a stable, typed
 // shape instead of sniffing status codes at every call site. normalizeError
-// maps any thrown value into a ConnectClientError carrying the canonical
-// code name, an HTTP-ish status, a retryability verdict, and a
+// maps any thrown value into a ConnectClientError — a ConnectError subclass,
+// so connect-es consumers keep working — carrying the canonical code name,
+// an HTTP-ish status, a retryability verdict, the backend's reason, and a
 // human-presentable message.
 import { Code, ConnectError } from "@connectrpc/connect";
 import { TRACERESPONSE_HEADER, traceIdFrom } from "./trace.js";
@@ -73,6 +74,20 @@ const HTTP_STATUS = {
     [Code.DeadlineExceeded]: 504,
     [Code.Internal]: 500,
 };
+/**
+ * codeName — the canonical wire name of a Connect code: `Code.NotFound` →
+ * "not_found", `Code.DeadlineExceeded` → "deadline_exceeded". The spelling
+ * the Connect protocol puts on the wire and in the "[code] " message prefix.
+ *
+ * (An earlier version lower-cased the enum key, which produced "notfound" —
+ * a name that matches nothing the server or the docs spell.)
+ */
+export function codeName(code) {
+    const key = Code[code];
+    if (typeof key !== "string")
+        return "unknown";
+    return key.replace(/[A-Z]/g, (c, i) => (i === 0 ? "" : "_") + c.toLowerCase());
+}
 /**
  * isConnectClientErrorShape — the STRUCTURAL test behind
  * {@link ConnectClientError}'s `instanceof`.
@@ -83,6 +98,10 @@ const HTTP_STATUS = {
  * package holds two distinct ConnectClientError classes. Matching on shape
  * instead of identity is what makes the two agree: the shape is the
  * contract, the constructor is not.
+ *
+ * The shape is a ConnectError's (numeric `code`, `metadata`, `rawMessage`)
+ * plus the fields this class adds; `name` is "ConnectError" for the reason
+ * given on the class.
  */
 function isConnectClientErrorShape(v) {
     if (!(v instanceof Error))
@@ -90,22 +109,40 @@ function isConnectClientErrorShape(v) {
     if (Object.getPrototypeOf(v) === ConnectClientError.prototype)
         return true;
     const e = v;
-    return (v.name === "ConnectClientError" &&
-        typeof e.code === "string" &&
+    return (v.name === "ConnectError" &&
+        typeof e.code === "number" &&
+        typeof e.codeName === "string" &&
+        typeof e.rawMessage === "string" &&
         typeof e.status === "number" &&
         typeof e.retryable === "boolean" &&
         (typeof e.reason === "string" || e.reason === null));
 }
 /**
- * ConnectClientError is the single typed error shape the app catches. It is
- * a plain Error subclass so it works with React Query, error boundaries, and
- * `instanceof` alike.
+ * ConnectClientError is the single typed error shape the app catches.
+ *
+ * It IS a ConnectError — a subclass — so the error the runtime's
+ * errorNormalizeInterceptor throws still satisfies every consumer written
+ * against connect-es: `err instanceof ConnectError` holds, `err.code` is the
+ * numeric `Code`, and `metadata`, `details`, `findDetails()` and `rawMessage`
+ * are the original error's. What it adds is the normalized view: `codeName`,
+ * `status`, `retryable`, `reason` and `traceId`. An app that already branches
+ * on ConnectError can therefore adopt the runtime chain one call site at a
+ * time; nothing downgrades to `Code.Unknown` because a catch block met a type
+ * it did not expect.
+ *
+ * `name` stays "ConnectError". That is load-bearing: connect-es's
+ * `ConnectError[Symbol.hasInstance]` accepts an object whose prototype is
+ * exactly `ConnectError.prototype`, or one NAMED "ConnectError" with the
+ * right fields — a subclass instance is the second case, so any other name
+ * fails `instanceof ConnectError`.
+ *
+ * `message` is the server's text WITHOUT the "[code] " framing (the same as
+ * `rawMessage`), so it is presentable at every layer; connect-es's own
+ * `message` carries the prefix. Render with {@link userMessage} regardless.
  */
-export class ConnectClientError extends Error {
+export class ConnectClientError extends ConnectError {
     /** Canonical Connect code name, e.g. "unavailable", "not_found". */
-    code;
-    /** Numeric Connect code (Code enum), or undefined for non-Connect errors. */
-    connectCode;
+    codeName;
     /** Approximate HTTP status, for telemetry and generic UI. */
     status;
     /** True when a transparent retry is reasonable (transient failures). */
@@ -124,14 +161,25 @@ export class ConnectClientError extends Error {
      * key to every server span and log line of that request.
      */
     traceId;
+    /**
+     * `status` and `retryable` default from `code`; `reason` defaults to the
+     * x-forge-error-reason entry in `metadata`.
+     */
     constructor(args) {
-        super(args.message, { cause: args.cause });
-        this.name = "ConnectClientError";
-        this.code = args.code;
-        this.connectCode = args.connectCode;
-        this.status = args.status;
-        this.retryable = args.retryable;
-        this.reason = args.reason ?? null;
+        super(args.message, args.code, args.metadata, undefined, args.cause);
+        // ConnectError's constructor takes only OUTGOING details (a server's);
+        // a client error carries the INCOMING ones it received, so they are
+        // assigned rather than passed. Its name, "ConnectError", is kept (above).
+        if (args.details)
+            this.details = args.details;
+        this.message = args.message;
+        this.codeName = codeName(args.code);
+        this.status = args.status ?? HTTP_STATUS[args.code] ?? 500;
+        this.retryable = args.retryable ?? isRetryableCode(args.code);
+        this.reason =
+            args.reason !== undefined
+                ? args.reason
+                : this.metadata.get(FORGE_ERROR_REASON_HEADER) || null;
         this.traceId = args.traceId ?? null;
     }
     /**
@@ -140,11 +188,8 @@ export class ConnectClientError extends Error {
      * working when two copies of this package end up in one bundle (see
      * {@link isConnectClientErrorShape}). Without it, normalizeError's
      * pass-through guard misses an already-normalized error from the other
-     * copy; that error's `name` is "ConnectClientError" rather than
-     * "ConnectError", so it misses the ConnectError branch too and is re-wrapped
-     * through the generic Error branch — silently downgrading every error in the
-     * app to code "unknown", status 500, no connectCode and no reason.
-     * @connectrpc/connect does the same on ConnectError, for the same reason.
+     * copy and re-wraps it as a fresh error. @connectrpc/connect does the same
+     * on ConnectError, for the same reason.
      */
     static [Symbol.hasInstance](v) {
         return isConnectClientErrorShape(v);
@@ -163,7 +208,8 @@ export function isRetryableCode(code) {
  * Both `instanceof` checks below match on SHAPE rather than class identity —
  * ours via ConnectClientError's Symbol.hasInstance, ConnectError's via the one
  * @connectrpc/connect ships — so neither branch is missed when a second copy
- * of either package lands in the bundle.
+ * of either package lands in the bundle. The ConnectClientError check comes
+ * first because every ConnectClientError is also a ConnectError.
  */
 export function normalizeError(err, requestTraceId = null) {
     if (err instanceof ConnectClientError) {
@@ -174,12 +220,12 @@ export function normalizeError(err, requestTraceId = null) {
             // Strip the "[code] " prefix so the message is user-presentable at
             // every layer.
             message: stripServerFraming(err.rawMessage || err.message),
-            code: Code[err.code]?.toLowerCase() ?? "unknown",
-            connectCode: err.code,
-            status: HTTP_STATUS[err.code] ?? 500,
-            retryable: isRetryableCode(err.code),
-            // Stable machine reason from backend metadata (backend owns the set).
-            reason: err.metadata.get(FORGE_ERROR_REASON_HEADER) || null,
+            code: err.code,
+            // The original metadata and details ride along, so `findDetails()` and
+            // `metadata.get(...)` answer exactly as they did on the raw error. The
+            // reason (backend-owned) is read from that metadata by the constructor.
+            metadata: err.metadata,
+            details: err.details,
             // The server's own span when it answered; the trace this runtime asked
             // for when it did not (a proxy error, an older server).
             traceId: traceIdFrom(err.metadata.get(TRACERESPONSE_HEADER)) ?? requestTraceId,
@@ -187,6 +233,16 @@ export function normalizeError(err, requestTraceId = null) {
         });
     }
     if (err instanceof Error) {
+        // An aborted or timed-out fetch is a cancellation, as ConnectError.from
+        // reads it.
+        if (err.name === "AbortError" || err.name === "TimeoutError") {
+            return new ConnectClientError({
+                message: stripServerFraming(err.message),
+                code: Code.Canceled,
+                traceId: requestTraceId,
+                cause: err,
+            });
+        }
         // A network fault (fetch rejected: offline, DNS, CORS preflight, TLS)
         // surfaces as a TypeError — that, and only that, is a safe transparent
         // retry. A generic Error is NOT blanket-retried (blanket-retrying every
@@ -194,7 +250,7 @@ export function normalizeError(err, requestTraceId = null) {
         const networkFault = err instanceof TypeError;
         return new ConnectClientError({
             message: stripServerFraming(err.message),
-            code: networkFault ? "unavailable" : "unknown",
+            code: networkFault ? Code.Unavailable : Code.Unknown,
             status: networkFault ? 503 : 500,
             retryable: networkFault,
             reason: null,
@@ -204,7 +260,7 @@ export function normalizeError(err, requestTraceId = null) {
     }
     return new ConnectClientError({
         message: typeof err === "string" ? stripServerFraming(err) : "Unknown error",
-        code: "unknown",
+        code: Code.Unknown,
         status: 500,
         retryable: false,
         reason: null,

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Typed client errors. Connect surfaces failures as ConnectError with a\n// numeric Code; the rest of the app should reason about a stable, typed\n// shape instead of sniffing status codes at every call site. normalizeError\n// maps any thrown value into a ConnectClientError carrying the canonical\n// code name, an HTTP-ish status, a retryability verdict, and a\n// human-presentable message.\nimport { Code, ConnectError } from \"@connectrpc/connect\";\n\nimport { TRACERESPONSE_HEADER, traceIdFrom } from \"./trace.js\";\n\n/**\n * FORGE_ERROR_REASON_HEADER is the Connect trailer/metadata key carrying a\n * stable, machine-readable reason code (snake_case) the backend sets for\n * every error. UI/routing keys off `error.reason` instead of matching\n * human-readable message strings — the message text is display-only and\n * may change. The backend owns the setter; the frontend only reads it.\n */\nexport const FORGE_ERROR_REASON_HEADER = \"x-forge-error-reason\";\n\n/**\n * stripServerFraming removes the transport framing that must never surface\n * to a user: the leading \"[code] \" gRPC-code prefix connect-es puts on\n * `ConnectError.message`. What survives is the message the server wrote,\n * which is exactly what a user should read.\n *\n * This is the SINGLE implementation — a project never wants a different\n * answer here, and a copy frozen into a scaffold could never be corrected\n * once shipped. Idempotent: framing that has already been stripped strips\n * to itself.\n */\nexport function stripServerFraming(message: string): string {\n  return message.replace(/^\\[[a-z_]+\\]\\s*/i, \"\").trim();\n}\n\n/** The copy shown when an error carries no presentable message of its own. */\nconst DEFAULT_USER_MESSAGE = \"Something went wrong. Please try again.\";\n\n/**\n * userMessage — turn any thrown value into copy fit for end users.\n *\n * `ConnectError.message` prefixes the gRPC code (\"[not_found] no such task\");\n * `rawMessage` is the server's human-readable text without that framing, and\n * stripServerFraming drops the prefix from whichever of the two is available.\n * Use this everywhere an error is SHOWN (banners, toasts) instead of\n * `err.message`.\n *\n * Pass `fallback` to override the default copy for a surface that wants its\n * own wording.\n */\nexport function userMessage(\n  err: unknown,\n  fallback: string = DEFAULT_USER_MESSAGE,\n): string {\n  if (err instanceof ConnectError) {\n    return stripServerFraming(err.rawMessage || err.message) || fallback;\n  }\n  if (err instanceof Error) {\n    return stripServerFraming(err.message) || fallback;\n  }\n  return err == null ? fallback : stripServerFraming(String(err)) || fallback;\n}\n\n/** Connect codes worth a transparent transport-level retry. */\nconst RETRYABLE = new Set<Code>([\n  Code.Unavailable,\n  Code.DeadlineExceeded,\n  Code.Aborted,\n  Code.ResourceExhausted,\n]);\n\n/** Rough Connect-code → HTTP-status mapping for display/telemetry only. */\nconst HTTP_STATUS: Partial<Record<Code, number>> = {\n  [Code.InvalidArgument]: 400,\n  [Code.Unauthenticated]: 401,\n  [Code.PermissionDenied]: 403,\n  [Code.NotFound]: 404,\n  [Code.AlreadyExists]: 409,\n  [Code.ResourceExhausted]: 429,\n  [Code.Unimplemented]: 501,\n  [Code.Unavailable]: 503,\n  [Code.DeadlineExceeded]: 504,\n  [Code.Internal]: 500,\n};\n\n/**\n * isConnectClientErrorShape — the STRUCTURAL test behind\n * {@link ConnectClientError}'s `instanceof`.\n *\n * A class object is per module instance, not per package. npm nests a\n * transitive dependency on any version conflict, and a bundler can pull one\n * package in as both ESM and CJS, so a tree holding two copies of this\n * package holds two distinct ConnectClientError classes. Matching on shape\n * instead of identity is what makes the two agree: the shape is the\n * contract, the constructor is not.\n */\nfunction isConnectClientErrorShape(v: unknown): v is ConnectClientError {\n  if (!(v instanceof Error)) return false;\n  if (Object.getPrototypeOf(v) === ConnectClientError.prototype) return true;\n  const e = v as Partial<ConnectClientError>;\n  return (\n    v.name === \"ConnectClientError\" &&\n    typeof e.code === \"string\" &&\n    typeof e.status === \"number\" &&\n    typeof e.retryable === \"boolean\" &&\n    (typeof e.reason === \"string\" || e.reason === null)\n  );\n}\n\n/**\n * ConnectClientError is the single typed error shape the app catches. It is\n * a plain Error subclass so it works with React Query, error boundaries, and\n * `instanceof` alike.\n */\nexport class ConnectClientError extends Error {\n  /** Canonical Connect code name, e.g. \"unavailable\", \"not_found\". */\n  readonly code: string;\n  /** Numeric Connect code (Code enum), or undefined for non-Connect errors. */\n  readonly connectCode?: Code;\n  /** Approximate HTTP status, for telemetry and generic UI. */\n  readonly status: number;\n  /** True when a transparent retry is reasonable (transient failures). */\n  readonly retryable: boolean;\n  /**\n   * Stable machine-readable reason code from the backend\n   * (x-forge-error-reason metadata), or null. Key UI/routing off THIS,\n   * never off `message` — message text is display-only.\n   */\n  readonly reason: string | null;\n  /**\n   * The trace the failed request was recorded in: the server's\n   * `traceresponse` when it sent one, else the trace id of the traceparent\n   * this runtime sent, else null (the request never left the browser). Put it\n   * in a bug report, a toast's \"copy details\", or a support ticket — it is the\n   * key to every server span and log line of that request.\n   */\n  readonly traceId: string | null;\n\n  constructor(args: {\n    message: string;\n    code: string;\n    connectCode?: Code;\n    status: number;\n    retryable: boolean;\n    reason?: string | null;\n    traceId?: string | null;\n    cause?: unknown;\n  }) {\n    super(args.message, { cause: args.cause });\n    this.name = \"ConnectClientError\";\n    this.code = args.code;\n    this.connectCode = args.connectCode;\n    this.status = args.status;\n    this.retryable = args.retryable;\n    this.reason = args.reason ?? null;\n    this.traceId = args.traceId ?? null;\n  }\n\n  /**\n   * `instanceof` matches on SHAPE, not on class identity — so every check\n   * spelled `err instanceof ConnectClientError`, here and in app code, keeps\n   * working when two copies of this package end up in one bundle (see\n   * {@link isConnectClientErrorShape}). Without it, normalizeError's\n   * pass-through guard misses an already-normalized error from the other\n   * copy; that error's `name` is \"ConnectClientError\" rather than\n   * \"ConnectError\", so it misses the ConnectError branch too and is re-wrapped\n   * through the generic Error branch — silently downgrading every error in the\n   * app to code \"unknown\", status 500, no connectCode and no reason.\n   * @connectrpc/connect does the same on ConnectError, for the same reason.\n   */\n  static [Symbol.hasInstance](v: unknown): boolean {\n    return isConnectClientErrorShape(v);\n  }\n}\n\n/** isRetryable reports whether a Connect code merits a transport retry. */\nexport function isRetryableCode(code: Code): boolean {\n  return RETRYABLE.has(code);\n}\n\n/**\n * normalizeError coerces any thrown value into a ConnectClientError. Already-\n * normalized errors pass through unchanged so the interceptor chain never\n * double-wraps. `requestTraceId` is the trace id of the traceparent the\n * request carried, used when the server sent no `traceresponse`.\n *\n * Both `instanceof` checks below match on SHAPE rather than class identity —\n * ours via ConnectClientError's Symbol.hasInstance, ConnectError's via the one\n * @connectrpc/connect ships — so neither branch is missed when a second copy\n * of either package lands in the bundle.\n */\nexport function normalizeError(\n  err: unknown,\n  requestTraceId: string | null = null,\n): ConnectClientError {\n  if (err instanceof ConnectClientError) {\n    return err;\n  }\n\n  if (err instanceof ConnectError) {\n    return new ConnectClientError({\n      // Strip the \"[code] \" prefix so the message is user-presentable at\n      // every layer.\n      message: stripServerFraming(err.rawMessage || err.message),\n      code: Code[err.code]?.toLowerCase() ?? \"unknown\",\n      connectCode: err.code,\n      status: HTTP_STATUS[err.code] ?? 500,\n      retryable: isRetryableCode(err.code),\n      // Stable machine reason from backend metadata (backend owns the set).\n      reason: err.metadata.get(FORGE_ERROR_REASON_HEADER) || null,\n      // The server's own span when it answered; the trace this runtime asked\n      // for when it did not (a proxy error, an older server).\n      traceId:\n        traceIdFrom(err.metadata.get(TRACERESPONSE_HEADER)) ?? requestTraceId,\n      cause: err,\n    });\n  }\n\n  if (err instanceof Error) {\n    // A network fault (fetch rejected: offline, DNS, CORS preflight, TLS)\n    // surfaces as a TypeError — that, and only that, is a safe transparent\n    // retry. A generic Error is NOT blanket-retried (blanket-retrying every\n    // bare Error widened the blast radius to non-idempotent failures).\n    const networkFault = err instanceof TypeError;\n    return new ConnectClientError({\n      message: stripServerFraming(err.message),\n      code: networkFault ? \"unavailable\" : \"unknown\",\n      status: networkFault ? 503 : 500,\n      retryable: networkFault,\n      reason: null,\n      traceId: requestTraceId,\n      cause: err,\n    });\n  }\n\n  return new ConnectClientError({\n    message:\n      typeof err === \"string\" ? stripServerFraming(err) : \"Unknown error\",\n    code: \"unknown\",\n    status: 500,\n    retryable: false,\n    reason: null,\n    cause: err,\n  });\n}\n"]}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Typed client errors. Connect surfaces failures as ConnectError with a\n// numeric Code; the rest of the app should reason about a stable, typed\n// shape instead of sniffing status codes at every call site. normalizeError\n// maps any thrown value into a ConnectClientError — a ConnectError subclass,\n// so connect-es consumers keep working — carrying the canonical code name,\n// an HTTP-ish status, a retryability verdict, the backend's reason, and a\n// human-presentable message.\nimport { Code, ConnectError } from \"@connectrpc/connect\";\n\nimport { TRACERESPONSE_HEADER, traceIdFrom } from \"./trace.js\";\n\n/**\n * FORGE_ERROR_REASON_HEADER is the Connect trailer/metadata key carrying a\n * stable, machine-readable reason code (snake_case) the backend sets for\n * every error. UI/routing keys off `error.reason` instead of matching\n * human-readable message strings — the message text is display-only and\n * may change. The backend owns the setter; the frontend only reads it.\n */\nexport const FORGE_ERROR_REASON_HEADER = \"x-forge-error-reason\";\n\n/**\n * stripServerFraming removes the transport framing that must never surface\n * to a user: the leading \"[code] \" gRPC-code prefix connect-es puts on\n * `ConnectError.message`. What survives is the message the server wrote,\n * which is exactly what a user should read.\n *\n * This is the SINGLE implementation — a project never wants a different\n * answer here, and a copy frozen into a scaffold could never be corrected\n * once shipped. Idempotent: framing that has already been stripped strips\n * to itself.\n */\nexport function stripServerFraming(message: string): string {\n  return message.replace(/^\\[[a-z_]+\\]\\s*/i, \"\").trim();\n}\n\n/** The copy shown when an error carries no presentable message of its own. */\nconst DEFAULT_USER_MESSAGE = \"Something went wrong. Please try again.\";\n\n/**\n * userMessage — turn any thrown value into copy fit for end users.\n *\n * `ConnectError.message` prefixes the gRPC code (\"[not_found] no such task\");\n * `rawMessage` is the server's human-readable text without that framing, and\n * stripServerFraming drops the prefix from whichever of the two is available.\n * Use this everywhere an error is SHOWN (banners, toasts) instead of\n * `err.message`.\n *\n * Pass `fallback` to override the default copy for a surface that wants its\n * own wording.\n */\nexport function userMessage(\n  err: unknown,\n  fallback: string = DEFAULT_USER_MESSAGE,\n): string {\n  if (err instanceof ConnectError) {\n    return stripServerFraming(err.rawMessage || err.message) || fallback;\n  }\n  if (err instanceof Error) {\n    return stripServerFraming(err.message) || fallback;\n  }\n  return err == null ? fallback : stripServerFraming(String(err)) || fallback;\n}\n\n/** Connect codes worth a transparent transport-level retry. */\nconst RETRYABLE = new Set<Code>([\n  Code.Unavailable,\n  Code.DeadlineExceeded,\n  Code.Aborted,\n  Code.ResourceExhausted,\n]);\n\n/** Rough Connect-code → HTTP-status mapping for display/telemetry only. */\nconst HTTP_STATUS: Partial<Record<Code, number>> = {\n  [Code.InvalidArgument]: 400,\n  [Code.Unauthenticated]: 401,\n  [Code.PermissionDenied]: 403,\n  [Code.NotFound]: 404,\n  [Code.AlreadyExists]: 409,\n  [Code.ResourceExhausted]: 429,\n  [Code.Unimplemented]: 501,\n  [Code.Unavailable]: 503,\n  [Code.DeadlineExceeded]: 504,\n  [Code.Internal]: 500,\n};\n\n/**\n * codeName — the canonical wire name of a Connect code: `Code.NotFound` →\n * \"not_found\", `Code.DeadlineExceeded` → \"deadline_exceeded\". The spelling\n * the Connect protocol puts on the wire and in the \"[code] \" message prefix.\n *\n * (An earlier version lower-cased the enum key, which produced \"notfound\" —\n * a name that matches nothing the server or the docs spell.)\n */\nexport function codeName(code: Code): string {\n  const key = Code[code];\n  if (typeof key !== \"string\") return \"unknown\";\n  return key.replace(\n    /[A-Z]/g,\n    (c, i: number) => (i === 0 ? \"\" : \"_\") + c.toLowerCase(),\n  );\n}\n\n/**\n * isConnectClientErrorShape — the STRUCTURAL test behind\n * {@link ConnectClientError}'s `instanceof`.\n *\n * A class object is per module instance, not per package. npm nests a\n * transitive dependency on any version conflict, and a bundler can pull one\n * package in as both ESM and CJS, so a tree holding two copies of this\n * package holds two distinct ConnectClientError classes. Matching on shape\n * instead of identity is what makes the two agree: the shape is the\n * contract, the constructor is not.\n *\n * The shape is a ConnectError's (numeric `code`, `metadata`, `rawMessage`)\n * plus the fields this class adds; `name` is \"ConnectError\" for the reason\n * given on the class.\n */\nfunction isConnectClientErrorShape(v: unknown): v is ConnectClientError {\n  if (!(v instanceof Error)) return false;\n  if (Object.getPrototypeOf(v) === ConnectClientError.prototype) return true;\n  const e = v as Partial<ConnectClientError>;\n  return (\n    v.name === \"ConnectError\" &&\n    typeof e.code === \"number\" &&\n    typeof e.codeName === \"string\" &&\n    typeof e.rawMessage === \"string\" &&\n    typeof e.status === \"number\" &&\n    typeof e.retryable === \"boolean\" &&\n    (typeof e.reason === \"string\" || e.reason === null)\n  );\n}\n\n/** Detail types a ConnectError carries; spelled off the base class's field. */\ntype ConnectErrorDetails = ConnectError[\"details\"];\n\n/**\n * ConnectClientError is the single typed error shape the app catches.\n *\n * It IS a ConnectError — a subclass — so the error the runtime's\n * errorNormalizeInterceptor throws still satisfies every consumer written\n * against connect-es: `err instanceof ConnectError` holds, `err.code` is the\n * numeric `Code`, and `metadata`, `details`, `findDetails()` and `rawMessage`\n * are the original error's. What it adds is the normalized view: `codeName`,\n * `status`, `retryable`, `reason` and `traceId`. An app that already branches\n * on ConnectError can therefore adopt the runtime chain one call site at a\n * time; nothing downgrades to `Code.Unknown` because a catch block met a type\n * it did not expect.\n *\n * `name` stays \"ConnectError\". That is load-bearing: connect-es's\n * `ConnectError[Symbol.hasInstance]` accepts an object whose prototype is\n * exactly `ConnectError.prototype`, or one NAMED \"ConnectError\" with the\n * right fields — a subclass instance is the second case, so any other name\n * fails `instanceof ConnectError`.\n *\n * `message` is the server's text WITHOUT the \"[code] \" framing (the same as\n * `rawMessage`), so it is presentable at every layer; connect-es's own\n * `message` carries the prefix. Render with {@link userMessage} regardless.\n */\nexport class ConnectClientError extends ConnectError {\n  /** Canonical Connect code name, e.g. \"unavailable\", \"not_found\". */\n  readonly codeName: string;\n  /** Approximate HTTP status, for telemetry and generic UI. */\n  readonly status: number;\n  /** True when a transparent retry is reasonable (transient failures). */\n  readonly retryable: boolean;\n  /**\n   * Stable machine-readable reason code from the backend\n   * (x-forge-error-reason metadata), or null. Key UI/routing off THIS,\n   * never off `message` — message text is display-only.\n   */\n  readonly reason: string | null;\n  /**\n   * The trace the failed request was recorded in: the server's\n   * `traceresponse` when it sent one, else the trace id of the traceparent\n   * this runtime sent, else null (the request never left the browser). Put it\n   * in a bug report, a toast's \"copy details\", or a support ticket — it is the\n   * key to every server span and log line of that request.\n   */\n  readonly traceId: string | null;\n\n  /**\n   * `status` and `retryable` default from `code`; `reason` defaults to the\n   * x-forge-error-reason entry in `metadata`.\n   */\n  constructor(args: {\n    /** The server's message, without \"[code] \" framing. */\n    message: string;\n    code: Code;\n    metadata?: HeadersInit;\n    details?: ConnectErrorDetails;\n    status?: number;\n    retryable?: boolean;\n    reason?: string | null;\n    traceId?: string | null;\n    cause?: unknown;\n  }) {\n    super(args.message, args.code, args.metadata, undefined, args.cause);\n    // ConnectError's constructor takes only OUTGOING details (a server's);\n    // a client error carries the INCOMING ones it received, so they are\n    // assigned rather than passed. Its name, \"ConnectError\", is kept (above).\n    if (args.details) this.details = args.details;\n    this.message = args.message;\n    this.codeName = codeName(args.code);\n    this.status = args.status ?? HTTP_STATUS[args.code] ?? 500;\n    this.retryable = args.retryable ?? isRetryableCode(args.code);\n    this.reason =\n      args.reason !== undefined\n        ? args.reason\n        : this.metadata.get(FORGE_ERROR_REASON_HEADER) || null;\n    this.traceId = args.traceId ?? null;\n  }\n\n  /**\n   * `instanceof` matches on SHAPE, not on class identity — so every check\n   * spelled `err instanceof ConnectClientError`, here and in app code, keeps\n   * working when two copies of this package end up in one bundle (see\n   * {@link isConnectClientErrorShape}). Without it, normalizeError's\n   * pass-through guard misses an already-normalized error from the other\n   * copy and re-wraps it as a fresh error. @connectrpc/connect does the same\n   * on ConnectError, for the same reason.\n   */\n  static [Symbol.hasInstance](v: unknown): boolean {\n    return isConnectClientErrorShape(v);\n  }\n}\n\n/** isRetryable reports whether a Connect code merits a transport retry. */\nexport function isRetryableCode(code: Code): boolean {\n  return RETRYABLE.has(code);\n}\n\n/**\n * normalizeError coerces any thrown value into a ConnectClientError. Already-\n * normalized errors pass through unchanged so the interceptor chain never\n * double-wraps. `requestTraceId` is the trace id of the traceparent the\n * request carried, used when the server sent no `traceresponse`.\n *\n * Both `instanceof` checks below match on SHAPE rather than class identity —\n * ours via ConnectClientError's Symbol.hasInstance, ConnectError's via the one\n * @connectrpc/connect ships — so neither branch is missed when a second copy\n * of either package lands in the bundle. The ConnectClientError check comes\n * first because every ConnectClientError is also a ConnectError.\n */\nexport function normalizeError(\n  err: unknown,\n  requestTraceId: string | null = null,\n): ConnectClientError {\n  if (err instanceof ConnectClientError) {\n    return err;\n  }\n\n  if (err instanceof ConnectError) {\n    return new ConnectClientError({\n      // Strip the \"[code] \" prefix so the message is user-presentable at\n      // every layer.\n      message: stripServerFraming(err.rawMessage || err.message),\n      code: err.code,\n      // The original metadata and details ride along, so `findDetails()` and\n      // `metadata.get(...)` answer exactly as they did on the raw error. The\n      // reason (backend-owned) is read from that metadata by the constructor.\n      metadata: err.metadata,\n      details: err.details,\n      // The server's own span when it answered; the trace this runtime asked\n      // for when it did not (a proxy error, an older server).\n      traceId:\n        traceIdFrom(err.metadata.get(TRACERESPONSE_HEADER)) ?? requestTraceId,\n      cause: err,\n    });\n  }\n\n  if (err instanceof Error) {\n    // An aborted or timed-out fetch is a cancellation, as ConnectError.from\n    // reads it.\n    if (err.name === \"AbortError\" || err.name === \"TimeoutError\") {\n      return new ConnectClientError({\n        message: stripServerFraming(err.message),\n        code: Code.Canceled,\n        traceId: requestTraceId,\n        cause: err,\n      });\n    }\n    // A network fault (fetch rejected: offline, DNS, CORS preflight, TLS)\n    // surfaces as a TypeError — that, and only that, is a safe transparent\n    // retry. A generic Error is NOT blanket-retried (blanket-retrying every\n    // bare Error widened the blast radius to non-idempotent failures).\n    const networkFault = err instanceof TypeError;\n    return new ConnectClientError({\n      message: stripServerFraming(err.message),\n      code: networkFault ? Code.Unavailable : Code.Unknown,\n      status: networkFault ? 503 : 500,\n      retryable: networkFault,\n      reason: null,\n      traceId: requestTraceId,\n      cause: err,\n    });\n  }\n\n  return new ConnectClientError({\n    message:\n      typeof err === \"string\" ? stripServerFraming(err) : \"Unknown error\",\n    code: Code.Unknown,\n    status: 500,\n    retryable: false,\n    reason: null,\n    cause: err,\n  });\n}\n"]}

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { authInterceptor, buildRuntimeInterceptors, errorNormalizeInterceptor, h
  * Typed client errors, and the backend-framing strippers every surface that
  * SHOWS an error goes through.
  */
-export { ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normalizeError, stripServerFraming, userMessage, } from "./errors.js";
+export { codeName, ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normalizeError, stripServerFraming, userMessage, } from "./errors.js";
 /**
  * Mount-prefix helpers, for the URLs Next.js's router never sees — absolute
  * URLs handed to external systems that round-trip back into the app.

package/dist/index.js

@@ -22,7 +22,7 @@ export { authInterceptor, buildRuntimeInterceptors, errorNormalizeInterceptor, h
  * Typed client errors, and the backend-framing strippers every surface that
  * SHOWS an error goes through.
  */
-export { ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normalizeError, stripServerFraming, userMessage, } from "./errors.js";
+export { codeName, ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normalizeError, stripServerFraming, userMessage, } from "./errors.js";
 /**
  * Mount-prefix helpers, for the URLs Next.js's router never sees — absolute
  * URLs handed to external systems that round-trip back into the app.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAC5E,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,4CAA4C;AAE5C,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,4EAA4E;AAC5E,sEAAsE;AAEtE,mCAAmC;AACnC,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,OAAO,EACL,cAAc,EACd,YAAY,EACZ,iBAAiB,GAElB,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,GAKhB,MAAM,YAAY,CAAC;AAEpB,qCAAqC;AACrC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,qFAAqF;AACrF,OAAO,EACL,SAAS,EACT,eAAe,EACf,UAAU,GAIX,MAAM,cAAc,CAAC;AAEtB,gFAAgF;AAChF,OAAO,EAAE,YAAY,EAA0B,MAAM,gBAAgB,CAAC;AAEtE,+EAA+E;AAC/E,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,yEAAyE;AACzE,OAAO,EACL,gBAAgB,GAMjB,MAAM,iBAAiB,CAAC;AAEzB,gEAAgE;AAChE,OAAO,EAAE,UAAU,EAAwB,MAAM,kBAAkB,CAAC;AAEpE,uFAAuF;AACvF,OAAO,EACL,QAAQ,GAIT,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,GAErB,MAAM,qBAAqB,CAAC;AAE7B,qFAAqF;AACrF,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE3E;;;;;;GAMG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,GAGN,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,aAAa,CAAC","sourcesContent":["// @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Public barrel. Import batteries from \"@reliantlabs/forge-web-runtime\".\n//\n// Everything here is MECHANISM: the transport interceptor stack, the session,\n// the error boundary, the toast queue, the <Resource> tristate ladder, W3C\n// trace propagation, client RUM. Nothing here reaches into an application —\n// app-shaped values (auth state, event subscriptions, toast markup) arrive as\n// props, so an app can restyle or replace its own files freely.\n//\n// Presentation that a project is meant to own — the component library under\n// src/components/ui, globals.css, nav, layout — deliberately stays in the\n// scaffold and is NOT part of this package.\n\n// The per-group docs below are JSDoc, not `//`, on purpose: TypeScript's\n// declaration emit preserves JSDoc and DROPS line comments, and dist/ is now\n// the whole of what this package publishes. `forge project libraries` reads\n// this inventory out of the published barrel, and a consumer's editor shows\n// it on hover — both would get symbols with no explanation otherwise.\n\n/** Transport interceptor stack. */\nexport {\n  authInterceptor,\n  buildRuntimeInterceptors,\n  errorNormalizeInterceptor,\n  headerInterceptor,\n  retryInterceptor,\n  traceInterceptor,\n  type RuntimeInterceptorConfig,\n} from \"./interceptors.js\";\n\n/**\n * Typed client errors, and the backend-framing strippers every surface that\n * SHOWS an error goes through.\n */\nexport {\n  ConnectClientError,\n  FORGE_ERROR_REASON_HEADER,\n  isRetryableCode,\n  normalizeError,\n  stripServerFraming,\n  userMessage,\n} from \"./errors.js\";\n\n/**\n * Mount-prefix helpers, for the URLs Next.js's router never sees — absolute\n * URLs handed to external systems that round-trip back into the app.\n *\n * Barrel-exported rather than behind a subpath: three string functions with\n * no imports, so there is no dependency footprint for a subpath to fence off.\n */\nexport {\n  createBasePath,\n  joinBasePath,\n  normalizeBasePath,\n  type BasePathHelpers,\n} from \"./basepath.js\";\n\n/**\n * Money and basis points as integers: format minor units through Intl, and\n * parse form input back to minor units without rounding.\n *\n * The web counterpart of forge/pkg/money — an int64 count of the currency's\n * minor unit plus an ISO 4217 code, exact past 2^53. Barrel-exported for the\n * same reason as the base-path helpers: it imports nothing.\n */\nexport {\n  basisPointsToInput,\n  currencyMinorDigits,\n  formatBasisPoints,\n  formatMinorUnits,\n  minorUnitsToInput,\n  parseBasisPoints,\n  parseMinorUnits,\n  type BasisPointsOptions,\n  type MoneyOptions,\n  type ParseBasisPointsOptions,\n  type ParseMoneyOptions,\n} from \"./money.js\";\n\n/** W3C trace-context propagation. */\nexport {\n  freshTraceparent,\n  injectTraceContext,\n  setTraceSampled,\n  traceIdFrom,\n  TRACEPARENT_RE,\n  TRACERESPONSE_HEADER,\n} from \"./trace.js\";\n\n/** Session: the signed-in user, derived from the app's auth state and JWT claims. */\nexport {\n  decodeJwt,\n  SessionProvider,\n  useSession,\n  type JwtClaims,\n  type Session,\n  type SessionAuth,\n} from \"./session.js\";\n\n/** The app-shell provider set: session + error boundary + toast host in one. */\nexport { RuntimeShell, type RuntimeShellProps } from \"./providers.js\";\n\n/** Error boundary with a designed crash fallback, for a route or a subtree. */\nexport {\n  DefaultErrorFallback,\n  RuntimeErrorBoundary,\n} from \"./error-boundary.js\";\n\n/** The toast queue. The app supplies the event source and the markup. */\nexport {\n  RuntimeToastHost,\n  type RuntimeToast,\n  type RuntimeToastHostProps,\n  type RuntimeToastPayload,\n  type RuntimeToastSink,\n  type RuntimeToastVariant,\n} from \"./toast-host.js\";\n\n/** Route guarding: render a page only to a signed-in caller. */\nexport { RouteGuard, type RouteGuardProps } from \"./route-guard.js\";\n\n/** Generic data-table container: the tristate ladder, filter and cursor pagination. */\nexport {\n  Resource,\n  type ResourceColumn,\n  type ResourceProps,\n  type ResourceStatus,\n} from \"./resource.js\";\n\n/**\n * Record a caught error with the browser telemetry SDK, when one is running.\n * A no-op otherwise, so it is safe in any catch block. The SDK itself arrives\n * through the \"/telemetry\" subpath, never the barrel.\n */\nexport {\n  reportException,\n  setExceptionReporter,\n  type ExceptionAttributes,\n} from \"./error-reporter.js\";\n\n/** The server trace id a failed RPC's error carries (ConnectClientError.traceId). */\nexport { SERVER_TRACE_ID_ATTRIBUTE, serverTraceIdOf } from \"./trace-id.js\";\n\n/**\n * Product events, the signed-in user and the consent kill-switch for browser\n * telemetry. Like reportException these are safe to call anywhere — no-ops on\n * the server and when telemetry is off — and calls made while the SDK is still\n * loading are held and replayed. The SDK itself arrives through the\n * \"/telemetry\" subpath, never the barrel.\n */\nexport {\n  disableTelemetry,\n  setTelemetryUser,\n  track,\n  type TrackProps,\n  type TrackValue,\n} from \"./track.js\";\n\n/**\n * Dev-only browser log forwarding: mirrors console output and uncaught errors\n * to the dev server, which prints them into\n * `.forge/logs/<env>/frontend_<name>.log`. No-ops unless `dev: true`, and the\n * receiving endpoint exists only in a dev server — so a production bundle\n * neither posts nor has anywhere to post to.\n */\nexport {\n  DEV_LOG_ENDPOINT,\n  devLoggingInstalled,\n  installDevLogging,\n  uninstallDevLogging,\n  type DevLoggingOptions,\n  type DevLogPayload,\n} from \"./devlog.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAC5E,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,4CAA4C;AAE5C,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,4EAA4E;AAC5E,sEAAsE;AAEtE,mCAAmC;AACnC,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,OAAO,EACL,QAAQ,EACR,kBAAkB,EAClB,yBAAyB,EACzB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,OAAO,EACL,cAAc,EACd,YAAY,EACZ,iBAAiB,GAElB,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,GAKhB,MAAM,YAAY,CAAC;AAEpB,qCAAqC;AACrC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,qFAAqF;AACrF,OAAO,EACL,SAAS,EACT,eAAe,EACf,UAAU,GAIX,MAAM,cAAc,CAAC;AAEtB,gFAAgF;AAChF,OAAO,EAAE,YAAY,EAA0B,MAAM,gBAAgB,CAAC;AAEtE,+EAA+E;AAC/E,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,yEAAyE;AACzE,OAAO,EACL,gBAAgB,GAMjB,MAAM,iBAAiB,CAAC;AAEzB,gEAAgE;AAChE,OAAO,EAAE,UAAU,EAAwB,MAAM,kBAAkB,CAAC;AAEpE,uFAAuF;AACvF,OAAO,EACL,QAAQ,GAIT,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,GAErB,MAAM,qBAAqB,CAAC;AAE7B,qFAAqF;AACrF,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE3E;;;;;;GAMG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,GAGN,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,aAAa,CAAC","sourcesContent":["// @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Public barrel. Import batteries from \"@reliantlabs/forge-web-runtime\".\n//\n// Everything here is MECHANISM: the transport interceptor stack, the session,\n// the error boundary, the toast queue, the <Resource> tristate ladder, W3C\n// trace propagation, client RUM. Nothing here reaches into an application —\n// app-shaped values (auth state, event subscriptions, toast markup) arrive as\n// props, so an app can restyle or replace its own files freely.\n//\n// Presentation that a project is meant to own — the component library under\n// src/components/ui, globals.css, nav, layout — deliberately stays in the\n// scaffold and is NOT part of this package.\n\n// The per-group docs below are JSDoc, not `//`, on purpose: TypeScript's\n// declaration emit preserves JSDoc and DROPS line comments, and dist/ is now\n// the whole of what this package publishes. `forge project libraries` reads\n// this inventory out of the published barrel, and a consumer's editor shows\n// it on hover — both would get symbols with no explanation otherwise.\n\n/** Transport interceptor stack. */\nexport {\n  authInterceptor,\n  buildRuntimeInterceptors,\n  errorNormalizeInterceptor,\n  headerInterceptor,\n  retryInterceptor,\n  traceInterceptor,\n  type RuntimeInterceptorConfig,\n} from \"./interceptors.js\";\n\n/**\n * Typed client errors, and the backend-framing strippers every surface that\n * SHOWS an error goes through.\n */\nexport {\n  codeName,\n  ConnectClientError,\n  FORGE_ERROR_REASON_HEADER,\n  isRetryableCode,\n  normalizeError,\n  stripServerFraming,\n  userMessage,\n} from \"./errors.js\";\n\n/**\n * Mount-prefix helpers, for the URLs Next.js's router never sees — absolute\n * URLs handed to external systems that round-trip back into the app.\n *\n * Barrel-exported rather than behind a subpath: three string functions with\n * no imports, so there is no dependency footprint for a subpath to fence off.\n */\nexport {\n  createBasePath,\n  joinBasePath,\n  normalizeBasePath,\n  type BasePathHelpers,\n} from \"./basepath.js\";\n\n/**\n * Money and basis points as integers: format minor units through Intl, and\n * parse form input back to minor units without rounding.\n *\n * The web counterpart of forge/pkg/money — an int64 count of the currency's\n * minor unit plus an ISO 4217 code, exact past 2^53. Barrel-exported for the\n * same reason as the base-path helpers: it imports nothing.\n */\nexport {\n  basisPointsToInput,\n  currencyMinorDigits,\n  formatBasisPoints,\n  formatMinorUnits,\n  minorUnitsToInput,\n  parseBasisPoints,\n  parseMinorUnits,\n  type BasisPointsOptions,\n  type MoneyOptions,\n  type ParseBasisPointsOptions,\n  type ParseMoneyOptions,\n} from \"./money.js\";\n\n/** W3C trace-context propagation. */\nexport {\n  freshTraceparent,\n  injectTraceContext,\n  setTraceSampled,\n  traceIdFrom,\n  TRACEPARENT_RE,\n  TRACERESPONSE_HEADER,\n} from \"./trace.js\";\n\n/** Session: the signed-in user, derived from the app's auth state and JWT claims. */\nexport {\n  decodeJwt,\n  SessionProvider,\n  useSession,\n  type JwtClaims,\n  type Session,\n  type SessionAuth,\n} from \"./session.js\";\n\n/** The app-shell provider set: session + error boundary + toast host in one. */\nexport { RuntimeShell, type RuntimeShellProps } from \"./providers.js\";\n\n/** Error boundary with a designed crash fallback, for a route or a subtree. */\nexport {\n  DefaultErrorFallback,\n  RuntimeErrorBoundary,\n} from \"./error-boundary.js\";\n\n/** The toast queue. The app supplies the event source and the markup. */\nexport {\n  RuntimeToastHost,\n  type RuntimeToast,\n  type RuntimeToastHostProps,\n  type RuntimeToastPayload,\n  type RuntimeToastSink,\n  type RuntimeToastVariant,\n} from \"./toast-host.js\";\n\n/** Route guarding: render a page only to a signed-in caller. */\nexport { RouteGuard, type RouteGuardProps } from \"./route-guard.js\";\n\n/** Generic data-table container: the tristate ladder, filter and cursor pagination. */\nexport {\n  Resource,\n  type ResourceColumn,\n  type ResourceProps,\n  type ResourceStatus,\n} from \"./resource.js\";\n\n/**\n * Record a caught error with the browser telemetry SDK, when one is running.\n * A no-op otherwise, so it is safe in any catch block. The SDK itself arrives\n * through the \"/telemetry\" subpath, never the barrel.\n */\nexport {\n  reportException,\n  setExceptionReporter,\n  type ExceptionAttributes,\n} from \"./error-reporter.js\";\n\n/** The server trace id a failed RPC's error carries (ConnectClientError.traceId). */\nexport { SERVER_TRACE_ID_ATTRIBUTE, serverTraceIdOf } from \"./trace-id.js\";\n\n/**\n * Product events, the signed-in user and the consent kill-switch for browser\n * telemetry. Like reportException these are safe to call anywhere — no-ops on\n * the server and when telemetry is off — and calls made while the SDK is still\n * loading are held and replayed. The SDK itself arrives through the\n * \"/telemetry\" subpath, never the barrel.\n */\nexport {\n  disableTelemetry,\n  setTelemetryUser,\n  track,\n  type TrackProps,\n  type TrackValue,\n} from \"./track.js\";\n\n/**\n * Dev-only browser log forwarding: mirrors console output and uncaught errors\n * to the dev server, which prints them into\n * `.forge/logs/<env>/frontend_<name>.log`. No-ops unless `dev: true`, and the\n * receiving endpoint exists only in a dev server — so a production bundle\n * neither posts nor has anywhere to post to.\n */\nexport {\n  DEV_LOG_ENDPOINT,\n  devLoggingInstalled,\n  installDevLogging,\n  uninstallDevLogging,\n  type DevLoggingOptions,\n  type DevLogPayload,\n} from \"./devlog.js\";\n"]}

package/dist/interceptors.d.ts

@@ -49,5 +49,5 @@ export declare function retryInterceptor(cfg: RuntimeInterceptorConfig): Interce
  * retry owner (see the retry-ownership note at the top of this file).
  */
 export declare function buildRuntimeInterceptors(cfg?: RuntimeInterceptorConfig): Interceptor[];
-export { ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normalizeError, } from "./errors.js";
+export { codeName, ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normalizeError, } from "./errors.js";
 export { freshTraceparent, injectTraceContext, setTraceSampled, traceIdFrom, TRACEPARENT_RE, TRACERESPONSE_HEADER, } from "./trace.js";

package/dist/interceptors.js

@@ -158,6 +158,6 @@ export function buildRuntimeInterceptors(cfg = {}) {
 // write a handler without the type; setTraceSampled is traceInterceptor's
 // only knob. A consumer of "@reliantlabs/forge-web-runtime/interceptors" must
 // never have to fall back to the React-typed barrel to complete the job.
-export { ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normalizeError, } from "./errors.js";
+export { codeName, ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normalizeError, } from "./errors.js";
 export { freshTraceparent, injectTraceContext, setTraceSampled, traceIdFrom, TRACEPARENT_RE, TRACERESPONSE_HEADER, } from "./trace.js";
 //# sourceMappingURL=interceptors.js.map

package/dist/interceptors.js.map

@@ -1 +1 @@
-{"version":3,"file":"interceptors.js","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// This module is also the package's SECOND ENTRY POINT, published as\n// \"@reliantlabs/forge-web-runtime/interceptors\". It is the DOM-free, React-free\n// half of the runtime: the transport layer and nothing else. Importing it\n// pulls in exactly ./errors and ./trace — no React, no @types/react, no\n// window/document. That matters for React Native, where Expo pins React 18\n// while the package's components are typed against React 19: a mobile app\n// importing the full barrel would typecheck the components it never renders\n// and fail. Everything re-exported at the bottom of this file is part of\n// this entry point's surface; keep it React-free (guarded by\n// interceptors-entry.test.ts).\n//\n// The Connect transport interceptor stack. This is the one place every\n// frontend→backend call flows through, composed once and handed to\n// createConnectTransport by the app's own connect module. Order (outermost\n// first):\n//\n//   error-normalize → auth → brand headers → traceparent\n//\n// error-normalize is outermost so every caller sees a typed\n// ConnectClientError instead of a raw ConnectError.\n//\n// RETRY OWNERSHIP — read before adding a retry layer.\n// The single retry owner is the app's React Query client: it\n// structurally knows reads from writes, so it retries transient READ\n// failures and NEVER retries a mutation — no duplicate writes. Each React\n// Query retry re-runs the queryFn, which re-runs this whole interceptor\n// chain (fresh token + traceparent), so nothing is lost by not retrying\n// here. `retryInterceptor` below is therefore NOT in the default chain; it\n// stays exported (idempotency-gated) only for callers who use the raw\n// transport OUTSIDE React Query. Putting it back in the default chain would\n// stack two retry layers AND retry non-idempotent mutations — the bug this\n// split fixed.\nimport { MethodOptions_IdempotencyLevel } from \"@bufbuild/protobuf/wkt\";\n\nimport { ConnectClientError, normalizeError } from \"./errors.js\";\nimport { telemetryReady } from \"./telemetry-gate.js\";\nimport { injectTraceContext, traceIdFrom } from \"./trace.js\";\n\nimport type {\n  Interceptor,\n  UnaryRequest,\n  StreamRequest,\n} from \"@connectrpc/connect\";\n\n/**\n * RuntimeInterceptorConfig is the seam the app wires its runtime dependencies\n * through. Everything is optional: an unconfigured chain still propagates\n * traceparent and normalizes errors.\n */\nexport interface RuntimeInterceptorConfig {\n  /** Returns the current bearer token, or null when unauthenticated. */\n  getToken?: () => Promise<string | null> | string | null;\n  /** Returns the active brand, attached as the X-Brand header. */\n  getBrand?: () => string | null | undefined;\n  /** Invoked with the typed error on every failed RPC (telemetry sink). */\n  onError?: (err: ConnectClientError) => void;\n  /** Max transparent retries for retryable unary failures. Default 2. */\n  maxRetries?: number;\n  /** Base backoff in ms; grows exponentially with jitter. Default 200. */\n  retryBaseMs?: number;\n}\n\nconst sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));\n\n/** Attaches the bearer token from the app's auth provider. */\nexport function authInterceptor(cfg: RuntimeInterceptorConfig): Interceptor {\n  return (next) => async (req) => {\n    const token = cfg.getToken ? await cfg.getToken() : null;\n    if (token) {\n      req.header.set(\"Authorization\", `Bearer ${token}`);\n    }\n    return next(req);\n  };\n}\n\n/** Attaches brand context headers when the app supplies them. */\nexport function headerInterceptor(cfg: RuntimeInterceptorConfig): Interceptor {\n  return (next) => async (req) => {\n    const brand = cfg.getBrand?.();\n    if (brand) {\n      req.header.set(\"X-Brand\", brand);\n    }\n    return next(req);\n  };\n}\n\n/**\n * Propagates a W3C traceparent so the backend (otelconnect + otelhttp) joins\n * the same distributed trace. Always emits a valid header — see trace.ts.\n *\n * While browser telemetry is still starting it waits (bounded; see\n * telemetry-gate.ts) so the call is made through the SDK's patched fetch and\n * its traceparent names a span the browser really exports.\n */\nexport function traceInterceptor(): Interceptor {\n  return (next) => async (req) => {\n    await telemetryReady();\n    injectTraceContext(req.header);\n    return next(req);\n  };\n}\n\n/** Converts any thrown failure into a typed ConnectClientError. */\nexport function errorNormalizeInterceptor(\n  cfg: RuntimeInterceptorConfig,\n): Interceptor {\n  return (next) => async (req) => {\n    try {\n      return await next(req);\n    } catch (err) {\n      // traceInterceptor (innermost) has written the traceparent onto this\n      // same request by now: the fallback when the server sent no\n      // traceresponse.\n      const normalized = normalizeError(\n        err,\n        traceIdFrom(req.header.get(\"traceparent\")),\n      );\n      cfg.onError?.(normalized);\n      throw normalized;\n    }\n  };\n}\n\n/**\n * retryEligible reports whether a request is SAFE to retry transparently:\n * a no-side-effects / idempotent method (declared via proto\n * `idempotency_level`), or one carrying an explicit Idempotency-Key header.\n * A plain mutation (the default IDEMPOTENCY_UNKNOWN) is never retried, so a\n * transparent retry can't produce a duplicate write.\n */\nfunction retryEligible(req: UnaryRequest | StreamRequest): boolean {\n  const level = req.method.idempotency;\n  if (\n    level === MethodOptions_IdempotencyLevel.NO_SIDE_EFFECTS ||\n    level === MethodOptions_IdempotencyLevel.IDEMPOTENT\n  ) {\n    return true;\n  }\n  return req.header.has(\"Idempotency-Key\");\n}\n\n/**\n * Transparently retries retryable failures with exponential backoff +\n * jitter — for IDEMPOTENT requests ONLY (see retryEligible). NOT part of the\n * default chain: React Query owns retries (see the retry-ownership note at\n * the top of this file). Exported for callers using the raw transport\n * outside React Query. Streaming RPCs are never retried (a partially-\n * consumed stream can't be safely replayed).\n */\nexport function retryInterceptor(cfg: RuntimeInterceptorConfig): Interceptor {\n  const max = cfg.maxRetries ?? 2;\n  const base = cfg.retryBaseMs ?? 200;\n  return (next) => async (req) => {\n    if (req.stream || !retryEligible(req)) {\n      return next(req);\n    }\n    let attempt = 0;\n    for (;;) {\n      try {\n        return await next(req);\n      } catch (err) {\n        const normalized =\n          err instanceof ConnectClientError ? err : normalizeError(err);\n        if (attempt >= max || !normalized.retryable) {\n          throw normalized;\n        }\n        const backoff = base * 2 ** attempt + Math.random() * base;\n        await sleep(backoff);\n        attempt++;\n      }\n    }\n  };\n}\n\n/**\n * buildRuntimeInterceptors composes the full stack in the correct order.\n * Pass the result to createConnectTransport's `interceptors` option.\n *\n * retryInterceptor is deliberately NOT included — React Query is the single\n * retry owner (see the retry-ownership note at the top of this file).\n */\nexport function buildRuntimeInterceptors(\n  cfg: RuntimeInterceptorConfig = {},\n): Interceptor[] {\n  return [\n    errorNormalizeInterceptor(cfg),\n    authInterceptor(cfg),\n    headerInterceptor(cfg),\n    traceInterceptor(),\n  ];\n}\n\n// ── The rest of the transport-layer surface ──────────────────────────────\n//\n// These belong to this entry point because the interceptor stack's contract\n// is expressed in them: errorNormalizeInterceptor THROWS ConnectClientError\n// and RuntimeInterceptorConfig.onError RECEIVES one, so a consumer cannot\n// write a handler without the type; setTraceSampled is traceInterceptor's\n// only knob. A consumer of \"@reliantlabs/forge-web-runtime/interceptors\" must\n// never have to fall back to the React-typed barrel to complete the job.\n\nexport {\n  ConnectClientError,\n  FORGE_ERROR_REASON_HEADER,\n  isRetryableCode,\n  normalizeError,\n} from \"./errors.js\";\n\nexport {\n  freshTraceparent,\n  injectTraceContext,\n  setTraceSampled,\n  traceIdFrom,\n  TRACEPARENT_RE,\n  TRACERESPONSE_HEADER,\n} from \"./trace.js\";\n"]}
+{"version":3,"file":"interceptors.js","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// This module is also the package's SECOND ENTRY POINT, published as\n// \"@reliantlabs/forge-web-runtime/interceptors\". It is the DOM-free, React-free\n// half of the runtime: the transport layer and nothing else. Importing it\n// pulls in exactly ./errors and ./trace — no React, no @types/react, no\n// window/document. That matters for React Native, where Expo pins React 18\n// while the package's components are typed against React 19: a mobile app\n// importing the full barrel would typecheck the components it never renders\n// and fail. Everything re-exported at the bottom of this file is part of\n// this entry point's surface; keep it React-free (guarded by\n// interceptors-entry.test.ts).\n//\n// The Connect transport interceptor stack. This is the one place every\n// frontend→backend call flows through, composed once and handed to\n// createConnectTransport by the app's own connect module. Order (outermost\n// first):\n//\n//   error-normalize → auth → brand headers → traceparent\n//\n// error-normalize is outermost so every caller sees a typed\n// ConnectClientError instead of a raw ConnectError.\n//\n// RETRY OWNERSHIP — read before adding a retry layer.\n// The single retry owner is the app's React Query client: it\n// structurally knows reads from writes, so it retries transient READ\n// failures and NEVER retries a mutation — no duplicate writes. Each React\n// Query retry re-runs the queryFn, which re-runs this whole interceptor\n// chain (fresh token + traceparent), so nothing is lost by not retrying\n// here. `retryInterceptor` below is therefore NOT in the default chain; it\n// stays exported (idempotency-gated) only for callers who use the raw\n// transport OUTSIDE React Query. Putting it back in the default chain would\n// stack two retry layers AND retry non-idempotent mutations — the bug this\n// split fixed.\nimport { MethodOptions_IdempotencyLevel } from \"@bufbuild/protobuf/wkt\";\n\nimport { ConnectClientError, normalizeError } from \"./errors.js\";\nimport { telemetryReady } from \"./telemetry-gate.js\";\nimport { injectTraceContext, traceIdFrom } from \"./trace.js\";\n\nimport type {\n  Interceptor,\n  UnaryRequest,\n  StreamRequest,\n} from \"@connectrpc/connect\";\n\n/**\n * RuntimeInterceptorConfig is the seam the app wires its runtime dependencies\n * through. Everything is optional: an unconfigured chain still propagates\n * traceparent and normalizes errors.\n */\nexport interface RuntimeInterceptorConfig {\n  /** Returns the current bearer token, or null when unauthenticated. */\n  getToken?: () => Promise<string | null> | string | null;\n  /** Returns the active brand, attached as the X-Brand header. */\n  getBrand?: () => string | null | undefined;\n  /** Invoked with the typed error on every failed RPC (telemetry sink). */\n  onError?: (err: ConnectClientError) => void;\n  /** Max transparent retries for retryable unary failures. Default 2. */\n  maxRetries?: number;\n  /** Base backoff in ms; grows exponentially with jitter. Default 200. */\n  retryBaseMs?: number;\n}\n\nconst sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));\n\n/** Attaches the bearer token from the app's auth provider. */\nexport function authInterceptor(cfg: RuntimeInterceptorConfig): Interceptor {\n  return (next) => async (req) => {\n    const token = cfg.getToken ? await cfg.getToken() : null;\n    if (token) {\n      req.header.set(\"Authorization\", `Bearer ${token}`);\n    }\n    return next(req);\n  };\n}\n\n/** Attaches brand context headers when the app supplies them. */\nexport function headerInterceptor(cfg: RuntimeInterceptorConfig): Interceptor {\n  return (next) => async (req) => {\n    const brand = cfg.getBrand?.();\n    if (brand) {\n      req.header.set(\"X-Brand\", brand);\n    }\n    return next(req);\n  };\n}\n\n/**\n * Propagates a W3C traceparent so the backend (otelconnect + otelhttp) joins\n * the same distributed trace. Always emits a valid header — see trace.ts.\n *\n * While browser telemetry is still starting it waits (bounded; see\n * telemetry-gate.ts) so the call is made through the SDK's patched fetch and\n * its traceparent names a span the browser really exports.\n */\nexport function traceInterceptor(): Interceptor {\n  return (next) => async (req) => {\n    await telemetryReady();\n    injectTraceContext(req.header);\n    return next(req);\n  };\n}\n\n/** Converts any thrown failure into a typed ConnectClientError. */\nexport function errorNormalizeInterceptor(\n  cfg: RuntimeInterceptorConfig,\n): Interceptor {\n  return (next) => async (req) => {\n    try {\n      return await next(req);\n    } catch (err) {\n      // traceInterceptor (innermost) has written the traceparent onto this\n      // same request by now: the fallback when the server sent no\n      // traceresponse.\n      const normalized = normalizeError(\n        err,\n        traceIdFrom(req.header.get(\"traceparent\")),\n      );\n      cfg.onError?.(normalized);\n      throw normalized;\n    }\n  };\n}\n\n/**\n * retryEligible reports whether a request is SAFE to retry transparently:\n * a no-side-effects / idempotent method (declared via proto\n * `idempotency_level`), or one carrying an explicit Idempotency-Key header.\n * A plain mutation (the default IDEMPOTENCY_UNKNOWN) is never retried, so a\n * transparent retry can't produce a duplicate write.\n */\nfunction retryEligible(req: UnaryRequest | StreamRequest): boolean {\n  const level = req.method.idempotency;\n  if (\n    level === MethodOptions_IdempotencyLevel.NO_SIDE_EFFECTS ||\n    level === MethodOptions_IdempotencyLevel.IDEMPOTENT\n  ) {\n    return true;\n  }\n  return req.header.has(\"Idempotency-Key\");\n}\n\n/**\n * Transparently retries retryable failures with exponential backoff +\n * jitter — for IDEMPOTENT requests ONLY (see retryEligible). NOT part of the\n * default chain: React Query owns retries (see the retry-ownership note at\n * the top of this file). Exported for callers using the raw transport\n * outside React Query. Streaming RPCs are never retried (a partially-\n * consumed stream can't be safely replayed).\n */\nexport function retryInterceptor(cfg: RuntimeInterceptorConfig): Interceptor {\n  const max = cfg.maxRetries ?? 2;\n  const base = cfg.retryBaseMs ?? 200;\n  return (next) => async (req) => {\n    if (req.stream || !retryEligible(req)) {\n      return next(req);\n    }\n    let attempt = 0;\n    for (;;) {\n      try {\n        return await next(req);\n      } catch (err) {\n        const normalized =\n          err instanceof ConnectClientError ? err : normalizeError(err);\n        if (attempt >= max || !normalized.retryable) {\n          throw normalized;\n        }\n        const backoff = base * 2 ** attempt + Math.random() * base;\n        await sleep(backoff);\n        attempt++;\n      }\n    }\n  };\n}\n\n/**\n * buildRuntimeInterceptors composes the full stack in the correct order.\n * Pass the result to createConnectTransport's `interceptors` option.\n *\n * retryInterceptor is deliberately NOT included — React Query is the single\n * retry owner (see the retry-ownership note at the top of this file).\n */\nexport function buildRuntimeInterceptors(\n  cfg: RuntimeInterceptorConfig = {},\n): Interceptor[] {\n  return [\n    errorNormalizeInterceptor(cfg),\n    authInterceptor(cfg),\n    headerInterceptor(cfg),\n    traceInterceptor(),\n  ];\n}\n\n// ── The rest of the transport-layer surface ──────────────────────────────\n//\n// These belong to this entry point because the interceptor stack's contract\n// is expressed in them: errorNormalizeInterceptor THROWS ConnectClientError\n// and RuntimeInterceptorConfig.onError RECEIVES one, so a consumer cannot\n// write a handler without the type; setTraceSampled is traceInterceptor's\n// only knob. A consumer of \"@reliantlabs/forge-web-runtime/interceptors\" must\n// never have to fall back to the React-typed barrel to complete the job.\n\nexport {\n  codeName,\n  ConnectClientError,\n  FORGE_ERROR_REASON_HEADER,\n  isRetryableCode,\n  normalizeError,\n} from \"./errors.js\";\n\nexport {\n  freshTraceparent,\n  injectTraceContext,\n  setTraceSampled,\n  traceIdFrom,\n  TRACEPARENT_RE,\n  TRACERESPONSE_HEADER,\n} from \"./trace.js\";\n"]}

package/dist/service-hooks.d.ts

@@ -56,7 +56,7 @@ export type ServiceMutationHook<Schema extends DescMessage, Response> = (options
  * Query's default `Error`. That type is declared on the OPTIONS parameter
  * because React Query takes the result's error type from the same TError it
  * reads there, so `query.error` is a ConnectClientError at every call site
- * with nothing to pass. Typing it as `Error` hid `.reason`, `.code`, `.status`
+ * with nothing to pass. Typing it as `Error` hid `.reason`, `.codeName`, `.status`
  * and `.retryable`, and left `err.message.includes(...)` as the only
  * expression that compiled — the one thing the error contract forbids.
  */

package/dist/service-hooks.js

@@ -79,7 +79,7 @@ export function serviceKeys(service) {
  * Query's default `Error`. That type is declared on the OPTIONS parameter
  * because React Query takes the result's error type from the same TError it
  * reads there, so `query.error` is a ConnectClientError at every call site
- * with nothing to pass. Typing it as `Error` hid `.reason`, `.code`, `.status`
+ * with nothing to pass. Typing it as `Error` hid `.reason`, `.codeName`, `.status`
  * and `.retryable`, and left `err.message.includes(...)` as the only
  * expression that compiled — the one thing the error contract forbids.
  */

package/dist/service-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"service-hooks.js","sourceRoot":"","sources":["../src/service-hooks.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,sEAAsE;AACtE,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,uEAAuE;AACvE,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,gEAAgE;AAChE,EAAE;AACF,8EAA8E;AAC9E,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AACrE,qEAAqE;AACrE,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,sEAAsE;AACtE,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,sEAAsE;AACtE,wEAAwE;AACxE,6EAA6E;AAC7E,4EAA4E;AAC5E,mCAAmC;AACnC,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,uDAAuD;AACvD,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,OAAO,EACL,MAAM,EACN,MAAM,GAGP,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,QAAQ,EACR,cAAc,GAKf,MAAM,uBAAuB,CAAC;AAW/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,GAA6B;IAE7B,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC;AAoBD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO;QACL,GAAG,EAAE,CAAC,OAAO,CAAU;QACvB,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAU;QAClD,KAAK,EACH,CACE,MAAc,EACd,MAAc,EACd,WAAoB,EACpB,EAAE,CACJ,CAAC,GAA6B,EAAmB,EAAE,CACjD,WAAW,KAAK,SAAS;YACvB,CAAC,CAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;YACvD,CAAC,CAAE,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;KAC3E,CAAC;AACJ,CAAC;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA0D,EAC1D,IAA0D;IAE1D,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CACtB,QAAQ,CAAC;QACP,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;QACrB,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;QACxB,GAAG,OAAO;KACX,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,aAA8B,EAC9B,IAA0D;IAE1D,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;QACrC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAC7C,OAAO,WAAW,CAAC;YACjB,UAAU,EAAE,CAAC,GAA6B,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;YACxD,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE;gBACrB,WAAW,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC3D,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACvB,CAAC;YACD,GAAG,IAAI;SACR,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\n// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Every export below is a React hook or builds one, so this module belongs in\n// the CLIENT graph. Without the directive the Next.js App Router compiles it\n// into the SERVER graph, where it binds a SECOND @tanstack/react-query\n// instance and every generated hook throws \"No QueryClient set\" at runtime —\n// invisible to tsc, eslint AND `next build`. published-surface.test.ts asserts\n// the directive survives into dist/. It is NOT applied package-wide: the\n// ./interceptors subpath exists to be importable without React.\n//\n// The React Query wrapper machinery behind forge's generated per-service hook\n// files (`src/hooks/<svc>-service-hooks_gen.ts`).\n//\n// WHAT WAS HERE BEFORE. Each generated file re-emitted the same three things\n// per RPC: a query-key entry, a useQuery or useMutation wrapper, and — for\n// mutations — the entity-scoped invalidateQueries plus the onSuccess\n// composition, with the reasoning for each re-inlined as comments. A\n// five-service project rendered five copies of machinery that differed only in\n// RPC names and message types. This module IS that machinery, written once.\n// The generated file keeps exactly what varies per RPC: the name, the request\n// schema, the response type, query-vs-mutation, and the entity scope.\n//\n// WHY A SUBPATH AND NOT THE BARREL. This module imports @tanstack/react-query.\n// Every browser frontend forge scaffolds depends on it — but the barrel is\n// also what a consumer imports for interceptors and errors alone, and\n// anchoring React Query there would make a non-React consumer resolve a\n// package it never installed. Same reasoning as ./mock-transport and ./otel:\n// an engine with its own dependency footprint gets its own entry point, and\n// React Query is an OPTIONAL peer.\n//\n// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — the\n// app-wide MutationCache in src/lib/query-client.ts is the single error-toast\n// chokepoint, and pages that render errors inline pass\n// `meta: { silenceErrorToast: true }`. It never defaults success-side UX\n// either: \"CreateOrder succeeded\" leaks RPC names into the UI, so the toast /\n// redirect / inline confirmation stays the call site's via options.onSuccess.\nimport {\n  create,\n  toJson,\n  type DescMessage,\n  type MessageInitShape,\n} from \"@bufbuild/protobuf\";\nimport {\n  useMutation,\n  useQuery,\n  useQueryClient,\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n} from \"@tanstack/react-query\";\n\nimport type { ConnectClientError } from \"./errors.js\";\n\n/**\n * A generated query key. The tuple is [service, entity?, method,\n * protojson(req)] for a method key and [service] / [service, entity] for the\n * broader scopes.\n */\nexport type ServiceQueryKey = readonly unknown[];\n\n/**\n * requestKey projects a request init into protojson for use inside a query\n * key. Two reasons this is not the raw request object:\n *\n *   - React Query's default hasher is JSON.stringify, which THROWS on bigint\n *     fields (any proto int64) — the raw message crashes the cache.\n *   - protojson normalizes representations, so { id: 1 } and { id: \"1\" } land\n *     in ONE cache entry instead of silently splitting the cache.\n *\n * Exported because a hand-written hook that wants to share a generated hook's\n * cache entry has to hash its request the identical way.\n */\nexport function requestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: MessageInitShape<Schema>,\n): unknown {\n  return toJson(schema, create(schema, req));\n}\n\n/** The three key-scope builders a generated key factory is assembled from. */\nexport interface ServiceKeyBuilders {\n  /** Every query on this service: [service]. */\n  readonly all: readonly [string];\n  /** Every query for one CRUD entity: [service, entity]. Mutations invalidate this. */\n  entity(name: string): readonly [string, string];\n  /**\n   * One query: [service, entity?, method, protojson(req)]. Returns the\n   * per-request key FUNCTION, which is what both the query hook and any\n   * call-site prefetch/setQueryData use.\n   */\n  query<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): (req: MessageInitShape<Schema>) => ServiceQueryKey;\n}\n\n/**\n * serviceKeys returns the builders for one service's query-key factory.\n *\n * Cache-key semantics are a compatibility contract, not an implementation\n * detail: an existing app's\n * `invalidateQueries({ queryKey: orderServiceKeys.order })` has to keep\n * matching the keys its queries were registered under across a version bump.\n * So the tuple order and contents produced here are fixed, and identical to\n * what forge previously inlined into every generated hook file.\n */\nexport function serviceKeys(service: string): ServiceKeyBuilders {\n  return {\n    all: [service] as const,\n    entity: (name: string) => [service, name] as const,\n    query:\n      <Schema extends DescMessage>(\n        method: string,\n        schema: Schema,\n        entityScope?: string,\n      ) =>\n      (req: MessageInitShape<Schema>): ServiceQueryKey =>\n        entityScope === undefined\n          ? ([service, method, requestKey(schema, req)] as const)\n          : ([service, entityScope, method, requestKey(schema, req)] as const),\n  };\n}\n\n/** A generated query hook: `useGetOrder(req, options?)`. */\nexport type ServiceQueryHook<Schema extends DescMessage, Response> = (\n  req: MessageInitShape<Schema>,\n  options?: Partial<UseQueryOptions<Response, ConnectClientError>>,\n) => UseQueryResult<Response, ConnectClientError>;\n\n/** A generated mutation hook: `useCreateOrder(options?)`. */\nexport type ServiceMutationHook<Schema extends DescMessage, Response> = (\n  options?: Partial<\n    UseMutationOptions<Response, ConnectClientError, MessageInitShape<Schema>>\n  >,\n) => UseMutationResult<Response, ConnectClientError, MessageInitShape<Schema>>;\n\n/**\n * createQueryHook builds one useQuery wrapper.\n *\n * The signature it returns is the one call sites already use — `(req,\n * options?)`, with the error typed as ConnectClientError rather than React\n * Query's default `Error`. That type is declared on the OPTIONS parameter\n * because React Query takes the result's error type from the same TError it\n * reads there, so `query.error` is a ConnectClientError at every call site\n * with nothing to pass. Typing it as `Error` hid `.reason`, `.code`, `.status`\n * and `.retryable`, and left `err.message.includes(...)` as the only\n * expression that compiled — the one thing the error contract forbids.\n */\nexport function createQueryHook<Schema extends DescMessage, Response>(\n  keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceQueryHook<Schema, Response> {\n  return (req, options) =>\n    useQuery({\n      queryKey: keyFor(req),\n      queryFn: () => call(req),\n      ...options,\n    });\n}\n\n/**\n * createMutationHook builds one useMutation wrapper with scoped invalidation.\n *\n * invalidateKey is the entity scope when the RPC maps to a CRUD entity, and\n * the whole-service scope otherwise — a bespoke mutation may touch anything,\n * so over-invalidating is the safe default there.\n *\n * The invalidation is composed BEFORE the caller's onSuccess and is never\n * replaced by it: onSuccess is destructured out and re-invoked after the\n * invalidate, while the rest of the options object is spread separately. A\n * caller passing onSuccess therefore ADDS behaviour, rather than silently\n * disabling the cache refresh — which is exactly what a plain `...options`\n * spread over a default onSuccess would do.\n */\nexport function createMutationHook<Schema extends DescMessage, Response>(\n  invalidateKey: ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceMutationHook<Schema, Response> {\n  return (options) => {\n    const queryClient = useQueryClient();\n    const { onSuccess, ...rest } = options ?? {};\n    return useMutation({\n      mutationFn: (req: MessageInitShape<Schema>) => call(req),\n      onSuccess: (...args) => {\n        queryClient.invalidateQueries({ queryKey: invalidateKey });\n        onSuccess?.(...args);\n      },\n      ...rest,\n    });\n  };\n}\n"]}
+{"version":3,"file":"service-hooks.js","sourceRoot":"","sources":["../src/service-hooks.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,sEAAsE;AACtE,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,uEAAuE;AACvE,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,gEAAgE;AAChE,EAAE;AACF,8EAA8E;AAC9E,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AACrE,qEAAqE;AACrE,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,sEAAsE;AACtE,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,sEAAsE;AACtE,wEAAwE;AACxE,6EAA6E;AAC7E,4EAA4E;AAC5E,mCAAmC;AACnC,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,uDAAuD;AACvD,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,OAAO,EACL,MAAM,EACN,MAAM,GAGP,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,QAAQ,EACR,cAAc,GAKf,MAAM,uBAAuB,CAAC;AAW/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,GAA6B;IAE7B,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC;AAoBD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO;QACL,GAAG,EAAE,CAAC,OAAO,CAAU;QACvB,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAU;QAClD,KAAK,EACH,CACE,MAAc,EACd,MAAc,EACd,WAAoB,EACpB,EAAE,CACJ,CAAC,GAA6B,EAAmB,EAAE,CACjD,WAAW,KAAK,SAAS;YACvB,CAAC,CAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;YACvD,CAAC,CAAE,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;KAC3E,CAAC;AACJ,CAAC;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA0D,EAC1D,IAA0D;IAE1D,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CACtB,QAAQ,CAAC;QACP,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;QACrB,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;QACxB,GAAG,OAAO;KACX,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,aAA8B,EAC9B,IAA0D;IAE1D,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;QACrC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAC7C,OAAO,WAAW,CAAC;YACjB,UAAU,EAAE,CAAC,GAA6B,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;YACxD,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE;gBACrB,WAAW,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC3D,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACvB,CAAC;YACD,GAAG,IAAI;SACR,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\n// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Every export below is a React hook or builds one, so this module belongs in\n// the CLIENT graph. Without the directive the Next.js App Router compiles it\n// into the SERVER graph, where it binds a SECOND @tanstack/react-query\n// instance and every generated hook throws \"No QueryClient set\" at runtime —\n// invisible to tsc, eslint AND `next build`. published-surface.test.ts asserts\n// the directive survives into dist/. It is NOT applied package-wide: the\n// ./interceptors subpath exists to be importable without React.\n//\n// The React Query wrapper machinery behind forge's generated per-service hook\n// files (`src/hooks/<svc>-service-hooks_gen.ts`).\n//\n// WHAT WAS HERE BEFORE. Each generated file re-emitted the same three things\n// per RPC: a query-key entry, a useQuery or useMutation wrapper, and — for\n// mutations — the entity-scoped invalidateQueries plus the onSuccess\n// composition, with the reasoning for each re-inlined as comments. A\n// five-service project rendered five copies of machinery that differed only in\n// RPC names and message types. This module IS that machinery, written once.\n// The generated file keeps exactly what varies per RPC: the name, the request\n// schema, the response type, query-vs-mutation, and the entity scope.\n//\n// WHY A SUBPATH AND NOT THE BARREL. This module imports @tanstack/react-query.\n// Every browser frontend forge scaffolds depends on it — but the barrel is\n// also what a consumer imports for interceptors and errors alone, and\n// anchoring React Query there would make a non-React consumer resolve a\n// package it never installed. Same reasoning as ./mock-transport and ./otel:\n// an engine with its own dependency footprint gets its own entry point, and\n// React Query is an OPTIONAL peer.\n//\n// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — the\n// app-wide MutationCache in src/lib/query-client.ts is the single error-toast\n// chokepoint, and pages that render errors inline pass\n// `meta: { silenceErrorToast: true }`. It never defaults success-side UX\n// either: \"CreateOrder succeeded\" leaks RPC names into the UI, so the toast /\n// redirect / inline confirmation stays the call site's via options.onSuccess.\nimport {\n  create,\n  toJson,\n  type DescMessage,\n  type MessageInitShape,\n} from \"@bufbuild/protobuf\";\nimport {\n  useMutation,\n  useQuery,\n  useQueryClient,\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n} from \"@tanstack/react-query\";\n\nimport type { ConnectClientError } from \"./errors.js\";\n\n/**\n * A generated query key. The tuple is [service, entity?, method,\n * protojson(req)] for a method key and [service] / [service, entity] for the\n * broader scopes.\n */\nexport type ServiceQueryKey = readonly unknown[];\n\n/**\n * requestKey projects a request init into protojson for use inside a query\n * key. Two reasons this is not the raw request object:\n *\n *   - React Query's default hasher is JSON.stringify, which THROWS on bigint\n *     fields (any proto int64) — the raw message crashes the cache.\n *   - protojson normalizes representations, so { id: 1 } and { id: \"1\" } land\n *     in ONE cache entry instead of silently splitting the cache.\n *\n * Exported because a hand-written hook that wants to share a generated hook's\n * cache entry has to hash its request the identical way.\n */\nexport function requestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: MessageInitShape<Schema>,\n): unknown {\n  return toJson(schema, create(schema, req));\n}\n\n/** The three key-scope builders a generated key factory is assembled from. */\nexport interface ServiceKeyBuilders {\n  /** Every query on this service: [service]. */\n  readonly all: readonly [string];\n  /** Every query for one CRUD entity: [service, entity]. Mutations invalidate this. */\n  entity(name: string): readonly [string, string];\n  /**\n   * One query: [service, entity?, method, protojson(req)]. Returns the\n   * per-request key FUNCTION, which is what both the query hook and any\n   * call-site prefetch/setQueryData use.\n   */\n  query<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): (req: MessageInitShape<Schema>) => ServiceQueryKey;\n}\n\n/**\n * serviceKeys returns the builders for one service's query-key factory.\n *\n * Cache-key semantics are a compatibility contract, not an implementation\n * detail: an existing app's\n * `invalidateQueries({ queryKey: orderServiceKeys.order })` has to keep\n * matching the keys its queries were registered under across a version bump.\n * So the tuple order and contents produced here are fixed, and identical to\n * what forge previously inlined into every generated hook file.\n */\nexport function serviceKeys(service: string): ServiceKeyBuilders {\n  return {\n    all: [service] as const,\n    entity: (name: string) => [service, name] as const,\n    query:\n      <Schema extends DescMessage>(\n        method: string,\n        schema: Schema,\n        entityScope?: string,\n      ) =>\n      (req: MessageInitShape<Schema>): ServiceQueryKey =>\n        entityScope === undefined\n          ? ([service, method, requestKey(schema, req)] as const)\n          : ([service, entityScope, method, requestKey(schema, req)] as const),\n  };\n}\n\n/** A generated query hook: `useGetOrder(req, options?)`. */\nexport type ServiceQueryHook<Schema extends DescMessage, Response> = (\n  req: MessageInitShape<Schema>,\n  options?: Partial<UseQueryOptions<Response, ConnectClientError>>,\n) => UseQueryResult<Response, ConnectClientError>;\n\n/** A generated mutation hook: `useCreateOrder(options?)`. */\nexport type ServiceMutationHook<Schema extends DescMessage, Response> = (\n  options?: Partial<\n    UseMutationOptions<Response, ConnectClientError, MessageInitShape<Schema>>\n  >,\n) => UseMutationResult<Response, ConnectClientError, MessageInitShape<Schema>>;\n\n/**\n * createQueryHook builds one useQuery wrapper.\n *\n * The signature it returns is the one call sites already use — `(req,\n * options?)`, with the error typed as ConnectClientError rather than React\n * Query's default `Error`. That type is declared on the OPTIONS parameter\n * because React Query takes the result's error type from the same TError it\n * reads there, so `query.error` is a ConnectClientError at every call site\n * with nothing to pass. Typing it as `Error` hid `.reason`, `.codeName`, `.status`\n * and `.retryable`, and left `err.message.includes(...)` as the only\n * expression that compiled — the one thing the error contract forbids.\n */\nexport function createQueryHook<Schema extends DescMessage, Response>(\n  keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceQueryHook<Schema, Response> {\n  return (req, options) =>\n    useQuery({\n      queryKey: keyFor(req),\n      queryFn: () => call(req),\n      ...options,\n    });\n}\n\n/**\n * createMutationHook builds one useMutation wrapper with scoped invalidation.\n *\n * invalidateKey is the entity scope when the RPC maps to a CRUD entity, and\n * the whole-service scope otherwise — a bespoke mutation may touch anything,\n * so over-invalidating is the safe default there.\n *\n * The invalidation is composed BEFORE the caller's onSuccess and is never\n * replaced by it: onSuccess is destructured out and re-invoked after the\n * invalidate, while the rest of the options object is spread separately. A\n * caller passing onSuccess therefore ADDS behaviour, rather than silently\n * disabling the cache refresh — which is exactly what a plain `...options`\n * spread over a default onSuccess would do.\n */\nexport function createMutationHook<Schema extends DescMessage, Response>(\n  invalidateKey: ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceMutationHook<Schema, Response> {\n  return (options) => {\n    const queryClient = useQueryClient();\n    const { onSuccess, ...rest } = options ?? {};\n    return useMutation({\n      mutationFn: (req: MessageInitShape<Schema>) => call(req),\n      onSuccess: (...args) => {\n        queryClient.invalidateQueries({ queryKey: invalidateKey });\n        onSuccess?.(...args);\n      },\n      ...rest,\n    });\n  };\n}\n"]}

package/dist/vite.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * The environment variable `forge env up` sets on a frontend's dev server
+ * when the frontend's runtime config document was rendered outside its tree.
+ * Its value is an absolute path.
+ */
+export declare const FORGE_RUNTIME_CONFIG_FILE_ENV = "FORGE_RUNTIME_CONFIG_FILE";
+type NextFn = (err?: unknown) => void;
+type Middleware = (req: IncomingMessage, res: ServerResponse, next: NextFn) => void;
+/** The part of a Vite dev / preview server this plugin uses. */
+export interface RuntimeConfigServer {
+    config: {
+        base: string;
+        logger: {
+            warn(msg: string): void;
+        };
+    };
+    middlewares: {
+        use(fn: Middleware): unknown;
+    };
+    watcher?: {
+        add(paths: string | readonly string[]): unknown;
+        on(event: "change", listener: (path: string) => void): unknown;
+    };
+    ws?: {
+        send(payload: {
+            type: "full-reload";
+            path?: string;
+        }): void;
+    };
+}
+export interface ForgeRuntimeConfigOptions {
+    /**
+     * The document to serve. Defaults to `process.env.FORGE_RUNTIME_CONFIG_FILE`
+     * as the dev server sees it. Empty or unset makes the plugin inert.
+     */
+    file?: string;
+}
+/** The plugin object; structurally a Vite `Plugin`. */
+export interface ForgeRuntimeConfigPlugin {
+    name: string;
+    configureServer(server: RuntimeConfigServer): void;
+    configurePreviewServer(server: RuntimeConfigServer): void;
+}
+/**
+ * forgeRuntimeConfig serves `<base>config.js` from the file forge rendered
+ * for this frontend, when there is one. Add it to `plugins` in
+ * vite.config.ts:
+ *
+ * ```ts
+ * import { forgeRuntimeConfig } from "@reliantlabs/forge-web-runtime/vite";
+ * export default defineConfig({ plugins: [react(), forgeRuntimeConfig()] });
+ * ```
+ */
+export declare function forgeRuntimeConfig(options?: ForgeRuntimeConfigOptions): ForgeRuntimeConfigPlugin;
+export {};

package/dist/vite.js

@@ -0,0 +1,116 @@
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// forgeRuntimeConfig — a Vite plugin that serves the frontend's runtime
+// config document (`config.js`, which sets `window.__FORGE_CONFIG__`) from a
+// file forge rendered OUTSIDE the frontend's own tree.
+//
+// # Why
+//
+// A frontend normally carries its dev document at `public/config.js`, written
+// by `forge generate` / `forge env up` in the project that owns the frontend.
+// A frontend whose code lives in ANOTHER repository — a sibling checkout
+// (`path: "../reliant/web"`) in dev, a source pin when building — has no
+// directory forge may write into: putting one repo's rendered environment in
+// another repo's working tree is a diff in someone else's `git status`. So the
+// project that declares the environment renders the document to its own
+// `.forge/runtime-config/<frontend>/config.js`, and `forge env up` hands the
+// path to the frontend's dev server as FORGE_RUNTIME_CONFIG_FILE. This plugin
+// is the dev server's half: it answers `<base>config.js` from that file.
+//
+// With the variable unset (the frontend's own repo runs its own dev server,
+// or a build) the plugin does nothing, and `public/config.js` is served as
+// before — so adding it to a vite.config.ts is safe in every mode.
+//
+// The file is read on EVERY request rather than once: `forge env up`
+// re-renders it after identity and jobs converge, and a page reload must see
+// that, not the value from when the dev server started. A change also sends
+// the page a full reload, so an open tab picks it up without a click.
+//
+// Structural types only: this module imports nothing from `vite`, so the
+// package takes no dependency on any Vite major. The plugin object is
+// assignable to Vite's `Plugin` (vite.test.ts pins that).
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+/**
+ * The environment variable `forge env up` sets on a frontend's dev server
+ * when the frontend's runtime config document was rendered outside its tree.
+ * Its value is an absolute path.
+ */
+export const FORGE_RUNTIME_CONFIG_FILE_ENV = "FORGE_RUNTIME_CONFIG_FILE";
+/** The document's file name, which is also the path it is served at. */
+const CONFIG_JS = "config.js";
+/**
+ * configPath is the request path the document is served at under `base`.
+ * Vite normalizes a dev server's base to "/" or "/prefix/"; a relative base
+ * ("./", a build-only setting) is served from the root.
+ */
+function configPath(base) {
+    const b = base.startsWith("/") ? base : "/";
+    return (b.endsWith("/") ? b : `${b}/`) + CONFIG_JS;
+}
+function requestPath(req) {
+    const url = req.url ?? "";
+    const q = url.search(/[?#]/);
+    return q < 0 ? url : url.slice(0, q);
+}
+/**
+ * forgeRuntimeConfig serves `<base>config.js` from the file forge rendered
+ * for this frontend, when there is one. Add it to `plugins` in
+ * vite.config.ts:
+ *
+ * ```ts
+ * import { forgeRuntimeConfig } from "@reliantlabs/forge-web-runtime/vite";
+ * export default defineConfig({ plugins: [react(), forgeRuntimeConfig()] });
+ * ```
+ */
+export function forgeRuntimeConfig(options = {}) {
+    const raw = options.file ?? process.env[FORGE_RUNTIME_CONFIG_FILE_ENV] ?? "";
+    const file = raw.trim() === "" ? "" : resolve(raw.trim());
+    const install = (server, live) => {
+        if (file === "")
+            return;
+        const path = configPath(server.config.base);
+        server.middlewares.use((req, res, next) => {
+            if ((req.method !== "GET" && req.method !== "HEAD") ||
+                requestPath(req) !== path) {
+                next();
+                return;
+            }
+            readFile(file, "utf8").then((body) => {
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "text/javascript; charset=utf-8");
+                // The document is per environment and re-rendered while the dev
+                // server runs; a cached copy is a stale environment.
+                res.setHeader("Cache-Control", "no-store");
+                res.end(req.method === "HEAD" ? undefined : body);
+            }, (err) => {
+                // Loud, not silent: the page will fall back to whatever
+                // public/config.js says (or to config_gen.ts's defaults), and the
+                // only clue is this line in the dev server's log.
+                server.config.logger.warn(`[forge-runtime-config] ${FORGE_RUNTIME_CONFIG_FILE_ENV}=${file} is unreadable ` +
+                    `(${err instanceof Error ? err.message : String(err)}); ` +
+                    `serving ${path} from the frontend's own tree instead. ` +
+                    "Re-run `forge env up` in the project that declares this frontend.");
+                next();
+            });
+        });
+        if (live && server.watcher) {
+            server.watcher.add(file);
+            server.watcher.on("change", (changed) => {
+                if (resolve(changed) === file) {
+                    server.ws?.send({ type: "full-reload", path: "*" });
+                }
+            });
+        }
+    };
+    return {
+        name: "forge-runtime-config",
+        configureServer(server) {
+            install(server, true);
+        },
+        configurePreviewServer(server) {
+            install(server, false);
+        },
+    };
+}
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// forgeRuntimeConfig — a Vite plugin that serves the frontend's runtime\n// config document (`config.js`, which sets `window.__FORGE_CONFIG__`) from a\n// file forge rendered OUTSIDE the frontend's own tree.\n//\n// # Why\n//\n// A frontend normally carries its dev document at `public/config.js`, written\n// by `forge generate` / `forge env up` in the project that owns the frontend.\n// A frontend whose code lives in ANOTHER repository — a sibling checkout\n// (`path: \"../reliant/web\"`) in dev, a source pin when building — has no\n// directory forge may write into: putting one repo's rendered environment in\n// another repo's working tree is a diff in someone else's `git status`. So the\n// project that declares the environment renders the document to its own\n// `.forge/runtime-config/<frontend>/config.js`, and `forge env up` hands the\n// path to the frontend's dev server as FORGE_RUNTIME_CONFIG_FILE. This plugin\n// is the dev server's half: it answers `<base>config.js` from that file.\n//\n// With the variable unset (the frontend's own repo runs its own dev server,\n// or a build) the plugin does nothing, and `public/config.js` is served as\n// before — so adding it to a vite.config.ts is safe in every mode.\n//\n// The file is read on EVERY request rather than once: `forge env up`\n// re-renders it after identity and jobs converge, and a page reload must see\n// that, not the value from when the dev server started. A change also sends\n// the page a full reload, so an open tab picks it up without a click.\n//\n// Structural types only: this module imports nothing from `vite`, so the\n// package takes no dependency on any Vite major. The plugin object is\n// assignable to Vite's `Plugin` (vite.test.ts pins that).\nimport { readFile } from \"node:fs/promises\";\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\nimport { resolve } from \"node:path\";\n\n/**\n * The environment variable `forge env up` sets on a frontend's dev server\n * when the frontend's runtime config document was rendered outside its tree.\n * Its value is an absolute path.\n */\nexport const FORGE_RUNTIME_CONFIG_FILE_ENV = \"FORGE_RUNTIME_CONFIG_FILE\";\n\n/** The document's file name, which is also the path it is served at. */\nconst CONFIG_JS = \"config.js\";\n\ntype NextFn = (err?: unknown) => void;\ntype Middleware = (\n  req: IncomingMessage,\n  res: ServerResponse,\n  next: NextFn,\n) => void;\n\n/** The part of a Vite dev / preview server this plugin uses. */\nexport interface RuntimeConfigServer {\n  config: {\n    base: string;\n    logger: { warn(msg: string): void };\n  };\n  middlewares: { use(fn: Middleware): unknown };\n  watcher?: {\n    add(paths: string | readonly string[]): unknown;\n    on(event: \"change\", listener: (path: string) => void): unknown;\n  };\n  ws?: { send(payload: { type: \"full-reload\"; path?: string }): void };\n}\n\nexport interface ForgeRuntimeConfigOptions {\n  /**\n   * The document to serve. Defaults to `process.env.FORGE_RUNTIME_CONFIG_FILE`\n   * as the dev server sees it. Empty or unset makes the plugin inert.\n   */\n  file?: string;\n}\n\n/** The plugin object; structurally a Vite `Plugin`. */\nexport interface ForgeRuntimeConfigPlugin {\n  name: string;\n  configureServer(server: RuntimeConfigServer): void;\n  configurePreviewServer(server: RuntimeConfigServer): void;\n}\n\n/**\n * configPath is the request path the document is served at under `base`.\n * Vite normalizes a dev server's base to \"/\" or \"/prefix/\"; a relative base\n * (\"./\", a build-only setting) is served from the root.\n */\nfunction configPath(base: string): string {\n  const b = base.startsWith(\"/\") ? base : \"/\";\n  return (b.endsWith(\"/\") ? b : `${b}/`) + CONFIG_JS;\n}\n\nfunction requestPath(req: IncomingMessage): string {\n  const url = req.url ?? \"\";\n  const q = url.search(/[?#]/);\n  return q < 0 ? url : url.slice(0, q);\n}\n\n/**\n * forgeRuntimeConfig serves `<base>config.js` from the file forge rendered\n * for this frontend, when there is one. Add it to `plugins` in\n * vite.config.ts:\n *\n * ```ts\n * import { forgeRuntimeConfig } from \"@reliantlabs/forge-web-runtime/vite\";\n * export default defineConfig({ plugins: [react(), forgeRuntimeConfig()] });\n * ```\n */\nexport function forgeRuntimeConfig(\n  options: ForgeRuntimeConfigOptions = {},\n): ForgeRuntimeConfigPlugin {\n  const raw = options.file ?? process.env[FORGE_RUNTIME_CONFIG_FILE_ENV] ?? \"\";\n  const file = raw.trim() === \"\" ? \"\" : resolve(raw.trim());\n\n  const install = (server: RuntimeConfigServer, live: boolean): void => {\n    if (file === \"\") return;\n    const path = configPath(server.config.base);\n    server.middlewares.use((req, res, next) => {\n      if (\n        (req.method !== \"GET\" && req.method !== \"HEAD\") ||\n        requestPath(req) !== path\n      ) {\n        next();\n        return;\n      }\n      readFile(file, \"utf8\").then(\n        (body) => {\n          res.statusCode = 200;\n          res.setHeader(\"Content-Type\", \"text/javascript; charset=utf-8\");\n          // The document is per environment and re-rendered while the dev\n          // server runs; a cached copy is a stale environment.\n          res.setHeader(\"Cache-Control\", \"no-store\");\n          res.end(req.method === \"HEAD\" ? undefined : body);\n        },\n        (err: unknown) => {\n          // Loud, not silent: the page will fall back to whatever\n          // public/config.js says (or to config_gen.ts's defaults), and the\n          // only clue is this line in the dev server's log.\n          server.config.logger.warn(\n            `[forge-runtime-config] ${FORGE_RUNTIME_CONFIG_FILE_ENV}=${file} is unreadable ` +\n              `(${err instanceof Error ? err.message : String(err)}); ` +\n              `serving ${path} from the frontend's own tree instead. ` +\n              \"Re-run `forge env up` in the project that declares this frontend.\",\n          );\n          next();\n        },\n      );\n    });\n    if (live && server.watcher) {\n      server.watcher.add(file);\n      server.watcher.on(\"change\", (changed) => {\n        if (resolve(changed) === file) {\n          server.ws?.send({ type: \"full-reload\", path: \"*\" });\n        }\n      });\n    }\n  };\n\n  return {\n    name: \"forge-runtime-config\",\n    configureServer(server) {\n      install(server, true);\n    },\n    configurePreviewServer(server) {\n      install(server, false);\n    },\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reliantlabs/forge-web-runtime",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The forge frontend runtime: Connect interceptor stack, session, error boundary, toast queue, <Resource> container, W3C trace propagation and the HyperDX browser SDK wiring (errors, console, network, traces; replay off by default). The web twin of forge/pkg.",
   "license": "Apache-2.0",
   "//repository note": "REQUIRED for `npm publish --provenance`, not decoration. npm cross-checks this against the repository in the signed provenance statement and rejects the publish with a 422 if they disagree — an absent field reads as \"\" and fails that comparison. `directory` names the subdirectory this package lives in, so the provenance points at the real source. Omitting this is what made the first 0.3.1 publish fail AFTER the tarball had been signed and written to the sigstore transparency log.",
@@ -54,6 +54,10 @@
       "types": "./dist/telemetry.d.ts",
       "default": "./dist/telemetry.js"
     },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {