@webpieces/core-util 0.4.790 → 0.4.791

package/README.md

@@ -6,7 +6,7 @@ Utility functions for WebPieces applications. Works in both browser and Node.js
 
 React Native consumers use `@webpieces/core-util/errors` for canonical semantic errors (`ApiEndUserError`, `ApiNotFoundError`, and the other API categories) and `@webpieces/core-util/ipc` for shared contracts and connection types. These two subpaths are checked with public declaration fixtures, Metro Android/iOS bundles, and Hermes compilation; the broad root barrel is not certified for React Native.
 
-Use `@webpieces/ipc-bridge` for generated clients and typed receivers. HTTP preserves status 266 for `ApiEndUserError`: monitoring succeeds, while generated clients throw it for GUI display. Its optional `edgeHttpStatus` (400/404/409/422, the third constructor argument before `cause`) survives every hop and is what a partner-facing edge in `setEndUserStatus('edge')` mode answers instead. All API errors are transport-neutral, use standard `cause`, and have no HTTP `.code`. See [the taxonomy and verification guide](https://github.com/deanhiller/webpieces-ts/blob/main/docs/portable-ipc-and-errors.md).
+Use `@webpieces/ipc-bridge` for generated clients and typed receivers. HTTP preserves status 266 for `ApiEndUserError`: monitoring succeeds, while generated clients throw it for GUI display. Its optional `edgeHttpStatus` (400/404/409/422, the third constructor argument before `cause`) survives every hop and is what a server answers instead when the CALLER's `SURFACE` is `public-api` (see `SurfaceEndUserStatus`). All API errors are transport-neutral, use standard `cause`, and have no HTTP `.code`. See [the taxonomy and verification guide](https://github.com/deanhiller/webpieces-ts/blob/main/docs/portable-ipc-and-errors.md).
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/core-util",
-  "version": "0.4.790",
+  "version": "0.4.791",
   "description": "Utility functions for WebPieces - works in browser and Node.js",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/errors/ReceivedApiErrorRule.d.ts

@@ -0,0 +1,43 @@
+import { ApiError } from './ApiError';
+/**
+ * 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.
+ *
+ * A status a peer answered describes OUR request to it. It is never, by itself, an answer for our
+ * own caller, and the two ways it can be wrong have OPPOSITE owners:
+ *
+ * - **caller-error status (4xx-equivalent) -> {@link ApiImplementationError}.** WE sent a bad request,
+ *   called a path that does not exist, or presented the wrong credentials. MY bug. The peer that
+ *   answered 404 is correct.
+ * - **server-error status (5xx-equivalent) -> {@link ApiDependencyError}.** THEY broke. Not my bug,
+ *   so this process's failure metrics stay clean and page the right team.
+ * - **an {@link ApiDependencyError} coming back -> rethrown AS-IS.** The fault is already attributed,
+ *   somewhere further downstream; this hop adds nothing by re-wrapping it, and re-wrapping would bury
+ *   the original message one `cause` deeper on every hop of a chain.
+ * - **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.
+ *
+ * # Why this is UNIFORM, in a browser as much as in a server
+ *
+ * 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
+ * received a 404 the browser called the wrong path — that is the BROWSER's bug, and the code that
+ * catches it wants to know that, not to show a user a spinner. Read in a browser this reads exactly
+ * as intended: `ApiImplementationError` means the client has a bug, `ApiDependencyError` means the
+ * server has one.
+ *
+ * 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 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.
+     * @param message - the text to carry forward: the decoded payload's message, else whatever the
+     *   transport could salvage from the body.
+     * @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): Error;
+}

package/src/errors/ReceivedApiErrorRule.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReceivedApiErrorRule = void 0;
+const ApiError_1 = require("./ApiError");
+/**
+ * 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.
+ *
+ * A status a peer answered describes OUR request to it. It is never, by itself, an answer for our
+ * own caller, and the two ways it can be wrong have OPPOSITE owners:
+ *
+ * - **caller-error status (4xx-equivalent) -> {@link ApiImplementationError}.** WE sent a bad request,
+ *   called a path that does not exist, or presented the wrong credentials. MY bug. The peer that
+ *   answered 404 is correct.
+ * - **server-error status (5xx-equivalent) -> {@link ApiDependencyError}.** THEY broke. Not my bug,
+ *   so this process's failure metrics stay clean and page the right team.
+ * - **an {@link ApiDependencyError} coming back -> rethrown AS-IS.** The fault is already attributed,
+ *   somewhere further downstream; this hop adds nothing by re-wrapping it, and re-wrapping would bury
+ *   the original message one `cause` deeper on every hop of a chain.
+ * - **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.
+ *
+ * # Why this is UNIFORM, in a browser as much as in a server
+ *
+ * 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
+ * received a 404 the browser called the wrong path — that is the BROWSER's bug, and the code that
+ * catches it wants to know that, not to show a user a spinner. Read in a browser this reads exactly
+ * as intended: `ApiImplementationError` means the client has a bug, `ApiDependencyError` means the
+ * server has one.
+ *
+ * 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 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.
+     * @param message - the text to carry forward: the decoded payload's message, else whatever the
+     *   transport could salvage from the body.
+     * @param decoded - the peer's own typed error when the body was a webpieces `ApiErrorPayload`.
+     *   Absent for a foreign responder.
+     */
+    // webpieces-disable no-function-outside-class -- stateless shared rule, called by both protocol translators
+    static adapt(statusCode, message, decoded) {
+        // 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) {
+            return decoded;
+        }
+        if (statusCode >= 500) {
+            return new ApiError_1.ApiDependencyError(`dependency answered ${statusCode} — it is broken, not this service. ` +
+                `Downstream said: ${message}`, decoded);
+        }
+        return new ApiError_1.ApiImplementationError(`dependency answered ${statusCode}. That status describes OUR request to it, not an ` +
+            `answer for our caller, so this service owns it — check the path, the base URL, ` +
+            `whether the dependency is deployed, and our service credentials. ` +
+            `Downstream said: ${message}`, decoded);
+    }
+}
+exports.ReceivedApiErrorRule = ReceivedApiErrorRule;
+//# sourceMappingURL=ReceivedApiErrorRule.js.map

package/src/errors/ReceivedApiErrorRule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReceivedApiErrorRule.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ReceivedApiErrorRule.ts"],"names":[],"mappings":";;;AAAA,yCAKoB;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAa,oBAAoB;IAC7B;;;;;;;;OAQG;IACH,4GAA4G;IAC5G,MAAM,CAAC,KAAK,CAAC,UAAkB,EAAE,OAAe,EAAE,OAAkB;QAChE,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,IAAI,OAAO,YAAY,6BAAkB,EAAE,CAAC;YACxC,OAAO,OAAO,CAAC;QACnB,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;AAlCD,oDAkCC","sourcesContent":["import {\n    ApiDependencyError,\n    ApiEndUserError,\n    ApiError,\n    ApiImplementationError,\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 * - **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 * - **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 * - **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(statusCode: number, message: string, decoded?: ApiError): 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 (decoded instanceof ApiDependencyError) {\n            return decoded;\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"]}

package/src/errors/index.d.ts

@@ -2,4 +2,5 @@ export { ApiError, ApiNotFoundError, ApiDependencyError, ApiUnavailableError, Ap
 export type { ApiErrorKind, ApiStatusCode, EdgeHttpStatus } from './ApiError';
 export { ApiErrorCodec, ApiErrorPayload } from './ApiErrorCodec';
 export { ApiErrorBoundary } from './ApiErrorBoundary';
+export { ReceivedApiErrorRule } from './ReceivedApiErrorRule';
 export { ENTITY_NOT_FOUND, WRONG_LOGIN_TYPE, WRONG_LOGIN, NOT_APPROVED, EMAIL_NOT_CONFIRMED, WRONG_DOMAIN, WRONG_COMPANY, NO_REG_CODE, } from './AuthErrorSubtypes';

package/src/errors/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = exports.ENTITY_NOT_FOUND = exports.ApiErrorBoundary = exports.ApiErrorPayload = exports.ApiErrorCodec = exports.ApiCodedError = exports.ApiNotImplementedError = exports.ApiUnsupportedMediaTypeError = exports.ApiPreconditionFailedError = exports.ApiUnprocessableError = exports.ApiConflictError = exports.ApiDependencyBackoffError = exports.ApiUnauthorizedError = exports.ApiBadRequestError = exports.ApiEndUserError = exports.ApiEndpointNotFoundError = exports.ApiConnectionError = exports.ApiRequestTimeoutError = exports.ApiForbiddenError = exports.ApiRateLimitedError = exports.ApiImplementationError = exports.ApiDependencyTimeoutError = exports.ApiUnavailableError = exports.ApiDependencyError = exports.ApiNotFoundError = exports.ApiError = void 0;
+exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = exports.ENTITY_NOT_FOUND = exports.ReceivedApiErrorRule = exports.ApiErrorBoundary = exports.ApiErrorPayload = exports.ApiErrorCodec = exports.ApiCodedError = exports.ApiNotImplementedError = exports.ApiUnsupportedMediaTypeError = exports.ApiPreconditionFailedError = exports.ApiUnprocessableError = exports.ApiConflictError = exports.ApiDependencyBackoffError = exports.ApiUnauthorizedError = exports.ApiBadRequestError = exports.ApiEndUserError = exports.ApiEndpointNotFoundError = exports.ApiConnectionError = exports.ApiRequestTimeoutError = exports.ApiForbiddenError = exports.ApiRateLimitedError = exports.ApiImplementationError = exports.ApiDependencyTimeoutError = exports.ApiUnavailableError = exports.ApiDependencyError = exports.ApiNotFoundError = exports.ApiError = void 0;
 var ApiError_1 = require("./ApiError");
 Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return ApiError_1.ApiError; } });
 Object.defineProperty(exports, "ApiNotFoundError", { enumerable: true, get: function () { return ApiError_1.ApiNotFoundError; } });
@@ -28,6 +28,8 @@ Object.defineProperty(exports, "ApiErrorCodec", { enumerable: true, get: functio
 Object.defineProperty(exports, "ApiErrorPayload", { enumerable: true, get: function () { return ApiErrorCodec_1.ApiErrorPayload; } });
 var ApiErrorBoundary_1 = require("./ApiErrorBoundary");
 Object.defineProperty(exports, "ApiErrorBoundary", { enumerable: true, get: function () { return ApiErrorBoundary_1.ApiErrorBoundary; } });
+var ReceivedApiErrorRule_1 = require("./ReceivedApiErrorRule");
+Object.defineProperty(exports, "ReceivedApiErrorRule", { enumerable: true, get: function () { return ReceivedApiErrorRule_1.ReceivedApiErrorRule; } });
 var AuthErrorSubtypes_1 = require("./AuthErrorSubtypes");
 Object.defineProperty(exports, "ENTITY_NOT_FOUND", { enumerable: true, get: function () { return AuthErrorSubtypes_1.ENTITY_NOT_FOUND; } });
 Object.defineProperty(exports, "WRONG_LOGIN_TYPE", { enumerable: true, get: function () { return AuthErrorSubtypes_1.WRONG_LOGIN_TYPE; } });

package/src/errors/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/index.ts"],"names":[],"mappings":";;;AAAA,uCAsBoB;AArBhB,oGAAA,QAAQ,OAAA;AACR,4GAAA,gBAAgB,OAAA;AAChB,8GAAA,kBAAkB,OAAA;AAClB,+GAAA,mBAAmB,OAAA;AACnB,qHAAA,yBAAyB,OAAA;AACzB,kHAAA,sBAAsB,OAAA;AACtB,+GAAA,mBAAmB,OAAA;AACnB,6GAAA,iBAAiB,OAAA;AACjB,kHAAA,sBAAsB,OAAA;AACtB,8GAAA,kBAAkB,OAAA;AAClB,oHAAA,wBAAwB,OAAA;AACxB,2GAAA,eAAe,OAAA;AACf,8GAAA,kBAAkB,OAAA;AAClB,gHAAA,oBAAoB,OAAA;AACpB,qHAAA,yBAAyB,OAAA;AACzB,4GAAA,gBAAgB,OAAA;AAChB,iHAAA,qBAAqB,OAAA;AACrB,sHAAA,0BAA0B,OAAA;AAC1B,wHAAA,4BAA4B,OAAA;AAC5B,kHAAA,sBAAsB,OAAA;AACtB,yGAAA,aAAa,OAAA;AAGjB,iDAAiE;AAAxD,8GAAA,aAAa,OAAA;AAAE,gHAAA,eAAe,OAAA;AACvC,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AACzB,yDAS6B;AARzB,qHAAA,gBAAgB,OAAA;AAChB,qHAAA,gBAAgB,OAAA;AAChB,gHAAA,WAAW,OAAA;AACX,iHAAA,YAAY,OAAA;AACZ,wHAAA,mBAAmB,OAAA;AACnB,iHAAA,YAAY,OAAA;AACZ,kHAAA,aAAa,OAAA;AACb,gHAAA,WAAW,OAAA","sourcesContent":["export {\n    ApiError,\n    ApiNotFoundError,\n    ApiDependencyError,\n    ApiUnavailableError,\n    ApiDependencyTimeoutError,\n    ApiImplementationError,\n    ApiRateLimitedError,\n    ApiForbiddenError,\n    ApiRequestTimeoutError,\n    ApiConnectionError,\n    ApiEndpointNotFoundError,\n    ApiEndUserError,\n    ApiBadRequestError,\n    ApiUnauthorizedError,\n    ApiDependencyBackoffError,\n    ApiConflictError,\n    ApiUnprocessableError,\n    ApiPreconditionFailedError,\n    ApiUnsupportedMediaTypeError,\n    ApiNotImplementedError,\n    ApiCodedError,\n} from './ApiError';\nexport type { ApiErrorKind, ApiStatusCode, EdgeHttpStatus } from './ApiError';\nexport { ApiErrorCodec, ApiErrorPayload } from './ApiErrorCodec';\nexport { ApiErrorBoundary } from './ApiErrorBoundary';\nexport {\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './AuthErrorSubtypes';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/index.ts"],"names":[],"mappings":";;;AAAA,uCAsBoB;AArBhB,oGAAA,QAAQ,OAAA;AACR,4GAAA,gBAAgB,OAAA;AAChB,8GAAA,kBAAkB,OAAA;AAClB,+GAAA,mBAAmB,OAAA;AACnB,qHAAA,yBAAyB,OAAA;AACzB,kHAAA,sBAAsB,OAAA;AACtB,+GAAA,mBAAmB,OAAA;AACnB,6GAAA,iBAAiB,OAAA;AACjB,kHAAA,sBAAsB,OAAA;AACtB,8GAAA,kBAAkB,OAAA;AAClB,oHAAA,wBAAwB,OAAA;AACxB,2GAAA,eAAe,OAAA;AACf,8GAAA,kBAAkB,OAAA;AAClB,gHAAA,oBAAoB,OAAA;AACpB,qHAAA,yBAAyB,OAAA;AACzB,4GAAA,gBAAgB,OAAA;AAChB,iHAAA,qBAAqB,OAAA;AACrB,sHAAA,0BAA0B,OAAA;AAC1B,wHAAA,4BAA4B,OAAA;AAC5B,kHAAA,sBAAsB,OAAA;AACtB,yGAAA,aAAa,OAAA;AAGjB,iDAAiE;AAAxD,8GAAA,aAAa,OAAA;AAAE,gHAAA,eAAe,OAAA;AACvC,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AACzB,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAC7B,yDAS6B;AARzB,qHAAA,gBAAgB,OAAA;AAChB,qHAAA,gBAAgB,OAAA;AAChB,gHAAA,WAAW,OAAA;AACX,iHAAA,YAAY,OAAA;AACZ,wHAAA,mBAAmB,OAAA;AACnB,iHAAA,YAAY,OAAA;AACZ,kHAAA,aAAa,OAAA;AACb,gHAAA,WAAW,OAAA","sourcesContent":["export {\n    ApiError,\n    ApiNotFoundError,\n    ApiDependencyError,\n    ApiUnavailableError,\n    ApiDependencyTimeoutError,\n    ApiImplementationError,\n    ApiRateLimitedError,\n    ApiForbiddenError,\n    ApiRequestTimeoutError,\n    ApiConnectionError,\n    ApiEndpointNotFoundError,\n    ApiEndUserError,\n    ApiBadRequestError,\n    ApiUnauthorizedError,\n    ApiDependencyBackoffError,\n    ApiConflictError,\n    ApiUnprocessableError,\n    ApiPreconditionFailedError,\n    ApiUnsupportedMediaTypeError,\n    ApiNotImplementedError,\n    ApiCodedError,\n} from './ApiError';\nexport type { ApiErrorKind, ApiStatusCode, EdgeHttpStatus } from './ApiError';\nexport { ApiErrorCodec, ApiErrorPayload } from './ApiErrorCodec';\nexport { ApiErrorBoundary } from './ApiErrorBoundary';\nexport { ReceivedApiErrorRule } from './ReceivedApiErrorRule';\nexport {\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './AuthErrorSubtypes';\n"]}

package/src/http/ClientRegistry.d.ts

@@ -1,4 +1,4 @@
-import { ErrorTranslators } from './ErrorTranslators';
+import { ErrorTranslator } from './ErrorTranslator';
 import { FailureClassifier } from './FailureClassifier';
 import { ApiMethodInfo } from './ApiMethodInfo';
 /**
@@ -54,19 +54,25 @@ export declare class ClientRegistry {
     /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */
     private static deriver;
     /**
-     * The app's ONE {@link ErrorTranslators}, consulted BEFORE webpieces' built-in error mapping in
-     * BOTH directions. Process-global, set once at startup on the SERVER and in the BROWSER — the
-     * same no-DI pattern as {@link ClientRegistry.mappings} above.
+     * The process's ONE {@link ErrorTranslator}. NEVER undefined — it starts life holding
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, and {@link ClientRegistry.setErrorTranslator}
+     * REPLACES it. Process-global, set once at startup on the SERVER and in the BROWSER — the same
+     * no-DI pattern as {@link ClientRegistry.mappings} above.
+     *
+     * There is no "did anyone register one" question anywhere in the framework because this field
+     * cannot be empty: every caller makes ONE unconditional call, and an app translator declines an
+     * error by DELEGATING to {@link WebpiecesDefaultErrorTranslator}.
      *
      * ONE, not a list, on purpose: an app that has several layers of error policy composes them
      * INSIDE its own `toWire`, where the precedence is written down, instead of leaving it implicit
      * in the order two unrelated startup paths happened to register.
      */
-    private static errorTranslators;
+    private static errorTranslator;
     /**
      * The app/company DEFAULT {@link FailureClassifier} — ONE per process, reads {@link ApiMethodInfo.side}
-     * so a single strategy covers the server router AND all internal clients. Undefined = use the
-     * webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}). Populated once at startup on the
+     * so a single strategy covers the server router AND all internal clients. NEVER undefined: it
+     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}) and
+     * {@link ClientRegistry.setDefaultFailureClassifier} replaces it. Populated once at startup on the
      * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.
      */
     private static appDefaultFailureClassifier;
@@ -114,23 +120,23 @@ export declare class ClientRegistry {
      */
     static resolve(svcName: string): Promise<string>;
     /**
-     * Install the app's {@link ErrorTranslators} — the ONE symmetric owner of error translation for
+     * Install the app's {@link ErrorTranslator} — the ONE symmetric owner of error translation for
      * this process, server side AND every client side. Consulted BEFORE webpieces' built-in mapping
      * in both directions. Call ONCE at startup, on the server AND in the browser, mirroring
      * {@link ClientRegistry.addMapping}.
      *
      * `set`, not `add`: see the field doc above for why a registry LIST is not wanted.
      */
-    static setErrorTranslators(translators: ErrorTranslators): void;
+    static setErrorTranslator(translator: ErrorTranslator): void;
     /**
-     * The app's installed {@link ErrorTranslators}, or `undefined` when this process installed none.
+     * THE {@link ErrorTranslator} for this process — never `undefined`, so a caller never branches.
      *
-     * The `undefined` here is "nobody registered", which is a fact about the PROCESS — it is not a
-     * per-error "not mine". A registered translator answers EVERY error and EVERY response, declining
-     * by delegating to the webpieces default (see {@link ErrorTranslators}), so a caller asks this
-     * question exactly once and then makes one unconditional call.
+     * Until an app calls {@link ClientRegistry.setErrorTranslator} this is
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}. A registered translator answers EVERY error and
+     * EVERY response, declining by delegating to the webpieces default (see {@link ErrorTranslator}),
+     * so every call site in the framework is one unconditional line.
      */
-    static getErrorTranslators(): ErrorTranslators | undefined;
+    static getErrorTranslator(): ErrorTranslator;
     /**
      * Set the app/company DEFAULT failure classifier — ONE per process, covering the server router and
      * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the
@@ -154,8 +160,13 @@ export declare class ClientRegistry {
      */
     static classifyFailure(error: Error, methodInfo: ApiMethodInfo): boolean;
     /**
-     * Reset mappings, the deriver, the error translators, AND failure classifiers. For tests, so
-     * the process-globals do not leak across specs.
+     * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec
+     * cannot leak its registrations into the next.
+     *
+     * It RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole
+     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default failure
+     * classifier are non-optional now, so "cleared" is not a state they have. A spec that wants
+     * webpieces' own behaviour back asks for exactly that.
      */
-    static clear(): void;
+    static resetForTests(): void;
 }

package/src/http/ClientRegistry.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientRegistry = void 0;
 const WebpiecesDefaultFailureClassifier_1 = require("./WebpiecesDefaultFailureClassifier");
+const WebpiecesDefaultErrorTranslator_1 = require("./WebpiecesDefaultErrorTranslator");
 /**
  * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every
  * environment. A client is built once but a URL is per-environment, so the URL belongs here rather
@@ -42,22 +43,28 @@ class ClientRegistry {
     /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */
     static deriver;
     /**
-     * The app's ONE {@link ErrorTranslators}, consulted BEFORE webpieces' built-in error mapping in
-     * BOTH directions. Process-global, set once at startup on the SERVER and in the BROWSER — the
-     * same no-DI pattern as {@link ClientRegistry.mappings} above.
+     * The process's ONE {@link ErrorTranslator}. NEVER undefined — it starts life holding
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, and {@link ClientRegistry.setErrorTranslator}
+     * REPLACES it. Process-global, set once at startup on the SERVER and in the BROWSER — the same
+     * no-DI pattern as {@link ClientRegistry.mappings} above.
+     *
+     * There is no "did anyone register one" question anywhere in the framework because this field
+     * cannot be empty: every caller makes ONE unconditional call, and an app translator declines an
+     * error by DELEGATING to {@link WebpiecesDefaultErrorTranslator}.
      *
      * ONE, not a list, on purpose: an app that has several layers of error policy composes them
      * INSIDE its own `toWire`, where the precedence is written down, instead of leaving it implicit
      * in the order two unrelated startup paths happened to register.
      */
-    static errorTranslators;
+    static errorTranslator = WebpiecesDefaultErrorTranslator_1.WEBPIECES_DEFAULT_ERROR_TRANSLATOR;
     /**
      * The app/company DEFAULT {@link FailureClassifier} — ONE per process, reads {@link ApiMethodInfo.side}
-     * so a single strategy covers the server router AND all internal clients. Undefined = use the
-     * webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}). Populated once at startup on the
+     * so a single strategy covers the server router AND all internal clients. NEVER undefined: it
+     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}) and
+     * {@link ClientRegistry.setDefaultFailureClassifier} replaces it. Populated once at startup on the
      * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.
      */
-    static appDefaultFailureClassifier;
+    static appDefaultFailureClassifier = WebpiecesDefaultFailureClassifier_1.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER;
     /**
      * Per-EXTERNAL-client {@link FailureClassifier}s, keyed by {@link ApiMethodInfo.apiClass}
      * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external
@@ -146,7 +153,7 @@ class ClientRegistry {
         return url;
     }
     /**
-     * Install the app's {@link ErrorTranslators} — the ONE symmetric owner of error translation for
+     * Install the app's {@link ErrorTranslator} — the ONE symmetric owner of error translation for
      * this process, server side AND every client side. Consulted BEFORE webpieces' built-in mapping
      * in both directions. Call ONCE at startup, on the server AND in the browser, mirroring
      * {@link ClientRegistry.addMapping}.
@@ -154,20 +161,20 @@ class ClientRegistry {
      * `set`, not `add`: see the field doc above for why a registry LIST is not wanted.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
-    static setErrorTranslators(translators) {
-        ClientRegistry.errorTranslators = translators;
+    static setErrorTranslator(translator) {
+        ClientRegistry.errorTranslator = translator;
     }
     /**
-     * The app's installed {@link ErrorTranslators}, or `undefined` when this process installed none.
+     * THE {@link ErrorTranslator} for this process — never `undefined`, so a caller never branches.
      *
-     * The `undefined` here is "nobody registered", which is a fact about the PROCESS — it is not a
-     * per-error "not mine". A registered translator answers EVERY error and EVERY response, declining
-     * by delegating to the webpieces default (see {@link ErrorTranslators}), so a caller asks this
-     * question exactly once and then makes one unconditional call.
+     * Until an app calls {@link ClientRegistry.setErrorTranslator} this is
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}. A registered translator answers EVERY error and
+     * EVERY response, declining by delegating to the webpieces default (see {@link ErrorTranslator}),
+     * so every call site in the framework is one unconditional line.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
-    static getErrorTranslators() {
-        return ClientRegistry.errorTranslators;
+    static getErrorTranslator() {
+        return ClientRegistry.errorTranslator;
     }
     /**
      * Set the app/company DEFAULT failure classifier — ONE per process, covering the server router and
@@ -205,24 +212,27 @@ class ClientRegistry {
                 return verdict;
             }
         }
-        if (ClientRegistry.appDefaultFailureClassifier !== undefined) {
-            const verdict = ClientRegistry.appDefaultFailureClassifier.isFailure(error, methodInfo);
-            if (verdict !== undefined) {
-                return verdict;
-            }
+        const verdict = ClientRegistry.appDefaultFailureClassifier.isFailure(error, methodInfo);
+        if (verdict !== undefined) {
+            return verdict;
         }
         return WebpiecesDefaultFailureClassifier_1.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER.isFailure(error, methodInfo) ?? true;
     }
     /**
-     * Reset mappings, the deriver, the error translators, AND failure classifiers. For tests, so
-     * the process-globals do not leak across specs.
+     * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec
+     * cannot leak its registrations into the next.
+     *
+     * It RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole
+     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default failure
+     * classifier are non-optional now, so "cleared" is not a state they have. A spec that wants
+     * webpieces' own behaviour back asks for exactly that.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
-    static clear() {
+    static resetForTests() {
         ClientRegistry.mappings.clear();
         ClientRegistry.deriver = undefined;
-        ClientRegistry.errorTranslators = undefined;
-        ClientRegistry.appDefaultFailureClassifier = undefined;
+        ClientRegistry.errorTranslator = WebpiecesDefaultErrorTranslator_1.WEBPIECES_DEFAULT_ERROR_TRANSLATOR;
+        ClientRegistry.appDefaultFailureClassifier = WebpiecesDefaultFailureClassifier_1.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER;
         ClientRegistry.failureClassifiersByApiClass.clear();
     }
 }

package/src/http/ClientRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ClientRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { ErrorTranslators } from './ErrorTranslators';\nimport { FailureClassifier } from './FailureClassifier';\nimport { WEBPIECES_DEFAULT_FAILURE_CLASSIFIER } from './WebpiecesDefaultFailureClassifier';\nimport { ApiMethodInfo } from './ApiMethodInfo';\n\n/**\n * Derives a base URL for a service name that has NO registered mapping — the pluggable half of\n * {@link ClientRegistry} resolution. One per environment, installed once at startup:\n *\n * - `gcpCloudRunDeriver()` (@webpieces/gcp-identity) — the Cloud Run formula, read from the metadata\n *   server. For code running ON GCP.\n * - `gcpCloudRunDeriver(new GcpCloudRunTarget(projectNumber, region))` — the SAME formula with the\n *   values supplied from config, for code running OFF GCP that still calls Cloud Run (a CLI, CI).\n * - {@link templateDeriver} (this package, browser-safe) — pure string substitution, for AWS or\n *   anything else with predictable DNS.\n * - none at all — a browser goes same-origin, and localhost/tests hand-register their mappings.\n */\nexport type ServiceUrlDeriver = (svcName: string) => Promise<string>;\n\n/**\n * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every\n * environment. A client is built once but a URL is per-environment, so the URL belongs here rather\n * than on the client: clients carry ONLY a svcName.\n *\n * Resolution is one precedence chain, identical in the browser, in node, and in Cloud Tasks:\n *\n *   1. a registered mapping wins — the localhost port table, AWS, an external API, another region\n *      or project, a host that is not Cloud Run at all. Populated at startup from per-env config.\n *   2. else the installed {@link ServiceUrlDeriver}, if any — GCP's built-in, a DNS template, or\n *      your own. OPTIONAL on purpose: localhost is inherently a TABLE (helper-fsdb -> :8401,\n *      helper-portal -> :8201 have per-service ports), so explicit mappings must stay sufficient on\n *      their own.\n *   3. else the caller's fallback: the BROWSER goes relative (same origin — see\n *      {@link ClientRegistry.tryResolve}), while node THROWS (see {@link ClientRegistry.resolve}),\n *      because a server has no \"own origin\" and an unresolvable peer is a setup bug.\n *\n * Configured like {@link HeaderRegistry} / LogManager — populated once at startup, then globally\n * accessible with NO DI wiring. It is browser-safe (no `process.env`, no node-only deps), which is\n * why it lives in core-util rather than gcp-identity.\n *\n * A `svcName` should be the nx MODULE name of the service you are calling — that is the one name\n * `architecture:validate-runtime-architecture` can verify actually exists, so a typo or a rename\n * fails the build instead of failing in production. When the DEPLOYED name differs (an environment\n * prefix like `tf-`, or a Cloud Run service named unlike its module), translate it in ONE place —\n * the deriver below, or a `serviceName` alias in the module's project.json — never at the call site.\n *\n * ```ts\n * // startup, from the current environment's config:\n * ClientRegistry.addMapping('server2', 8202);                       // -> http://localhost:8202\n * ClientRegistry.addUrlMapping('email', 'https://email.other-region.example');\n * ClientRegistry.setDeriver(gcpCloudRunDeriver());                  // everything else, on GCP\n * ```\n */\nexport class ClientRegistry {\n    /** svcName -> resolved base URL. Process-global; populated at startup per environment. */\n    private static readonly mappings = new Map<string, string>();\n\n    /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */\n    private static deriver: ServiceUrlDeriver | undefined;\n\n    /**\n     * The app's ONE {@link ErrorTranslators}, consulted BEFORE webpieces' built-in error mapping in\n     * BOTH directions. Process-global, set once at startup on the SERVER and in the BROWSER — the\n     * same no-DI pattern as {@link ClientRegistry.mappings} above.\n     *\n     * ONE, not a list, on purpose: an app that has several layers of error policy composes them\n     * INSIDE its own `toWire`, where the precedence is written down, instead of leaving it implicit\n     * in the order two unrelated startup paths happened to register.\n     */\n    private static errorTranslators: ErrorTranslators | undefined;\n\n    /**\n     * The app/company DEFAULT {@link FailureClassifier} — ONE per process, reads {@link ApiMethodInfo.side}\n     * so a single strategy covers the server router AND all internal clients. Undefined = use the\n     * webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}). Populated once at startup on the\n     * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.\n     */\n    private static appDefaultFailureClassifier: FailureClassifier | undefined;\n\n    /**\n     * Per-EXTERNAL-client {@link FailureClassifier}s, keyed by {@link ApiMethodInfo.apiClass}\n     * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external\n     * client overrides the default for its own apiClass only. Internal clients / the server register\n     * nothing here and fall through to the default. See {@link ClientRegistry.classifyFailure}.\n     */\n    private static readonly failureClassifiersByApiClass = new Map<string, FailureClassifier>();\n\n    /** Map a service name to `http://localhost:<port>`. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addMapping(svcName: string, port: number): void {\n        ClientRegistry.mappings.set(svcName, `http://localhost:${port}`);\n    }\n\n    /**\n     * Map a service name to an explicit base URL (any host / any environment).\n     *\n     * The EMPTY STRING is a legal, meaningful mapping: it makes the service relative, i.e.\n     * same-origin, because the client builds its URL as `${baseUrl}${route.path}`.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addUrlMapping(svcName: string, url: string): void {\n        ClientRegistry.mappings.set(svcName, url);\n    }\n\n    /**\n     * Install the environment's {@link ServiceUrlDeriver} — how to resolve a svcName that has NO\n     * mapping. Optional: an environment that registers every svcName it calls needs none.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setDeriver(fn: ServiceUrlDeriver): void {\n        ClientRegistry.deriver = fn;\n    }\n\n    /** The registered override for `svcName`, or undefined if none. Registry only — no derivation. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryLookup(svcName: string): string | undefined {\n        return ClientRegistry.mappings.get(svcName);\n    }\n\n    /**\n     * Resolve `svcName` to its registered base URL. THROWS if the service was never registered.\n     * Registry only — it does NOT consult the deriver; prefer {@link ClientRegistry.resolve}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static lookup(svcName: string): string {\n        const url = ClientRegistry.tryLookup(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL registered for service \"${svcName}\". Register it at startup: ` +\n                    `ClientRegistry.addMapping(svcName, port) for a localhost port, or ` +\n                    `ClientRegistry.addUrlMapping(svcName, url) for an explicit URL.`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Steps 1 + 2 of the chain: the registered mapping, else the installed deriver, else undefined.\n     * Non-throwing — the BROWSER uses this and treats undefined as \"\" (relative → same origin),\n     * which is what a browser app calling the backend it was served from wants by default.\n     *\n     * Note the `!== undefined` guard: an empty-string mapping is a legal answer (\"this service is\n     * same-origin\"), so it must NOT fall through to derivation.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryResolve(svcName: string): Promise<string | undefined> {\n        const override = ClientRegistry.tryLookup(svcName);\n        if (override !== undefined) {\n            return Promise.resolve(override);\n        }\n        if (!ClientRegistry.deriver) {\n            return Promise.resolve(undefined);\n        }\n        return ClientRegistry.deriver(svcName);\n    }\n\n    /**\n     * The full chain, with node's fallback: mapping, else deriver, else THROW. A server has no \"own\n     * origin\" to go relative to, so an unresolvable peer is a setup bug and must fail loudly — and\n     * say how to fix it.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static async resolve(svcName: string): Promise<string> {\n        const url = await ClientRegistry.tryResolve(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL for service \"${svcName}\".\\n` +\n                    `  - localhost/AWS: ClientRegistry.addMapping('${svcName}', 8401)\\n` +\n                    `                or ClientRegistry.addUrlMapping('${svcName}', 'https://...')\\n` +\n                    `  - GCP: install a deriver — ClientRegistry.setDeriver(gcpCloudRunDeriver())\\n` +\n                    `  - deployed name differs from the module name (e.g. a 'tf-' prefix)? Translate it ONCE\\n` +\n                    `    in the deriver — setDeriver(s => gcpCloudRunDeriver()('tf-' + s)) — so every call\\n` +\n                    `    site keeps naming the MODULE, which architecture:validate-runtime-architecture checks`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Install the app's {@link ErrorTranslators} — the ONE symmetric owner of error translation for\n     * this process, server side AND every client side. Consulted BEFORE webpieces' built-in mapping\n     * in both directions. Call ONCE at startup, on the server AND in the browser, mirroring\n     * {@link ClientRegistry.addMapping}.\n     *\n     * `set`, not `add`: see the field doc above for why a registry LIST is not wanted.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setErrorTranslators(translators: ErrorTranslators): void {\n        ClientRegistry.errorTranslators = translators;\n    }\n\n    /**\n     * The app's installed {@link ErrorTranslators}, or `undefined` when this process installed none.\n     *\n     * The `undefined` here is \"nobody registered\", which is a fact about the PROCESS — it is not a\n     * per-error \"not mine\". A registered translator answers EVERY error and EVERY response, declining\n     * by delegating to the webpieces default (see {@link ErrorTranslators}), so a caller asks this\n     * question exactly once and then makes one unconditional call.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static getErrorTranslators(): ErrorTranslators | undefined {\n        return ClientRegistry.errorTranslators;\n    }\n\n    /**\n     * Set the app/company DEFAULT failure classifier — ONE per process, covering the server router and\n     * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the\n     * server AND in the browser. Overrides the webpieces built-in for calls no per-apiClass classifier\n     * claims. See {@link FailureClassifier}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setDefaultFailureClassifier(classifier: FailureClassifier): void {\n        ClientRegistry.appDefaultFailureClassifier = classifier;\n    }\n\n    /**\n     * Register a per-EXTERNAL-client failure classifier, keyed by {@link ApiMethodInfo.apiClass}\n     * (e.g. 'FirestoreAdminClient'). Consulted BEFORE the default tier for calls with that apiClass.\n     * Call ONCE at startup. See {@link FailureClassifier}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addFailureClassifier(apiClass: string, classifier: FailureClassifier): void {\n        ClientRegistry.failureClassifiersByApiClass.set(apiClass, classifier);\n    }\n\n    /**\n     * Is this thrown API-call error a real FAILURE (true) or an expected non-failure (false)?\n     * Resolved most-specific-first, and ALWAYS definitive (returns a boolean):\n     *   1. the per-apiClass classifier, if one is registered for `methodInfo.apiClass` — unless it defers;\n     *   2. else the app default classifier, if one was set — unless it defers;\n     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}), which never defers.\n     * A `?? true` backstop keeps an unexpectedly-deferring built-in fail-safe (treat as failure).\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static classifyFailure(error: Error, methodInfo: ApiMethodInfo): boolean {\n        const perClient = ClientRegistry.failureClassifiersByApiClass.get(methodInfo.apiClass);\n        if (perClient !== undefined) {\n            const verdict = perClient.isFailure(error, methodInfo);\n            if (verdict !== undefined) {\n                return verdict;\n            }\n        }\n        if (ClientRegistry.appDefaultFailureClassifier !== undefined) {\n            const verdict = ClientRegistry.appDefaultFailureClassifier.isFailure(error, methodInfo);\n            if (verdict !== undefined) {\n                return verdict;\n            }\n        }\n        return WEBPIECES_DEFAULT_FAILURE_CLASSIFIER.isFailure(error, methodInfo) ?? true;\n    }\n\n    /**\n     * Reset mappings, the deriver, the error translators, AND failure classifiers. For tests, so\n     * the process-globals do not leak across specs.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static clear(): void {\n        ClientRegistry.mappings.clear();\n        ClientRegistry.deriver = undefined;\n        ClientRegistry.errorTranslators = undefined;\n        ClientRegistry.appDefaultFailureClassifier = undefined;\n        ClientRegistry.failureClassifiersByApiClass.clear();\n    }\n}\n"]}
+{"version":3,"file":"ClientRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ClientRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { ErrorTranslator } from './ErrorTranslator';\nimport { FailureClassifier } from './FailureClassifier';\nimport { WEBPIECES_DEFAULT_FAILURE_CLASSIFIER } from './WebpiecesDefaultFailureClassifier';\nimport { WEBPIECES_DEFAULT_ERROR_TRANSLATOR } from './WebpiecesDefaultErrorTranslator';\nimport { ApiMethodInfo } from './ApiMethodInfo';\n\n/**\n * Derives a base URL for a service name that has NO registered mapping — the pluggable half of\n * {@link ClientRegistry} resolution. One per environment, installed once at startup:\n *\n * - `gcpCloudRunDeriver()` (@webpieces/gcp-identity) — the Cloud Run formula, read from the metadata\n *   server. For code running ON GCP.\n * - `gcpCloudRunDeriver(new GcpCloudRunTarget(projectNumber, region))` — the SAME formula with the\n *   values supplied from config, for code running OFF GCP that still calls Cloud Run (a CLI, CI).\n * - {@link templateDeriver} (this package, browser-safe) — pure string substitution, for AWS or\n *   anything else with predictable DNS.\n * - none at all — a browser goes same-origin, and localhost/tests hand-register their mappings.\n */\nexport type ServiceUrlDeriver = (svcName: string) => Promise<string>;\n\n/**\n * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every\n * environment. A client is built once but a URL is per-environment, so the URL belongs here rather\n * than on the client: clients carry ONLY a svcName.\n *\n * Resolution is one precedence chain, identical in the browser, in node, and in Cloud Tasks:\n *\n *   1. a registered mapping wins — the localhost port table, AWS, an external API, another region\n *      or project, a host that is not Cloud Run at all. Populated at startup from per-env config.\n *   2. else the installed {@link ServiceUrlDeriver}, if any — GCP's built-in, a DNS template, or\n *      your own. OPTIONAL on purpose: localhost is inherently a TABLE (helper-fsdb -> :8401,\n *      helper-portal -> :8201 have per-service ports), so explicit mappings must stay sufficient on\n *      their own.\n *   3. else the caller's fallback: the BROWSER goes relative (same origin — see\n *      {@link ClientRegistry.tryResolve}), while node THROWS (see {@link ClientRegistry.resolve}),\n *      because a server has no \"own origin\" and an unresolvable peer is a setup bug.\n *\n * Configured like {@link HeaderRegistry} / LogManager — populated once at startup, then globally\n * accessible with NO DI wiring. It is browser-safe (no `process.env`, no node-only deps), which is\n * why it lives in core-util rather than gcp-identity.\n *\n * A `svcName` should be the nx MODULE name of the service you are calling — that is the one name\n * `architecture:validate-runtime-architecture` can verify actually exists, so a typo or a rename\n * fails the build instead of failing in production. When the DEPLOYED name differs (an environment\n * prefix like `tf-`, or a Cloud Run service named unlike its module), translate it in ONE place —\n * the deriver below, or a `serviceName` alias in the module's project.json — never at the call site.\n *\n * ```ts\n * // startup, from the current environment's config:\n * ClientRegistry.addMapping('server2', 8202);                       // -> http://localhost:8202\n * ClientRegistry.addUrlMapping('email', 'https://email.other-region.example');\n * ClientRegistry.setDeriver(gcpCloudRunDeriver());                  // everything else, on GCP\n * ```\n */\nexport class ClientRegistry {\n    /** svcName -> resolved base URL. Process-global; populated at startup per environment. */\n    private static readonly mappings = new Map<string, string>();\n\n    /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */\n    private static deriver: ServiceUrlDeriver | undefined;\n\n    /**\n     * The process's ONE {@link ErrorTranslator}. NEVER undefined — it starts life holding\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, and {@link ClientRegistry.setErrorTranslator}\n     * REPLACES it. Process-global, set once at startup on the SERVER and in the BROWSER — the same\n     * no-DI pattern as {@link ClientRegistry.mappings} above.\n     *\n     * There is no \"did anyone register one\" question anywhere in the framework because this field\n     * cannot be empty: every caller makes ONE unconditional call, and an app translator declines an\n     * error by DELEGATING to {@link WebpiecesDefaultErrorTranslator}.\n     *\n     * ONE, not a list, on purpose: an app that has several layers of error policy composes them\n     * INSIDE its own `toWire`, where the precedence is written down, instead of leaving it implicit\n     * in the order two unrelated startup paths happened to register.\n     */\n    private static errorTranslator: ErrorTranslator = WEBPIECES_DEFAULT_ERROR_TRANSLATOR;\n\n    /**\n     * The app/company DEFAULT {@link FailureClassifier} — ONE per process, reads {@link ApiMethodInfo.side}\n     * so a single strategy covers the server router AND all internal clients. NEVER undefined: it\n     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}) and\n     * {@link ClientRegistry.setDefaultFailureClassifier} replaces it. Populated once at startup on the\n     * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.\n     */\n    private static appDefaultFailureClassifier: FailureClassifier =\n        WEBPIECES_DEFAULT_FAILURE_CLASSIFIER;\n\n    /**\n     * Per-EXTERNAL-client {@link FailureClassifier}s, keyed by {@link ApiMethodInfo.apiClass}\n     * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external\n     * client overrides the default for its own apiClass only. Internal clients / the server register\n     * nothing here and fall through to the default. See {@link ClientRegistry.classifyFailure}.\n     */\n    private static readonly failureClassifiersByApiClass = new Map<string, FailureClassifier>();\n\n    /** Map a service name to `http://localhost:<port>`. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addMapping(svcName: string, port: number): void {\n        ClientRegistry.mappings.set(svcName, `http://localhost:${port}`);\n    }\n\n    /**\n     * Map a service name to an explicit base URL (any host / any environment).\n     *\n     * The EMPTY STRING is a legal, meaningful mapping: it makes the service relative, i.e.\n     * same-origin, because the client builds its URL as `${baseUrl}${route.path}`.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addUrlMapping(svcName: string, url: string): void {\n        ClientRegistry.mappings.set(svcName, url);\n    }\n\n    /**\n     * Install the environment's {@link ServiceUrlDeriver} — how to resolve a svcName that has NO\n     * mapping. Optional: an environment that registers every svcName it calls needs none.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setDeriver(fn: ServiceUrlDeriver): void {\n        ClientRegistry.deriver = fn;\n    }\n\n    /** The registered override for `svcName`, or undefined if none. Registry only — no derivation. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryLookup(svcName: string): string | undefined {\n        return ClientRegistry.mappings.get(svcName);\n    }\n\n    /**\n     * Resolve `svcName` to its registered base URL. THROWS if the service was never registered.\n     * Registry only — it does NOT consult the deriver; prefer {@link ClientRegistry.resolve}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static lookup(svcName: string): string {\n        const url = ClientRegistry.tryLookup(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL registered for service \"${svcName}\". Register it at startup: ` +\n                    `ClientRegistry.addMapping(svcName, port) for a localhost port, or ` +\n                    `ClientRegistry.addUrlMapping(svcName, url) for an explicit URL.`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Steps 1 + 2 of the chain: the registered mapping, else the installed deriver, else undefined.\n     * Non-throwing — the BROWSER uses this and treats undefined as \"\" (relative → same origin),\n     * which is what a browser app calling the backend it was served from wants by default.\n     *\n     * Note the `!== undefined` guard: an empty-string mapping is a legal answer (\"this service is\n     * same-origin\"), so it must NOT fall through to derivation.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryResolve(svcName: string): Promise<string | undefined> {\n        const override = ClientRegistry.tryLookup(svcName);\n        if (override !== undefined) {\n            return Promise.resolve(override);\n        }\n        if (!ClientRegistry.deriver) {\n            return Promise.resolve(undefined);\n        }\n        return ClientRegistry.deriver(svcName);\n    }\n\n    /**\n     * The full chain, with node's fallback: mapping, else deriver, else THROW. A server has no \"own\n     * origin\" to go relative to, so an unresolvable peer is a setup bug and must fail loudly — and\n     * say how to fix it.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static async resolve(svcName: string): Promise<string> {\n        const url = await ClientRegistry.tryResolve(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL for service \"${svcName}\".\\n` +\n                    `  - localhost/AWS: ClientRegistry.addMapping('${svcName}', 8401)\\n` +\n                    `                or ClientRegistry.addUrlMapping('${svcName}', 'https://...')\\n` +\n                    `  - GCP: install a deriver — ClientRegistry.setDeriver(gcpCloudRunDeriver())\\n` +\n                    `  - deployed name differs from the module name (e.g. a 'tf-' prefix)? Translate it ONCE\\n` +\n                    `    in the deriver — setDeriver(s => gcpCloudRunDeriver()('tf-' + s)) — so every call\\n` +\n                    `    site keeps naming the MODULE, which architecture:validate-runtime-architecture checks`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Install the app's {@link ErrorTranslator} — the ONE symmetric owner of error translation for\n     * this process, server side AND every client side. Consulted BEFORE webpieces' built-in mapping\n     * in both directions. Call ONCE at startup, on the server AND in the browser, mirroring\n     * {@link ClientRegistry.addMapping}.\n     *\n     * `set`, not `add`: see the field doc above for why a registry LIST is not wanted.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setErrorTranslator(translator: ErrorTranslator): void {\n        ClientRegistry.errorTranslator = translator;\n    }\n\n    /**\n     * THE {@link ErrorTranslator} for this process — never `undefined`, so a caller never branches.\n     *\n     * Until an app calls {@link ClientRegistry.setErrorTranslator} this is\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}. A registered translator answers EVERY error and\n     * EVERY response, declining by delegating to the webpieces default (see {@link ErrorTranslator}),\n     * so every call site in the framework is one unconditional line.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static getErrorTranslator(): ErrorTranslator {\n        return ClientRegistry.errorTranslator;\n    }\n\n    /**\n     * Set the app/company DEFAULT failure classifier — ONE per process, covering the server router and\n     * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the\n     * server AND in the browser. Overrides the webpieces built-in for calls no per-apiClass classifier\n     * claims. See {@link FailureClassifier}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setDefaultFailureClassifier(classifier: FailureClassifier): void {\n        ClientRegistry.appDefaultFailureClassifier = classifier;\n    }\n\n    /**\n     * Register a per-EXTERNAL-client failure classifier, keyed by {@link ApiMethodInfo.apiClass}\n     * (e.g. 'FirestoreAdminClient'). Consulted BEFORE the default tier for calls with that apiClass.\n     * Call ONCE at startup. See {@link FailureClassifier}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addFailureClassifier(apiClass: string, classifier: FailureClassifier): void {\n        ClientRegistry.failureClassifiersByApiClass.set(apiClass, classifier);\n    }\n\n    /**\n     * Is this thrown API-call error a real FAILURE (true) or an expected non-failure (false)?\n     * Resolved most-specific-first, and ALWAYS definitive (returns a boolean):\n     *   1. the per-apiClass classifier, if one is registered for `methodInfo.apiClass` — unless it defers;\n     *   2. else the app default classifier, if one was set — unless it defers;\n     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}), which never defers.\n     * A `?? true` backstop keeps an unexpectedly-deferring built-in fail-safe (treat as failure).\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static classifyFailure(error: Error, methodInfo: ApiMethodInfo): boolean {\n        const perClient = ClientRegistry.failureClassifiersByApiClass.get(methodInfo.apiClass);\n        if (perClient !== undefined) {\n            const verdict = perClient.isFailure(error, methodInfo);\n            if (verdict !== undefined) {\n                return verdict;\n            }\n        }\n        const verdict = ClientRegistry.appDefaultFailureClassifier.isFailure(error, methodInfo);\n        if (verdict !== undefined) {\n            return verdict;\n        }\n        return WEBPIECES_DEFAULT_FAILURE_CLASSIFIER.isFailure(error, methodInfo) ?? true;\n    }\n\n    /**\n     * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec\n     * cannot leak its registrations into the next.\n     *\n     * It RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole\n     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default failure\n     * classifier are non-optional now, so \"cleared\" is not a state they have. A spec that wants\n     * webpieces' own behaviour back asks for exactly that.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static resetForTests(): void {\n        ClientRegistry.mappings.clear();\n        ClientRegistry.deriver = undefined;\n        ClientRegistry.errorTranslator = WEBPIECES_DEFAULT_ERROR_TRANSLATOR;\n        ClientRegistry.appDefaultFailureClassifier = WEBPIECES_DEFAULT_FAILURE_CLASSIFIER;\n        ClientRegistry.failureClassifiersByApiClass.clear();\n    }\n}\n"]}

package/src/http/ErrorTranslator.d.ts

@@ -0,0 +1,115 @@
+import { HttpResponseDto } from './HttpResponseDto';
+/**
+ * ErrorTranslator - ONE symmetric place an app owns HTTP error translation, in BOTH directions, over
+ * the WHOLE response.
+ *
+ * An app implements this ONCE and registers it ONCE per process via
+ * {@link ClientRegistry.setErrorTranslator} — on the server AND in the browser. Its `toWire` runs on
+ * the SERVER (`ExpressWrapper.handleError`) and its `fromWire` runs on every CLIENT in that process
+ * (`ClientErrorTranslator.throwIfFailure`, shared by `http-client-node` and `http-client-browser`).
+ * The payoff is type symmetry across the wire: the server throws `OrderNotFoundError` and the caller
+ * CATCHES `OrderNotFoundError`, instead of decoding a status code by hand at every call site.
+ *
+ * # THERE IS ALWAYS A TRANSLATOR
+ *
+ * {@link ClientRegistry.getErrorTranslator} is non-optional and starts life holding
+ * {@link WebpiecesDefaultErrorTranslator}. So no caller anywhere asks "did anyone register one" —
+ * every call site is ONE unconditional line. A registered app translator REPLACES the default and
+ * declines by DELEGATING to it:
+ *
+ * ```ts
+ * private readonly fallback = new WebpiecesDefaultErrorTranslator();
+ * ```
+ *
+ * That is one call, it is visible at the call site, and it composes: an app that wants to DECORATE
+ * the default rather than replace it does so by calling it and editing the result. A `next` parameter
+ * was considered and rejected — it buys nothing this does not, and it puts the framework back in the
+ * business of sequencing somebody else's precedence.
+ *
+ * # Both halves speak {@link HttpResponseDto}, and that is the point
+ *
+ * `toWire` PRODUCES exactly what `fromWire` CONSUMES. Reading the two methods against each other in
+ * one file is what makes a mistake visible, which is why this is one object rather than two
+ * separately-registered functions.
+ *
+ * # The whole response, not a status plus a body
+ *
+ * The previous contract could express only `(statusCode, protocolError)`, so an app could not put its
+ * own trace id, `Retry-After`, `WWW-Authenticate` or a cookie on an error response. A translator now
+ * returns the status code, the reason phrase, the header LIST and the body — everything.
+ *
+ * # `toWire` RETURNS a response; `fromWire` THROWS
+ *
+ * They are mirrors, not twins. `toWire` is called inside a catch and its whole job is to produce a
+ * value, so it returns one. `fromWire` is called on a response the caller is about to be handed, and
+ * its whole job is to stop that from happening, so it THROWS and is typed `void`. Returning an
+ * `Error` the caller then has to remember to throw was the previous shape and it is exactly the bug
+ * class this deletes: a `void` return cannot be silently dropped.
+ *
+ * There is exactly ONE registered ErrorTranslator per process (a `set`, not an `add` to a list):
+ * precedence between an app's own layers is the APP's to compose explicitly inside its `toWire`,
+ * rather than something hidden in registration order inside the framework.
+ *
+ * # Not covered: 404 / unknown route
+ *
+ * A request that matches no route has no route context and never reaches this seam. That is
+ * deliberate and out of scope.
+ *
+ * This is a business-logic contract (methods, not data), so it is an interface per the webpieces
+ * guidelines.
+ *
+ * ```ts
+ * class OrderErrorPayload {
+ *     constructor(public message: string, public errorCode: string) {}
+ * }
+ *
+ * export class OrderErrorTranslator implements ErrorTranslator {
+ *     private readonly fallback = new WebpiecesDefaultErrorTranslator();
+ *
+ *     toWire(error: Error): HttpResponseDto {
+ *         if (!(error instanceof OrderNotFoundError)) {
+ *             return this.fallback.toWire(error);        // not mine -> webpieces default
+ *         }
+ *         const body = new OrderErrorPayload(error.message, 'ORDER_NOT_FOUND');
+ *         return new HttpResponseDto(
+ *             new HttpResponseStatus(460, 'Order Not Found'),
+ *             [new HttpHeader('x-order-trace', error.traceId)],
+ *             body,
+ *         );
+ *     }
+ *
+ *     fromWire(response: HttpResponseDto): void {
+ *         if (response.status.code !== 460) {
+ *             this.fallback.fromWire(response);          // not mine -> webpieces default
+ *             return;
+ *         }
+ *         throw new OrderNotFoundError(String(response.body));
+ *     }
+ * }
+ *
+ * // startup, ONCE per process (server AND browser)
+ * ClientRegistry.setErrorTranslator(new OrderErrorTranslator());
+ * ```
+ */
+export interface ErrorTranslator {
+    /**
+     * SERVER: exception -> the ENTIRE response (status code, reason phrase, headers, body). Always a
+     * response, never `undefined`; decline by returning
+     * `new WebpiecesDefaultErrorTranslator().toWire(error)`.
+     */
+    toWire(error: Error): HttpResponseDto;
+    /**
+     * CLIENT: the ENTIRE response -> a THROW. Receives the SAME shape `toWire` produces, normalised
+     * from whichever transport read it.
+     *
+     * Called for EVERY response, including a 2xx — deliberately, so an app whose 200 body signals
+     * failure can turn it into a throw. Returning normally means "let this response through"; the
+     * webpieces default returns normally for any 2xx that is not 266 and throws otherwise. Decline by
+     * calling `new WebpiecesDefaultErrorTranslator().fromWire(response)`.
+     *
+     * A non-2xx response can never reach a typed caller even if an app translator forgets to throw:
+     * `ClientErrorTranslator.throwIfFailure` applies the webpieces default behind it. That is bug
+     * containment, not a "was one registered" branch.
+     */
+    fromWire(response: HttpResponseDto): void;
+}

package/src/http/{ErrorTranslators.js → ErrorTranslator.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=ErrorTranslators.js.map
+//# sourceMappingURL=ErrorTranslator.js.map