@reliantlabs/forge-web-runtime 0.3.0

package/dist/errors.js

@@ -0,0 +1,199 @@
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// 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
+// human-presentable message.
+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
+ * every error. UI/routing keys off `error.reason` instead of matching
+ * human-readable message strings — the message text is display-only and
+ * may change. The backend owns the setter; the frontend only reads it.
+ */
+export const FORGE_ERROR_REASON_HEADER = "x-forge-error-reason";
+/**
+ * stripServerFraming removes the transport framing that must never surface
+ * to a user: the leading "[code] " gRPC-code prefix connect-es puts on
+ * `ConnectError.message`. What survives is the message the server wrote,
+ * which is exactly what a user should read.
+ *
+ * This is the SINGLE implementation — a project never wants a different
+ * answer here, and a copy frozen into a scaffold could never be corrected
+ * once shipped. Idempotent: framing that has already been stripped strips
+ * to itself.
+ */
+export function stripServerFraming(message) {
+    return message.replace(/^\[[a-z_]+\]\s*/i, "").trim();
+}
+/** The copy shown when an error carries no presentable message of its own. */
+const DEFAULT_USER_MESSAGE = "Something went wrong. Please try again.";
+/**
+ * userMessage — turn any thrown value into copy fit for end users.
+ *
+ * `ConnectError.message` prefixes the gRPC code ("[not_found] no such task");
+ * `rawMessage` is the server's human-readable text without that framing, and
+ * stripServerFraming drops the prefix from whichever of the two is available.
+ * Use this everywhere an error is SHOWN (banners, toasts) instead of
+ * `err.message`.
+ *
+ * Pass `fallback` to override the default copy for a surface that wants its
+ * own wording.
+ */
+export function userMessage(err, fallback = DEFAULT_USER_MESSAGE) {
+    if (err instanceof ConnectError) {
+        return stripServerFraming(err.rawMessage || err.message) || fallback;
+    }
+    if (err instanceof Error) {
+        return stripServerFraming(err.message) || fallback;
+    }
+    return err == null ? fallback : stripServerFraming(String(err)) || fallback;
+}
+/** Connect codes worth a transparent transport-level retry. */
+const RETRYABLE = new Set([
+    Code.Unavailable,
+    Code.DeadlineExceeded,
+    Code.Aborted,
+    Code.ResourceExhausted,
+]);
+/** Rough Connect-code → HTTP-status mapping for display/telemetry only. */
+const HTTP_STATUS = {
+    [Code.InvalidArgument]: 400,
+    [Code.Unauthenticated]: 401,
+    [Code.PermissionDenied]: 403,
+    [Code.NotFound]: 404,
+    [Code.AlreadyExists]: 409,
+    [Code.ResourceExhausted]: 429,
+    [Code.Unimplemented]: 501,
+    [Code.Unavailable]: 503,
+    [Code.DeadlineExceeded]: 504,
+    [Code.Internal]: 500,
+};
+/**
+ * isConnectClientErrorShape — the STRUCTURAL test behind
+ * {@link ConnectClientError}'s `instanceof`.
+ *
+ * A class object is per module instance, not per package. npm nests a
+ * transitive dependency on any version conflict, and a bundler can pull one
+ * package in as both ESM and CJS, so a tree holding two copies of this
+ * 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.
+ */
+function isConnectClientErrorShape(v) {
+    if (!(v instanceof Error))
+        return false;
+    if (Object.getPrototypeOf(v) === ConnectClientError.prototype)
+        return true;
+    const e = v;
+    return (v.name === "ConnectClientError" &&
+        typeof e.code === "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.
+ */
+export class ConnectClientError extends Error {
+    /** Canonical Connect code name, e.g. "unavailable", "not_found". */
+    code;
+    /** Numeric Connect code (Code enum), or undefined for non-Connect errors. */
+    connectCode;
+    /** Approximate HTTP status, for telemetry and generic UI. */
+    status;
+    /** True when a transparent retry is reasonable (transient failures). */
+    retryable;
+    /**
+     * Stable machine-readable reason code from the backend
+     * (x-forge-error-reason metadata), or null. Key UI/routing off THIS,
+     * never off `message` — message text is display-only.
+     */
+    reason;
+    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;
+    }
+    /**
+     * `instanceof` matches on SHAPE, not on class identity — so every check
+     * spelled `err instanceof ConnectClientError`, here and in app code, keeps
+     * 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.
+     */
+    static [Symbol.hasInstance](v) {
+        return isConnectClientErrorShape(v);
+    }
+}
+/** isRetryable reports whether a Connect code merits a transport retry. */
+export function isRetryableCode(code) {
+    return RETRYABLE.has(code);
+}
+/**
+ * normalizeError coerces any thrown value into a ConnectClientError. Already-
+ * normalized errors pass through unchanged so the interceptor chain never
+ * double-wraps.
+ *
+ * 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.
+ */
+export function normalizeError(err) {
+    if (err instanceof ConnectClientError) {
+        return err;
+    }
+    if (err instanceof ConnectError) {
+        return new ConnectClientError({
+            // 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,
+            cause: err,
+        });
+    }
+    if (err instanceof Error) {
+        // 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
+        // bare Error widened the blast radius to non-idempotent failures).
+        const networkFault = err instanceof TypeError;
+        return new ConnectClientError({
+            message: stripServerFraming(err.message),
+            code: networkFault ? "unavailable" : "unknown",
+            status: networkFault ? 503 : 500,
+            retryable: networkFault,
+            reason: null,
+            cause: err,
+        });
+    }
+    return new ConnectClientError({
+        message: typeof err === "string" ? stripServerFraming(err) : "Unknown error",
+        code: "unknown",
+        status: 500,
+        retryable: false,
+        reason: null,
+        cause: err,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +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\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(err: unknown, fallback: string = DEFAULT_USER_MESSAGE): 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  constructor(args: {\n    message: string;\n    code: string;\n    connectCode?: Code;\n    status: number;\n    retryable: boolean;\n    reason?: 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  }\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.\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(err: unknown): 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      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      cause: err,\n    });\n  }\n\n  return new ConnectClientError({\n    message: 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"]}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/** Transport interceptor stack. */
+export { authInterceptor, buildRuntimeInterceptors, errorNormalizeInterceptor, headerInterceptor, retryInterceptor, traceInterceptor, type RuntimeInterceptorConfig, } from "./interceptors.js";
+/**
+ * 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";
+/**
+ * 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.
+ *
+ * Barrel-exported rather than behind a subpath: three string functions with
+ * no imports, so there is no dependency footprint for a subpath to fence off.
+ */
+export { createBasePath, joinBasePath, normalizeBasePath, type BasePathHelpers, } from "./basepath.js";
+/** W3C trace-context propagation. */
+export { freshTraceparent, injectTraceContext, setTraceSampled, TRACEPARENT_RE, } from "./trace.js";
+/** Session: the signed-in user, derived from the app's auth state and JWT claims. */
+export { decodeJwt, SessionProvider, useSession, type JwtClaims, type Session, type SessionAuth, } from "./session.js";
+/** The app-shell provider set: session + error boundary + toast host in one. */
+export { RuntimeShell, type RuntimeShellProps } from "./providers.js";
+/** Error boundary with a designed crash fallback, for a route or a subtree. */
+export { DefaultErrorFallback, RuntimeErrorBoundary, } from "./error-boundary.js";
+/** The toast queue. The app supplies the event source and the markup. */
+export { RuntimeToastHost, type RuntimeToast, type RuntimeToastHostProps, type RuntimeToastPayload, type RuntimeToastSink, type RuntimeToastVariant, } from "./toast-host.js";
+/** Route guarding: render a page only to a signed-in caller. */
+export { RouteGuard, type RouteGuardProps } from "./route-guard.js";
+/** Generic data-table container: the tristate ladder, filter and cursor pagination. */
+export { Resource, type ResourceColumn, type ResourceProps, type ResourceStatus, } from "./resource.js";
+/** Client RUM (opt-in export). */
+export { initClientTelemetry, type TelemetryConfig, type TelemetryEvent, } from "./telemetry.js";

package/dist/index.js

@@ -0,0 +1,50 @@
+// @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// Public barrel. Import batteries from "@reliantlabs/forge-web-runtime".
+//
+// Everything here is MECHANISM: the transport interceptor stack, the session,
+// the error boundary, the toast queue, the <Resource> tristate ladder, W3C
+// trace propagation, client RUM. Nothing here reaches into an application —
+// app-shaped values (auth state, event subscriptions, toast markup) arrive as
+// props, so an app can restyle or replace its own files freely.
+//
+// Presentation that a project is meant to own — the component library under
+// src/components/ui, globals.css, nav, layout — deliberately stays in the
+// scaffold and is NOT part of this package.
+// The per-group docs below are JSDoc, not `//`, on purpose: TypeScript's
+// declaration emit preserves JSDoc and DROPS line comments, and dist/ is now
+// the whole of what this package publishes. `forge project libraries` reads
+// this inventory out of the published barrel, and a consumer's editor shows
+// it on hover — both would get symbols with no explanation otherwise.
+/** Transport interceptor stack. */
+export { authInterceptor, buildRuntimeInterceptors, errorNormalizeInterceptor, headerInterceptor, retryInterceptor, traceInterceptor, } from "./interceptors.js";
+/**
+ * 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";
+/**
+ * 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.
+ *
+ * Barrel-exported rather than behind a subpath: three string functions with
+ * no imports, so there is no dependency footprint for a subpath to fence off.
+ */
+export { createBasePath, joinBasePath, normalizeBasePath, } from "./basepath.js";
+/** W3C trace-context propagation. */
+export { freshTraceparent, injectTraceContext, setTraceSampled, TRACEPARENT_RE, } from "./trace.js";
+/** Session: the signed-in user, derived from the app's auth state and JWT claims. */
+export { decodeJwt, SessionProvider, useSession, } from "./session.js";
+/** The app-shell provider set: session + error boundary + toast host in one. */
+export { RuntimeShell } from "./providers.js";
+/** Error boundary with a designed crash fallback, for a route or a subtree. */
+export { DefaultErrorFallback, RuntimeErrorBoundary, } from "./error-boundary.js";
+/** The toast queue. The app supplies the event source and the markup. */
+export { RuntimeToastHost, } from "./toast-host.js";
+/** Route guarding: render a page only to a signed-in caller. */
+export { RouteGuard } from "./route-guard.js";
+/** Generic data-table container: the tristate ladder, filter and cursor pagination. */
+export { Resource, } from "./resource.js";
+/** Client RUM (opt-in export). */
+export { initClientTelemetry, } from "./telemetry.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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,qCAAqC;AACrC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,cAAc,GACf,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,kCAAkC;AAClC,OAAO,EACL,mBAAmB,GAGpB,MAAM,gBAAgB,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/** W3C trace-context propagation. */\nexport {\n  freshTraceparent,\n  injectTraceContext,\n  setTraceSampled,\n  TRACEPARENT_RE,\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/** Client RUM (opt-in export). */\nexport {\n  initClientTelemetry,\n  type TelemetryConfig,\n  type TelemetryEvent,\n} from \"./telemetry.js\";\n"]}

package/dist/interceptors.d.ts

@@ -0,0 +1,49 @@
+import { ConnectClientError } from "./errors.js";
+import type { Interceptor } from "@connectrpc/connect";
+/**
+ * RuntimeInterceptorConfig is the seam the app wires its runtime dependencies
+ * through. Everything is optional: an unconfigured chain still propagates
+ * traceparent and normalizes errors.
+ */
+export interface RuntimeInterceptorConfig {
+    /** Returns the current bearer token, or null when unauthenticated. */
+    getToken?: () => Promise<string | null> | string | null;
+    /** Returns the active brand, attached as the X-Brand header. */
+    getBrand?: () => string | null | undefined;
+    /** Invoked with the typed error on every failed RPC (telemetry sink). */
+    onError?: (err: ConnectClientError) => void;
+    /** Max transparent retries for retryable unary failures. Default 2. */
+    maxRetries?: number;
+    /** Base backoff in ms; grows exponentially with jitter. Default 200. */
+    retryBaseMs?: number;
+}
+/** Attaches the bearer token from the app's auth provider. */
+export declare function authInterceptor(cfg: RuntimeInterceptorConfig): Interceptor;
+/** Attaches brand context headers when the app supplies them. */
+export declare function headerInterceptor(cfg: RuntimeInterceptorConfig): Interceptor;
+/**
+ * Propagates a W3C traceparent so the backend (otelconnect + otelhttp) joins
+ * the same distributed trace. Always emits a valid header — see trace.ts.
+ */
+export declare function traceInterceptor(): Interceptor;
+/** Converts any thrown failure into a typed ConnectClientError. */
+export declare function errorNormalizeInterceptor(cfg: RuntimeInterceptorConfig): Interceptor;
+/**
+ * Transparently retries retryable failures with exponential backoff +
+ * jitter — for IDEMPOTENT requests ONLY (see retryEligible). NOT part of the
+ * default chain: React Query owns retries (see the retry-ownership note at
+ * the top of this file). Exported for callers using the raw transport
+ * outside React Query. Streaming RPCs are never retried (a partially-
+ * consumed stream can't be safely replayed).
+ */
+export declare function retryInterceptor(cfg: RuntimeInterceptorConfig): Interceptor;
+/**
+ * buildRuntimeInterceptors composes the full stack in the correct order.
+ * Pass the result to createConnectTransport's `interceptors` option.
+ *
+ * retryInterceptor is deliberately NOT included — React Query is the single
+ * 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 { freshTraceparent, injectTraceContext, setTraceSampled, TRACEPARENT_RE, } from "./trace.js";

package/dist/interceptors.js

@@ -0,0 +1,154 @@
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// This module is also the package's SECOND ENTRY POINT, published as
+// "@reliantlabs/forge-web-runtime/interceptors". It is the DOM-free, React-free
+// half of the runtime: the transport layer and nothing else. Importing it
+// pulls in exactly ./errors and ./trace — no React, no @types/react, no
+// window/document. That matters for React Native, where Expo pins React 18
+// while the package's components are typed against React 19: a mobile app
+// importing the full barrel would typecheck the components it never renders
+// and fail. Everything re-exported at the bottom of this file is part of
+// this entry point's surface; keep it React-free (guarded by
+// interceptors-entry.test.ts).
+//
+// The Connect transport interceptor stack. This is the one place every
+// frontend→backend call flows through, composed once and handed to
+// createConnectTransport by the app's own connect module. Order (outermost
+// first):
+//
+//   error-normalize → auth → brand headers → traceparent
+//
+// error-normalize is outermost so every caller sees a typed
+// ConnectClientError instead of a raw ConnectError.
+//
+// RETRY OWNERSHIP — read before adding a retry layer.
+// The single retry owner is the app's React Query client: it
+// structurally knows reads from writes, so it retries transient READ
+// failures and NEVER retries a mutation — no duplicate writes. Each React
+// Query retry re-runs the queryFn, which re-runs this whole interceptor
+// chain (fresh token + traceparent), so nothing is lost by not retrying
+// here. `retryInterceptor` below is therefore NOT in the default chain; it
+// stays exported (idempotency-gated) only for callers who use the raw
+// transport OUTSIDE React Query. Putting it back in the default chain would
+// stack two retry layers AND retry non-idempotent mutations — the bug this
+// split fixed.
+import { MethodOptions_IdempotencyLevel } from "@bufbuild/protobuf/wkt";
+import { ConnectClientError, normalizeError } from "./errors.js";
+import { injectTraceContext } from "./trace.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Attaches the bearer token from the app's auth provider. */
+export function authInterceptor(cfg) {
+    return (next) => async (req) => {
+        const token = cfg.getToken ? await cfg.getToken() : null;
+        if (token) {
+            req.header.set("Authorization", `Bearer ${token}`);
+        }
+        return next(req);
+    };
+}
+/** Attaches brand context headers when the app supplies them. */
+export function headerInterceptor(cfg) {
+    return (next) => async (req) => {
+        const brand = cfg.getBrand?.();
+        if (brand) {
+            req.header.set("X-Brand", brand);
+        }
+        return next(req);
+    };
+}
+/**
+ * Propagates a W3C traceparent so the backend (otelconnect + otelhttp) joins
+ * the same distributed trace. Always emits a valid header — see trace.ts.
+ */
+export function traceInterceptor() {
+    return (next) => async (req) => {
+        injectTraceContext(req.header);
+        return next(req);
+    };
+}
+/** Converts any thrown failure into a typed ConnectClientError. */
+export function errorNormalizeInterceptor(cfg) {
+    return (next) => async (req) => {
+        try {
+            return await next(req);
+        }
+        catch (err) {
+            const normalized = normalizeError(err);
+            cfg.onError?.(normalized);
+            throw normalized;
+        }
+    };
+}
+/**
+ * retryEligible reports whether a request is SAFE to retry transparently:
+ * a no-side-effects / idempotent method (declared via proto
+ * `idempotency_level`), or one carrying an explicit Idempotency-Key header.
+ * A plain mutation (the default IDEMPOTENCY_UNKNOWN) is never retried, so a
+ * transparent retry can't produce a duplicate write.
+ */
+function retryEligible(req) {
+    const level = req.method.idempotency;
+    if (level === MethodOptions_IdempotencyLevel.NO_SIDE_EFFECTS ||
+        level === MethodOptions_IdempotencyLevel.IDEMPOTENT) {
+        return true;
+    }
+    return req.header.has("Idempotency-Key");
+}
+/**
+ * Transparently retries retryable failures with exponential backoff +
+ * jitter — for IDEMPOTENT requests ONLY (see retryEligible). NOT part of the
+ * default chain: React Query owns retries (see the retry-ownership note at
+ * the top of this file). Exported for callers using the raw transport
+ * outside React Query. Streaming RPCs are never retried (a partially-
+ * consumed stream can't be safely replayed).
+ */
+export function retryInterceptor(cfg) {
+    const max = cfg.maxRetries ?? 2;
+    const base = cfg.retryBaseMs ?? 200;
+    return (next) => async (req) => {
+        if (req.stream || !retryEligible(req)) {
+            return next(req);
+        }
+        let attempt = 0;
+        for (;;) {
+            try {
+                return await next(req);
+            }
+            catch (err) {
+                const normalized = err instanceof ConnectClientError ? err : normalizeError(err);
+                if (attempt >= max || !normalized.retryable) {
+                    throw normalized;
+                }
+                const backoff = base * 2 ** attempt + Math.random() * base;
+                await sleep(backoff);
+                attempt++;
+            }
+        }
+    };
+}
+/**
+ * buildRuntimeInterceptors composes the full stack in the correct order.
+ * Pass the result to createConnectTransport's `interceptors` option.
+ *
+ * retryInterceptor is deliberately NOT included — React Query is the single
+ * retry owner (see the retry-ownership note at the top of this file).
+ */
+export function buildRuntimeInterceptors(cfg = {}) {
+    return [
+        errorNormalizeInterceptor(cfg),
+        authInterceptor(cfg),
+        headerInterceptor(cfg),
+        traceInterceptor(),
+    ];
+}
+// ── The rest of the transport-layer surface ──────────────────────────────
+//
+// These belong to this entry point because the interceptor stack's contract
+// is expressed in them: errorNormalizeInterceptor THROWS ConnectClientError
+// and RuntimeInterceptorConfig.onError RECEIVES one, so a consumer cannot
+// 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 { freshTraceparent, injectTraceContext, setTraceSampled, TRACEPARENT_RE, } from "./trace.js";
+//# sourceMappingURL=interceptors.js.map

package/dist/interceptors.js.map

@@ -0,0 +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 { injectTraceContext } from \"./trace.js\";\n\nimport type { Interceptor, UnaryRequest, StreamRequest } 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 */\nexport function traceInterceptor(): Interceptor {\n  return (next) => async (req) => {\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      const normalized = normalizeError(err);\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  TRACEPARENT_RE,\n} from \"./trace.js\";\n"]}