@webpieces/core-util 0.4.879 → 0.4.881

package/src/errors/EndUserErrorCode.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EndUserErrorCode = void 0;
+/**
+ * The grammar of `ApiEndUserError.errorCode`: `<code>[:<detail>]`.
+ *
+ * - `<code>` names WHICH mistake it was (`user-not-found`, `terms-not-accepted`). It is what
+ *   {@link EndUserErrorRegistry} matches on to rebuild the subclass on the receiving side, so it must
+ *   not itself contain a `:`.
+ * - `<detail>` is optional DATA the client acts on (the id that was not found, the terms version to
+ *   accept), never prose: prose belongs in the message. Everything after the FIRST `:` is the detail,
+ *   so a detail may itself contain colons.
+ *
+ * Kept as one tiny stateless class so a throw site, the registry and an app's own client code all
+ * split the string the same way.
+ */
+class EndUserErrorCode {
+    static SEPARATOR = ':';
+    /** `code` alone, or `code:detail` when a detail is given. */
+    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server
+    static format(code, detail) {
+        return detail === undefined ? code : `${code}${EndUserErrorCode.SEPARATOR}${detail}`;
+    }
+    /** The `<code>` part: everything before the first `:`, or the whole string when there is none. */
+    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server
+    static codeOf(errorCode) {
+        const at = errorCode.indexOf(EndUserErrorCode.SEPARATOR);
+        return at < 0 ? errorCode : errorCode.slice(0, at);
+    }
+    /** The `<detail>` part: everything after the first `:`, or undefined when there is none. */
+    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server
+    static detailOf(errorCode) {
+        const at = errorCode.indexOf(EndUserErrorCode.SEPARATOR);
+        return at < 0 ? undefined : errorCode.slice(at + 1);
+    }
+}
+exports.EndUserErrorCode = EndUserErrorCode;
+//# sourceMappingURL=EndUserErrorCode.js.map

package/src/errors/EndUserErrorCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EndUserErrorCode.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/EndUserErrorCode.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,MAAa,gBAAgB;IACzB,MAAM,CAAU,SAAS,GAAG,GAAG,CAAC;IAEhC,6DAA6D;IAC7D,uGAAuG;IACvG,MAAM,CAAC,MAAM,CAAC,IAAY,EAAE,MAAe;QACvC,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,gBAAgB,CAAC,SAAS,GAAG,MAAM,EAAE,CAAC;IACzF,CAAC;IAED,kGAAkG;IAClG,uGAAuG;IACvG,MAAM,CAAC,MAAM,CAAC,SAAiB;QAC3B,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACzD,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,4FAA4F;IAC5F,uGAAuG;IACvG,MAAM,CAAC,QAAQ,CAAC,SAAiB;QAC7B,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACzD,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACxD,CAAC;;AArBL,4CAsBC","sourcesContent":["/**\n * The grammar of `ApiEndUserError.errorCode`: `<code>[:<detail>]`.\n *\n * - `<code>` names WHICH mistake it was (`user-not-found`, `terms-not-accepted`). It is what\n *   {@link EndUserErrorRegistry} matches on to rebuild the subclass on the receiving side, so it must\n *   not itself contain a `:`.\n * - `<detail>` is optional DATA the client acts on (the id that was not found, the terms version to\n *   accept), never prose: prose belongs in the message. Everything after the FIRST `:` is the detail,\n *   so a detail may itself contain colons.\n *\n * Kept as one tiny stateless class so a throw site, the registry and an app's own client code all\n * split the string the same way.\n */\nexport class EndUserErrorCode {\n    static readonly SEPARATOR = ':';\n\n    /** `code` alone, or `code:detail` when a detail is given. */\n    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server\n    static format(code: string, detail?: string): string {\n        return detail === undefined ? code : `${code}${EndUserErrorCode.SEPARATOR}${detail}`;\n    }\n\n    /** The `<code>` part: everything before the first `:`, or the whole string when there is none. */\n    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server\n    static codeOf(errorCode: string): string {\n        const at = errorCode.indexOf(EndUserErrorCode.SEPARATOR);\n        return at < 0 ? errorCode : errorCode.slice(0, at);\n    }\n\n    /** The `<detail>` part: everything after the first `:`, or undefined when there is none. */\n    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server\n    static detailOf(errorCode: string): string | undefined {\n        const at = errorCode.indexOf(EndUserErrorCode.SEPARATOR);\n        return at < 0 ? undefined : errorCode.slice(at + 1);\n    }\n}\n"]}

package/src/errors/EndUserErrorRegistry.d.ts

@@ -0,0 +1,61 @@
+import { ApiEndUserError, EdgeHttpStatus } from './ApiError';
+/**
+ * Rebuilds one registered {@link ApiEndUserError} subclass from what crossed the wire. It receives
+ * the published message and the `<detail>` half of `errorCode` (see {@link EndUserErrorCode}); the
+ * subclass's constructor fixes the `<code>` half itself.
+ */
+export type EndUserErrorFactory = (message: string, detail: string | undefined) => ApiEndUserError;
+/**
+ * errorCode -> {@link ApiEndUserError} SUBCLASS, so the receiving side of a 266 can `instanceof` WHICH
+ * mistake it was (send the person to the Terms page, treat a missing item as "it was deleted")
+ * instead of string-matching `errorCode` at every catch site.
+ *
+ * `ApiErrorCodec` consults it for every decoded `end-user` payload, which is the one decode HTTP
+ * (`WebpiecesDefaultErrorTranslator.fromWire`), IPC and JSONL streams all share, so a registration
+ * covers every protocol at once. Matching is on the `<code>` half of the `<code>[:<detail>]` grammar.
+ * An UNKNOWN code decodes to the base `ApiEndUserError` with `errorCode` and `edgeHttpStatus` intact:
+ * forward compatible, an old client receiving a new code still shows the message.
+ *
+ * REGISTER ONCE AT STARTUP, in EVERY process that may receive the error: the browser bundle, the
+ * Expo shell and every server. A server needs it too, because a server that receives a 266 from a
+ * peer rethrows the decoded error to its own caller, and only a decoded subclass is still that
+ * subclass when the next hop catches it.
+ *
+ * ```ts
+ * export class TermsNotAcceptedError extends ApiEndUserError {
+ *     static readonly CODE = 'terms-not-accepted';
+ *     constructor(message: string, detail?: string, cause?: Error) {
+ *         super(message, EndUserErrorCode.format(TermsNotAcceptedError.CODE, detail), undefined, cause);
+ *     }
+ * }
+ *
+ * // startup, ONCE per process (browser AND server)
+ * EndUserErrorRegistry.register(TermsNotAcceptedError.CODE,
+ *     (message: string, detail: string | undefined) => new TermsNotAcceptedError(message, detail));
+ * ```
+ *
+ * The webpieces generics ({@link ApiEndUserNotFoundError}, {@link ApiEndUserForbiddenError},
+ * {@link ApiEndUserBadRequestError}) are PRE-REGISTERED here, so they decode typed with no setup.
+ * App-specific subclasses stay in the app.
+ *
+ * Process-global and static, like `ClientRegistry` / `HeaderRegistry`: the codec that consults it is
+ * a static, protocol-neutral decoder reached from the browser, node and IPC alike, and a registration
+ * is a fact about the PROCESS's error taxonomy, not about any one client.
+ */
+export declare class EndUserErrorRegistry {
+    private static readonly factories;
+    /**
+     * Register the subclass for `code`. `code` is the bare `<code>` (no `:`), normally the subclass's
+     * static `CODE`. Registering a code twice THROWS: two classes claiming one code is a collision
+     * that would otherwise decode to whichever registered last, depending on startup order.
+     */
+    static register(code: string, factory: EndUserErrorFactory): void;
+    /**
+     * The decoded end-user error for a received payload: the registered subclass for `errorCode`'s
+     * `<code>`, else the base {@link ApiEndUserError} carrying everything the wire sent.
+     */
+    static create(message: string, errorCode?: string, edgeHttpStatus?: EdgeHttpStatus): ApiEndUserError;
+    /** Back to a fresh process: the webpieces built-ins only. For TESTS, so specs cannot leak. */
+    static resetForTests(): void;
+    private static builtIns;
+}

package/src/errors/EndUserErrorRegistry.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EndUserErrorRegistry = void 0;
+const ApiError_1 = require("./ApiError");
+const EndUserErrorCode_1 = require("./EndUserErrorCode");
+const EndUserErrors_1 = require("./EndUserErrors");
+/**
+ * errorCode -> {@link ApiEndUserError} SUBCLASS, so the receiving side of a 266 can `instanceof` WHICH
+ * mistake it was (send the person to the Terms page, treat a missing item as "it was deleted")
+ * instead of string-matching `errorCode` at every catch site.
+ *
+ * `ApiErrorCodec` consults it for every decoded `end-user` payload, which is the one decode HTTP
+ * (`WebpiecesDefaultErrorTranslator.fromWire`), IPC and JSONL streams all share, so a registration
+ * covers every protocol at once. Matching is on the `<code>` half of the `<code>[:<detail>]` grammar.
+ * An UNKNOWN code decodes to the base `ApiEndUserError` with `errorCode` and `edgeHttpStatus` intact:
+ * forward compatible, an old client receiving a new code still shows the message.
+ *
+ * REGISTER ONCE AT STARTUP, in EVERY process that may receive the error: the browser bundle, the
+ * Expo shell and every server. A server needs it too, because a server that receives a 266 from a
+ * peer rethrows the decoded error to its own caller, and only a decoded subclass is still that
+ * subclass when the next hop catches it.
+ *
+ * ```ts
+ * export class TermsNotAcceptedError extends ApiEndUserError {
+ *     static readonly CODE = 'terms-not-accepted';
+ *     constructor(message: string, detail?: string, cause?: Error) {
+ *         super(message, EndUserErrorCode.format(TermsNotAcceptedError.CODE, detail), undefined, cause);
+ *     }
+ * }
+ *
+ * // startup, ONCE per process (browser AND server)
+ * EndUserErrorRegistry.register(TermsNotAcceptedError.CODE,
+ *     (message: string, detail: string | undefined) => new TermsNotAcceptedError(message, detail));
+ * ```
+ *
+ * The webpieces generics ({@link ApiEndUserNotFoundError}, {@link ApiEndUserForbiddenError},
+ * {@link ApiEndUserBadRequestError}) are PRE-REGISTERED here, so they decode typed with no setup.
+ * App-specific subclasses stay in the app.
+ *
+ * Process-global and static, like `ClientRegistry` / `HeaderRegistry`: the codec that consults it is
+ * a static, protocol-neutral decoder reached from the browser, node and IPC alike, and a registration
+ * is a fact about the PROCESS's error taxonomy, not about any one client.
+ */
+class EndUserErrorRegistry {
+    static factories = EndUserErrorRegistry.builtIns();
+    /**
+     * Register the subclass for `code`. `code` is the bare `<code>` (no `:`), normally the subclass's
+     * static `CODE`. Registering a code twice THROWS: two classes claiming one code is a collision
+     * that would otherwise decode to whichever registered last, depending on startup order.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like ClientRegistry/HeaderRegistry); populated once at startup, never DI-injected
+    static register(code, factory) {
+        if (code.length === 0 || code.includes(EndUserErrorCode_1.EndUserErrorCode.SEPARATOR)) {
+            throw new ApiError_1.ApiImplementationError(`EndUserErrorRegistry.register('${code}'): a code must be non-empty and must not ` +
+                `contain '${EndUserErrorCode_1.EndUserErrorCode.SEPARATOR}'. The errorCode grammar is ` +
+                `<code>[:<detail>]; register the bare <code>, normally the subclass's static CODE.`);
+        }
+        if (EndUserErrorRegistry.factories.has(code)) {
+            throw new ApiError_1.ApiImplementationError(`EndUserErrorRegistry.register('${code}'): that code is already registered. Two ` +
+                `ApiEndUserError subclasses cannot share one errorCode; rename one of them. ` +
+                `(Tests: call EndUserErrorRegistry.resetForTests() between specs.)`);
+        }
+        EndUserErrorRegistry.factories.set(code, factory);
+    }
+    /**
+     * The decoded end-user error for a received payload: the registered subclass for `errorCode`'s
+     * `<code>`, else the base {@link ApiEndUserError} carrying everything the wire sent.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like ClientRegistry/HeaderRegistry); populated once at startup, never DI-injected
+    static create(message, errorCode, edgeHttpStatus) {
+        if (errorCode === undefined)
+            return new ApiError_1.ApiEndUserError(message, errorCode, edgeHttpStatus);
+        const factory = EndUserErrorRegistry.factories.get(EndUserErrorCode_1.EndUserErrorCode.codeOf(errorCode));
+        if (factory === undefined)
+            return new ApiError_1.ApiEndUserError(message, errorCode, edgeHttpStatus);
+        return factory(message, EndUserErrorCode_1.EndUserErrorCode.detailOf(errorCode));
+    }
+    /** Back to a fresh process: the webpieces built-ins only. For TESTS, so specs cannot leak. */
+    // webpieces-disable no-function-outside-class -- static global singleton (like ClientRegistry/HeaderRegistry); populated once at startup, never DI-injected
+    static resetForTests() {
+        EndUserErrorRegistry.factories.clear();
+        EndUserErrorRegistry.builtIns().forEach((factory, code) => EndUserErrorRegistry.factories.set(code, factory));
+    }
+    // webpieces-disable no-function-outside-class -- the built-in table, shared by the initializer and resetForTests
+    static builtIns() {
+        return new Map([
+            [
+                EndUserErrors_1.ApiEndUserNotFoundError.CODE,
+                (message, detail) => new EndUserErrors_1.ApiEndUserNotFoundError(message, detail),
+            ],
+            [
+                EndUserErrors_1.ApiEndUserForbiddenError.CODE,
+                (message, detail) => new EndUserErrors_1.ApiEndUserForbiddenError(message, detail),
+            ],
+            [
+                EndUserErrors_1.ApiEndUserBadRequestError.CODE,
+                (message, detail) => new EndUserErrors_1.ApiEndUserBadRequestError(message, detail),
+            ],
+        ]);
+    }
+}
+exports.EndUserErrorRegistry = EndUserErrorRegistry;
+//# sourceMappingURL=EndUserErrorRegistry.js.map

package/src/errors/EndUserErrorRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EndUserErrorRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/EndUserErrorRegistry.ts"],"names":[],"mappings":";;;AAAA,yCAAqF;AACrF,yDAAsD;AACtD,mDAIyB;AASzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAa,oBAAoB;IACrB,MAAM,CAAU,SAAS,GAAG,oBAAoB,CAAC,QAAQ,EAAE,CAAC;IAEpE;;;;OAIG;IACH,4JAA4J;IAC5J,MAAM,CAAC,QAAQ,CAAC,IAAY,EAAE,OAA4B;QACtD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,mCAAgB,CAAC,SAAS,CAAC,EAAE,CAAC;YACjE,MAAM,IAAI,iCAAsB,CAC5B,kCAAkC,IAAI,4CAA4C;gBAC9E,YAAY,mCAAgB,CAAC,SAAS,8BAA8B;gBACpE,mFAAmF,CAC1F,CAAC;QACN,CAAC;QACD,IAAI,oBAAoB,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,iCAAsB,CAC5B,kCAAkC,IAAI,2CAA2C;gBAC7E,6EAA6E;gBAC7E,mEAAmE,CAC1E,CAAC;QACN,CAAC;QACD,oBAAoB,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAED;;;OAGG;IACH,4JAA4J;IAC5J,MAAM,CAAC,MAAM,CACT,OAAe,EACf,SAAkB,EAClB,cAA+B;QAE/B,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,IAAI,0BAAe,CAAC,OAAO,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;QAC5F,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,GAAG,CAAC,mCAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QACvF,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,IAAI,0BAAe,CAAC,OAAO,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;QAC1F,OAAO,OAAO,CAAC,OAAO,EAAE,mCAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,8FAA8F;IAC9F,4JAA4J;IAC5J,MAAM,CAAC,aAAa;QAChB,oBAAoB,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvC,oBAAoB,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,OAA4B,EAAE,IAAY,EAAE,EAAE,CACnF,oBAAoB,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CACpD,CAAC;IACN,CAAC;IAED,iHAAiH;IACzG,MAAM,CAAC,QAAQ;QACnB,OAAO,IAAI,GAAG,CAA8B;YACxC;gBACI,uCAAuB,CAAC,IAAI;gBAC5B,CAAC,OAAe,EAAE,MAA0B,EAAE,EAAE,CAC5C,IAAI,uCAAuB,CAAC,OAAO,EAAE,MAAM,CAAC;aACnD;YACD;gBACI,wCAAwB,CAAC,IAAI;gBAC7B,CAAC,OAAe,EAAE,MAA0B,EAAE,EAAE,CAC5C,IAAI,wCAAwB,CAAC,OAAO,EAAE,MAAM,CAAC;aACpD;YACD;gBACI,yCAAyB,CAAC,IAAI;gBAC9B,CAAC,OAAe,EAAE,MAA0B,EAAE,EAAE,CAC5C,IAAI,yCAAyB,CAAC,OAAO,EAAE,MAAM,CAAC;aACrD;SACJ,CAAC,CAAC;IACP,CAAC;;AAvEL,oDAwEC","sourcesContent":["import { ApiEndUserError, ApiImplementationError, EdgeHttpStatus } from './ApiError';\nimport { EndUserErrorCode } from './EndUserErrorCode';\nimport {\n    ApiEndUserBadRequestError,\n    ApiEndUserForbiddenError,\n    ApiEndUserNotFoundError,\n} from './EndUserErrors';\n\n/**\n * Rebuilds one registered {@link ApiEndUserError} subclass from what crossed the wire. It receives\n * the published message and the `<detail>` half of `errorCode` (see {@link EndUserErrorCode}); the\n * subclass's constructor fixes the `<code>` half itself.\n */\nexport type EndUserErrorFactory = (message: string, detail: string | undefined) => ApiEndUserError;\n\n/**\n * errorCode -> {@link ApiEndUserError} SUBCLASS, so the receiving side of a 266 can `instanceof` WHICH\n * mistake it was (send the person to the Terms page, treat a missing item as \"it was deleted\")\n * instead of string-matching `errorCode` at every catch site.\n *\n * `ApiErrorCodec` consults it for every decoded `end-user` payload, which is the one decode HTTP\n * (`WebpiecesDefaultErrorTranslator.fromWire`), IPC and JSONL streams all share, so a registration\n * covers every protocol at once. Matching is on the `<code>` half of the `<code>[:<detail>]` grammar.\n * An UNKNOWN code decodes to the base `ApiEndUserError` with `errorCode` and `edgeHttpStatus` intact:\n * forward compatible, an old client receiving a new code still shows the message.\n *\n * REGISTER ONCE AT STARTUP, in EVERY process that may receive the error: the browser bundle, the\n * Expo shell and every server. A server needs it too, because a server that receives a 266 from a\n * peer rethrows the decoded error to its own caller, and only a decoded subclass is still that\n * subclass when the next hop catches it.\n *\n * ```ts\n * export class TermsNotAcceptedError extends ApiEndUserError {\n *     static readonly CODE = 'terms-not-accepted';\n *     constructor(message: string, detail?: string, cause?: Error) {\n *         super(message, EndUserErrorCode.format(TermsNotAcceptedError.CODE, detail), undefined, cause);\n *     }\n * }\n *\n * // startup, ONCE per process (browser AND server)\n * EndUserErrorRegistry.register(TermsNotAcceptedError.CODE,\n *     (message: string, detail: string | undefined) => new TermsNotAcceptedError(message, detail));\n * ```\n *\n * The webpieces generics ({@link ApiEndUserNotFoundError}, {@link ApiEndUserForbiddenError},\n * {@link ApiEndUserBadRequestError}) are PRE-REGISTERED here, so they decode typed with no setup.\n * App-specific subclasses stay in the app.\n *\n * Process-global and static, like `ClientRegistry` / `HeaderRegistry`: the codec that consults it is\n * a static, protocol-neutral decoder reached from the browser, node and IPC alike, and a registration\n * is a fact about the PROCESS's error taxonomy, not about any one client.\n */\nexport class EndUserErrorRegistry {\n    private static readonly factories = EndUserErrorRegistry.builtIns();\n\n    /**\n     * Register the subclass for `code`. `code` is the bare `<code>` (no `:`), normally the subclass's\n     * static `CODE`. Registering a code twice THROWS: two classes claiming one code is a collision\n     * that would otherwise decode to whichever registered last, depending on startup order.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like ClientRegistry/HeaderRegistry); populated once at startup, never DI-injected\n    static register(code: string, factory: EndUserErrorFactory): void {\n        if (code.length === 0 || code.includes(EndUserErrorCode.SEPARATOR)) {\n            throw new ApiImplementationError(\n                `EndUserErrorRegistry.register('${code}'): a code must be non-empty and must not ` +\n                    `contain '${EndUserErrorCode.SEPARATOR}'. The errorCode grammar is ` +\n                    `<code>[:<detail>]; register the bare <code>, normally the subclass's static CODE.`,\n            );\n        }\n        if (EndUserErrorRegistry.factories.has(code)) {\n            throw new ApiImplementationError(\n                `EndUserErrorRegistry.register('${code}'): that code is already registered. Two ` +\n                    `ApiEndUserError subclasses cannot share one errorCode; rename one of them. ` +\n                    `(Tests: call EndUserErrorRegistry.resetForTests() between specs.)`,\n            );\n        }\n        EndUserErrorRegistry.factories.set(code, factory);\n    }\n\n    /**\n     * The decoded end-user error for a received payload: the registered subclass for `errorCode`'s\n     * `<code>`, else the base {@link ApiEndUserError} carrying everything the wire sent.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like ClientRegistry/HeaderRegistry); populated once at startup, never DI-injected\n    static create(\n        message: string,\n        errorCode?: string,\n        edgeHttpStatus?: EdgeHttpStatus,\n    ): ApiEndUserError {\n        if (errorCode === undefined) return new ApiEndUserError(message, errorCode, edgeHttpStatus);\n        const factory = EndUserErrorRegistry.factories.get(EndUserErrorCode.codeOf(errorCode));\n        if (factory === undefined) return new ApiEndUserError(message, errorCode, edgeHttpStatus);\n        return factory(message, EndUserErrorCode.detailOf(errorCode));\n    }\n\n    /** Back to a fresh process: the webpieces built-ins only. For TESTS, so specs cannot leak. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like ClientRegistry/HeaderRegistry); populated once at startup, never DI-injected\n    static resetForTests(): void {\n        EndUserErrorRegistry.factories.clear();\n        EndUserErrorRegistry.builtIns().forEach((factory: EndUserErrorFactory, code: string) =>\n            EndUserErrorRegistry.factories.set(code, factory),\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- the built-in table, shared by the initializer and resetForTests\n    private static builtIns(): Map<string, EndUserErrorFactory> {\n        return new Map<string, EndUserErrorFactory>([\n            [\n                ApiEndUserNotFoundError.CODE,\n                (message: string, detail: string | undefined) =>\n                    new ApiEndUserNotFoundError(message, detail),\n            ],\n            [\n                ApiEndUserForbiddenError.CODE,\n                (message: string, detail: string | undefined) =>\n                    new ApiEndUserForbiddenError(message, detail),\n            ],\n            [\n                ApiEndUserBadRequestError.CODE,\n                (message: string, detail: string | undefined) =>\n                    new ApiEndUserBadRequestError(message, detail),\n            ],\n        ]);\n    }\n}\n"]}

package/src/errors/EndUserErrors.d.ts

@@ -0,0 +1,28 @@
+import { ApiEndUserError } from './ApiError';
+/**
+ * The thing the end user asked about does not exist (or no longer does): "that report was deleted".
+ * A partner-facing edge answers 404 for it.
+ */
+export declare class ApiEndUserNotFoundError extends ApiEndUserError {
+    static readonly CODE = "user-not-found";
+    constructor(message: string, detail?: string, cause?: Error);
+}
+/**
+ * The end user may not do this, and the message tells them why ("only the owner can delete this
+ * board"). Deliberately NOT `ApiForbiddenError`: that is a 403 authorization failure whose text is
+ * never published, while this is an expected answer shown to the person verbatim. It sets no
+ * `edgeHttpStatus`, because `EdgeHttpStatus` excludes 403 on purpose: authorization keeps its own type.
+ */
+export declare class ApiEndUserForbiddenError extends ApiEndUserError {
+    static readonly CODE = "user-forbidden";
+    constructor(message: string, detail?: string, cause?: Error);
+}
+/**
+ * The end user's input was well-formed but wrong in a way they must fix ("the two passwords do not
+ * match"). A partner-facing edge answers 400 for it. Distinct from `ApiBadRequestError`, whose
+ * `message` is operator-only and which means the CALLER built a bad request.
+ */
+export declare class ApiEndUserBadRequestError extends ApiEndUserError {
+    static readonly CODE = "user-bad-request";
+    constructor(message: string, detail?: string, cause?: Error);
+}

package/src/errors/EndUserErrors.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiEndUserBadRequestError = exports.ApiEndUserForbiddenError = exports.ApiEndUserNotFoundError = void 0;
+const ApiError_1 = require("./ApiError");
+const EndUserErrorCode_1 = require("./EndUserErrorCode");
+/*
+ * The generic end-user subclasses webpieces ships. Each one follows THE subclass pattern (issue
+ * #1173), which an app copies for its own (terms-not-accepted, domain refusals):
+ *
+ *   1. `CODE` is a static constant and the constructor FIXES it, so a throw site cannot send a missing
+ *      or misspelled code; the caller supplies only the message and, optionally, a `detail` (data the
+ *      client acts on, never prose — see EndUserErrorCode).
+ *   2. It is REGISTERED ONCE at startup, in every process that may receive it (browser bundle, Expo
+ *      shell, every server), so `fromWire(toWire(new X(...)))` is an `X` on both ends of every hop:
+ *
+ *        EndUserErrorRegistry.register(TermsNotAcceptedError.CODE,
+ *            (message: string, detail: string | undefined) => new TermsNotAcceptedError(message, detail));
+ *
+ * These three are pre-registered by webpieces itself (see EndUserErrorRegistry), so they decode typed
+ * with no app setup. Their codes carry a `user-` prefix so they cannot collide with an `ApiErrorKind`
+ * of the same name and so an app's own short codes stay free.
+ */
+/**
+ * The thing the end user asked about does not exist (or no longer does): "that report was deleted".
+ * A partner-facing edge answers 404 for it.
+ */
+class ApiEndUserNotFoundError extends ApiError_1.ApiEndUserError {
+    static CODE = 'user-not-found';
+    constructor(message, detail, cause) {
+        super(message, EndUserErrorCode_1.EndUserErrorCode.format(ApiEndUserNotFoundError.CODE, detail), 404, cause);
+    }
+}
+exports.ApiEndUserNotFoundError = ApiEndUserNotFoundError;
+/**
+ * The end user may not do this, and the message tells them why ("only the owner can delete this
+ * board"). Deliberately NOT `ApiForbiddenError`: that is a 403 authorization failure whose text is
+ * never published, while this is an expected answer shown to the person verbatim. It sets no
+ * `edgeHttpStatus`, because `EdgeHttpStatus` excludes 403 on purpose: authorization keeps its own type.
+ */
+class ApiEndUserForbiddenError extends ApiError_1.ApiEndUserError {
+    static CODE = 'user-forbidden';
+    constructor(message, detail, cause) {
+        super(message, EndUserErrorCode_1.EndUserErrorCode.format(ApiEndUserForbiddenError.CODE, detail), undefined, cause);
+    }
+}
+exports.ApiEndUserForbiddenError = ApiEndUserForbiddenError;
+/**
+ * The end user's input was well-formed but wrong in a way they must fix ("the two passwords do not
+ * match"). A partner-facing edge answers 400 for it. Distinct from `ApiBadRequestError`, whose
+ * `message` is operator-only and which means the CALLER built a bad request.
+ */
+class ApiEndUserBadRequestError extends ApiError_1.ApiEndUserError {
+    static CODE = 'user-bad-request';
+    constructor(message, detail, cause) {
+        super(message, EndUserErrorCode_1.EndUserErrorCode.format(ApiEndUserBadRequestError.CODE, detail), 400, cause);
+    }
+}
+exports.ApiEndUserBadRequestError = ApiEndUserBadRequestError;
+//# sourceMappingURL=EndUserErrors.js.map

package/src/errors/EndUserErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EndUserErrors.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/EndUserErrors.ts"],"names":[],"mappings":";;;AAAA,yCAA6C;AAC7C,yDAAsD;AAEtD;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,MAAa,uBAAwB,SAAQ,0BAAe;IACxD,MAAM,CAAU,IAAI,GAAG,gBAAgB,CAAC;IAExC,YAAY,OAAe,EAAE,MAAe,EAAE,KAAa;QACvD,KAAK,CAAC,OAAO,EAAE,mCAAgB,CAAC,MAAM,CAAC,uBAAuB,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9F,CAAC;;AALL,0DAMC;AAED;;;;;GAKG;AACH,MAAa,wBAAyB,SAAQ,0BAAe;IACzD,MAAM,CAAU,IAAI,GAAG,gBAAgB,CAAC;IAExC,YAAY,OAAe,EAAE,MAAe,EAAE,KAAa;QACvD,KAAK,CACD,OAAO,EACP,mCAAgB,CAAC,MAAM,CAAC,wBAAwB,CAAC,IAAI,EAAE,MAAM,CAAC,EAC9D,SAAS,EACT,KAAK,CACR,CAAC;IACN,CAAC;;AAVL,4DAWC;AAED;;;;GAIG;AACH,MAAa,yBAA0B,SAAQ,0BAAe;IAC1D,MAAM,CAAU,IAAI,GAAG,kBAAkB,CAAC;IAE1C,YAAY,OAAe,EAAE,MAAe,EAAE,KAAa;QACvD,KAAK,CAAC,OAAO,EAAE,mCAAgB,CAAC,MAAM,CAAC,yBAAyB,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAChG,CAAC;;AALL,8DAMC","sourcesContent":["import { ApiEndUserError } from './ApiError';\nimport { EndUserErrorCode } from './EndUserErrorCode';\n\n/*\n * The generic end-user subclasses webpieces ships. Each one follows THE subclass pattern (issue\n * #1173), which an app copies for its own (terms-not-accepted, domain refusals):\n *\n *   1. `CODE` is a static constant and the constructor FIXES it, so a throw site cannot send a missing\n *      or misspelled code; the caller supplies only the message and, optionally, a `detail` (data the\n *      client acts on, never prose — see EndUserErrorCode).\n *   2. It is REGISTERED ONCE at startup, in every process that may receive it (browser bundle, Expo\n *      shell, every server), so `fromWire(toWire(new X(...)))` is an `X` on both ends of every hop:\n *\n *        EndUserErrorRegistry.register(TermsNotAcceptedError.CODE,\n *            (message: string, detail: string | undefined) => new TermsNotAcceptedError(message, detail));\n *\n * These three are pre-registered by webpieces itself (see EndUserErrorRegistry), so they decode typed\n * with no app setup. Their codes carry a `user-` prefix so they cannot collide with an `ApiErrorKind`\n * of the same name and so an app's own short codes stay free.\n */\n\n/**\n * The thing the end user asked about does not exist (or no longer does): \"that report was deleted\".\n * A partner-facing edge answers 404 for it.\n */\nexport class ApiEndUserNotFoundError extends ApiEndUserError {\n    static readonly CODE = 'user-not-found';\n\n    constructor(message: string, detail?: string, cause?: Error) {\n        super(message, EndUserErrorCode.format(ApiEndUserNotFoundError.CODE, detail), 404, cause);\n    }\n}\n\n/**\n * The end user may not do this, and the message tells them why (\"only the owner can delete this\n * board\"). Deliberately NOT `ApiForbiddenError`: that is a 403 authorization failure whose text is\n * never published, while this is an expected answer shown to the person verbatim. It sets no\n * `edgeHttpStatus`, because `EdgeHttpStatus` excludes 403 on purpose: authorization keeps its own type.\n */\nexport class ApiEndUserForbiddenError extends ApiEndUserError {\n    static readonly CODE = 'user-forbidden';\n\n    constructor(message: string, detail?: string, cause?: Error) {\n        super(\n            message,\n            EndUserErrorCode.format(ApiEndUserForbiddenError.CODE, detail),\n            undefined,\n            cause,\n        );\n    }\n}\n\n/**\n * The end user's input was well-formed but wrong in a way they must fix (\"the two passwords do not\n * match\"). A partner-facing edge answers 400 for it. Distinct from `ApiBadRequestError`, whose\n * `message` is operator-only and which means the CALLER built a bad request.\n */\nexport class ApiEndUserBadRequestError extends ApiEndUserError {\n    static readonly CODE = 'user-bad-request';\n\n    constructor(message: string, detail?: string, cause?: Error) {\n        super(message, EndUserErrorCode.format(ApiEndUserBadRequestError.CODE, detail), 400, cause);\n    }\n}\n"]}

package/src/errors/ReceivedApiErrorRule.d.ts

@@ -1,4 +1,5 @@
 import { ApiError } from './ApiError';
+import { ClientRole } from './ClientRole';
 /**
  * THE rule for an error this process RECEIVED from another one — identical over HTTP and over IPC,
  * which is why it lives here and not in either protocol's translator.
@@ -17,9 +18,13 @@ import { ApiError } from './ApiError';
  * - **408/429/502/503/504 preserve retry-relevant semantics.** Timeout, backoff, bad-gateway and
  *   unavailable must not collapse into the generic non-retryable dependency bucket.
  * - **266 / `end-user` -> {@link ApiEndUserError}**, the intended user-facing message, published
- *   verbatim. It is the one message the taxonomy lets a peer write for a human.
+ *   verbatim. It is the one message the taxonomy lets a peer write for a human. `ApiErrorCodec` has
+ *   already rebuilt the registered SUBCLASS for its `errorCode` (see `EndUserErrorRegistry`).
+ * - **426 / `client-too-old` -> {@link ApiClientTooOldError}, rethrown AS-IS, on EVERY hop and for
+ *   every {@link ClientRole}.** It is not "I called wrong", it is "the build on the calling side is
+ *   older than the server allows", and every receiver must see "upgrade", never a bug report.
  *
- * # Why this is UNIFORM, in a browser as much as in a server
+ * # Why this is UNIFORM, in a browser as much as in a server — with ONE exception, 401
  *
  * An earlier design made the browser pass a received status through unchanged on the theory that
  * "the browser IS the user's agent, so a 404 is the user's answer". That is wrong. If a browser
@@ -28,11 +33,27 @@ import { ApiError } from './ApiError';
  * as intended: `ApiImplementationError` means the client has a bug, `ApiDependencyError` means the
  * server has one.
  *
+ * **401 is the exception, and it is why the rule takes a {@link ClientRole}.** A received 401 means
+ * "the credential I presented was rejected", and WHOSE credential that was depends on who I am:
+ *
+ * - an {@link ClientRole.END_USER_CLIENT} (browser bundle, Expo shell, remote MCP client) presented
+ *   the USER's session, so a 401 carrying the webpieces `unauthorized` payload is decoded as
+ *   {@link ApiUnauthorizedError}: "log in again" (and, for a remote MCP client, "go find the
+ *   authorization server"), not a bug.
+ * - a {@link ClientRole.SERVER} presented ITS OWN credential, so a 401 stays
+ *   {@link ApiImplementationError} -> a 500 to its own caller. Relaying it as 401 would tell the
+ *   browser "your session expired" and log the user out for a backend misconfiguration, and it would
+ *   stop paging the team whose credential is broken.
+ *
+ * Every other status reads the same in both roles, so the role is consulted for 401 alone. The role
+ * has no default: each client states it at setup (see {@link ClientRole}).
+ *
  * An app that genuinely wants a peer's status relayed as its OWN typed error says so out loud, in one
  * greppable place, by throwing it from its registered translator's `fromWire`.
  */
 export declare class ReceivedApiErrorRule {
     /**
+     * @param role - who received it, declared at the client's setup. Decides what a 401 means.
      * @param statusCode - the HTTP status the peer published. IPC has no wire status, so it derives
      *   the equivalent from the payload's `kind` through the same `ApiErrorHttpStatus` table — one
      *   table, so the two protocols cannot drift apart.
@@ -41,5 +62,14 @@ export declare class ReceivedApiErrorRule {
      * @param decoded - the peer's own typed error when the body was a webpieces `ApiErrorPayload`.
      *   Absent for a foreign responder.
      */
-    static adapt(statusCode: number, message: string, decoded?: ApiError, retryAfterSeconds?: number): Error;
+    static adapt(role: ClientRole, statusCode: number, message: string, decoded?: ApiError, retryAfterSeconds?: number): Error;
+    /**
+     * The peer's own typed error, rethrown AS-IS, when re-classifying it would change its meaning:
+     *
+     * - {@link ApiClientTooOldError}: an upgrade, never a bug, on every hop and for every role.
+     * - a 401 {@link ApiUnauthorizedError} received by an END-USER client: the credential it sent IS
+     *   the user's session, so this is "log in again". A SERVER's 401 is its own bug and falls through.
+     * - a dependency failure: already attributed further downstream.
+     */
+    private static passesThrough;
 }

package/src/errors/ReceivedApiErrorRule.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReceivedApiErrorRule = void 0;
 const ApiError_1 = require("./ApiError");
+const ClientRole_1 = require("./ClientRole");
 /**
  * THE rule for an error this process RECEIVED from another one — identical over HTTP and over IPC,
  * which is why it lives here and not in either protocol's translator.
@@ -20,9 +21,13 @@ const ApiError_1 = require("./ApiError");
  * - **408/429/502/503/504 preserve retry-relevant semantics.** Timeout, backoff, bad-gateway and
  *   unavailable must not collapse into the generic non-retryable dependency bucket.
  * - **266 / `end-user` -> {@link ApiEndUserError}**, the intended user-facing message, published
- *   verbatim. It is the one message the taxonomy lets a peer write for a human.
+ *   verbatim. It is the one message the taxonomy lets a peer write for a human. `ApiErrorCodec` has
+ *   already rebuilt the registered SUBCLASS for its `errorCode` (see `EndUserErrorRegistry`).
+ * - **426 / `client-too-old` -> {@link ApiClientTooOldError}, rethrown AS-IS, on EVERY hop and for
+ *   every {@link ClientRole}.** It is not "I called wrong", it is "the build on the calling side is
+ *   older than the server allows", and every receiver must see "upgrade", never a bug report.
  *
- * # Why this is UNIFORM, in a browser as much as in a server
+ * # Why this is UNIFORM, in a browser as much as in a server — with ONE exception, 401
  *
  * An earlier design made the browser pass a received status through unchanged on the theory that
  * "the browser IS the user's agent, so a 404 is the user's answer". That is wrong. If a browser
@@ -31,11 +36,27 @@ const ApiError_1 = require("./ApiError");
  * as intended: `ApiImplementationError` means the client has a bug, `ApiDependencyError` means the
  * server has one.
  *
+ * **401 is the exception, and it is why the rule takes a {@link ClientRole}.** A received 401 means
+ * "the credential I presented was rejected", and WHOSE credential that was depends on who I am:
+ *
+ * - an {@link ClientRole.END_USER_CLIENT} (browser bundle, Expo shell, remote MCP client) presented
+ *   the USER's session, so a 401 carrying the webpieces `unauthorized` payload is decoded as
+ *   {@link ApiUnauthorizedError}: "log in again" (and, for a remote MCP client, "go find the
+ *   authorization server"), not a bug.
+ * - a {@link ClientRole.SERVER} presented ITS OWN credential, so a 401 stays
+ *   {@link ApiImplementationError} -> a 500 to its own caller. Relaying it as 401 would tell the
+ *   browser "your session expired" and log the user out for a backend misconfiguration, and it would
+ *   stop paging the team whose credential is broken.
+ *
+ * Every other status reads the same in both roles, so the role is consulted for 401 alone. The role
+ * has no default: each client states it at setup (see {@link ClientRole}).
+ *
  * An app that genuinely wants a peer's status relayed as its OWN typed error says so out loud, in one
  * greppable place, by throwing it from its registered translator's `fromWire`.
  */
 class ReceivedApiErrorRule {
     /**
+     * @param role - who received it, declared at the client's setup. Decides what a 401 means.
      * @param statusCode - the HTTP status the peer published. IPC has no wire status, so it derives
      *   the equivalent from the payload's `kind` through the same `ApiErrorHttpStatus` table — one
      *   table, so the two protocols cannot drift apart.
@@ -45,16 +66,13 @@ class ReceivedApiErrorRule {
      *   Absent for a foreign responder.
      */
     // webpieces-disable no-function-outside-class -- stateless shared rule, called by both protocol translators
-    static adapt(statusCode, message, decoded, retryAfterSeconds) {
+    static adapt(role, statusCode, message, decoded, retryAfterSeconds) {
         // 266 is protocol SUCCESS carrying the actor's own answer — the one message published verbatim.
         if (statusCode === 266) {
             return decoded instanceof ApiError_1.ApiEndUserError ? decoded : new ApiError_1.ApiEndUserError(message);
         }
-        if (decoded instanceof ApiError_1.ApiDependencyError ||
-            decoded instanceof ApiError_1.ApiBadGatewayError ||
-            decoded instanceof ApiError_1.ApiUnavailableError ||
-            decoded instanceof ApiError_1.ApiDependencyTimeoutError ||
-            decoded instanceof ApiError_1.ApiDependencyBackoffError) {
+        if (decoded !== undefined &&
+            ReceivedApiErrorRule.passesThrough(role, statusCode, decoded)) {
             return decoded;
         }
         if (statusCode === 408 || statusCode === 504) {
@@ -79,6 +97,27 @@ class ReceivedApiErrorRule {
             `whether the dependency is deployed, and our service credentials. ` +
             `Downstream said: ${message}`, decoded);
     }
+    /**
+     * The peer's own typed error, rethrown AS-IS, when re-classifying it would change its meaning:
+     *
+     * - {@link ApiClientTooOldError}: an upgrade, never a bug, on every hop and for every role.
+     * - a 401 {@link ApiUnauthorizedError} received by an END-USER client: the credential it sent IS
+     *   the user's session, so this is "log in again". A SERVER's 401 is its own bug and falls through.
+     * - a dependency failure: already attributed further downstream.
+     */
+    // webpieces-disable no-function-outside-class -- stateless shared rule, called by both protocol translators
+    static passesThrough(role, statusCode, decoded) {
+        if (decoded instanceof ApiError_1.ApiClientTooOldError)
+            return true;
+        if (statusCode === 401 && decoded instanceof ApiError_1.ApiUnauthorizedError) {
+            return role === ClientRole_1.ClientRole.END_USER_CLIENT;
+        }
+        return (decoded instanceof ApiError_1.ApiDependencyError ||
+            decoded instanceof ApiError_1.ApiBadGatewayError ||
+            decoded instanceof ApiError_1.ApiUnavailableError ||
+            decoded instanceof ApiError_1.ApiDependencyTimeoutError ||
+            decoded instanceof ApiError_1.ApiDependencyBackoffError);
+    }
 }
 exports.ReceivedApiErrorRule = ReceivedApiErrorRule;
 //# sourceMappingURL=ReceivedApiErrorRule.js.map

package/src/errors/ReceivedApiErrorRule.js.map

@@ -1 +1 @@
-{"version":3,"file":"ReceivedApiErrorRule.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ReceivedApiErrorRule.ts"],"names":[],"mappings":";;;AAAA,yCASoB;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAa,oBAAoB;IAC7B;;;;;;;;OAQG;IACH,4GAA4G;IAC5G,MAAM,CAAC,KAAK,CACR,UAAkB,EAClB,OAAe,EACf,OAAkB,EAClB,iBAA0B;QAE1B,gGAAgG;QAChG,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YACrB,OAAO,OAAO,YAAY,0BAAe,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,0BAAe,CAAC,OAAO,CAAC,CAAC;QACvF,CAAC;QACD,IACI,OAAO,YAAY,6BAAkB;YACrC,OAAO,YAAY,6BAAkB;YACrC,OAAO,YAAY,8BAAmB;YACtC,OAAO,YAAY,oCAAyB;YAC5C,OAAO,YAAY,oCAAyB,EAC9C,CAAC;YACC,OAAO,OAAO,CAAC;QACnB,CAAC;QACD,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YAC3C,OAAO,IAAI,oCAAyB,CAChC,kCAAkC,UAAU,sBAAsB,OAAO,EAAE,EAC3E,OAAO,CACV,CAAC;QACN,CAAC;QACD,IAAI,UAAU,KAAK,GAAG,IAAI,CAAC,UAAU,KAAK,GAAG,IAAI,iBAAiB,KAAK,SAAS,CAAC,EAAE,CAAC;YAChF,OAAO,IAAI,oCAAyB,CAChC,wDAAwD,UAAU,IAAI;gBAClE,oBAAoB,OAAO,EAAE,EACjC,iBAAiB,EACjB,OAAO,CACV,CAAC;QACN,CAAC;QACD,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YACrB,OAAO,IAAI,6BAAkB,CACzB,+CAA+C,OAAO,EAAE,EACxD,OAAO,CACV,CAAC;QACN,CAAC;QACD,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YACrB,OAAO,IAAI,8BAAmB,CAC1B,0DAA0D,OAAO,EAAE,EACnE,OAAO,CACV,CAAC;QACN,CAAC;QACD,IAAI,UAAU,IAAI,GAAG,EAAE,CAAC;YACpB,OAAO,IAAI,6BAAkB,CACzB,uBAAuB,UAAU,qCAAqC;gBAClE,oBAAoB,OAAO,EAAE,EACjC,OAAO,CACV,CAAC;QACN,CAAC;QACD,OAAO,IAAI,iCAAsB,CAC7B,uBAAuB,UAAU,oDAAoD;YACjF,iFAAiF;YACjF,mEAAmE;YACnE,oBAAoB,OAAO,EAAE,EACjC,OAAO,CACV,CAAC;IACN,CAAC;CACJ;AAvED,oDAuEC","sourcesContent":["import {\n    ApiBadGatewayError,\n    ApiDependencyBackoffError,\n    ApiDependencyError,\n    ApiDependencyTimeoutError,\n    ApiEndUserError,\n    ApiError,\n    ApiImplementationError,\n    ApiUnavailableError,\n} from './ApiError';\n\n/**\n * THE rule for an error this process RECEIVED from another one — identical over HTTP and over IPC,\n * which is why it lives here and not in either protocol's translator.\n *\n * A status a peer answered describes OUR request to it. It is never, by itself, an answer for our\n * own caller, and the two ways it can be wrong have OPPOSITE owners:\n *\n * - **ordinary caller-error status (4xx-equivalent) -> {@link ApiImplementationError}.** WE sent a bad request,\n *   called a path that does not exist, or presented the wrong credentials. MY bug. The peer that\n *   answered 404 is correct.\n * - **ordinary server-error status (5xx-equivalent) -> {@link ApiDependencyError}.** THEY broke. Not my bug,\n *   so this process's failure metrics stay clean and page the right team.\n * - **an {@link ApiDependencyError} coming back -> rethrown AS-IS.** The fault is already attributed,\n *   somewhere further downstream; this hop adds nothing by re-wrapping it, and re-wrapping would bury\n *   the original message one `cause` deeper on every hop of a chain.\n * - **408/429/502/503/504 preserve retry-relevant semantics.** Timeout, backoff, bad-gateway and\n *   unavailable must not collapse into the generic non-retryable dependency bucket.\n * - **266 / `end-user` -> {@link ApiEndUserError}**, the intended user-facing message, published\n *   verbatim. It is the one message the taxonomy lets a peer write for a human.\n *\n * # Why this is UNIFORM, in a browser as much as in a server\n *\n * An earlier design made the browser pass a received status through unchanged on the theory that\n * \"the browser IS the user's agent, so a 404 is the user's answer\". That is wrong. If a browser\n * received a 404 the browser called the wrong path — that is the BROWSER's bug, and the code that\n * catches it wants to know that, not to show a user a spinner. Read in a browser this reads exactly\n * as intended: `ApiImplementationError` means the client has a bug, `ApiDependencyError` means the\n * server has one.\n *\n * An app that genuinely wants a peer's status relayed as its OWN typed error says so out loud, in one\n * greppable place, by throwing it from its registered translator's `fromWire`.\n */\nexport class ReceivedApiErrorRule {\n    /**\n     * @param statusCode - the HTTP status the peer published. IPC has no wire status, so it derives\n     *   the equivalent from the payload's `kind` through the same `ApiErrorHttpStatus` table — one\n     *   table, so the two protocols cannot drift apart.\n     * @param message - the text to carry forward: the decoded payload's message, else whatever the\n     *   transport could salvage from the body.\n     * @param decoded - the peer's own typed error when the body was a webpieces `ApiErrorPayload`.\n     *   Absent for a foreign responder.\n     */\n    // webpieces-disable no-function-outside-class -- stateless shared rule, called by both protocol translators\n    static adapt(\n        statusCode: number,\n        message: string,\n        decoded?: ApiError,\n        retryAfterSeconds?: number,\n    ): Error {\n        // 266 is protocol SUCCESS carrying the actor's own answer — the one message published verbatim.\n        if (statusCode === 266) {\n            return decoded instanceof ApiEndUserError ? decoded : new ApiEndUserError(message);\n        }\n        if (\n            decoded instanceof ApiDependencyError ||\n            decoded instanceof ApiBadGatewayError ||\n            decoded instanceof ApiUnavailableError ||\n            decoded instanceof ApiDependencyTimeoutError ||\n            decoded instanceof ApiDependencyBackoffError\n        ) {\n            return decoded;\n        }\n        if (statusCode === 408 || statusCode === 504) {\n            return new ApiDependencyTimeoutError(\n                `dependency timed out with HTTP ${statusCode}. Downstream said: ${message}`,\n                decoded,\n            );\n        }\n        if (statusCode === 429 || (statusCode === 503 && retryAfterSeconds !== undefined)) {\n            return new ApiDependencyBackoffError(\n                `dependency asked this service to back off after HTTP ${statusCode}. ` +\n                    `Downstream said: ${message}`,\n                retryAfterSeconds,\n                decoded,\n            );\n        }\n        if (statusCode === 502) {\n            return new ApiBadGatewayError(\n                `gateway answered HTTP 502. Downstream said: ${message}`,\n                decoded,\n            );\n        }\n        if (statusCode === 503) {\n            return new ApiUnavailableError(\n                `dependency is unavailable (HTTP 503). Downstream said: ${message}`,\n                decoded,\n            );\n        }\n        if (statusCode >= 500) {\n            return new ApiDependencyError(\n                `dependency answered ${statusCode} — it is broken, not this service. ` +\n                    `Downstream said: ${message}`,\n                decoded,\n            );\n        }\n        return new ApiImplementationError(\n            `dependency answered ${statusCode}. That status describes OUR request to it, not an ` +\n                `answer for our caller, so this service owns it — check the path, the base URL, ` +\n                `whether the dependency is deployed, and our service credentials. ` +\n                `Downstream said: ${message}`,\n            decoded,\n        );\n    }\n}\n"]}
+{"version":3,"file":"ReceivedApiErrorRule.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ReceivedApiErrorRule.ts"],"names":[],"mappings":";;;AAAA,yCAWoB;AACpB,6CAA0C;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAa,oBAAoB;IAC7B;;;;;;;;;OASG;IACH,4GAA4G;IAC5G,MAAM,CAAC,KAAK,CACR,IAAgB,EAChB,UAAkB,EAClB,OAAe,EACf,OAAkB,EAClB,iBAA0B;QAE1B,gGAAgG;QAChG,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YACrB,OAAO,OAAO,YAAY,0BAAe,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,0BAAe,CAAC,OAAO,CAAC,CAAC;QACvF,CAAC;QACD,IACI,OAAO,KAAK,SAAS;YACrB,oBAAoB,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAC/D,CAAC;YACC,OAAO,OAAO,CAAC;QACnB,CAAC;QACD,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YAC3C,OAAO,IAAI,oCAAyB,CAChC,kCAAkC,UAAU,sBAAsB,OAAO,EAAE,EAC3E,OAAO,CACV,CAAC;QACN,CAAC;QACD,IAAI,UAAU,KAAK,GAAG,IAAI,CAAC,UAAU,KAAK,GAAG,IAAI,iBAAiB,KAAK,SAAS,CAAC,EAAE,CAAC;YAChF,OAAO,IAAI,oCAAyB,CAChC,wDAAwD,UAAU,IAAI;gBAClE,oBAAoB,OAAO,EAAE,EACjC,iBAAiB,EACjB,OAAO,CACV,CAAC;QACN,CAAC;QACD,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YACrB,OAAO,IAAI,6BAAkB,CACzB,+CAA+C,OAAO,EAAE,EACxD,OAAO,CACV,CAAC;QACN,CAAC;QACD,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YACrB,OAAO,IAAI,8BAAmB,CAC1B,0DAA0D,OAAO,EAAE,EACnE,OAAO,CACV,CAAC;QACN,CAAC;QACD,IAAI,UAAU,IAAI,GAAG,EAAE,CAAC;YACpB,OAAO,IAAI,6BAAkB,CACzB,uBAAuB,UAAU,qCAAqC;gBAClE,oBAAoB,OAAO,EAAE,EACjC,OAAO,CACV,CAAC;QACN,CAAC;QACD,OAAO,IAAI,iCAAsB,CAC7B,uBAAuB,UAAU,oDAAoD;YACjF,iFAAiF;YACjF,mEAAmE;YACnE,oBAAoB,OAAO,EAAE,EACjC,OAAO,CACV,CAAC;IACN,CAAC;IAED;;;;;;;OAOG;IACH,4GAA4G;IACpG,MAAM,CAAC,aAAa,CAAC,IAAgB,EAAE,UAAkB,EAAE,OAAc;QAC7E,IAAI,OAAO,YAAY,+BAAoB;YAAE,OAAO,IAAI,CAAC;QACzD,IAAI,UAAU,KAAK,GAAG,IAAI,OAAO,YAAY,+BAAoB,EAAE,CAAC;YAChE,OAAO,IAAI,KAAK,uBAAU,CAAC,eAAe,CAAC;QAC/C,CAAC;QACD,OAAO,CACH,OAAO,YAAY,6BAAkB;YACrC,OAAO,YAAY,6BAAkB;YACrC,OAAO,YAAY,8BAAmB;YACtC,OAAO,YAAY,oCAAyB;YAC5C,OAAO,YAAY,oCAAyB,CAC/C,CAAC;IACN,CAAC;CACJ;AA7FD,oDA6FC","sourcesContent":["import {\n    ApiBadGatewayError,\n    ApiClientTooOldError,\n    ApiDependencyBackoffError,\n    ApiDependencyError,\n    ApiDependencyTimeoutError,\n    ApiEndUserError,\n    ApiError,\n    ApiImplementationError,\n    ApiUnauthorizedError,\n    ApiUnavailableError,\n} from './ApiError';\nimport { ClientRole } from './ClientRole';\n\n/**\n * THE rule for an error this process RECEIVED from another one — identical over HTTP and over IPC,\n * which is why it lives here and not in either protocol's translator.\n *\n * A status a peer answered describes OUR request to it. It is never, by itself, an answer for our\n * own caller, and the two ways it can be wrong have OPPOSITE owners:\n *\n * - **ordinary caller-error status (4xx-equivalent) -> {@link ApiImplementationError}.** WE sent a bad request,\n *   called a path that does not exist, or presented the wrong credentials. MY bug. The peer that\n *   answered 404 is correct.\n * - **ordinary server-error status (5xx-equivalent) -> {@link ApiDependencyError}.** THEY broke. Not my bug,\n *   so this process's failure metrics stay clean and page the right team.\n * - **an {@link ApiDependencyError} coming back -> rethrown AS-IS.** The fault is already attributed,\n *   somewhere further downstream; this hop adds nothing by re-wrapping it, and re-wrapping would bury\n *   the original message one `cause` deeper on every hop of a chain.\n * - **408/429/502/503/504 preserve retry-relevant semantics.** Timeout, backoff, bad-gateway and\n *   unavailable must not collapse into the generic non-retryable dependency bucket.\n * - **266 / `end-user` -> {@link ApiEndUserError}**, the intended user-facing message, published\n *   verbatim. It is the one message the taxonomy lets a peer write for a human. `ApiErrorCodec` has\n *   already rebuilt the registered SUBCLASS for its `errorCode` (see `EndUserErrorRegistry`).\n * - **426 / `client-too-old` -> {@link ApiClientTooOldError}, rethrown AS-IS, on EVERY hop and for\n *   every {@link ClientRole}.** It is not \"I called wrong\", it is \"the build on the calling side is\n *   older than the server allows\", and every receiver must see \"upgrade\", never a bug report.\n *\n * # Why this is UNIFORM, in a browser as much as in a server — with ONE exception, 401\n *\n * An earlier design made the browser pass a received status through unchanged on the theory that\n * \"the browser IS the user's agent, so a 404 is the user's answer\". That is wrong. If a browser\n * received a 404 the browser called the wrong path — that is the BROWSER's bug, and the code that\n * catches it wants to know that, not to show a user a spinner. Read in a browser this reads exactly\n * as intended: `ApiImplementationError` means the client has a bug, `ApiDependencyError` means the\n * server has one.\n *\n * **401 is the exception, and it is why the rule takes a {@link ClientRole}.** A received 401 means\n * \"the credential I presented was rejected\", and WHOSE credential that was depends on who I am:\n *\n * - an {@link ClientRole.END_USER_CLIENT} (browser bundle, Expo shell, remote MCP client) presented\n *   the USER's session, so a 401 carrying the webpieces `unauthorized` payload is decoded as\n *   {@link ApiUnauthorizedError}: \"log in again\" (and, for a remote MCP client, \"go find the\n *   authorization server\"), not a bug.\n * - a {@link ClientRole.SERVER} presented ITS OWN credential, so a 401 stays\n *   {@link ApiImplementationError} -> a 500 to its own caller. Relaying it as 401 would tell the\n *   browser \"your session expired\" and log the user out for a backend misconfiguration, and it would\n *   stop paging the team whose credential is broken.\n *\n * Every other status reads the same in both roles, so the role is consulted for 401 alone. The role\n * has no default: each client states it at setup (see {@link ClientRole}).\n *\n * An app that genuinely wants a peer's status relayed as its OWN typed error says so out loud, in one\n * greppable place, by throwing it from its registered translator's `fromWire`.\n */\nexport class ReceivedApiErrorRule {\n    /**\n     * @param role - who received it, declared at the client's setup. Decides what a 401 means.\n     * @param statusCode - the HTTP status the peer published. IPC has no wire status, so it derives\n     *   the equivalent from the payload's `kind` through the same `ApiErrorHttpStatus` table — one\n     *   table, so the two protocols cannot drift apart.\n     * @param message - the text to carry forward: the decoded payload's message, else whatever the\n     *   transport could salvage from the body.\n     * @param decoded - the peer's own typed error when the body was a webpieces `ApiErrorPayload`.\n     *   Absent for a foreign responder.\n     */\n    // webpieces-disable no-function-outside-class -- stateless shared rule, called by both protocol translators\n    static adapt(\n        role: ClientRole,\n        statusCode: number,\n        message: string,\n        decoded?: ApiError,\n        retryAfterSeconds?: number,\n    ): Error {\n        // 266 is protocol SUCCESS carrying the actor's own answer — the one message published verbatim.\n        if (statusCode === 266) {\n            return decoded instanceof ApiEndUserError ? decoded : new ApiEndUserError(message);\n        }\n        if (\n            decoded !== undefined &&\n            ReceivedApiErrorRule.passesThrough(role, statusCode, decoded)\n        ) {\n            return decoded;\n        }\n        if (statusCode === 408 || statusCode === 504) {\n            return new ApiDependencyTimeoutError(\n                `dependency timed out with HTTP ${statusCode}. Downstream said: ${message}`,\n                decoded,\n            );\n        }\n        if (statusCode === 429 || (statusCode === 503 && retryAfterSeconds !== undefined)) {\n            return new ApiDependencyBackoffError(\n                `dependency asked this service to back off after HTTP ${statusCode}. ` +\n                    `Downstream said: ${message}`,\n                retryAfterSeconds,\n                decoded,\n            );\n        }\n        if (statusCode === 502) {\n            return new ApiBadGatewayError(\n                `gateway answered HTTP 502. Downstream said: ${message}`,\n                decoded,\n            );\n        }\n        if (statusCode === 503) {\n            return new ApiUnavailableError(\n                `dependency is unavailable (HTTP 503). Downstream said: ${message}`,\n                decoded,\n            );\n        }\n        if (statusCode >= 500) {\n            return new ApiDependencyError(\n                `dependency answered ${statusCode} — it is broken, not this service. ` +\n                    `Downstream said: ${message}`,\n                decoded,\n            );\n        }\n        return new ApiImplementationError(\n            `dependency answered ${statusCode}. That status describes OUR request to it, not an ` +\n                `answer for our caller, so this service owns it — check the path, the base URL, ` +\n                `whether the dependency is deployed, and our service credentials. ` +\n                `Downstream said: ${message}`,\n            decoded,\n        );\n    }\n\n    /**\n     * The peer's own typed error, rethrown AS-IS, when re-classifying it would change its meaning:\n     *\n     * - {@link ApiClientTooOldError}: an upgrade, never a bug, on every hop and for every role.\n     * - a 401 {@link ApiUnauthorizedError} received by an END-USER client: the credential it sent IS\n     *   the user's session, so this is \"log in again\". A SERVER's 401 is its own bug and falls through.\n     * - a dependency failure: already attributed further downstream.\n     */\n    // webpieces-disable no-function-outside-class -- stateless shared rule, called by both protocol translators\n    private static passesThrough(role: ClientRole, statusCode: number, decoded: Error): boolean {\n        if (decoded instanceof ApiClientTooOldError) return true;\n        if (statusCode === 401 && decoded instanceof ApiUnauthorizedError) {\n            return role === ClientRole.END_USER_CLIENT;\n        }\n        return (\n            decoded instanceof ApiDependencyError ||\n            decoded instanceof ApiBadGatewayError ||\n            decoded instanceof ApiUnavailableError ||\n            decoded instanceof ApiDependencyTimeoutError ||\n            decoded instanceof ApiDependencyBackoffError\n        );\n    }\n}\n"]}

package/src/errors/ReportableApiFailure.d.ts

@@ -0,0 +1,43 @@
+import { ApiCallSite } from './ApiCallSite';
+/**
+ * The report-time wrapper for a failed api call: named `RpcCallFailed`, message
+ * `Api.method failed: <original message>`, the CALL SITE's stack, and `cause` = the original error.
+ *
+ * NEVER THROWN. It exists only to be handed to an error reporter, so that the reported stack is the
+ * app line that made the call while the original failure (and its own framework stack) is still
+ * one `cause` hop away. Here `cause` is honest — the call failed BECAUSE of the original error —
+ * which is exactly why the call site itself is not stored as the original's `cause`.
+ */
+export declare class RpcCallFailed extends Error {
+    readonly callSite: ApiCallSite;
+    constructor(callSite: ApiCallSite, original: Error);
+    /**
+     * The call site's frames without its own header line. V8 prefixes a stack with
+     * `Name: message`; SpiderMonkey and JavaScriptCore do not, so only a matching first line is cut.
+     */
+    private static framesOf;
+}
+/**
+ * What an error reporter needs to report a failed api call well: the {@link RpcCallFailed} wrapper
+ * and a suggested grouping `fingerprint` of `[original.name, 'Api.method']`, so failures group per
+ * endpoint and error type instead of collapsing into one issue for the whole app.
+ *
+ * Reporter-agnostic on purpose — webpieces does not depend on any error-reporting SDK. A Sentry app,
+ * for example, would do:
+ *
+ * ```ts
+ * const report = ReportableApiFailure.toReportableError(err);
+ * if (report) Sentry.captureException(report.error, { fingerprint: [...report.fingerprint] });
+ * else Sentry.captureException(err);
+ * ```
+ */
+export declare class ReportableApiFailure {
+    readonly error: RpcCallFailed;
+    readonly fingerprint: readonly string[];
+    constructor(error: RpcCallFailed, fingerprint: readonly string[]);
+    /**
+     * The reportable form of `failure`, or undefined when it carries no call site (it did not come
+     * out of a generated api client, so there is nothing to add — report it as it is).
+     */
+    static toReportableError(failure: unknown): ReportableApiFailure | undefined;
+}