@webpieces/core-util 0.4.777 → 0.4.779

package/package.json

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

package/src/errors/ApiCodedErrorCompileAssertions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * COMPILE-TIME assertions for `ApiStatusCode`: an out-of-range or fractional status on
+ * `ApiCodedError` is a compile error, not a runtime throw. Each `@ts-expect-error` below fails the
+ * build (TS2578) if its line ever starts compiling. This is a non-spec file on purpose: vitest strips
+ * types, and tsconfig.lib.json excludes specs, so only a compiled file makes these assertions real.
+ */
+export declare class ApiCodedErrorCompileAssertions {
+    /** Every edge of the legal range compiles, including codes a named class already owns. */
+    legitimate(): void;
+    illegal(): void;
+    /** A dynamic number must be narrowed first; after the guard it compiles. */
+    dynamic(value: number): void;
+}

package/src/errors/ApiCodedErrorCompileAssertions.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiCodedErrorCompileAssertions = void 0;
+const ApiError_1 = require("./ApiError");
+/**
+ * COMPILE-TIME assertions for `ApiStatusCode`: an out-of-range or fractional status on
+ * `ApiCodedError` is a compile error, not a runtime throw. Each `@ts-expect-error` below fails the
+ * build (TS2578) if its line ever starts compiling. This is a non-spec file on purpose: vitest strips
+ * types, and tsconfig.lib.json excludes specs, so only a compiled file makes these assertions real.
+ */
+class ApiCodedErrorCompileAssertions {
+    /** Every edge of the legal range compiles, including codes a named class already owns. */
+    legitimate() {
+        void new ApiError_1.ApiCodedError('x', 100);
+        void new ApiError_1.ApiCodedError('x', 404);
+        void new ApiError_1.ApiCodedError('x', 460, 'app-code');
+        void new ApiError_1.ApiCodedError('x', 599);
+    }
+    illegal() {
+        // @ts-expect-error -- below 100 is not an HTTP status
+        void new ApiError_1.ApiCodedError('x', 99);
+        // @ts-expect-error -- 600 and above is not an HTTP status
+        void new ApiError_1.ApiCodedError('x', 600);
+        // @ts-expect-error -- a status is an integer
+        void new ApiError_1.ApiCodedError('x', 404.5);
+    }
+    /** A dynamic number must be narrowed first; after the guard it compiles. */
+    dynamic(value) {
+        // @ts-expect-error -- an unnarrowed number is not a status code
+        void new ApiError_1.ApiCodedError('x', value);
+        if (ApiError_1.ApiCodedError.isStatusCode(value))
+            void new ApiError_1.ApiCodedError('x', value);
+    }
+}
+exports.ApiCodedErrorCompileAssertions = ApiCodedErrorCompileAssertions;
+//# sourceMappingURL=ApiCodedErrorCompileAssertions.js.map

package/src/errors/ApiCodedErrorCompileAssertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiCodedErrorCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiCodedErrorCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,yCAA2C;AAE3C;;;;;GAKG;AACH,MAAa,8BAA8B;IACvC,0FAA0F;IAC1F,UAAU;QACN,KAAK,IAAI,wBAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjC,KAAK,IAAI,wBAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjC,KAAK,IAAI,wBAAa,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;QAC7C,KAAK,IAAI,wBAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,OAAO;QACH,sDAAsD;QACtD,KAAK,IAAI,wBAAa,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAChC,0DAA0D;QAC1D,KAAK,IAAI,wBAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjC,6CAA6C;QAC7C,KAAK,IAAI,wBAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,4EAA4E;IAC5E,OAAO,CAAC,KAAa;QACjB,gEAAgE;QAChE,KAAK,IAAI,wBAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACnC,IAAI,wBAAa,CAAC,YAAY,CAAC,KAAK,CAAC;YAAE,KAAK,IAAI,wBAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9E,CAAC;CACJ;AAxBD,wEAwBC","sourcesContent":["import { ApiCodedError } from './ApiError';\n\n/**\n * COMPILE-TIME assertions for `ApiStatusCode`: an out-of-range or fractional status on\n * `ApiCodedError` is a compile error, not a runtime throw. Each `@ts-expect-error` below fails the\n * build (TS2578) if its line ever starts compiling. This is a non-spec file on purpose: vitest strips\n * types, and tsconfig.lib.json excludes specs, so only a compiled file makes these assertions real.\n */\nexport class ApiCodedErrorCompileAssertions {\n    /** Every edge of the legal range compiles, including codes a named class already owns. */\n    legitimate(): void {\n        void new ApiCodedError('x', 100);\n        void new ApiCodedError('x', 404);\n        void new ApiCodedError('x', 460, 'app-code');\n        void new ApiCodedError('x', 599);\n    }\n\n    illegal(): void {\n        // @ts-expect-error -- below 100 is not an HTTP status\n        void new ApiCodedError('x', 99);\n        // @ts-expect-error -- 600 and above is not an HTTP status\n        void new ApiCodedError('x', 600);\n        // @ts-expect-error -- a status is an integer\n        void new ApiCodedError('x', 404.5);\n    }\n\n    /** A dynamic number must be narrowed first; after the guard it compiles. */\n    dynamic(value: number): void {\n        // @ts-expect-error -- an unnarrowed number is not a status code\n        void new ApiCodedError('x', value);\n        if (ApiCodedError.isStatusCode(value)) void new ApiCodedError('x', value);\n    }\n}\n"]}

package/src/errors/ApiError.d.ts

@@ -1,4 +1,4 @@
-export type ApiErrorKind = 'end-user' | 'bad-request' | 'unauthorized' | 'forbidden' | 'not-found' | 'endpoint-not-found' | 'request-timeout' | 'rate-limited' | 'implementation' | 'dependency' | 'unavailable' | 'dependency-timeout' | 'dependency-backoff' | 'connection';
+export type ApiErrorKind = 'end-user' | 'bad-request' | 'unauthorized' | 'forbidden' | 'not-found' | 'endpoint-not-found' | 'request-timeout' | 'rate-limited' | 'conflict' | 'unprocessable' | 'precondition-failed' | 'unsupported-media-type' | 'not-implemented' | 'coded' | 'implementation' | 'dependency' | 'unavailable' | 'dependency-timeout' | 'dependency-backoff' | 'connection';
 /** Category for portable API failures. Concrete subclasses alone define protocol mappings. */
 export declare abstract class ApiError extends Error {
     abstract readonly kind: ApiErrorKind;
@@ -74,3 +74,49 @@ export declare class ApiDependencyBackoffError extends ApiError {
     readonly kind: "dependency-backoff";
     constructor(message: string, retryAfterSeconds?: number, cause?: Error);
 }
+/** The request conflicts with the current state of the target resource (HTTP 409). */
+export declare class ApiConflictError extends ApiError {
+    readonly kind: "conflict";
+}
+/** The request was well-formed but semantically unprocessable (HTTP 422). */
+export declare class ApiUnprocessableError extends ApiError {
+    readonly kind: "unprocessable";
+}
+/** A caller-supplied precondition (for example If-Match) did not hold (HTTP 412). */
+export declare class ApiPreconditionFailedError extends ApiError {
+    readonly kind: "precondition-failed";
+}
+/** The request body is in a media type this operation does not accept (HTTP 415). */
+export declare class ApiUnsupportedMediaTypeError extends ApiError {
+    readonly kind: "unsupported-media-type";
+}
+/** The operation exists in the contract but this server does not implement it (HTTP 501). */
+export declare class ApiNotImplementedError extends ApiError {
+    readonly kind: "not-implemented";
+}
+/** Builds the tuple [0, 1, ..., N-1]; tail-recursive so TypeScript can reach 600. */
+type StatusRange<N extends number, Acc extends number[] = []> = Acc['length'] extends N ? Acc : StatusRange<N, [...Acc, Acc['length']]>;
+/**
+ * Every integer from 100 through 599 as a literal union. `new ApiCodedError(msg, 600)`,
+ * `new ApiCodedError(msg, 99)` and `new ApiCodedError(msg, 404.5)` do not compile; a dynamic
+ * `number` must be narrowed with {@link ApiCodedError.isStatusCode} first.
+ */
+export type ApiStatusCode = Exclude<StatusRange<600>[number], StatusRange<100>[number]>;
+/**
+ * Catch-all carrying an explicit protocol status for outcomes no named ApiError covers. Any code in
+ * 100-599 is accepted, including one a named class already owns. `statusCode` and `errorCode` survive
+ * every remote hop through `ApiErrorCodec`; `message` stays operator-only like every other non
+ * end-user kind. A status below 500 is a caller outcome (except 408 and 429, which mirror
+ * `ApiRequestTimeoutError` and `ApiRateLimitedError`); 500 and above is a server/dependency fault.
+ */
+export declare class ApiCodedError extends ApiError {
+    readonly statusCode: ApiStatusCode;
+    errorCode?: string | undefined;
+    readonly kind: "coded";
+    constructor(message: string, statusCode: ApiStatusCode, errorCode?: string | undefined, cause?: Error);
+    /** Narrows a dynamic number (for example one read off the wire) to a legal status code. */
+    static isStatusCode(value: unknown): value is ApiStatusCode;
+    /** True when the status describes the caller's mistake rather than a fault on the serving side. */
+    isCallerError(): boolean;
+}
+export {};

package/src/errors/ApiError.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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;
 /** Category for portable API failures. Concrete subclasses alone define protocol mappings. */
 class ApiError extends Error {
     subType;
@@ -110,4 +110,56 @@ class ApiDependencyBackoffError extends ApiError {
     }
 }
 exports.ApiDependencyBackoffError = ApiDependencyBackoffError;
+/** The request conflicts with the current state of the target resource (HTTP 409). */
+class ApiConflictError extends ApiError {
+    kind = 'conflict';
+}
+exports.ApiConflictError = ApiConflictError;
+/** The request was well-formed but semantically unprocessable (HTTP 422). */
+class ApiUnprocessableError extends ApiError {
+    kind = 'unprocessable';
+}
+exports.ApiUnprocessableError = ApiUnprocessableError;
+/** A caller-supplied precondition (for example If-Match) did not hold (HTTP 412). */
+class ApiPreconditionFailedError extends ApiError {
+    kind = 'precondition-failed';
+}
+exports.ApiPreconditionFailedError = ApiPreconditionFailedError;
+/** The request body is in a media type this operation does not accept (HTTP 415). */
+class ApiUnsupportedMediaTypeError extends ApiError {
+    kind = 'unsupported-media-type';
+}
+exports.ApiUnsupportedMediaTypeError = ApiUnsupportedMediaTypeError;
+/** The operation exists in the contract but this server does not implement it (HTTP 501). */
+class ApiNotImplementedError extends ApiError {
+    kind = 'not-implemented';
+}
+exports.ApiNotImplementedError = ApiNotImplementedError;
+/**
+ * Catch-all carrying an explicit protocol status for outcomes no named ApiError covers. Any code in
+ * 100-599 is accepted, including one a named class already owns. `statusCode` and `errorCode` survive
+ * every remote hop through `ApiErrorCodec`; `message` stays operator-only like every other non
+ * end-user kind. A status below 500 is a caller outcome (except 408 and 429, which mirror
+ * `ApiRequestTimeoutError` and `ApiRateLimitedError`); 500 and above is a server/dependency fault.
+ */
+class ApiCodedError extends ApiError {
+    statusCode;
+    errorCode;
+    kind = 'coded';
+    constructor(message, statusCode, errorCode, cause) {
+        super(message, cause);
+        this.statusCode = statusCode;
+        this.errorCode = errorCode;
+    }
+    /** Narrows a dynamic number (for example one read off the wire) to a legal status code. */
+    // webpieces-disable no-function-outside-class -- stateless status guard; webpieces-disable no-any-unknown -- wire and app values are narrowed here
+    static isStatusCode(value) {
+        return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599;
+    }
+    /** True when the status describes the caller's mistake rather than a fault on the serving side. */
+    isCallerError() {
+        return this.statusCode < 500 && this.statusCode !== 408 && this.statusCode !== 429;
+    }
+}
+exports.ApiCodedError = ApiCodedError;
 //# sourceMappingURL=ApiError.js.map

package/src/errors/ApiError.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiError.ts"],"names":[],"mappings":";;;AAgBA,8FAA8F;AAC9F,MAAsB,QAAS,SAAQ,KAAK;IAEjC,OAAO,CAAU;IAExB,YAAY,OAAe,EAAE,KAAa;QACtC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAChC,CAAC;CACJ;AARD,4BAQC;AAED,MAAa,gBAAiB,SAAQ,QAAQ;IACxB,IAAI,GAAiB,WAAW,CAAC;CACtD;AAFD,4CAEC;AACD,MAAa,kBAAmB,SAAQ,QAAQ;IAC1B,IAAI,GAAG,YAAqB,CAAC;CAClD;AAFD,gDAEC;AACD,MAAa,mBAAoB,SAAQ,QAAQ;IAC3B,IAAI,GAAG,aAAsB,CAAC;CACnD;AAFD,kDAEC;AACD,MAAa,yBAA0B,SAAQ,QAAQ;IACjC,IAAI,GAAG,oBAA6B,CAAC;CAC1D;AAFD,8DAEC;AAED,2GAA2G;AAC3G,MAAa,sBAAuB,SAAQ,QAAQ;IAM5B;IALF,IAAI,GAAG,gBAAyB,CAAC;IAEnD,YACI,OAAe,EACf,KAAa,EACG,cAAc,KAAK;QAEnC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAFN,gBAAW,GAAX,WAAW,CAAQ;IAGvC,CAAC;CACJ;AAVD,wDAUC;AAED,MAAa,mBAAoB,SAAQ,QAAQ;IAC3B,IAAI,GAAG,cAAuB,CAAC;CACpD;AAFD,kDAEC;AACD,MAAa,iBAAkB,SAAQ,QAAQ;IACzB,IAAI,GAAG,WAAoB,CAAC;CACjD;AAFD,8CAEC;AACD,MAAa,sBAAuB,SAAQ,QAAQ;IAC9B,IAAI,GAAG,iBAA0B,CAAC;CACvD;AAFD,wDAEC;AAED,gGAAgG;AAChG,MAAa,kBAAmB,SAAQ,QAAQ;IAC1B,IAAI,GAAG,YAAqB,CAAC;CAClD;AAFD,gDAEC;AAED,2EAA2E;AAC3E,MAAa,wBAAyB,SAAQ,gBAAgB;IACxC,IAAI,GAAG,oBAA6B,CAAC;CAC1D;AAFD,4DAEC;AAED;;;;;;;GAOG;AACH,MAAa,eAAgB,SAAQ,QAAQ;IAK9B;IAJO,IAAI,GAAG,UAAmB,CAAC;IAE7C,YACI,OAAe,EACR,SAAkB,EACzB,KAAa;QAEb,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAHf,cAAS,GAAT,SAAS,CAAS;QAIzB,IAAI,CAAC,OAAO,GAAG,YAAY,CAAC;IAChC,CAAC;CACJ;AAXD,0CAWC;AAED;;;;;GAKG;AACH,MAAa,kBAAmB,SAAQ,QAAQ;IAKjC;IACA;IALO,IAAI,GAAG,aAAsB,CAAC;IAEhD,YACI,OAAe,EACR,KAAc,EACd,aAAsB,EAC7B,KAAa;QAEb,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAJf,UAAK,GAAL,KAAK,CAAS;QACd,kBAAa,GAAb,aAAa,CAAS;IAIjC,CAAC;CACJ;AAXD,gDAWC;AAED,MAAa,oBAAqB,SAAQ,QAAQ;IAC5B,IAAI,GAAG,cAAuB,CAAC;IAEjD,YAAY,OAAe,EAAE,OAAgB,EAAE,KAAa;QACxD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CACJ;AAPD,oDAOC;AAED,MAAa,yBAA0B,SAAQ,QAAQ;IAKxC;IAJO,IAAI,GAAG,oBAA6B,CAAC;IAEvD,YACI,OAAe,EACR,oBAAoB,EAAE,EAC7B,KAAa;QAEb,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAHf,sBAAiB,GAAjB,iBAAiB,CAAK;IAIjC,CAAC;CACJ;AAVD,8DAUC","sourcesContent":["export type ApiErrorKind =\n    | 'end-user'\n    | 'bad-request'\n    | 'unauthorized'\n    | 'forbidden'\n    | 'not-found'\n    | 'endpoint-not-found'\n    | 'request-timeout'\n    | 'rate-limited'\n    | 'implementation'\n    | 'dependency'\n    | 'unavailable'\n    | 'dependency-timeout'\n    | 'dependency-backoff'\n    | 'connection';\n\n/** Category for portable API failures. Concrete subclasses alone define protocol mappings. */\nexport abstract class ApiError extends Error {\n    abstract readonly kind: ApiErrorKind;\n    public subType?: string;\n\n    constructor(message: string, cause?: Error) {\n        super(message, { cause });\n        this.name = new.target.name;\n    }\n}\n\nexport class ApiNotFoundError extends ApiError {\n    override readonly kind: ApiErrorKind = 'not-found';\n}\nexport class ApiDependencyError extends ApiError {\n    override readonly kind = 'dependency' as const;\n}\nexport class ApiUnavailableError extends ApiError {\n    override readonly kind = 'unavailable' as const;\n}\nexport class ApiDependencyTimeoutError extends ApiError {\n    override readonly kind = 'dependency-timeout' as const;\n}\n\n/** A bug or invalid implementation state. Local errors become server errors only after a remote decode. */\nexport class ApiImplementationError extends ApiError {\n    override readonly kind = 'implementation' as const;\n\n    constructor(\n        message: string,\n        cause?: Error,\n        public readonly serverError = false,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiRateLimitedError extends ApiError {\n    override readonly kind = 'rate-limited' as const;\n}\nexport class ApiForbiddenError extends ApiError {\n    override readonly kind = 'forbidden' as const;\n}\nexport class ApiRequestTimeoutError extends ApiError {\n    override readonly kind = 'request-timeout' as const;\n}\n\n/** A caller-local connection failure. HTTP servers normalize this to ApiImplementationError. */\nexport class ApiConnectionError extends ApiError {\n    override readonly kind = 'connection' as const;\n}\n\n/** The API operation is missing, distinct from an absent domain entity. */\nexport class ApiEndpointNotFoundError extends ApiNotFoundError {\n    override readonly kind = 'endpoint-not-found' as const;\n}\n\n/**\n * Expected mistake by the ACTOR driving the call: the input was well-formed but wrong in a way the actor\n * must fix (for example \"the two passwords you entered do not match\"). The actor may be a human user in\n * a GUI OR an LLM calling an MCP tool; the same class serves both. Its message is deliberately\n * caller-safe and is the only ApiError message published verbatim: `ApiErrorCodec` keeps it (and\n * `errorCode`) across every remote hop, so a downstream service's text reaches the GUI or the model\n * byte-for-byte.\n */\nexport class ApiEndUserError extends ApiError {\n    override readonly kind = 'end-user' as const;\n\n    constructor(\n        message: string,\n        public errorCode?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n        this.subType = 'USER_ERROR';\n    }\n}\n\n/**\n * Invalid API caller input (malformed, or failed validation). `message` is operator-only diagnostic\n * text and may name internals; it is never published. `callerMessage` (plus `field`) is what a GUI OR\n * an MCP model is shown so it can correct its input, so throw sites that want the caller to\n * self-correct MUST set it.\n */\nexport class ApiBadRequestError extends ApiError {\n    override readonly kind = 'bad-request' as const;\n\n    constructor(\n        message: string,\n        public field?: string,\n        public callerMessage?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiUnauthorizedError extends ApiError {\n    override readonly kind = 'unauthorized' as const;\n\n    constructor(message: string, subType?: string, cause?: Error) {\n        super(message, cause);\n        this.subType = subType;\n    }\n}\n\nexport class ApiDependencyBackoffError extends ApiError {\n    override readonly kind = 'dependency-backoff' as const;\n\n    constructor(\n        message: string,\n        public retryAfterSeconds = 30,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n"]}
+{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiError.ts"],"names":[],"mappings":"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","sourcesContent":["export type ApiErrorKind =\n    | 'end-user'\n    | 'bad-request'\n    | 'unauthorized'\n    | 'forbidden'\n    | 'not-found'\n    | 'endpoint-not-found'\n    | 'request-timeout'\n    | 'rate-limited'\n    | 'conflict'\n    | 'unprocessable'\n    | 'precondition-failed'\n    | 'unsupported-media-type'\n    | 'not-implemented'\n    | 'coded'\n    | 'implementation'\n    | 'dependency'\n    | 'unavailable'\n    | 'dependency-timeout'\n    | 'dependency-backoff'\n    | 'connection';\n\n/** Category for portable API failures. Concrete subclasses alone define protocol mappings. */\nexport abstract class ApiError extends Error {\n    abstract readonly kind: ApiErrorKind;\n    public subType?: string;\n\n    constructor(message: string, cause?: Error) {\n        super(message, { cause });\n        this.name = new.target.name;\n    }\n}\n\nexport class ApiNotFoundError extends ApiError {\n    override readonly kind: ApiErrorKind = 'not-found';\n}\nexport class ApiDependencyError extends ApiError {\n    override readonly kind = 'dependency' as const;\n}\nexport class ApiUnavailableError extends ApiError {\n    override readonly kind = 'unavailable' as const;\n}\nexport class ApiDependencyTimeoutError extends ApiError {\n    override readonly kind = 'dependency-timeout' as const;\n}\n\n/** A bug or invalid implementation state. Local errors become server errors only after a remote decode. */\nexport class ApiImplementationError extends ApiError {\n    override readonly kind = 'implementation' as const;\n\n    constructor(\n        message: string,\n        cause?: Error,\n        public readonly serverError = false,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiRateLimitedError extends ApiError {\n    override readonly kind = 'rate-limited' as const;\n}\nexport class ApiForbiddenError extends ApiError {\n    override readonly kind = 'forbidden' as const;\n}\nexport class ApiRequestTimeoutError extends ApiError {\n    override readonly kind = 'request-timeout' as const;\n}\n\n/** A caller-local connection failure. HTTP servers normalize this to ApiImplementationError. */\nexport class ApiConnectionError extends ApiError {\n    override readonly kind = 'connection' as const;\n}\n\n/** The API operation is missing, distinct from an absent domain entity. */\nexport class ApiEndpointNotFoundError extends ApiNotFoundError {\n    override readonly kind = 'endpoint-not-found' as const;\n}\n\n/**\n * Expected mistake by the ACTOR driving the call: the input was well-formed but wrong in a way the actor\n * must fix (for example \"the two passwords you entered do not match\"). The actor may be a human user in\n * a GUI OR an LLM calling an MCP tool; the same class serves both. Its message is deliberately\n * caller-safe and is the only ApiError message published verbatim: `ApiErrorCodec` keeps it (and\n * `errorCode`) across every remote hop, so a downstream service's text reaches the GUI or the model\n * byte-for-byte.\n */\nexport class ApiEndUserError extends ApiError {\n    override readonly kind = 'end-user' as const;\n\n    constructor(\n        message: string,\n        public errorCode?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n        this.subType = 'USER_ERROR';\n    }\n}\n\n/**\n * Invalid API caller input (malformed, or failed validation). `message` is operator-only diagnostic\n * text and may name internals; it is never published. `callerMessage` (plus `field`) is what a GUI OR\n * an MCP model is shown so it can correct its input, so throw sites that want the caller to\n * self-correct MUST set it.\n */\nexport class ApiBadRequestError extends ApiError {\n    override readonly kind = 'bad-request' as const;\n\n    constructor(\n        message: string,\n        public field?: string,\n        public callerMessage?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiUnauthorizedError extends ApiError {\n    override readonly kind = 'unauthorized' as const;\n\n    constructor(message: string, subType?: string, cause?: Error) {\n        super(message, cause);\n        this.subType = subType;\n    }\n}\n\nexport class ApiDependencyBackoffError extends ApiError {\n    override readonly kind = 'dependency-backoff' as const;\n\n    constructor(\n        message: string,\n        public retryAfterSeconds = 30,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n\n/** The request conflicts with the current state of the target resource (HTTP 409). */\nexport class ApiConflictError extends ApiError {\n    override readonly kind = 'conflict' as const;\n}\n\n/** The request was well-formed but semantically unprocessable (HTTP 422). */\nexport class ApiUnprocessableError extends ApiError {\n    override readonly kind = 'unprocessable' as const;\n}\n\n/** A caller-supplied precondition (for example If-Match) did not hold (HTTP 412). */\nexport class ApiPreconditionFailedError extends ApiError {\n    override readonly kind = 'precondition-failed' as const;\n}\n\n/** The request body is in a media type this operation does not accept (HTTP 415). */\nexport class ApiUnsupportedMediaTypeError extends ApiError {\n    override readonly kind = 'unsupported-media-type' as const;\n}\n\n/** The operation exists in the contract but this server does not implement it (HTTP 501). */\nexport class ApiNotImplementedError extends ApiError {\n    override readonly kind = 'not-implemented' as const;\n}\n\n/** Builds the tuple [0, 1, ..., N-1]; tail-recursive so TypeScript can reach 600. */\ntype StatusRange<N extends number, Acc extends number[] = []> = Acc['length'] extends N\n    ? Acc\n    : StatusRange<N, [...Acc, Acc['length']]>;\n\n/**\n * Every integer from 100 through 599 as a literal union. `new ApiCodedError(msg, 600)`,\n * `new ApiCodedError(msg, 99)` and `new ApiCodedError(msg, 404.5)` do not compile; a dynamic\n * `number` must be narrowed with {@link ApiCodedError.isStatusCode} first.\n */\nexport type ApiStatusCode = Exclude<StatusRange<600>[number], StatusRange<100>[number]>;\n\n/**\n * Catch-all carrying an explicit protocol status for outcomes no named ApiError covers. Any code in\n * 100-599 is accepted, including one a named class already owns. `statusCode` and `errorCode` survive\n * every remote hop through `ApiErrorCodec`; `message` stays operator-only like every other non\n * end-user kind. A status below 500 is a caller outcome (except 408 and 429, which mirror\n * `ApiRequestTimeoutError` and `ApiRateLimitedError`); 500 and above is a server/dependency fault.\n */\nexport class ApiCodedError extends ApiError {\n    override readonly kind = 'coded' as const;\n\n    constructor(\n        message: string,\n        public readonly statusCode: ApiStatusCode,\n        public errorCode?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n\n    /** Narrows a dynamic number (for example one read off the wire) to a legal status code. */\n    // webpieces-disable no-function-outside-class -- stateless status guard; webpieces-disable no-any-unknown -- wire and app values are narrowed here\n    static isStatusCode(value: unknown): value is ApiStatusCode {\n        return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599;\n    }\n\n    /** True when the status describes the caller's mistake rather than a fault on the serving side. */\n    isCallerError(): boolean {\n        return this.statusCode < 500 && this.statusCode !== 408 && this.statusCode !== 429;\n    }\n}\n"]}

package/src/errors/ApiErrorBoundary.js

@@ -43,6 +43,16 @@ class ApiErrorBoundary {
             this.log.info(`Unauthorized: ${detail}`);
         else if (error instanceof ApiError_1.ApiForbiddenError)
             this.log.info(`Forbidden: ${detail}`);
+        else if (error instanceof ApiError_1.ApiConflictError)
+            this.log.info(`Conflict: ${detail}`);
+        else if (error instanceof ApiError_1.ApiUnprocessableError)
+            this.log.info(`Unprocessable: ${detail}`);
+        else if (error instanceof ApiError_1.ApiPreconditionFailedError)
+            this.log.info(`Precondition Failed: ${detail}`);
+        else if (error instanceof ApiError_1.ApiUnsupportedMediaTypeError)
+            this.log.info(`Unsupported Media Type: ${detail}`);
+        else if (error instanceof ApiError_1.ApiCodedError && error.isCallerError())
+            this.log.info(`Coded ${error.statusCode}: ${detail}`);
         else if (error instanceof ApiError_1.ApiRequestTimeoutError)
             this.log.error(`Request Timeout: ${detail}`);
         else

package/src/errors/ApiErrorBoundary.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiErrorBoundary.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiErrorBoundary.ts"],"names":[],"mappings":";;;AACA,kDAA4C;AAC5C,yCAUoB;AAEpB;;;;GAIG;AACH,MAAa,gBAAgB;IACI;IAA7B,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAE5C;;;;;OAKG;IACH,kGAAkG;IAClG,SAAS,CAAC,MAAe;QACrB,IAAI,MAAM,YAAY,mBAAQ,IAAI,CAAC,CAAC,MAAM,YAAY,6BAAkB,CAAC;YAAE,OAAO,MAAM,CAAC;QACzF,MAAM,KAAK,GAAG,IAAA,oBAAO,EAAC,MAAM,CAAC,CAAC;QAC9B,OAAO,IAAI,iCAAsB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,KAAe,EAAE,WAAoB;QACnD,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC;QACxD,IAAI,KAAK,YAAY,0BAAe;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;aAC5E,IAAI,KAAK,YAAY,6BAAkB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,gBAAgB,MAAM,EAAE,CAAC,CAAC;aACjF,IAAI,KAAK,YAAY,2BAAgB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,MAAM,EAAE,CAAC,CAAC;aAC7E,IAAI,KAAK,YAAY,+BAAoB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,MAAM,EAAE,CAAC,CAAC;aACpF,IAAI,KAAK,YAAY,4BAAiB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,MAAM,EAAE,CAAC,CAAC;aAC9E,IAAI,KAAK,YAAY,iCAAsB;YAC5C,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,MAAM,EAAE,CAAC,CAAC;;YAC5C,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,MAAM,EAAE,CAAC,CAAC;IAClD,CAAC;IAEO,cAAc,CAAC,KAAe;QAClC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,OAAO,SAAS,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,IAAI,YAAY,KAAK,CAAC,OAAO,IAAI,MAAM,KAAK,KAAK,CAAC,OAAO,GAAG,KAAK,EAAE,CAAC;IACjH,CAAC;CACJ;AArCD,4CAqCC","sourcesContent":["import { Logger } from '../logging/Logger';\nimport { toError } from '../lib/errorUtils';\nimport {\n    ApiBadRequestError,\n    ApiConnectionError,\n    ApiEndUserError,\n    ApiError,\n    ApiForbiddenError,\n    ApiImplementationError,\n    ApiNotFoundError,\n    ApiRequestTimeoutError,\n    ApiUnauthorizedError,\n} from './ApiError';\n\n/**\n * The ONE rule every outbound protocol boundary (HTTP server, MCP) applies to a thrown value before\n * rendering it, plus the one operator log line per failure. Adapters differ only in the wire shape\n * they render; normalization and log levels live here so they cannot drift apart.\n */\nexport class ApiErrorBoundary {\n    constructor(private readonly log: Logger) {}\n\n    /**\n     * An `ApiError` (except a caller-local `ApiConnectionError`) stays as-is. Anything else, including\n     * a raw `Error`, a non-Error throw, or a downstream connection failure, is a bug or broken state of\n     * THIS service and becomes `ApiImplementationError`. Its message stays operator-only: encoders\n     * publish only `ApiEndUserError` text.\n     */\n    // webpieces-disable no-any-unknown -- thrown values are unknown until normalized at this boundary\n    normalize(thrown: unknown): ApiError {\n        if (thrown instanceof ApiError && !(thrown instanceof ApiConnectionError)) return thrown;\n        const error = toError(thrown);\n        return new ApiImplementationError(error.message, error);\n    }\n\n    /**\n     * Logs one operator line at the per-kind level: expected caller outcomes at info, everything else\n     * at error. `correlation` is appended verbatim (for example `requestId=... tool=...`).\n     */\n    logOperatorDetail(error: ApiError, correlation?: string): void {\n        const suffix = correlation ? ` ${correlation}` : '';\n        const detail = `${this.operatorDetail(error)}${suffix}`;\n        if (error instanceof ApiEndUserError) this.log.info(`End User Error: ${detail}`);\n        else if (error instanceof ApiBadRequestError) this.log.info(`Bad Request: ${detail}`);\n        else if (error instanceof ApiNotFoundError) this.log.info(`Not Found: ${detail}`);\n        else if (error instanceof ApiUnauthorizedError) this.log.info(`Unauthorized: ${detail}`);\n        else if (error instanceof ApiForbiddenError) this.log.info(`Forbidden: ${detail}`);\n        else if (error instanceof ApiRequestTimeoutError)\n            this.log.error(`Request Timeout: ${detail}`);\n        else this.log.error(`API failure: ${detail}`);\n    }\n\n    private operatorDetail(error: ApiError): string {\n        const cause = error.cause instanceof Error ? ` cause=${error.cause.message}` : '';\n        return `[name=${error.name} kind=${error.kind} subType=${error.subType ?? 'none'}] ${error.message}${cause}`;\n    }\n}\n"]}
+{"version":3,"file":"ApiErrorBoundary.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiErrorBoundary.ts"],"names":[],"mappings":";;;AACA,kDAA4C;AAC5C,yCAeoB;AAEpB;;;;GAIG;AACH,MAAa,gBAAgB;IACI;IAA7B,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAE5C;;;;;OAKG;IACH,kGAAkG;IAClG,SAAS,CAAC,MAAe;QACrB,IAAI,MAAM,YAAY,mBAAQ,IAAI,CAAC,CAAC,MAAM,YAAY,6BAAkB,CAAC;YAAE,OAAO,MAAM,CAAC;QACzF,MAAM,KAAK,GAAG,IAAA,oBAAO,EAAC,MAAM,CAAC,CAAC;QAC9B,OAAO,IAAI,iCAAsB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,KAAe,EAAE,WAAoB;QACnD,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC;QACxD,IAAI,KAAK,YAAY,0BAAe;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;aAC5E,IAAI,KAAK,YAAY,6BAAkB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,gBAAgB,MAAM,EAAE,CAAC,CAAC;aACjF,IAAI,KAAK,YAAY,2BAAgB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,MAAM,EAAE,CAAC,CAAC;aAC7E,IAAI,KAAK,YAAY,+BAAoB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,MAAM,EAAE,CAAC,CAAC;aACpF,IAAI,KAAK,YAAY,4BAAiB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,MAAM,EAAE,CAAC,CAAC;aAC9E,IAAI,KAAK,YAAY,2BAAgB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,MAAM,EAAE,CAAC,CAAC;aAC5E,IAAI,KAAK,YAAY,gCAAqB;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,kBAAkB,MAAM,EAAE,CAAC,CAAC;aACtF,IAAI,KAAK,YAAY,qCAA0B;YAChD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;aAC/C,IAAI,KAAK,YAAY,uCAA4B;YAClD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;aAClD,IAAI,KAAK,YAAY,wBAAa,IAAI,KAAK,CAAC,aAAa,EAAE;YAC5D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC,CAAC;aACrD,IAAI,KAAK,YAAY,iCAAsB;YAC5C,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,MAAM,EAAE,CAAC,CAAC;;YAC5C,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,MAAM,EAAE,CAAC,CAAC;IAClD,CAAC;IAEO,cAAc,CAAC,KAAe;QAClC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,OAAO,SAAS,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,IAAI,YAAY,KAAK,CAAC,OAAO,IAAI,MAAM,KAAK,KAAK,CAAC,OAAO,GAAG,KAAK,EAAE,CAAC;IACjH,CAAC;CACJ;AA7CD,4CA6CC","sourcesContent":["import { Logger } from '../logging/Logger';\nimport { toError } from '../lib/errorUtils';\nimport {\n    ApiBadRequestError,\n    ApiCodedError,\n    ApiConflictError,\n    ApiConnectionError,\n    ApiEndUserError,\n    ApiError,\n    ApiForbiddenError,\n    ApiImplementationError,\n    ApiNotFoundError,\n    ApiPreconditionFailedError,\n    ApiRequestTimeoutError,\n    ApiUnauthorizedError,\n    ApiUnprocessableError,\n    ApiUnsupportedMediaTypeError,\n} from './ApiError';\n\n/**\n * The ONE rule every outbound protocol boundary (HTTP server, MCP) applies to a thrown value before\n * rendering it, plus the one operator log line per failure. Adapters differ only in the wire shape\n * they render; normalization and log levels live here so they cannot drift apart.\n */\nexport class ApiErrorBoundary {\n    constructor(private readonly log: Logger) {}\n\n    /**\n     * An `ApiError` (except a caller-local `ApiConnectionError`) stays as-is. Anything else, including\n     * a raw `Error`, a non-Error throw, or a downstream connection failure, is a bug or broken state of\n     * THIS service and becomes `ApiImplementationError`. Its message stays operator-only: encoders\n     * publish only `ApiEndUserError` text.\n     */\n    // webpieces-disable no-any-unknown -- thrown values are unknown until normalized at this boundary\n    normalize(thrown: unknown): ApiError {\n        if (thrown instanceof ApiError && !(thrown instanceof ApiConnectionError)) return thrown;\n        const error = toError(thrown);\n        return new ApiImplementationError(error.message, error);\n    }\n\n    /**\n     * Logs one operator line at the per-kind level: expected caller outcomes at info, everything else\n     * at error. `correlation` is appended verbatim (for example `requestId=... tool=...`).\n     */\n    logOperatorDetail(error: ApiError, correlation?: string): void {\n        const suffix = correlation ? ` ${correlation}` : '';\n        const detail = `${this.operatorDetail(error)}${suffix}`;\n        if (error instanceof ApiEndUserError) this.log.info(`End User Error: ${detail}`);\n        else if (error instanceof ApiBadRequestError) this.log.info(`Bad Request: ${detail}`);\n        else if (error instanceof ApiNotFoundError) this.log.info(`Not Found: ${detail}`);\n        else if (error instanceof ApiUnauthorizedError) this.log.info(`Unauthorized: ${detail}`);\n        else if (error instanceof ApiForbiddenError) this.log.info(`Forbidden: ${detail}`);\n        else if (error instanceof ApiConflictError) this.log.info(`Conflict: ${detail}`);\n        else if (error instanceof ApiUnprocessableError) this.log.info(`Unprocessable: ${detail}`);\n        else if (error instanceof ApiPreconditionFailedError)\n            this.log.info(`Precondition Failed: ${detail}`);\n        else if (error instanceof ApiUnsupportedMediaTypeError)\n            this.log.info(`Unsupported Media Type: ${detail}`);\n        else if (error instanceof ApiCodedError && error.isCallerError())\n            this.log.info(`Coded ${error.statusCode}: ${detail}`);\n        else if (error instanceof ApiRequestTimeoutError)\n            this.log.error(`Request Timeout: ${detail}`);\n        else this.log.error(`API failure: ${detail}`);\n    }\n\n    private operatorDetail(error: ApiError): string {\n        const cause = error.cause instanceof Error ? ` cause=${error.cause.message}` : '';\n        return `[name=${error.name} kind=${error.kind} subType=${error.subType ?? 'none'}] ${error.message}${cause}`;\n    }\n}\n"]}

package/src/errors/ApiErrorCodec.d.ts

@@ -9,6 +9,7 @@ export declare class ApiErrorPayload {
     callerMessage?: string;
     errorCode?: string;
     retryAfterSeconds?: number;
+    statusCode?: number;
     constructor(kind?: string, message?: string);
 }
 /** Bounded safe codec shared by HTTP, IPC, and other remote adapters. */
@@ -21,6 +22,7 @@ export declare class ApiErrorCodec {
     static isPayload(value: unknown): boolean;
     private static decodeDepth;
     private static decodeOne;
+    private static coded;
     private static remoteImplementationError;
     private static publicMessage;
     private static text;

package/src/errors/ApiErrorCodec.js

@@ -12,6 +12,7 @@ class ApiErrorPayload {
     callerMessage;
     errorCode;
     retryAfterSeconds;
+    statusCode;
     constructor(kind = 'implementation', message = 'Internal Error') {
         this.kind = kind;
         this.message = message;
@@ -32,6 +33,10 @@ class ApiErrorCodec {
             payload.subType = this.text(error.subType);
         if (error instanceof ApiError_1.ApiEndUserError)
             payload.errorCode = this.text(error.errorCode);
+        if (error instanceof ApiError_1.ApiCodedError) {
+            payload.statusCode = error.statusCode;
+            payload.errorCode = this.text(error.errorCode);
+        }
         if (error instanceof ApiError_1.ApiBadRequestError) {
             payload.field = this.text(error.field);
             payload.callerMessage = this.text(error.callerMessage);
@@ -100,6 +105,18 @@ class ApiErrorCodec {
                 return new ApiError_1.ApiRequestTimeoutError(message);
             case 'rate-limited':
                 return new ApiError_1.ApiRateLimitedError(message);
+            case 'conflict':
+                return new ApiError_1.ApiConflictError(message);
+            case 'unprocessable':
+                return new ApiError_1.ApiUnprocessableError(message);
+            case 'precondition-failed':
+                return new ApiError_1.ApiPreconditionFailedError(message);
+            case 'unsupported-media-type':
+                return new ApiError_1.ApiUnsupportedMediaTypeError(message);
+            case 'not-implemented':
+                return new ApiError_1.ApiNotImplementedError(message);
+            case 'coded':
+                return this.coded(message, field('statusCode'), field('errorCode'));
             case 'dependency':
                 return new ApiError_1.ApiDependencyError(message);
             case 'unavailable':
@@ -116,6 +133,12 @@ class ApiErrorCodec {
                 return this.remoteImplementationError();
         }
     }
+    // webpieces-disable no-function-outside-class -- coded wire decode; webpieces-disable no-any-unknown -- wire fields require validation
+    static coded(message, statusCode, errorCode) {
+        if (!ApiError_1.ApiCodedError.isStatusCode(statusCode))
+            return this.remoteImplementationError();
+        return new ApiError_1.ApiCodedError(message, statusCode, this.text(errorCode));
+    }
     // webpieces-disable no-function-outside-class -- concrete normalization for malformed remote errors
     static remoteImplementationError() {
         return new ApiError_1.ApiImplementationError('Internal Error', undefined, true);
@@ -155,6 +178,18 @@ class ApiErrorCodec {
                 return 'Request Timeout';
             case 'rate-limited':
                 return 'Rate Limited';
+            case 'conflict':
+                return 'Conflict';
+            case 'unprocessable':
+                return 'Unprocessable Content';
+            case 'precondition-failed':
+                return 'Precondition Failed';
+            case 'unsupported-media-type':
+                return 'Unsupported Media Type';
+            case 'not-implemented':
+                return 'Not Implemented';
+            case 'coded':
+                return 'Request Failed';
             case 'dependency':
                 return 'Dependency Error';
             case 'unavailable':
@@ -178,6 +213,12 @@ class ApiErrorCodec {
         'endpoint-not-found',
         'request-timeout',
         'rate-limited',
+        'conflict',
+        'unprocessable',
+        'precondition-failed',
+        'unsupported-media-type',
+        'not-implemented',
+        'coded',
         'implementation',
         'dependency',
         'unavailable',

package/src/errors/ApiErrorCodec.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiErrorCodec.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiErrorCodec.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    ApiBadRequestError,\n    ApiConnectionError,\n    ApiDependencyBackoffError,\n    ApiDependencyError,\n    ApiDependencyTimeoutError,\n    ApiEndpointNotFoundError,\n    ApiEndUserError,\n    ApiError,\n    ApiErrorKind,\n    ApiForbiddenError,\n    ApiImplementationError,\n    ApiNotFoundError,\n    ApiRateLimitedError,\n    ApiRequestTimeoutError,\n    ApiUnauthorizedError,\n    ApiUnavailableError,\n} from './ApiError';\n\n/** Allowlisted transport-neutral envelope. It never contains stacks or arbitrary properties. */\nexport class ApiErrorPayload {\n    public cause?: ApiErrorPayload;\n    public subType?: string;\n    public field?: string;\n    public callerMessage?: string;\n    public errorCode?: string;\n    public retryAfterSeconds?: number;\n\n    constructor(\n        public kind: string = 'implementation',\n        public message: string = 'Internal Error',\n    ) {}\n}\n\n/** Bounded safe codec shared by HTTP, IPC, and other remote adapters. */\nexport class ApiErrorCodec {\n    // webpieces-disable no-function-outside-class -- stateless public transport codec; webpieces-disable no-any-unknown -- thrown values are untrusted until narrowed\n    static encode(error: unknown): ApiErrorPayload {\n        return this.encodeDepth(error, 0);\n    }\n\n    // webpieces-disable no-function-outside-class -- recursive bounded transport codec; webpieces-disable no-any-unknown -- thrown causes require narrowing\n    private static encodeDepth(error: unknown, depth: number): ApiErrorPayload {\n        const kind = error instanceof ApiError ? error.kind : 'implementation';\n        const payload = new ApiErrorPayload(kind, this.publicMessage(error, kind));\n        if (error instanceof ApiError) payload.subType = this.text(error.subType);\n        if (error instanceof ApiEndUserError) payload.errorCode = this.text(error.errorCode);\n        if (error instanceof ApiBadRequestError) {\n            payload.field = this.text(error.field);\n            payload.callerMessage = this.text(error.callerMessage);\n        }\n        if (error instanceof ApiDependencyBackoffError) {\n            payload.retryAfterSeconds = this.wait(error.retryAfterSeconds);\n        }\n        if (error instanceof Error && depth < 3) {\n            const cause = Object.getOwnPropertyDescriptor(error, 'cause')?.value;\n            if (cause instanceof Error) payload.cause = this.encodeDepth(cause, depth + 1);\n        }\n        return payload;\n    }\n\n    /** Decode a value received from another process. Implementation failures are marked remote. */\n    // webpieces-disable no-function-outside-class -- stateless public transport codec; webpieces-disable no-any-unknown -- wire values require validation\n    static decode(value: unknown): ApiError {\n        return this.decodeDepth(value, 0);\n    }\n\n    /** Whether a body carries a recognized Webpieces semantic discriminator. */\n    // webpieces-disable no-function-outside-class -- stateless wire discriminator check; webpieces-disable no-any-unknown -- wire values require validation\n    static isPayload(value: unknown): boolean {\n        if (typeof value !== 'object' || value === null) return false;\n        const kind = Object.getOwnPropertyDescriptor(value, 'kind')?.value;\n        return typeof kind === 'string' && this.kinds.has(kind as ApiErrorKind);\n    }\n\n    // webpieces-disable no-function-outside-class -- recursive bounded transport codec; webpieces-disable no-any-unknown -- remote causes require validation\n    private static decodeDepth(value: unknown, depth: number): ApiError {\n        const error = this.decodeOne(value);\n        if (typeof value === 'object' && value !== null && depth < 3) {\n            const cause = Object.getOwnPropertyDescriptor(value, 'cause')?.value;\n            if (typeof cause === 'object' && cause !== null) {\n                // webpieces-disable no-anonymous-object-literals -- standard descriptor preserves Error.cause semantics\n                Object.defineProperty(error, 'cause', {\n                    value: this.decodeDepth(cause, depth + 1),\n                    configurable: true,\n                    writable: true,\n                });\n            }\n        }\n        return error;\n    }\n\n    // webpieces-disable no-function-outside-class -- allowlisted wire codec; webpieces-disable no-any-unknown -- wire fields require validation\n    private static decodeOne(value: unknown): ApiError {\n        if (typeof value !== 'object' || value === null) return this.remoteImplementationError();\n        // webpieces-disable no-any-unknown -- own wire fields remain untrusted until narrowed\n        const field = (key: string): unknown => Object.getOwnPropertyDescriptor(value, key)?.value;\n        const kind = field('kind');\n        const message = this.text(field('message')) ?? this.message(kind);\n        switch (kind) {\n            case 'end-user':\n                return new ApiEndUserError(message, this.text(field('errorCode')));\n            case 'bad-request':\n                return new ApiBadRequestError(\n                    message,\n                    this.text(field('field')),\n                    this.text(field('callerMessage')),\n                );\n            case 'unauthorized':\n                return new ApiUnauthorizedError(message, this.text(field('subType')));\n            case 'forbidden':\n                return new ApiForbiddenError(message);\n            case 'not-found':\n                return new ApiNotFoundError(message);\n            case 'endpoint-not-found':\n                return new ApiEndpointNotFoundError(message);\n            case 'request-timeout':\n                return new ApiRequestTimeoutError(message);\n            case 'rate-limited':\n                return new ApiRateLimitedError(message);\n            case 'dependency':\n                return new ApiDependencyError(message);\n            case 'unavailable':\n                return new ApiUnavailableError(message);\n            case 'dependency-timeout':\n                return new ApiDependencyTimeoutError(message);\n            case 'dependency-backoff':\n                return new ApiDependencyBackoffError(\n                    message,\n                    this.wait(field('retryAfterSeconds')),\n                );\n            case 'connection':\n                return new ApiConnectionError(message);\n            case 'implementation':\n                return new ApiImplementationError(message, undefined, true);\n            default:\n                return this.remoteImplementationError();\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- concrete normalization for malformed remote errors\n    private static remoteImplementationError(): ApiImplementationError {\n        return new ApiImplementationError('Internal Error', undefined, true);\n    }\n\n    // webpieces-disable no-function-outside-class -- caller-safe message selection; webpieces-disable no-any-unknown -- thrown values require narrowing\n    private static publicMessage(error: unknown, kind: ApiErrorKind): string {\n        if (error instanceof ApiEndUserError) return error.message.slice(0, 4096);\n        return this.message(kind);\n    }\n\n    // webpieces-disable no-function-outside-class -- wire string bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static text(value: unknown): string | undefined {\n        return typeof value === 'string' ? value.slice(0, 4096) : undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- wire number bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static wait(value: unknown): number | undefined {\n        return typeof value === 'number' && Number.isFinite(value) && value >= 0\n            ? Math.min(value, 86400)\n            : undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- allowlisted generic messages; webpieces-disable no-any-unknown -- discriminator is validated by switch\n    private static message(kind: unknown): string {\n        switch (kind) {\n            case 'end-user':\n                return 'End User Error';\n            case 'bad-request':\n                return 'Bad Request';\n            case 'unauthorized':\n                return 'Unauthorized';\n            case 'forbidden':\n                return 'Forbidden';\n            case 'not-found':\n                return 'Not Found';\n            case 'endpoint-not-found':\n                return 'Endpoint Not Found';\n            case 'request-timeout':\n                return 'Request Timeout';\n            case 'rate-limited':\n                return 'Rate Limited';\n            case 'dependency':\n                return 'Dependency Error';\n            case 'unavailable':\n                return 'Service Unavailable';\n            case 'dependency-timeout':\n                return 'Dependency Timeout';\n            case 'dependency-backoff':\n                return 'Dependency Unavailable';\n            case 'connection':\n                return 'Connection Error';\n            default:\n                return 'Internal Error';\n        }\n    }\n\n    private static readonly kinds: ReadonlySet<ApiErrorKind> = new Set<ApiErrorKind>([\n        'end-user',\n        'bad-request',\n        'unauthorized',\n        'forbidden',\n        'not-found',\n        'endpoint-not-found',\n        'request-timeout',\n        'rate-limited',\n        'implementation',\n        'dependency',\n        'unavailable',\n        'dependency-timeout',\n        'dependency-backoff',\n        'connection',\n    ]);\n}\n"]}
+{"version":3,"file":"ApiErrorCodec.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiErrorCodec.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    ApiBadRequestError,\n    ApiCodedError,\n    ApiConflictError,\n    ApiConnectionError,\n    ApiDependencyBackoffError,\n    ApiDependencyError,\n    ApiDependencyTimeoutError,\n    ApiEndpointNotFoundError,\n    ApiEndUserError,\n    ApiError,\n    ApiErrorKind,\n    ApiForbiddenError,\n    ApiImplementationError,\n    ApiNotFoundError,\n    ApiNotImplementedError,\n    ApiPreconditionFailedError,\n    ApiRateLimitedError,\n    ApiRequestTimeoutError,\n    ApiUnauthorizedError,\n    ApiUnavailableError,\n    ApiUnprocessableError,\n    ApiUnsupportedMediaTypeError,\n} from './ApiError';\n\n/** Allowlisted transport-neutral envelope. It never contains stacks or arbitrary properties. */\nexport class ApiErrorPayload {\n    public cause?: ApiErrorPayload;\n    public subType?: string;\n    public field?: string;\n    public callerMessage?: string;\n    public errorCode?: string;\n    public retryAfterSeconds?: number;\n    public statusCode?: number;\n\n    constructor(\n        public kind: string = 'implementation',\n        public message: string = 'Internal Error',\n    ) {}\n}\n\n/** Bounded safe codec shared by HTTP, IPC, and other remote adapters. */\nexport class ApiErrorCodec {\n    // webpieces-disable no-function-outside-class -- stateless public transport codec; webpieces-disable no-any-unknown -- thrown values are untrusted until narrowed\n    static encode(error: unknown): ApiErrorPayload {\n        return this.encodeDepth(error, 0);\n    }\n\n    // webpieces-disable no-function-outside-class -- recursive bounded transport codec; webpieces-disable no-any-unknown -- thrown causes require narrowing\n    private static encodeDepth(error: unknown, depth: number): ApiErrorPayload {\n        const kind = error instanceof ApiError ? error.kind : 'implementation';\n        const payload = new ApiErrorPayload(kind, this.publicMessage(error, kind));\n        if (error instanceof ApiError) payload.subType = this.text(error.subType);\n        if (error instanceof ApiEndUserError) payload.errorCode = this.text(error.errorCode);\n        if (error instanceof ApiCodedError) {\n            payload.statusCode = error.statusCode;\n            payload.errorCode = this.text(error.errorCode);\n        }\n        if (error instanceof ApiBadRequestError) {\n            payload.field = this.text(error.field);\n            payload.callerMessage = this.text(error.callerMessage);\n        }\n        if (error instanceof ApiDependencyBackoffError) {\n            payload.retryAfterSeconds = this.wait(error.retryAfterSeconds);\n        }\n        if (error instanceof Error && depth < 3) {\n            const cause = Object.getOwnPropertyDescriptor(error, 'cause')?.value;\n            if (cause instanceof Error) payload.cause = this.encodeDepth(cause, depth + 1);\n        }\n        return payload;\n    }\n\n    /** Decode a value received from another process. Implementation failures are marked remote. */\n    // webpieces-disable no-function-outside-class -- stateless public transport codec; webpieces-disable no-any-unknown -- wire values require validation\n    static decode(value: unknown): ApiError {\n        return this.decodeDepth(value, 0);\n    }\n\n    /** Whether a body carries a recognized Webpieces semantic discriminator. */\n    // webpieces-disable no-function-outside-class -- stateless wire discriminator check; webpieces-disable no-any-unknown -- wire values require validation\n    static isPayload(value: unknown): boolean {\n        if (typeof value !== 'object' || value === null) return false;\n        const kind = Object.getOwnPropertyDescriptor(value, 'kind')?.value;\n        return typeof kind === 'string' && this.kinds.has(kind as ApiErrorKind);\n    }\n\n    // webpieces-disable no-function-outside-class -- recursive bounded transport codec; webpieces-disable no-any-unknown -- remote causes require validation\n    private static decodeDepth(value: unknown, depth: number): ApiError {\n        const error = this.decodeOne(value);\n        if (typeof value === 'object' && value !== null && depth < 3) {\n            const cause = Object.getOwnPropertyDescriptor(value, 'cause')?.value;\n            if (typeof cause === 'object' && cause !== null) {\n                // webpieces-disable no-anonymous-object-literals -- standard descriptor preserves Error.cause semantics\n                Object.defineProperty(error, 'cause', {\n                    value: this.decodeDepth(cause, depth + 1),\n                    configurable: true,\n                    writable: true,\n                });\n            }\n        }\n        return error;\n    }\n\n    // webpieces-disable no-function-outside-class -- allowlisted wire codec; webpieces-disable no-any-unknown -- wire fields require validation\n    private static decodeOne(value: unknown): ApiError {\n        if (typeof value !== 'object' || value === null) return this.remoteImplementationError();\n        // webpieces-disable no-any-unknown -- own wire fields remain untrusted until narrowed\n        const field = (key: string): unknown => Object.getOwnPropertyDescriptor(value, key)?.value;\n        const kind = field('kind');\n        const message = this.text(field('message')) ?? this.message(kind);\n        switch (kind) {\n            case 'end-user':\n                return new ApiEndUserError(message, this.text(field('errorCode')));\n            case 'bad-request':\n                return new ApiBadRequestError(\n                    message,\n                    this.text(field('field')),\n                    this.text(field('callerMessage')),\n                );\n            case 'unauthorized':\n                return new ApiUnauthorizedError(message, this.text(field('subType')));\n            case 'forbidden':\n                return new ApiForbiddenError(message);\n            case 'not-found':\n                return new ApiNotFoundError(message);\n            case 'endpoint-not-found':\n                return new ApiEndpointNotFoundError(message);\n            case 'request-timeout':\n                return new ApiRequestTimeoutError(message);\n            case 'rate-limited':\n                return new ApiRateLimitedError(message);\n            case 'conflict':\n                return new ApiConflictError(message);\n            case 'unprocessable':\n                return new ApiUnprocessableError(message);\n            case 'precondition-failed':\n                return new ApiPreconditionFailedError(message);\n            case 'unsupported-media-type':\n                return new ApiUnsupportedMediaTypeError(message);\n            case 'not-implemented':\n                return new ApiNotImplementedError(message);\n            case 'coded':\n                return this.coded(message, field('statusCode'), field('errorCode'));\n            case 'dependency':\n                return new ApiDependencyError(message);\n            case 'unavailable':\n                return new ApiUnavailableError(message);\n            case 'dependency-timeout':\n                return new ApiDependencyTimeoutError(message);\n            case 'dependency-backoff':\n                return new ApiDependencyBackoffError(\n                    message,\n                    this.wait(field('retryAfterSeconds')),\n                );\n            case 'connection':\n                return new ApiConnectionError(message);\n            case 'implementation':\n                return new ApiImplementationError(message, undefined, true);\n            default:\n                return this.remoteImplementationError();\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- coded wire decode; webpieces-disable no-any-unknown -- wire fields require validation\n    private static coded(message: string, statusCode: unknown, errorCode: unknown): ApiError {\n        if (!ApiCodedError.isStatusCode(statusCode)) return this.remoteImplementationError();\n        return new ApiCodedError(message, statusCode, this.text(errorCode));\n    }\n\n    // webpieces-disable no-function-outside-class -- concrete normalization for malformed remote errors\n    private static remoteImplementationError(): ApiImplementationError {\n        return new ApiImplementationError('Internal Error', undefined, true);\n    }\n\n    // webpieces-disable no-function-outside-class -- caller-safe message selection; webpieces-disable no-any-unknown -- thrown values require narrowing\n    private static publicMessage(error: unknown, kind: ApiErrorKind): string {\n        if (error instanceof ApiEndUserError) return error.message.slice(0, 4096);\n        return this.message(kind);\n    }\n\n    // webpieces-disable no-function-outside-class -- wire string bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static text(value: unknown): string | undefined {\n        return typeof value === 'string' ? value.slice(0, 4096) : undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- wire number bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static wait(value: unknown): number | undefined {\n        return typeof value === 'number' && Number.isFinite(value) && value >= 0\n            ? Math.min(value, 86400)\n            : undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- allowlisted generic messages; webpieces-disable no-any-unknown -- discriminator is validated by switch\n    private static message(kind: unknown): string {\n        switch (kind) {\n            case 'end-user':\n                return 'End User Error';\n            case 'bad-request':\n                return 'Bad Request';\n            case 'unauthorized':\n                return 'Unauthorized';\n            case 'forbidden':\n                return 'Forbidden';\n            case 'not-found':\n                return 'Not Found';\n            case 'endpoint-not-found':\n                return 'Endpoint Not Found';\n            case 'request-timeout':\n                return 'Request Timeout';\n            case 'rate-limited':\n                return 'Rate Limited';\n            case 'conflict':\n                return 'Conflict';\n            case 'unprocessable':\n                return 'Unprocessable Content';\n            case 'precondition-failed':\n                return 'Precondition Failed';\n            case 'unsupported-media-type':\n                return 'Unsupported Media Type';\n            case 'not-implemented':\n                return 'Not Implemented';\n            case 'coded':\n                return 'Request Failed';\n            case 'dependency':\n                return 'Dependency Error';\n            case 'unavailable':\n                return 'Service Unavailable';\n            case 'dependency-timeout':\n                return 'Dependency Timeout';\n            case 'dependency-backoff':\n                return 'Dependency Unavailable';\n            case 'connection':\n                return 'Connection Error';\n            default:\n                return 'Internal Error';\n        }\n    }\n\n    private static readonly kinds: ReadonlySet<ApiErrorKind> = new Set<ApiErrorKind>([\n        'end-user',\n        'bad-request',\n        'unauthorized',\n        'forbidden',\n        'not-found',\n        'endpoint-not-found',\n        'request-timeout',\n        'rate-limited',\n        'conflict',\n        'unprocessable',\n        'precondition-failed',\n        'unsupported-media-type',\n        'not-implemented',\n        'coded',\n        'implementation',\n        'dependency',\n        'unavailable',\n        'dependency-timeout',\n        'dependency-backoff',\n        'connection',\n    ]);\n}\n"]}

package/src/errors/index.d.ts

@@ -1,5 +1,5 @@
-export { ApiError, ApiNotFoundError, ApiDependencyError, ApiUnavailableError, ApiDependencyTimeoutError, ApiImplementationError, ApiRateLimitedError, ApiForbiddenError, ApiRequestTimeoutError, ApiConnectionError, ApiEndpointNotFoundError, ApiEndUserError, ApiBadRequestError, ApiUnauthorizedError, ApiDependencyBackoffError, } from './ApiError';
-export type { ApiErrorKind } from './ApiError';
+export { ApiError, ApiNotFoundError, ApiDependencyError, ApiUnavailableError, ApiDependencyTimeoutError, ApiImplementationError, ApiRateLimitedError, ApiForbiddenError, ApiRequestTimeoutError, ApiConnectionError, ApiEndpointNotFoundError, ApiEndUserError, ApiBadRequestError, ApiUnauthorizedError, ApiDependencyBackoffError, ApiConflictError, ApiUnprocessableError, ApiPreconditionFailedError, ApiUnsupportedMediaTypeError, ApiNotImplementedError, ApiCodedError, } from './ApiError';
+export type { ApiErrorKind, ApiStatusCode } from './ApiError';
 export { ApiErrorCodec, ApiErrorPayload } from './ApiErrorCodec';
 export { ApiErrorBoundary } from './ApiErrorBoundary';
 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.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.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; } });
@@ -17,6 +17,12 @@ Object.defineProperty(exports, "ApiEndUserError", { enumerable: true, get: funct
 Object.defineProperty(exports, "ApiBadRequestError", { enumerable: true, get: function () { return ApiError_1.ApiBadRequestError; } });
 Object.defineProperty(exports, "ApiUnauthorizedError", { enumerable: true, get: function () { return ApiError_1.ApiUnauthorizedError; } });
 Object.defineProperty(exports, "ApiDependencyBackoffError", { enumerable: true, get: function () { return ApiError_1.ApiDependencyBackoffError; } });
+Object.defineProperty(exports, "ApiConflictError", { enumerable: true, get: function () { return ApiError_1.ApiConflictError; } });
+Object.defineProperty(exports, "ApiUnprocessableError", { enumerable: true, get: function () { return ApiError_1.ApiUnprocessableError; } });
+Object.defineProperty(exports, "ApiPreconditionFailedError", { enumerable: true, get: function () { return ApiError_1.ApiPreconditionFailedError; } });
+Object.defineProperty(exports, "ApiUnsupportedMediaTypeError", { enumerable: true, get: function () { return ApiError_1.ApiUnsupportedMediaTypeError; } });
+Object.defineProperty(exports, "ApiNotImplementedError", { enumerable: true, get: function () { return ApiError_1.ApiNotImplementedError; } });
+Object.defineProperty(exports, "ApiCodedError", { enumerable: true, get: function () { return ApiError_1.ApiCodedError; } });
 var ApiErrorCodec_1 = require("./ApiErrorCodec");
 Object.defineProperty(exports, "ApiErrorCodec", { enumerable: true, get: function () { return ApiErrorCodec_1.ApiErrorCodec; } });
 Object.defineProperty(exports, "ApiErrorPayload", { enumerable: true, get: function () { return ApiErrorCodec_1.ApiErrorPayload; } });

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,uCAgBoB;AAfhB,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;AAG7B,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} from './ApiError';\nexport type { ApiErrorKind } 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,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 } 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"]}

package/src/http/ApiErrorHttpStatus.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiErrorHttpStatus = void 0;
+const ApiError_1 = require("../errors/ApiError");
 /** HTTP-only adapter: semantic errors themselves have no protocol status property. */
 class ApiErrorHttpStatus {
     // webpieces-disable no-function-outside-class -- stateless mapping predicate
@@ -23,10 +24,24 @@ class ApiErrorHttpStatus {
                 return 404;
             case 'request-timeout':
                 return 408;
+            case 'conflict':
+                return 409;
+            case 'precondition-failed':
+                return 412;
+            case 'unsupported-media-type':
+                return 415;
+            case 'unprocessable':
+                return 422;
             case 'rate-limited':
                 return 429;
             case 'implementation':
                 return 500;
+            case 'not-implemented':
+                return 501;
+            case 'coded':
+                if (error instanceof ApiError_1.ApiCodedError)
+                    return error.statusCode;
+                throw new Error(`kind 'coded' must be an ApiCodedError, got ${error.name}`);
             case 'dependency':
                 return 502;
             case 'unavailable':

package/src/http/ApiErrorHttpStatus.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiErrorHttpStatus.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiErrorHttpStatus.ts"],"names":[],"mappings":";;;AAEA,sFAAsF;AACtF,MAAa,kBAAkB;IAC3B,6EAA6E;IAC7E,MAAM,CAAC,OAAO,CAAC,KAAe;QAC1B,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;IACvC,CAAC;IAED,2FAA2F;IAC3F,MAAM,CAAC,IAAI,CAAC,KAAe;QACvB,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,UAAU;gBACX,OAAO,GAAG,CAAC;YACf,KAAK,aAAa;gBACd,OAAO,GAAG,CAAC;YACf,KAAK,cAAc;gBACf,OAAO,GAAG,CAAC;YACf,KAAK,WAAW;gBACZ,OAAO,GAAG,CAAC;YACf,KAAK,WAAW,CAAC;YACjB,KAAK,oBAAoB;gBACrB,OAAO,GAAG,CAAC;YACf,KAAK,iBAAiB;gBAClB,OAAO,GAAG,CAAC;YACf,KAAK,cAAc;gBACf,OAAO,GAAG,CAAC;YACf,KAAK,gBAAgB;gBACjB,OAAO,GAAG,CAAC;YACf,KAAK,YAAY;gBACb,OAAO,GAAG,CAAC;YACf,KAAK,aAAa,CAAC;YACnB,KAAK,oBAAoB;gBACrB,OAAO,GAAG,CAAC;YACf,KAAK,oBAAoB;gBACrB,OAAO,GAAG,CAAC;YACf,KAAK,YAAY;gBACb,MAAM,IAAI,KAAK,CACX,4EAA4E,CAC/E,CAAC;QACV,CAAC;IACL,CAAC;CACJ;AAvCD,gDAuCC","sourcesContent":["import { ApiError } from '../errors/ApiError';\n\n/** HTTP-only adapter: semantic errors themselves have no protocol status property. */\nexport class ApiErrorHttpStatus {\n    // webpieces-disable no-function-outside-class -- stateless mapping predicate\n    static hasCode(error: ApiError): boolean {\n        return error.kind !== 'connection';\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless mapping shared by HTTP adapters\n    static code(error: ApiError): number {\n        switch (error.kind) {\n            case 'end-user':\n                return 266;\n            case 'bad-request':\n                return 400;\n            case 'unauthorized':\n                return 401;\n            case 'forbidden':\n                return 403;\n            case 'not-found':\n            case 'endpoint-not-found':\n                return 404;\n            case 'request-timeout':\n                return 408;\n            case 'rate-limited':\n                return 429;\n            case 'implementation':\n                return 500;\n            case 'dependency':\n                return 502;\n            case 'unavailable':\n            case 'dependency-backoff':\n                return 503;\n            case 'dependency-timeout':\n                return 504;\n            case 'connection':\n                throw new Error(\n                    'ApiConnectionError has no HTTP status; normalize it at the server boundary',\n                );\n        }\n    }\n}\n"]}
+{"version":3,"file":"ApiErrorHttpStatus.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiErrorHttpStatus.ts"],"names":[],"mappings":";;;AAAA,iDAA6D;AAE7D,sFAAsF;AACtF,MAAa,kBAAkB;IAC3B,6EAA6E;IAC7E,MAAM,CAAC,OAAO,CAAC,KAAe;QAC1B,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;IACvC,CAAC;IAED,2FAA2F;IAC3F,MAAM,CAAC,IAAI,CAAC,KAAe;QACvB,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,UAAU;gBACX,OAAO,GAAG,CAAC;YACf,KAAK,aAAa;gBACd,OAAO,GAAG,CAAC;YACf,KAAK,cAAc;gBACf,OAAO,GAAG,CAAC;YACf,KAAK,WAAW;gBACZ,OAAO,GAAG,CAAC;YACf,KAAK,WAAW,CAAC;YACjB,KAAK,oBAAoB;gBACrB,OAAO,GAAG,CAAC;YACf,KAAK,iBAAiB;gBAClB,OAAO,GAAG,CAAC;YACf,KAAK,UAAU;gBACX,OAAO,GAAG,CAAC;YACf,KAAK,qBAAqB;gBACtB,OAAO,GAAG,CAAC;YACf,KAAK,wBAAwB;gBACzB,OAAO,GAAG,CAAC;YACf,KAAK,eAAe;gBAChB,OAAO,GAAG,CAAC;YACf,KAAK,cAAc;gBACf,OAAO,GAAG,CAAC;YACf,KAAK,gBAAgB;gBACjB,OAAO,GAAG,CAAC;YACf,KAAK,iBAAiB;gBAClB,OAAO,GAAG,CAAC;YACf,KAAK,OAAO;gBACR,IAAI,KAAK,YAAY,wBAAa;oBAAE,OAAO,KAAK,CAAC,UAAU,CAAC;gBAC5D,MAAM,IAAI,KAAK,CAAC,8CAA8C,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YAChF,KAAK,YAAY;gBACb,OAAO,GAAG,CAAC;YACf,KAAK,aAAa,CAAC;YACnB,KAAK,oBAAoB;gBACrB,OAAO,GAAG,CAAC;YACf,KAAK,oBAAoB;gBACrB,OAAO,GAAG,CAAC;YACf,KAAK,YAAY;gBACb,MAAM,IAAI,KAAK,CACX,4EAA4E,CAC/E,CAAC;QACV,CAAC;IACL,CAAC;CACJ;AApDD,gDAoDC","sourcesContent":["import { ApiCodedError, ApiError } from '../errors/ApiError';\n\n/** HTTP-only adapter: semantic errors themselves have no protocol status property. */\nexport class ApiErrorHttpStatus {\n    // webpieces-disable no-function-outside-class -- stateless mapping predicate\n    static hasCode(error: ApiError): boolean {\n        return error.kind !== 'connection';\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless mapping shared by HTTP adapters\n    static code(error: ApiError): number {\n        switch (error.kind) {\n            case 'end-user':\n                return 266;\n            case 'bad-request':\n                return 400;\n            case 'unauthorized':\n                return 401;\n            case 'forbidden':\n                return 403;\n            case 'not-found':\n            case 'endpoint-not-found':\n                return 404;\n            case 'request-timeout':\n                return 408;\n            case 'conflict':\n                return 409;\n            case 'precondition-failed':\n                return 412;\n            case 'unsupported-media-type':\n                return 415;\n            case 'unprocessable':\n                return 422;\n            case 'rate-limited':\n                return 429;\n            case 'implementation':\n                return 500;\n            case 'not-implemented':\n                return 501;\n            case 'coded':\n                if (error instanceof ApiCodedError) return error.statusCode;\n                throw new Error(`kind 'coded' must be an ApiCodedError, got ${error.name}`);\n            case 'dependency':\n                return 502;\n            case 'unavailable':\n            case 'dependency-backoff':\n                return 503;\n            case 'dependency-timeout':\n                return 504;\n            case 'connection':\n                throw new Error(\n                    'ApiConnectionError has no HTTP status; normalize it at the server boundary',\n                );\n        }\n    }\n}\n"]}

package/src/http/RouteMetadataFactory.d.ts

@@ -8,6 +8,31 @@ export declare class RouteMetadataFactory {
     static create(apiClass: Function, methodName: string, controllerClassName?: string): RouteMetadata;
     private static validateEndpointOptions;
     private static validateStreamingParameters;
+    /**
+     * Refuse a contract in which two endpoints resolve to the same HTTP method + path.
+     *
+     * Empty paths are LEGAL (`@ApiPath('')` + `@Endpoint('', ...)` is how a contract says "the whole
+     * destination arrives per call"), so the thing actually worth rejecting is ambiguity: two methods
+     * that land on one route. On the server the second registration would silently shadow the first
+     * in the route map, and on the client both would dial the same URL — neither is ever what the
+     * author meant. Placeholder NAMES are ignored when comparing (`/a/{id}` and `/a/{key}` are the
+     * same route to a router), `''` and `'/'` compare equal (the server serves an empty path at the
+     * root), and the error names BOTH methods so the fix is obvious.
+     *
+     * Called by every transport that binds a whole contract (the generated clients and the server's
+     * route registration), so a duplicate dies at startup however the contract is consumed.
+     *
+     * @throws Error naming both colliding methods and the shared route.
+     */
+    static assertNoDuplicateRoutes(apiClass: Function): void;
+    /**
+     * Join `@ApiPath` and `@Endpoint` into the route path.
+     *
+     * Both empty joins to `''`, NOT `'/'`. A contract declaring `@ApiPath('')` + `@Endpoint('', ...)`
+     * is saying "this route adds nothing to the base URL", and a client whose base URL is a full
+     * destination (host + path + query) must send it byte for byte. Before #926 the client joined with
+     * plain concatenation (`'' + ''`), and forcing a `/` here broke exactly that (#944).
+     */
     private static joinPath;
     private static httpMethod;
     private static responseType;

package/src/http/RouteMetadataFactory.js

@@ -54,8 +54,52 @@ class RouteMetadataFactory {
             throw new Error(`${label} must take exactly one ResponseStream parameter.`);
         return undefined;
     }
+    /**
+     * Refuse a contract in which two endpoints resolve to the same HTTP method + path.
+     *
+     * Empty paths are LEGAL (`@ApiPath('')` + `@Endpoint('', ...)` is how a contract says "the whole
+     * destination arrives per call"), so the thing actually worth rejecting is ambiguity: two methods
+     * that land on one route. On the server the second registration would silently shadow the first
+     * in the route map, and on the client both would dial the same URL — neither is ever what the
+     * author meant. Placeholder NAMES are ignored when comparing (`/a/{id}` and `/a/{key}` are the
+     * same route to a router), `''` and `'/'` compare equal (the server serves an empty path at the
+     * root), and the error names BOTH methods so the fix is obvious.
+     *
+     * Called by every transport that binds a whole contract (the generated clients and the server's
+     * route registration), so a duplicate dies at startup however the contract is consumed.
+     *
+     * @throws Error naming both colliding methods and the shared route.
+     */
+    // webpieces-disable no-function-outside-class -- deterministic contract validation shared by DI-free browser and server runtimes
+    static assertNoDuplicateRoutes(apiClass) {
+        const label = apiClass.name || 'Unknown';
+        const seen = new Map();
+        for (const methodName of Object.keys((0, decorators_1.getEndpoints)(apiClass) ?? {})) {
+            const route = this.create(apiClass, methodName);
+            // '' and '/' are one route to a server (every request path starts with '/').
+            const shape = (route.path === '' ? '/' : route.path).replace(/\{[^{}]+\}/g, '{}');
+            const key = `${route.httpMethod} ${shape}`;
+            const previous = seen.get(key);
+            if (previous !== undefined) {
+                throw new Error(`${label}.${previous} and ${label}.${methodName} both resolve to ` +
+                    `${route.httpMethod} '${route.path}'. Two endpoints of one contract cannot share ` +
+                    `an HTTP method + path; give one of them a distinct @Endpoint path or HTTP method.`);
+            }
+            seen.set(key, methodName);
+        }
+    }
+    /**
+     * Join `@ApiPath` and `@Endpoint` into the route path.
+     *
+     * Both empty joins to `''`, NOT `'/'`. A contract declaring `@ApiPath('')` + `@Endpoint('', ...)`
+     * is saying "this route adds nothing to the base URL", and a client whose base URL is a full
+     * destination (host + path + query) must send it byte for byte. Before #926 the client joined with
+     * plain concatenation (`'' + ''`), and forcing a `/` here broke exactly that (#944).
+     */
     // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory
     static joinPath(basePath, endpointPath) {
+        if (basePath === '' && endpointPath === '')
+            return '';
         const joined = `${basePath}/${endpointPath}`.replace(/\/{2,}/g, '/');
         return joined.startsWith('/') ? joined : `/${joined}`;
     }

package/src/http/RouteMetadataFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouteMetadataFactory.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/RouteMetadataFactory.ts"],"names":[],"mappings":";;;AAAA,6CAMsB;AACtB,2EAA2E;AAC3E,iDAMwB;AACxB,mDAAgD;AAChD,2DAA2D;AAE3D;;;;GAIG;AACH,MAAa,oBAAoB;IAC7B,wIAAwI;IACxI,MAAM,CAAC,MAAM,CACT,QAAkB,EAClB,UAAkB,EAClB,mBAA4B;QAE5B,MAAM,SAAS,GAAG,IAAA,yBAAY,EAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC/C,MAAM,YAAY,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACX,6BAA6B,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI,UAAU,GAAG,CAC3E,CAAC;QACN,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAA,uBAAU,EAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,YAAY,CAAC,CAAC;QACzE,MAAM,OAAO,GAAG,IAAA,+BAAkB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,IAAA,wCAAoB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7E,IAAI,CAAC,uBAAuB,CACxB,QAAQ,EACR,UAAU,EACV,UAAU,EACV,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,OAAO,CAClB,CAAC;QACF,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACjE,MAAM,YAAY,GAAG,IAAA,wDAA4B,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACxE,MAAM,kBAAkB,GAAG,SAAS;YAChC,CAAC,CAAC,IAAI,CAAC,2BAA2B,CAC5B,QAAQ,EACR,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,CACf;YACH,CAAC,CAAC,IAAI,CAAC,kBAAkB,CACnB,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,UAAU,EACV,cAAc,EACd,YAAY,CACf,CAAC;QACR,MAAM,QAAQ,GAAG,YAAY;aACxB,GAAG,CACA,CAAC,WAAqC,EAAE,EAAE,CACtC,IAAI,mCAAoB,CACpB,WAAW,CAAC,KAAK,EACjB,WAAW,CAAC,MAAM,EAClB,WAAW,CAAC,QAAQ,EACpB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CACpD,CACR;aACA,IAAI,CAAC,CAAC,CAAuB,EAAE,CAAuB,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAEnF,OAAO,IAAI,6BAAa,CACpB,UAAU,EACV,QAAQ,EACR,UAAU,EACV,mBAAmB,EACnB,IAAA,wBAAW,EAAC,QAAQ,EAAE,UAAU,CAAC,EACjC,QAAQ,CAAC,IAAI,IAAI,YAAY,EAC7B,OAAO,CAAC,QAAQ,KAAK,IAAI,EACzB,IAAA,wBAAW,EAAC,QAAQ,EAAE,UAAU,CAAC,EACjC,OAAO,CAAC,OAAO,KAAK,IAAI,EACxB,QAAQ,EACR,kBAAkB,EAClB,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,UAAU,CAAC,EAC7D,SAAS,CACZ,CAAC;IACN,CAAC;IAED,4IAA4I;IACpI,MAAM,CAAC,uBAAuB,CAClC,QAAkB,EAClB,UAAkB,EAClB,UAA8B,EAC9B,QAAkB,EAClB,OAAiB;QAEjB,IAAI,UAAU,KAAK,KAAK,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,2EAA2E,CAC5G,CAAC;QACN,CAAC;QACD,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,0EAA0E,CAC3G,CAAC;QACN,CAAC;IACL,CAAC;IAED,+GAA+G;IACvG,MAAM,CAAC,2BAA2B,CACtC,QAAkB,EAClB,UAAkB,EAClB,UAA8B,EAC9B,cAAmC,EACnC,YAAiD;QAEjD,MAAM,KAAK,GAAG,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5D,IAAI,UAAU,KAAK,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,kCAAkC,CAAC,CAAC;QACvF,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,yDAAyD,CAAC,CAAC;QACvF,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,kDAAkD,CAAC,CAAC;QAChF,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,qGAAqG;IAC7F,MAAM,CAAC,QAAQ,CAAC,QAAgB,EAAE,YAAoB;QAC1D,MAAM,MAAM,GAAG,GAAG,QAAQ,IAAI,YAAY,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACrE,OAAO,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;IAC1D,CAAC;IAED,qGAAqG;IAC7F,MAAM,CAAC,UAAU,CACrB,KAAqC,EACrC,QAAkB,EAClB,UAAkB;QAElB,MAAM,MAAM,GAAG,KAAK,IAAI,MAAM,CAAC;QAC/B,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO,MAAM,CAAC;QACzD,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,qCAAqC,MAAM,CAAC,MAAM,CAAC,qBAAqB,CACzG,CAAC;IACN,CAAC;IAED,qGAAqG;IAC7F,MAAM,CAAC,YAAY,CACvB,KAAuC,EACvC,QAAkB,EAClB,UAAkB;QAElB,MAAM,YAAY,GAAG,KAAK,IAAI,MAAM,CAAC;QACrC,IAAI,YAAY,KAAK,MAAM,IAAI,YAAY,KAAK,MAAM;YAAE,OAAO,YAAY,CAAC;QAC5E,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,uCAAuC,MAAM,CAAC,YAAY,CAAC,sBAAsB,CAClH,CAAC;IACN,CAAC;IAED,sGAAsG;IAC9F,MAAM,CAAC,cAAc,CAAC,QAAkB,EAAE,UAAkB;QAChE,OAAO,OAAO,CAAC,WAAW,CAAC,mBAAmB,EAAE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;IAC1F,CAAC;IAED,kGAAkG;IAC1F,MAAM,CAAC,kBAAkB,CAC7B,QAAkB,EAClB,UAAkB,EAClB,QAAgB,EAChB,UAA8B,EAC9B,cAAmC,EACnC,YAAiD;QAEjD,MAAM,KAAK,GAAG,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5D,MAAM,YAAY,GAAG,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,CAC5D,CAAC,KAAuB,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CACxC,CAAC;QACF,MAAM,SAAS,GAAG,YAAY;aACzB,MAAM,CAAC,CAAC,WAAqC,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,KAAK,MAAM,CAAC;aAChF,GAAG,CAAC,CAAC,WAAqC,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC1E,KAAK,MAAM,WAAW,IAAI,IAAI,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,UAAU,QAAQ,eAAe,WAAW,wBAAwB,WAAW,eAAe,CACzG,CAAC;YACN,CAAC;QACL,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,yBAAyB,QAAQ,WAAW,QAAQ,aAAa,QAAQ,gBAAgB,CACpG,CAAC;YACN,CAAC;QACL,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QACnC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;QACxC,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACrC,MAAM,OAAO,GAAG,GAAG,WAAW,CAAC,MAAM,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;YAChE,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,UAAU,OAAO,mBAAmB,CAAC,CAAC;YAClE,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACtB,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAC1B,cAAc,CAAC,MAAM,EACrB,YAAY,CAAC,MAAM,CACf,CAAC,OAAe,EAAE,WAAqC,EAAE,EAAE,CACvD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,KAAK,GAAG,CAAC,CAAC,EAC5C,CAAC,CACJ,CACJ,CAAC;QACF,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,aAAa,EAAE,KAAK,EAAE,EAAE,CAAC;YACjD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,sFAAsF,OAAO,CAAC,CAAC,CAAC,eAAe,CAC1H,CAAC;QACN,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,QAAQ,OAAO,CAAC,MAAM,gHAAgH,CACjJ,CAAC;QACN,CAAC;QACD,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IAED,4GAA4G;IACpG,MAAM,CAAC,SAAS,CAAC,IAA0B;QAC/C,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,QAAQ,CAAC;QACrC,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,QAAQ,CAAC;QACrC,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,SAAS,CAAC;QACvC,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,OAAO,CAAC;QACnC,OAAO,SAAS,CAAC;IACrB,CAAC;CACJ;AA7ND,oDA6NC","sourcesContent":["import {\n    getApiPath,\n    getAuthMeta,\n    getEndpointOptions,\n    getEndpoints,\n    getMaskSpec,\n} from './decorators';\nimport { getHttpParameterDeclarations } from './http-parameter-decorators';\nimport {\n    ContractHttpMethod,\n    EndpointResponseType,\n    HttpParameterBinding,\n    HttpParameterDeclaration,\n    HttpParameterValueType,\n} from './HttpContract';\nimport { RouteMetadata } from './RouteMetadata';\nimport { getStreamingEndpoint } from './StreamingContract';\n\n/**\n * Build the one runtime route model consumed by incoming routing, in-process clients, and both\n * generated HTTP clients. Keeping this join/validation here prevents four subtly different\n * interpretations of the same decorators.\n */\nexport class RouteMetadataFactory {\n    // webpieces-disable no-function-outside-class -- deterministic decorator metadata factory shared by DI-free browser and server runtimes\n    static create(\n        apiClass: Function,\n        methodName: string,\n        controllerClassName?: string,\n    ): RouteMetadata {\n        const endpoints = getEndpoints(apiClass) ?? {};\n        const endpointPath = endpoints[methodName];\n        if (endpointPath === undefined) {\n            throw new Error(\n                `No @Endpoint metadata for ${apiClass.name || 'Unknown'}.${methodName}.`,\n            );\n        }\n        const fullPath = this.joinPath(getApiPath(apiClass) ?? '', endpointPath);\n        const options = getEndpointOptions(apiClass, methodName);\n        const streaming = getStreamingEndpoint(apiClass, methodName);\n        const httpMethod = this.httpMethod(options.httpMethod, apiClass, methodName);\n        this.validateEndpointOptions(\n            apiClass,\n            methodName,\n            httpMethod,\n            options.formPost,\n            options.rawBody,\n        );\n        const parameterTypes = this.parameterTypes(apiClass, methodName);\n        const declarations = getHttpParameterDeclarations(apiClass, methodName);\n        const bodyParameterIndex = streaming\n            ? this.validateStreamingParameters(\n                  apiClass,\n                  methodName,\n                  httpMethod,\n                  parameterTypes,\n                  declarations,\n              )\n            : this.validateParameters(\n                  apiClass,\n                  methodName,\n                  fullPath,\n                  httpMethod,\n                  parameterTypes,\n                  declarations,\n              );\n        const bindings = declarations\n            .map(\n                (declaration: HttpParameterDeclaration) =>\n                    new HttpParameterBinding(\n                        declaration.index,\n                        declaration.source,\n                        declaration.wireName,\n                        this.valueType(parameterTypes[declaration.index]),\n                    ),\n            )\n            .sort((a: HttpParameterBinding, b: HttpParameterBinding) => a.index - b.index);\n\n        return new RouteMetadata(\n            httpMethod,\n            fullPath,\n            methodName,\n            controllerClassName,\n            getAuthMeta(apiClass, methodName),\n            apiClass.name || 'UnknownApi',\n            options.formPost === true,\n            getMaskSpec(apiClass, methodName),\n            options.rawBody === true,\n            bindings,\n            bodyParameterIndex,\n            this.responseType(options.responseType, apiClass, methodName),\n            streaming,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper keeps the existing static metadata factory below the method-size limit\n    private static validateEndpointOptions(\n        apiClass: Function,\n        methodName: string,\n        httpMethod: ContractHttpMethod,\n        formPost?: boolean,\n        rawBody?: boolean,\n    ): void {\n        if (httpMethod === 'GET' && formPost === true) {\n            throw new Error(\n                `${apiClass.name}.${methodName} is GET and cannot declare formPost:true because GET has no request body.`,\n            );\n        }\n        if (httpMethod === 'GET' && rawBody === true) {\n            throw new Error(\n                `${apiClass.name}.${methodName} is GET and cannot declare rawBody:true because GET has no request body.`,\n            );\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure validator alongside existing contract validators\n    private static validateStreamingParameters(\n        apiClass: Function,\n        methodName: string,\n        httpMethod: ContractHttpMethod,\n        parameterTypes: readonly Function[],\n        declarations: readonly HttpParameterDeclaration[],\n    ): undefined {\n        const label = `${apiClass.name || 'Unknown'}.${methodName}`;\n        if (httpMethod !== 'POST') throw new Error(`${label} is streaming and must use POST.`);\n        if (declarations.length > 0)\n            throw new Error(`${label} is streaming and cannot declare path/query parameters.`);\n        if (parameterTypes.length !== 1)\n            throw new Error(`${label} must take exactly one ResponseStream parameter.`);\n        return undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static joinPath(basePath: string, endpointPath: string): string {\n        const joined = `${basePath}/${endpointPath}`.replace(/\\/{2,}/g, '/');\n        return joined.startsWith('/') ? joined : `/${joined}`;\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static httpMethod(\n        value: ContractHttpMethod | undefined,\n        apiClass: Function,\n        methodName: string,\n    ): ContractHttpMethod {\n        const method = value ?? 'POST';\n        if (method === 'GET' || method === 'POST') return method;\n        throw new Error(\n            `${apiClass.name}.${methodName} declares unsupported httpMethod '${String(method)}'; use GET or POST.`,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static responseType(\n        value: EndpointResponseType | undefined,\n        apiClass: Function,\n        methodName: string,\n    ): EndpointResponseType {\n        const responseType = value ?? 'body';\n        if (responseType === 'body' || responseType === 'full') return responseType;\n        throw new Error(\n            `${apiClass.name}.${methodName} declares unsupported responseType '${String(responseType)}'; use body or full.`,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- Reflect metadata lookup has no injectable dependency\n    private static parameterTypes(apiClass: Function, methodName: string): Function[] {\n        return Reflect.getMetadata('design:paramtypes', apiClass.prototype, methodName) ?? [];\n    }\n\n    // webpieces-disable no-function-outside-class -- private deterministic contract validation helper\n    private static validateParameters(\n        apiClass: Function,\n        methodName: string,\n        fullPath: string,\n        httpMethod: ContractHttpMethod,\n        parameterTypes: readonly Function[],\n        declarations: readonly HttpParameterDeclaration[],\n    ): number | undefined {\n        const label = `${apiClass.name || 'Unknown'}.${methodName}`;\n        const placeholders = [...fullPath.matchAll(/\\{([^{}]+)\\}/g)].map(\n            (match: RegExpMatchArray) => match[1],\n        );\n        const pathNames = declarations\n            .filter((declaration: HttpParameterDeclaration) => declaration.source === 'path')\n            .map((declaration: HttpParameterDeclaration) => declaration.wireName);\n        for (const placeholder of new Set(placeholders)) {\n            if (!pathNames.includes(placeholder)) {\n                throw new Error(\n                    `${label} path '${fullPath}' contains {${placeholder}} but no @PathParam('${placeholder}') parameter.`,\n                );\n            }\n        }\n        for (const pathName of pathNames) {\n            if (!placeholders.includes(pathName)) {\n                throw new Error(\n                    `${label} declares @PathParam('${pathName}') but '${fullPath}' has no {${pathName}} placeholder.`,\n                );\n            }\n        }\n\n        const seenWire = new Set<string>();\n        const mappedIndexes = new Set<number>();\n        for (const declaration of declarations) {\n            const wireKey = `${declaration.source}:${declaration.wireName}`;\n            if (seenWire.has(wireKey)) {\n                throw new Error(`${label} maps '${wireKey}' more than once.`);\n            }\n            seenWire.add(wireKey);\n            mappedIndexes.add(declaration.index);\n        }\n\n        const declaredCount = Math.max(\n            parameterTypes.length,\n            declarations.reduce(\n                (highest: number, declaration: HttpParameterDeclaration) =>\n                    Math.max(highest, declaration.index + 1),\n                0,\n            ),\n        );\n        const unbound: number[] = [];\n        for (let index = 0; index < declaredCount; index++) {\n            if (!mappedIndexes.has(index)) unbound.push(index);\n        }\n        if (httpMethod === 'GET' && unbound.length > 0) {\n            throw new Error(\n                `${label} is GET, so every parameter must use @PathParam(...) or @QueryParam(...); argument ${unbound[0]} is unmapped.`,\n            );\n        }\n        if (unbound.length > 1) {\n            throw new Error(\n                `${label} has ${unbound.length} unmapped parameters. POST permits exactly one unannotated request body; map every other parameter explicitly.`,\n            );\n        }\n        return unbound[0];\n    }\n\n    // webpieces-disable no-function-outside-class -- private conversion of reflected constructors to wire types\n    private static valueType(type: Function | undefined): HttpParameterValueType {\n        if (type === String) return 'string';\n        if (type === Number) return 'number';\n        if (type === Boolean) return 'boolean';\n        if (type === Array) return 'array';\n        return 'unknown';\n    }\n}\n"]}
+{"version":3,"file":"RouteMetadataFactory.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/RouteMetadataFactory.ts"],"names":[],"mappings":";;;AAAA,6CAMsB;AACtB,2EAA2E;AAC3E,iDAMwB;AACxB,mDAAgD;AAChD,2DAA2D;AAE3D;;;;GAIG;AACH,MAAa,oBAAoB;IAC7B,wIAAwI;IACxI,MAAM,CAAC,MAAM,CACT,QAAkB,EAClB,UAAkB,EAClB,mBAA4B;QAE5B,MAAM,SAAS,GAAG,IAAA,yBAAY,EAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC/C,MAAM,YAAY,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACX,6BAA6B,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI,UAAU,GAAG,CAC3E,CAAC;QACN,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAA,uBAAU,EAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,YAAY,CAAC,CAAC;QACzE,MAAM,OAAO,GAAG,IAAA,+BAAkB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,IAAA,wCAAoB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7E,IAAI,CAAC,uBAAuB,CACxB,QAAQ,EACR,UAAU,EACV,UAAU,EACV,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,OAAO,CAClB,CAAC;QACF,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACjE,MAAM,YAAY,GAAG,IAAA,wDAA4B,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACxE,MAAM,kBAAkB,GAAG,SAAS;YAChC,CAAC,CAAC,IAAI,CAAC,2BAA2B,CAC5B,QAAQ,EACR,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,CACf;YACH,CAAC,CAAC,IAAI,CAAC,kBAAkB,CACnB,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,UAAU,EACV,cAAc,EACd,YAAY,CACf,CAAC;QACR,MAAM,QAAQ,GAAG,YAAY;aACxB,GAAG,CACA,CAAC,WAAqC,EAAE,EAAE,CACtC,IAAI,mCAAoB,CACpB,WAAW,CAAC,KAAK,EACjB,WAAW,CAAC,MAAM,EAClB,WAAW,CAAC,QAAQ,EACpB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CACpD,CACR;aACA,IAAI,CAAC,CAAC,CAAuB,EAAE,CAAuB,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAEnF,OAAO,IAAI,6BAAa,CACpB,UAAU,EACV,QAAQ,EACR,UAAU,EACV,mBAAmB,EACnB,IAAA,wBAAW,EAAC,QAAQ,EAAE,UAAU,CAAC,EACjC,QAAQ,CAAC,IAAI,IAAI,YAAY,EAC7B,OAAO,CAAC,QAAQ,KAAK,IAAI,EACzB,IAAA,wBAAW,EAAC,QAAQ,EAAE,UAAU,CAAC,EACjC,OAAO,CAAC,OAAO,KAAK,IAAI,EACxB,QAAQ,EACR,kBAAkB,EAClB,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,UAAU,CAAC,EAC7D,SAAS,CACZ,CAAC;IACN,CAAC;IAED,4IAA4I;IACpI,MAAM,CAAC,uBAAuB,CAClC,QAAkB,EAClB,UAAkB,EAClB,UAA8B,EAC9B,QAAkB,EAClB,OAAiB;QAEjB,IAAI,UAAU,KAAK,KAAK,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,2EAA2E,CAC5G,CAAC;QACN,CAAC;QACD,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,0EAA0E,CAC3G,CAAC;QACN,CAAC;IACL,CAAC;IAED,+GAA+G;IACvG,MAAM,CAAC,2BAA2B,CACtC,QAAkB,EAClB,UAAkB,EAClB,UAA8B,EAC9B,cAAmC,EACnC,YAAiD;QAEjD,MAAM,KAAK,GAAG,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5D,IAAI,UAAU,KAAK,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,kCAAkC,CAAC,CAAC;QACvF,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,yDAAyD,CAAC,CAAC;QACvF,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,kDAAkD,CAAC,CAAC;QAChF,OAAO,SAAS,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,iIAAiI;IACjI,MAAM,CAAC,uBAAuB,CAAC,QAAkB;QAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,CAAC;QACzC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;QACvC,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,IAAA,yBAAY,EAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YACjE,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YAChD,6EAA6E;YAC7E,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YAClF,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,EAAE,CAAC;YAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,IAAI,QAAQ,QAAQ,KAAK,IAAI,UAAU,mBAAmB;oBAC9D,GAAG,KAAK,CAAC,UAAU,KAAK,KAAK,CAAC,IAAI,gDAAgD;oBAClF,mFAAmF,CAC1F,CAAC;YACN,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAC9B,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,qGAAqG;IAC7F,MAAM,CAAC,QAAQ,CAAC,QAAgB,EAAE,YAAoB;QAC1D,IAAI,QAAQ,KAAK,EAAE,IAAI,YAAY,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QACtD,MAAM,MAAM,GAAG,GAAG,QAAQ,IAAI,YAAY,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACrE,OAAO,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;IAC1D,CAAC;IAED,qGAAqG;IAC7F,MAAM,CAAC,UAAU,CACrB,KAAqC,EACrC,QAAkB,EAClB,UAAkB;QAElB,MAAM,MAAM,GAAG,KAAK,IAAI,MAAM,CAAC;QAC/B,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO,MAAM,CAAC;QACzD,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,qCAAqC,MAAM,CAAC,MAAM,CAAC,qBAAqB,CACzG,CAAC;IACN,CAAC;IAED,qGAAqG;IAC7F,MAAM,CAAC,YAAY,CACvB,KAAuC,EACvC,QAAkB,EAClB,UAAkB;QAElB,MAAM,YAAY,GAAG,KAAK,IAAI,MAAM,CAAC;QACrC,IAAI,YAAY,KAAK,MAAM,IAAI,YAAY,KAAK,MAAM;YAAE,OAAO,YAAY,CAAC;QAC5E,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,uCAAuC,MAAM,CAAC,YAAY,CAAC,sBAAsB,CAClH,CAAC;IACN,CAAC;IAED,sGAAsG;IAC9F,MAAM,CAAC,cAAc,CAAC,QAAkB,EAAE,UAAkB;QAChE,OAAO,OAAO,CAAC,WAAW,CAAC,mBAAmB,EAAE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;IAC1F,CAAC;IAED,kGAAkG;IAC1F,MAAM,CAAC,kBAAkB,CAC7B,QAAkB,EAClB,UAAkB,EAClB,QAAgB,EAChB,UAA8B,EAC9B,cAAmC,EACnC,YAAiD;QAEjD,MAAM,KAAK,GAAG,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5D,MAAM,YAAY,GAAG,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,CAC5D,CAAC,KAAuB,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CACxC,CAAC;QACF,MAAM,SAAS,GAAG,YAAY;aACzB,MAAM,CAAC,CAAC,WAAqC,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,KAAK,MAAM,CAAC;aAChF,GAAG,CAAC,CAAC,WAAqC,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC1E,KAAK,MAAM,WAAW,IAAI,IAAI,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,UAAU,QAAQ,eAAe,WAAW,wBAAwB,WAAW,eAAe,CACzG,CAAC;YACN,CAAC;QACL,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,yBAAyB,QAAQ,WAAW,QAAQ,aAAa,QAAQ,gBAAgB,CACpG,CAAC;YACN,CAAC;QACL,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QACnC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;QACxC,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACrC,MAAM,OAAO,GAAG,GAAG,WAAW,CAAC,MAAM,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;YAChE,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,UAAU,OAAO,mBAAmB,CAAC,CAAC;YAClE,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACtB,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAC1B,cAAc,CAAC,MAAM,EACrB,YAAY,CAAC,MAAM,CACf,CAAC,OAAe,EAAE,WAAqC,EAAE,EAAE,CACvD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,KAAK,GAAG,CAAC,CAAC,EAC5C,CAAC,CACJ,CACJ,CAAC;QACF,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,aAAa,EAAE,KAAK,EAAE,EAAE,CAAC;YACjD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,sFAAsF,OAAO,CAAC,CAAC,CAAC,eAAe,CAC1H,CAAC;QACN,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,QAAQ,OAAO,CAAC,MAAM,gHAAgH,CACjJ,CAAC;QACN,CAAC;QACD,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IAED,4GAA4G;IACpG,MAAM,CAAC,SAAS,CAAC,IAA0B;QAC/C,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,QAAQ,CAAC;QACrC,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,QAAQ,CAAC;QACrC,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,SAAS,CAAC;QACvC,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,OAAO,CAAC;QACnC,OAAO,SAAS,CAAC;IACrB,CAAC;CACJ;AA3QD,oDA2QC","sourcesContent":["import {\n    getApiPath,\n    getAuthMeta,\n    getEndpointOptions,\n    getEndpoints,\n    getMaskSpec,\n} from './decorators';\nimport { getHttpParameterDeclarations } from './http-parameter-decorators';\nimport {\n    ContractHttpMethod,\n    EndpointResponseType,\n    HttpParameterBinding,\n    HttpParameterDeclaration,\n    HttpParameterValueType,\n} from './HttpContract';\nimport { RouteMetadata } from './RouteMetadata';\nimport { getStreamingEndpoint } from './StreamingContract';\n\n/**\n * Build the one runtime route model consumed by incoming routing, in-process clients, and both\n * generated HTTP clients. Keeping this join/validation here prevents four subtly different\n * interpretations of the same decorators.\n */\nexport class RouteMetadataFactory {\n    // webpieces-disable no-function-outside-class -- deterministic decorator metadata factory shared by DI-free browser and server runtimes\n    static create(\n        apiClass: Function,\n        methodName: string,\n        controllerClassName?: string,\n    ): RouteMetadata {\n        const endpoints = getEndpoints(apiClass) ?? {};\n        const endpointPath = endpoints[methodName];\n        if (endpointPath === undefined) {\n            throw new Error(\n                `No @Endpoint metadata for ${apiClass.name || 'Unknown'}.${methodName}.`,\n            );\n        }\n        const fullPath = this.joinPath(getApiPath(apiClass) ?? '', endpointPath);\n        const options = getEndpointOptions(apiClass, methodName);\n        const streaming = getStreamingEndpoint(apiClass, methodName);\n        const httpMethod = this.httpMethod(options.httpMethod, apiClass, methodName);\n        this.validateEndpointOptions(\n            apiClass,\n            methodName,\n            httpMethod,\n            options.formPost,\n            options.rawBody,\n        );\n        const parameterTypes = this.parameterTypes(apiClass, methodName);\n        const declarations = getHttpParameterDeclarations(apiClass, methodName);\n        const bodyParameterIndex = streaming\n            ? this.validateStreamingParameters(\n                  apiClass,\n                  methodName,\n                  httpMethod,\n                  parameterTypes,\n                  declarations,\n              )\n            : this.validateParameters(\n                  apiClass,\n                  methodName,\n                  fullPath,\n                  httpMethod,\n                  parameterTypes,\n                  declarations,\n              );\n        const bindings = declarations\n            .map(\n                (declaration: HttpParameterDeclaration) =>\n                    new HttpParameterBinding(\n                        declaration.index,\n                        declaration.source,\n                        declaration.wireName,\n                        this.valueType(parameterTypes[declaration.index]),\n                    ),\n            )\n            .sort((a: HttpParameterBinding, b: HttpParameterBinding) => a.index - b.index);\n\n        return new RouteMetadata(\n            httpMethod,\n            fullPath,\n            methodName,\n            controllerClassName,\n            getAuthMeta(apiClass, methodName),\n            apiClass.name || 'UnknownApi',\n            options.formPost === true,\n            getMaskSpec(apiClass, methodName),\n            options.rawBody === true,\n            bindings,\n            bodyParameterIndex,\n            this.responseType(options.responseType, apiClass, methodName),\n            streaming,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper keeps the existing static metadata factory below the method-size limit\n    private static validateEndpointOptions(\n        apiClass: Function,\n        methodName: string,\n        httpMethod: ContractHttpMethod,\n        formPost?: boolean,\n        rawBody?: boolean,\n    ): void {\n        if (httpMethod === 'GET' && formPost === true) {\n            throw new Error(\n                `${apiClass.name}.${methodName} is GET and cannot declare formPost:true because GET has no request body.`,\n            );\n        }\n        if (httpMethod === 'GET' && rawBody === true) {\n            throw new Error(\n                `${apiClass.name}.${methodName} is GET and cannot declare rawBody:true because GET has no request body.`,\n            );\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure validator alongside existing contract validators\n    private static validateStreamingParameters(\n        apiClass: Function,\n        methodName: string,\n        httpMethod: ContractHttpMethod,\n        parameterTypes: readonly Function[],\n        declarations: readonly HttpParameterDeclaration[],\n    ): undefined {\n        const label = `${apiClass.name || 'Unknown'}.${methodName}`;\n        if (httpMethod !== 'POST') throw new Error(`${label} is streaming and must use POST.`);\n        if (declarations.length > 0)\n            throw new Error(`${label} is streaming and cannot declare path/query parameters.`);\n        if (parameterTypes.length !== 1)\n            throw new Error(`${label} must take exactly one ResponseStream parameter.`);\n        return undefined;\n    }\n\n    /**\n     * Refuse a contract in which two endpoints resolve to the same HTTP method + path.\n     *\n     * Empty paths are LEGAL (`@ApiPath('')` + `@Endpoint('', ...)` is how a contract says \"the whole\n     * destination arrives per call\"), so the thing actually worth rejecting is ambiguity: two methods\n     * that land on one route. On the server the second registration would silently shadow the first\n     * in the route map, and on the client both would dial the same URL — neither is ever what the\n     * author meant. Placeholder NAMES are ignored when comparing (`/a/{id}` and `/a/{key}` are the\n     * same route to a router), `''` and `'/'` compare equal (the server serves an empty path at the\n     * root), and the error names BOTH methods so the fix is obvious.\n     *\n     * Called by every transport that binds a whole contract (the generated clients and the server's\n     * route registration), so a duplicate dies at startup however the contract is consumed.\n     *\n     * @throws Error naming both colliding methods and the shared route.\n     */\n    // webpieces-disable no-function-outside-class -- deterministic contract validation shared by DI-free browser and server runtimes\n    static assertNoDuplicateRoutes(apiClass: Function): void {\n        const label = apiClass.name || 'Unknown';\n        const seen = new Map<string, string>();\n        for (const methodName of Object.keys(getEndpoints(apiClass) ?? {})) {\n            const route = this.create(apiClass, methodName);\n            // '' and '/' are one route to a server (every request path starts with '/').\n            const shape = (route.path === '' ? '/' : route.path).replace(/\\{[^{}]+\\}/g, '{}');\n            const key = `${route.httpMethod} ${shape}`;\n            const previous = seen.get(key);\n            if (previous !== undefined) {\n                throw new Error(\n                    `${label}.${previous} and ${label}.${methodName} both resolve to ` +\n                        `${route.httpMethod} '${route.path}'. Two endpoints of one contract cannot share ` +\n                        `an HTTP method + path; give one of them a distinct @Endpoint path or HTTP method.`,\n                );\n            }\n            seen.set(key, methodName);\n        }\n    }\n\n    /**\n     * Join `@ApiPath` and `@Endpoint` into the route path.\n     *\n     * Both empty joins to `''`, NOT `'/'`. A contract declaring `@ApiPath('')` + `@Endpoint('', ...)`\n     * is saying \"this route adds nothing to the base URL\", and a client whose base URL is a full\n     * destination (host + path + query) must send it byte for byte. Before #926 the client joined with\n     * plain concatenation (`'' + ''`), and forcing a `/` here broke exactly that (#944).\n     */\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static joinPath(basePath: string, endpointPath: string): string {\n        if (basePath === '' && endpointPath === '') return '';\n        const joined = `${basePath}/${endpointPath}`.replace(/\\/{2,}/g, '/');\n        return joined.startsWith('/') ? joined : `/${joined}`;\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static httpMethod(\n        value: ContractHttpMethod | undefined,\n        apiClass: Function,\n        methodName: string,\n    ): ContractHttpMethod {\n        const method = value ?? 'POST';\n        if (method === 'GET' || method === 'POST') return method;\n        throw new Error(\n            `${apiClass.name}.${methodName} declares unsupported httpMethod '${String(method)}'; use GET or POST.`,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static responseType(\n        value: EndpointResponseType | undefined,\n        apiClass: Function,\n        methodName: string,\n    ): EndpointResponseType {\n        const responseType = value ?? 'body';\n        if (responseType === 'body' || responseType === 'full') return responseType;\n        throw new Error(\n            `${apiClass.name}.${methodName} declares unsupported responseType '${String(responseType)}'; use body or full.`,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- Reflect metadata lookup has no injectable dependency\n    private static parameterTypes(apiClass: Function, methodName: string): Function[] {\n        return Reflect.getMetadata('design:paramtypes', apiClass.prototype, methodName) ?? [];\n    }\n\n    // webpieces-disable no-function-outside-class -- private deterministic contract validation helper\n    private static validateParameters(\n        apiClass: Function,\n        methodName: string,\n        fullPath: string,\n        httpMethod: ContractHttpMethod,\n        parameterTypes: readonly Function[],\n        declarations: readonly HttpParameterDeclaration[],\n    ): number | undefined {\n        const label = `${apiClass.name || 'Unknown'}.${methodName}`;\n        const placeholders = [...fullPath.matchAll(/\\{([^{}]+)\\}/g)].map(\n            (match: RegExpMatchArray) => match[1],\n        );\n        const pathNames = declarations\n            .filter((declaration: HttpParameterDeclaration) => declaration.source === 'path')\n            .map((declaration: HttpParameterDeclaration) => declaration.wireName);\n        for (const placeholder of new Set(placeholders)) {\n            if (!pathNames.includes(placeholder)) {\n                throw new Error(\n                    `${label} path '${fullPath}' contains {${placeholder}} but no @PathParam('${placeholder}') parameter.`,\n                );\n            }\n        }\n        for (const pathName of pathNames) {\n            if (!placeholders.includes(pathName)) {\n                throw new Error(\n                    `${label} declares @PathParam('${pathName}') but '${fullPath}' has no {${pathName}} placeholder.`,\n                );\n            }\n        }\n\n        const seenWire = new Set<string>();\n        const mappedIndexes = new Set<number>();\n        for (const declaration of declarations) {\n            const wireKey = `${declaration.source}:${declaration.wireName}`;\n            if (seenWire.has(wireKey)) {\n                throw new Error(`${label} maps '${wireKey}' more than once.`);\n            }\n            seenWire.add(wireKey);\n            mappedIndexes.add(declaration.index);\n        }\n\n        const declaredCount = Math.max(\n            parameterTypes.length,\n            declarations.reduce(\n                (highest: number, declaration: HttpParameterDeclaration) =>\n                    Math.max(highest, declaration.index + 1),\n                0,\n            ),\n        );\n        const unbound: number[] = [];\n        for (let index = 0; index < declaredCount; index++) {\n            if (!mappedIndexes.has(index)) unbound.push(index);\n        }\n        if (httpMethod === 'GET' && unbound.length > 0) {\n            throw new Error(\n                `${label} is GET, so every parameter must use @PathParam(...) or @QueryParam(...); argument ${unbound[0]} is unmapped.`,\n            );\n        }\n        if (unbound.length > 1) {\n            throw new Error(\n                `${label} has ${unbound.length} unmapped parameters. POST permits exactly one unannotated request body; map every other parameter explicitly.`,\n            );\n        }\n        return unbound[0];\n    }\n\n    // webpieces-disable no-function-outside-class -- private conversion of reflected constructors to wire types\n    private static valueType(type: Function | undefined): HttpParameterValueType {\n        if (type === String) return 'string';\n        if (type === Number) return 'number';\n        if (type === Boolean) return 'boolean';\n        if (type === Array) return 'array';\n        return 'unknown';\n    }\n}\n"]}

package/src/http/WebpiecesCoreHeaders.d.ts

@@ -162,6 +162,9 @@ export declare class WebpiecesCoreHeaders {
      * });
      * ```
      *
+     * The contract's path IS appended to it (base + `@ApiPath` + `@Endpoint`). When the stored value
+     * is a complete url — the usual partner-webhook row — use {@link OVERRIDE_FULL_URL} instead.
+     *
      * ONLY a client carrying a `ContextBaseUrlFilter` reads it. Every other client IGNORES this key
      * entirely, which is what stops an ambient value re-pointing every other client in the same
      * fan-out loop at a partner's server. Installing that ONE filter IS the opt-in, so
@@ -179,6 +182,28 @@ export declare class WebpiecesCoreHeaders {
      * it — the guard sits beneath every app filter and reads the fact that the request was moved.
      */
     static readonly OVERRIDE_BASE_URL: ContextKey<string, "untrusted">;
+    /**
+     * The COMPLETE url — host, path AND query — ONE outbound call should be sent to, verbatim. The
+     * sibling of {@link OVERRIDE_BASE_URL} for the other shape of runtime destination: a partner
+     * that does not implement our contract at their own host, but hands us one opaque url to POST
+     * to (`https://hooks.partner.example/in/abc?token=xyz`, straight out of a webhook row). With a
+     * base-URL override the contract's path would be appended to it and the url would be wrong; with
+     * this one the contract's path is NOT appended and nothing is inserted.
+     *
+     * ```ts
+     * RequestContext.run(() => {
+     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_FULL_URL, webhook.url);
+     *     return partnerWebhookClient.deliver(envelope);
+     * });
+     * ```
+     *
+     * ONLY a client carrying a `ContextFullUrlFilter` reads it, for exactly the reasons given on
+     * {@link OVERRIDE_BASE_URL}: installing that filter IS the opt-in, and every other client ignores
+     * the key. Not transferred over the wire (per-hop, or it becomes an SSRF pivot across the call
+     * tree), logged (it is what you want in a failed-delivery log line), and UNTRUSTED (a partner
+     * edited it) — which is why re-pointing at it arms the framework's SSRF guard automatically.
+     */
+    static readonly OVERRIDE_FULL_URL: ContextKey<string, "untrusted">;
     /**
      * NO CREDENTIAL KEYS LIVE HERE.
      *

package/src/http/WebpiecesCoreHeaders.js

@@ -180,6 +180,9 @@ class WebpiecesCoreHeaders {
      * });
      * ```
      *
+     * The contract's path IS appended to it (base + `@ApiPath` + `@Endpoint`). When the stored value
+     * is a complete url — the usual partner-webhook row — use {@link OVERRIDE_FULL_URL} instead.
+     *
      * ONLY a client carrying a `ContextBaseUrlFilter` reads it. Every other client IGNORES this key
      * entirely, which is what stops an ambient value re-pointing every other client in the same
      * fan-out loop at a partner's server. Installing that ONE filter IS the opt-in, so
@@ -200,6 +203,31 @@ class WebpiecesCoreHeaders {
     /*httpHeader*/ undefined, 
     /*maskInLogs*/ false, 
     /*isLogged*/ true);
+    /**
+     * The COMPLETE url — host, path AND query — ONE outbound call should be sent to, verbatim. The
+     * sibling of {@link OVERRIDE_BASE_URL} for the other shape of runtime destination: a partner
+     * that does not implement our contract at their own host, but hands us one opaque url to POST
+     * to (`https://hooks.partner.example/in/abc?token=xyz`, straight out of a webhook row). With a
+     * base-URL override the contract's path would be appended to it and the url would be wrong; with
+     * this one the contract's path is NOT appended and nothing is inserted.
+     *
+     * ```ts
+     * RequestContext.run(() => {
+     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_FULL_URL, webhook.url);
+     *     return partnerWebhookClient.deliver(envelope);
+     * });
+     * ```
+     *
+     * ONLY a client carrying a `ContextFullUrlFilter` reads it, for exactly the reasons given on
+     * {@link OVERRIDE_BASE_URL}: installing that filter IS the opt-in, and every other client ignores
+     * the key. Not transferred over the wire (per-hop, or it becomes an SSRF pivot across the call
+     * tree), logged (it is what you want in a failed-delivery log line), and UNTRUSTED (a partner
+     * edited it) — which is why re-pointing at it arms the framework's SSRF guard automatically.
+     */
+    static OVERRIDE_FULL_URL = ContextKey_1.ContextKey.untrusted('overrideFullUrl', 
+    /*httpHeader*/ undefined, 
+    /*maskInLogs*/ false, 
+    /*isLogged*/ true);
     /**
      * NO CREDENTIAL KEYS LIVE HERE.
      *
@@ -237,6 +265,7 @@ class WebpiecesCoreHeaders {
         WebpiecesCoreHeaders.CONTROLLER,
         WebpiecesCoreHeaders.METHOD,
         WebpiecesCoreHeaders.OVERRIDE_BASE_URL,
+        WebpiecesCoreHeaders.OVERRIDE_FULL_URL,
     ];
 }
 exports.WebpiecesCoreHeaders = WebpiecesCoreHeaders;

package/src/http/WebpiecesCoreHeaders.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebpiecesCoreHeaders.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WebpiecesCoreHeaders.ts"],"names":[],"mappings":"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","sourcesContent":["import { ContextKey, AnyContextKey } from '../ContextKey';\nimport { ApiCallInfo } from './ApiCallInfo';\n\n/**\n * Core framework context keys — the minimum the WebPieces framework needs to correlate one\n * request across every service it touches, and across every log line each of them writes.\n *\n * ONE id, propagated unchanged. The first service to see a request without an `x-request-id`\n * generates one (RequestContextHeaders.fillFromRequest); every hop copies it onward verbatim. Grep that id and you\n * have the whole call tree. There is no per-hop id and no parent pointer: a chain of ids you must\n * stitch back together buys nothing a single shared id does not already give you.\n *\n * Lives in core-util (browser-safe) so both the http clients and http-server can reference it.\n *\n * Exposed as {@link HeaderRegistry.DEFAULT_HEADERS} — a service opts into these by\n * passing `platformHeaders=true` to `HeaderRegistry.configure(...)`.\n *\n * Each key's `name` is the logical/log name; `httpHeader` is the wire name.\n */\nexport class WebpiecesCoreHeaders {\n    /**\n     * The id that correlates every hop of one request, and every log line of every hop.\n     * Generated by the first service to see a request without one; propagated unchanged after that.\n     */\n    static readonly REQUEST_ID = ContextKey.untrusted<string>('requestId', 'x-request-id');\n\n    /**\n     * WHICH SERVICE MINTED {@link REQUEST_ID} — the name from {@link ServiceInfo}, stamped by\n     * `RequestContextHeaders.fillFromRequest` ONLY on the branch that generates a new id (i.e. when\n     * the inbound request carried no `x-request-id`). It answers the question the id alone cannot:\n     * \"this trace starts here — is that right?\" An id appearing with no source means it came from\n     * outside; an id sourced by a service that should never be an entry point is a routing bug.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire, and that is the WHOLE POINT. If it\n     *   travelled, hop 2 would inherit it, hop 3 would inherit it, and \"who started this trace\"\n     *   would be indistinguishable from \"who passed it along\" — the origin, the one fact this key\n     *   carries, would be lost. It is absent on every hop that did NOT mint the id, which is exactly\n     *   the signal: present == I am the origin.\n     * - `isLogged` TRUE → emitted as a plain string at `jsonPayload.requestIdSource`.\n     */\n    static readonly REQUEST_ID_SOURCE = ContextKey.untrusted<string>(\n        'requestIdSource',\n        /*httpHeader*/ undefined,\n    );\n\n    /**\n     * The CALLER's build version — so a downstream server's logs record which build of the client\n     * called it (surfaces as `jsonPayload.clientVersion`). Distinct from the log line's own `version`\n     * (this service's build): `version` answers \"which build wrote this line?\", `clientVersion`\n     * answers \"which build asked us to?\".\n     *\n     * - `httpHeader` SET → transferred over the wire, BUT unlike a normal transferred key it is NOT\n     *   copied from the context onward. Each hop OVERWRITES it with its OWN `ServiceInfo.getVersion()`\n     *   as it becomes the client to the next hop (see `buildOutboundHeaders`), so on any given server\n     *   `clientVersion` is always the IMMEDIATE caller's version, never a stale grand-caller's.\n     * - `isLogged` TRUE → the inbound value lands in the context and flows through the normal log\n     *   field map; no backend change needed.\n     */\n    static readonly CLIENT_VERSION = ContextKey.untrusted<string>(\n        'clientVersion',\n        'x-webpieces-client-version',\n    );\n\n    /**\n     * A frontend/app-minted correlation id that groups every request triggered by ONE user ACTION.\n     *\n     * An \"action\" is a single thing the user did in the GUI — a CLICK on a button/link, or TYPING in a\n     * field — or a background poller tick: anything that may fan out into MULTIPLE remote calls. That one\n     * action fires 1..N browser HTTP calls, each of which gets its own framework-minted {@link REQUEST_ID}\n     * (one per HTTP call, shared within that call's server→server subtree). `actionId` sits ABOVE\n     * `requestId` and is what stitches those N requests back to the single action that caused them:\n     *\n     *     actionId  (app-minted, ONE per user action, rides EVERY call of that action)\n     *        └── 1..N requestId  (framework-minted, ONE per HTTP call)\n     *\n     * Grep one `actionId` in the logs → every `requestId` it spawned, and every log line of the whole\n     * action. Minted and refreshed by the app (a UI concern), carried under `x-webpieces-actionid`.\n     *\n     * Browser/app-minted ONLY: unlike {@link REQUEST_ID}, the framework transfers and logs it but must\n     * NOT auto-mint one server-side. Absent `actionId` ⇒ a non-action flow (system / cron / task), which\n     * is the correct signal.\n     *\n     * - `httpHeader` SET → transferred: copied off the inbound request into context and re-emitted on\n     *   outbound hops, so the id follows the action across services.\n     * - `isLogged` TRUE → emitted as a plain string on every log line of the request.\n     */\n    static readonly ACTION_ID = ContextKey.untrusted<string>('actionId', 'x-webpieces-actionid');\n\n    /**\n     * WHO the request is acting as, and WHAT they may do. All three are TRUSTED keys: they are the\n     * inputs to authorization decisions, so a reader must be able to tell \"the framework proved\n     * this\" from \"the caller typed this\" — see the trust section of the {@link ContextKey} doc.\n     *\n     * They keep their `httpHeader`, because propagating a verified identity to the next internal\n     * service is the point. What makes that safe is not the header being absent, it is WHO is\n     * allowed to have set it: an inbound value is held PENDING by\n     * `RequestContextHeaders.fillFromRequest` and admitted by `AuthFilter` only on a route that\n     * verified its CALLER (`@WpAuthOidc` / `@WpAuthSharedSecret`). On a browser-reachable route\n     * (`@WpAuthJwt` / public) the value must match what the authenticator itself derived, or the\n     * request is rejected.\n     *\n     * `provenance` says \"an app-bound JwtHook\" rather than naming one hook, because the framework\n     * default ({@link DefaultJwtHook}) stamps NO context entries at all — an app supplies a hook that\n     * returns {@link ContextTuple}s for the keys it can vouch for. Any of these three that an app's\n     * hook does NOT stamp will be rejected when a caller supplies it, which is the correct and loud\n     * outcome: nothing is vouching for it.\n     */\n    static readonly ORG_ID = ContextKey.trusted<string>(\n        'orgId',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-org-id',\n    );\n\n    static readonly USER_ID = ContextKey.trusted<string>(\n        'userId',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-user-id',\n    );\n\n    static readonly USER_ROLES = ContextKey.trusted<string>(\n        'roles',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-webpieces-roles',\n    );\n\n    /**\n     * Turns on test-case recording for this request (Java: x-webpieces-recording).\n     * Transferred so recording follows the request across service hops.\n     */\n    static readonly RECORDING = ContextKey.untrusted<string>('recording', 'x-webpieces-recording');\n\n    /**\n     * The structured API-call tag ({@link ApiCallInfo}) stamped by {@link LogApiCallImpl} around every\n     * outbound (client) / inbound (server) call. It rides the magic context so EVERY log line emitted\n     * during the call inherits a filterable `api` object, surfacing in GCP as nested\n     * `jsonPayload.api.{side,type,result,path,method}`.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire. Per-hop only: each server/client hop\n     *   stamps its own tag, so a downstream server records `side:'server'`, never the caller's `side:'client'`.\n     * - `isLogged` TRUE → emitted by the logging backends. It carries an OBJECT value, so the backends\n     *   read it via {@link HeaderRegistry.buildStructuredLogFields} (object-aware); the flat\n     *   `buildLogFields()` string map deliberately skips it (typeof-string guard).\n     */\n    static readonly API_CALL_INFO = ContextKey.untrusted<ApiCallInfo>(\n        'api',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The inbound request's HTTP method and path, stamped ONCE from the {@link HttpRequest} by\n     * `RequestContextHeaders.fillFromRequest` (the atomic inbound choke point every transport funnels\n     * through). They surface as top-level `jsonPayload.httpMethod` / `jsonPayload.requestPath` so every\n     * log line of the request carries them — they used to ride inside {@link ApiCallInfo} (`api.path` /\n     * `api.method`) but that coupled a per-CALL logger to the per-REQUEST transport shape.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire: a downstream hop stamps its OWN inbound\n     *   method/path, never the caller's. Outbound client calls never set these (no inbound path).\n     * - `isLogged` TRUE → emitted by the logging backends as plain strings.\n     */\n    static readonly HTTP_METHOD = ContextKey.untrusted<string>(\n        'httpMethod',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    static readonly REQUEST_PATH = ContextKey.untrusted<string>(\n        'requestPath',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The routed endpoint's IMPLEMENTATION identity: the concrete controller class name\n     * ({@link RouteMetadata.controllerClassName}, e.g. `LoginController`) and the handler method NAME\n     * ({@link RouteMetadata.methodName}, e.g. `login`), stamped once per request by {@link LogApiFilter}\n     * after route matching so every subsequent log line of the request carries them.\n     *\n     * These say WHICH CODE ran, which is what you actually grep for — far more useful than the raw\n     * `requestPath`. They are the top-level, filterable twin of what previously only lived nested in\n     * {@link ApiCallInfo} (`api.method.controllerName` / `api.method.methodName`). The local console\n     * formatters render them together as a compact `[Controller.method]` bracket; GCP keeps them as two\n     * separate `jsonPayload.controller` / `jsonPayload.method` fields.\n     *\n     * NOTE: `method` here is the CODE method name (e.g. `login`), NOT the HTTP verb — that is\n     * {@link HTTP_METHOD} (`httpMethod`).\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred: each hop stamps its OWN routed controller/method.\n     * - `isLogged` TRUE → emitted by the logging backends as plain strings.\n     */\n    static readonly CONTROLLER = ContextKey.untrusted<string>(\n        'controller',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    static readonly METHOD = ContextKey.untrusted<string>(\n        'method',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The base URL ONE outbound call should go to, overriding whatever the client's `ClientConfig`\n     * bound at construction — the answer to \"POST our published contract to a URL the PARTNER\n     * registered at runtime\" (an `OrganizationWebhook.url` column, an OAuth callback, a per-tenant\n     * or self-hosted host). The destination is DATA, not deployment, so it cannot be a svcName and\n     * there is nothing to register in {@link ClientRegistry}.\n     *\n     * ```ts\n     * RequestContext.run(() => {\n     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);\n     *     return partnerWebhookClient.deliver(envelope);\n     * });\n     * ```\n     *\n     * ONLY a client carrying a `ContextBaseUrlFilter` reads it. Every other client IGNORES this key\n     * entirely, which is what stops an ambient value re-pointing every other client in the same\n     * fan-out loop at a partner's server. Installing that ONE filter IS the opt-in, so\n     * `grep -rn ContextBaseUrlFilter` enumerates every client that can be re-pointed at all.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire, and that is load-bearing. This value\n     *   names where THIS hop goes. If it travelled, the callee would inherit it and re-point ITS\n     *   own outbound calls at the same host — one partner-supplied URL turning into an SSRF pivot\n     *   across the whole call tree. It is per-hop, always.\n     * - `isLogged` TRUE → the destination of a partner delivery is exactly what you want in the log\n     *   line when one fails.\n     *\n     * UNTRUSTED, necessarily: it comes from a database column a partner edited. That is precisely\n     * why re-pointing a request ARMS the framework's SSRF guard, automatically, rather than trusting\n     * it — the guard sits beneath every app filter and reads the fact that the request was moved.\n     */\n    static readonly OVERRIDE_BASE_URL = ContextKey.untrusted<string>(\n        'overrideBaseUrl',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * NO CREDENTIAL KEYS LIVE HERE.\n     *\n     * `authorization` and `x-webpieces-shared-secret` used to be ContextKeys. That made them\n     * TRANSFERRED keys, so the inbound transfer copied them off the request into the\n     * RequestContext, and every outbound RPC call and enqueued Cloud Task then carried the\n     * caller's credential onward — to services that had no business seeing it.\n     *\n     * A credential belongs to ONE request hop. It is read straight off the {@link HttpRequest}\n     * by the framework AuthFilter, and written straight onto the outbound request by the client\n     * that mints it (NodeProxyClient, GcpTaskInvoker, InMemoryTaskInvoker). It never enters the\n     * magic context, so nothing can propagate it by accident.\n     *\n     * An app that genuinely wants a credential to travel can still register its own ContextKey for\n     * it — but that is now an explicit, visible decision rather than the default.\n     */\n\n    /**\n     * All core context keys (the platform DEFAULT_HEADERS set). A `static readonly` CONSTANT, not a\n     * method: it is compile-time data — a list of the key definitions above — read once at the startup\n     * composition root (`HeaderRegistry.configure` / `HeaderRegistry.DEFAULT_HEADERS`). A method here\n     * would be un-injectable behavior the DI design graph can't reach; a constant is honest data.\n     */\n    static readonly ALL_HEADERS: AnyContextKey[] = [\n        WebpiecesCoreHeaders.REQUEST_ID,\n        WebpiecesCoreHeaders.REQUEST_ID_SOURCE,\n        WebpiecesCoreHeaders.CLIENT_VERSION,\n        WebpiecesCoreHeaders.ACTION_ID,\n        WebpiecesCoreHeaders.USER_ID,\n        WebpiecesCoreHeaders.ORG_ID,\n        WebpiecesCoreHeaders.USER_ROLES,\n        WebpiecesCoreHeaders.RECORDING,\n        WebpiecesCoreHeaders.API_CALL_INFO,\n        WebpiecesCoreHeaders.HTTP_METHOD,\n        WebpiecesCoreHeaders.REQUEST_PATH,\n        WebpiecesCoreHeaders.CONTROLLER,\n        WebpiecesCoreHeaders.METHOD,\n        WebpiecesCoreHeaders.OVERRIDE_BASE_URL,\n    ];\n}\n"]}
+{"version":3,"file":"WebpiecesCoreHeaders.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WebpiecesCoreHeaders.ts"],"names":[],"mappings":"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","sourcesContent":["import { ContextKey, AnyContextKey } from '../ContextKey';\nimport { ApiCallInfo } from './ApiCallInfo';\n\n/**\n * Core framework context keys — the minimum the WebPieces framework needs to correlate one\n * request across every service it touches, and across every log line each of them writes.\n *\n * ONE id, propagated unchanged. The first service to see a request without an `x-request-id`\n * generates one (RequestContextHeaders.fillFromRequest); every hop copies it onward verbatim. Grep that id and you\n * have the whole call tree. There is no per-hop id and no parent pointer: a chain of ids you must\n * stitch back together buys nothing a single shared id does not already give you.\n *\n * Lives in core-util (browser-safe) so both the http clients and http-server can reference it.\n *\n * Exposed as {@link HeaderRegistry.DEFAULT_HEADERS} — a service opts into these by\n * passing `platformHeaders=true` to `HeaderRegistry.configure(...)`.\n *\n * Each key's `name` is the logical/log name; `httpHeader` is the wire name.\n */\nexport class WebpiecesCoreHeaders {\n    /**\n     * The id that correlates every hop of one request, and every log line of every hop.\n     * Generated by the first service to see a request without one; propagated unchanged after that.\n     */\n    static readonly REQUEST_ID = ContextKey.untrusted<string>('requestId', 'x-request-id');\n\n    /**\n     * WHICH SERVICE MINTED {@link REQUEST_ID} — the name from {@link ServiceInfo}, stamped by\n     * `RequestContextHeaders.fillFromRequest` ONLY on the branch that generates a new id (i.e. when\n     * the inbound request carried no `x-request-id`). It answers the question the id alone cannot:\n     * \"this trace starts here — is that right?\" An id appearing with no source means it came from\n     * outside; an id sourced by a service that should never be an entry point is a routing bug.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire, and that is the WHOLE POINT. If it\n     *   travelled, hop 2 would inherit it, hop 3 would inherit it, and \"who started this trace\"\n     *   would be indistinguishable from \"who passed it along\" — the origin, the one fact this key\n     *   carries, would be lost. It is absent on every hop that did NOT mint the id, which is exactly\n     *   the signal: present == I am the origin.\n     * - `isLogged` TRUE → emitted as a plain string at `jsonPayload.requestIdSource`.\n     */\n    static readonly REQUEST_ID_SOURCE = ContextKey.untrusted<string>(\n        'requestIdSource',\n        /*httpHeader*/ undefined,\n    );\n\n    /**\n     * The CALLER's build version — so a downstream server's logs record which build of the client\n     * called it (surfaces as `jsonPayload.clientVersion`). Distinct from the log line's own `version`\n     * (this service's build): `version` answers \"which build wrote this line?\", `clientVersion`\n     * answers \"which build asked us to?\".\n     *\n     * - `httpHeader` SET → transferred over the wire, BUT unlike a normal transferred key it is NOT\n     *   copied from the context onward. Each hop OVERWRITES it with its OWN `ServiceInfo.getVersion()`\n     *   as it becomes the client to the next hop (see `buildOutboundHeaders`), so on any given server\n     *   `clientVersion` is always the IMMEDIATE caller's version, never a stale grand-caller's.\n     * - `isLogged` TRUE → the inbound value lands in the context and flows through the normal log\n     *   field map; no backend change needed.\n     */\n    static readonly CLIENT_VERSION = ContextKey.untrusted<string>(\n        'clientVersion',\n        'x-webpieces-client-version',\n    );\n\n    /**\n     * A frontend/app-minted correlation id that groups every request triggered by ONE user ACTION.\n     *\n     * An \"action\" is a single thing the user did in the GUI — a CLICK on a button/link, or TYPING in a\n     * field — or a background poller tick: anything that may fan out into MULTIPLE remote calls. That one\n     * action fires 1..N browser HTTP calls, each of which gets its own framework-minted {@link REQUEST_ID}\n     * (one per HTTP call, shared within that call's server→server subtree). `actionId` sits ABOVE\n     * `requestId` and is what stitches those N requests back to the single action that caused them:\n     *\n     *     actionId  (app-minted, ONE per user action, rides EVERY call of that action)\n     *        └── 1..N requestId  (framework-minted, ONE per HTTP call)\n     *\n     * Grep one `actionId` in the logs → every `requestId` it spawned, and every log line of the whole\n     * action. Minted and refreshed by the app (a UI concern), carried under `x-webpieces-actionid`.\n     *\n     * Browser/app-minted ONLY: unlike {@link REQUEST_ID}, the framework transfers and logs it but must\n     * NOT auto-mint one server-side. Absent `actionId` ⇒ a non-action flow (system / cron / task), which\n     * is the correct signal.\n     *\n     * - `httpHeader` SET → transferred: copied off the inbound request into context and re-emitted on\n     *   outbound hops, so the id follows the action across services.\n     * - `isLogged` TRUE → emitted as a plain string on every log line of the request.\n     */\n    static readonly ACTION_ID = ContextKey.untrusted<string>('actionId', 'x-webpieces-actionid');\n\n    /**\n     * WHO the request is acting as, and WHAT they may do. All three are TRUSTED keys: they are the\n     * inputs to authorization decisions, so a reader must be able to tell \"the framework proved\n     * this\" from \"the caller typed this\" — see the trust section of the {@link ContextKey} doc.\n     *\n     * They keep their `httpHeader`, because propagating a verified identity to the next internal\n     * service is the point. What makes that safe is not the header being absent, it is WHO is\n     * allowed to have set it: an inbound value is held PENDING by\n     * `RequestContextHeaders.fillFromRequest` and admitted by `AuthFilter` only on a route that\n     * verified its CALLER (`@WpAuthOidc` / `@WpAuthSharedSecret`). On a browser-reachable route\n     * (`@WpAuthJwt` / public) the value must match what the authenticator itself derived, or the\n     * request is rejected.\n     *\n     * `provenance` says \"an app-bound JwtHook\" rather than naming one hook, because the framework\n     * default ({@link DefaultJwtHook}) stamps NO context entries at all — an app supplies a hook that\n     * returns {@link ContextTuple}s for the keys it can vouch for. Any of these three that an app's\n     * hook does NOT stamp will be rejected when a caller supplies it, which is the correct and loud\n     * outcome: nothing is vouching for it.\n     */\n    static readonly ORG_ID = ContextKey.trusted<string>(\n        'orgId',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-org-id',\n    );\n\n    static readonly USER_ID = ContextKey.trusted<string>(\n        'userId',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-user-id',\n    );\n\n    static readonly USER_ROLES = ContextKey.trusted<string>(\n        'roles',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-webpieces-roles',\n    );\n\n    /**\n     * Turns on test-case recording for this request (Java: x-webpieces-recording).\n     * Transferred so recording follows the request across service hops.\n     */\n    static readonly RECORDING = ContextKey.untrusted<string>('recording', 'x-webpieces-recording');\n\n    /**\n     * The structured API-call tag ({@link ApiCallInfo}) stamped by {@link LogApiCallImpl} around every\n     * outbound (client) / inbound (server) call. It rides the magic context so EVERY log line emitted\n     * during the call inherits a filterable `api` object, surfacing in GCP as nested\n     * `jsonPayload.api.{side,type,result,path,method}`.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire. Per-hop only: each server/client hop\n     *   stamps its own tag, so a downstream server records `side:'server'`, never the caller's `side:'client'`.\n     * - `isLogged` TRUE → emitted by the logging backends. It carries an OBJECT value, so the backends\n     *   read it via {@link HeaderRegistry.buildStructuredLogFields} (object-aware); the flat\n     *   `buildLogFields()` string map deliberately skips it (typeof-string guard).\n     */\n    static readonly API_CALL_INFO = ContextKey.untrusted<ApiCallInfo>(\n        'api',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The inbound request's HTTP method and path, stamped ONCE from the {@link HttpRequest} by\n     * `RequestContextHeaders.fillFromRequest` (the atomic inbound choke point every transport funnels\n     * through). They surface as top-level `jsonPayload.httpMethod` / `jsonPayload.requestPath` so every\n     * log line of the request carries them — they used to ride inside {@link ApiCallInfo} (`api.path` /\n     * `api.method`) but that coupled a per-CALL logger to the per-REQUEST transport shape.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire: a downstream hop stamps its OWN inbound\n     *   method/path, never the caller's. Outbound client calls never set these (no inbound path).\n     * - `isLogged` TRUE → emitted by the logging backends as plain strings.\n     */\n    static readonly HTTP_METHOD = ContextKey.untrusted<string>(\n        'httpMethod',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    static readonly REQUEST_PATH = ContextKey.untrusted<string>(\n        'requestPath',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The routed endpoint's IMPLEMENTATION identity: the concrete controller class name\n     * ({@link RouteMetadata.controllerClassName}, e.g. `LoginController`) and the handler method NAME\n     * ({@link RouteMetadata.methodName}, e.g. `login`), stamped once per request by {@link LogApiFilter}\n     * after route matching so every subsequent log line of the request carries them.\n     *\n     * These say WHICH CODE ran, which is what you actually grep for — far more useful than the raw\n     * `requestPath`. They are the top-level, filterable twin of what previously only lived nested in\n     * {@link ApiCallInfo} (`api.method.controllerName` / `api.method.methodName`). The local console\n     * formatters render them together as a compact `[Controller.method]` bracket; GCP keeps them as two\n     * separate `jsonPayload.controller` / `jsonPayload.method` fields.\n     *\n     * NOTE: `method` here is the CODE method name (e.g. `login`), NOT the HTTP verb — that is\n     * {@link HTTP_METHOD} (`httpMethod`).\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred: each hop stamps its OWN routed controller/method.\n     * - `isLogged` TRUE → emitted by the logging backends as plain strings.\n     */\n    static readonly CONTROLLER = ContextKey.untrusted<string>(\n        'controller',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    static readonly METHOD = ContextKey.untrusted<string>(\n        'method',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The base URL ONE outbound call should go to, overriding whatever the client's `ClientConfig`\n     * bound at construction — the answer to \"POST our published contract to a URL the PARTNER\n     * registered at runtime\" (an `OrganizationWebhook.url` column, an OAuth callback, a per-tenant\n     * or self-hosted host). The destination is DATA, not deployment, so it cannot be a svcName and\n     * there is nothing to register in {@link ClientRegistry}.\n     *\n     * ```ts\n     * RequestContext.run(() => {\n     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);\n     *     return partnerWebhookClient.deliver(envelope);\n     * });\n     * ```\n     *\n     * The contract's path IS appended to it (base + `@ApiPath` + `@Endpoint`). When the stored value\n     * is a complete url — the usual partner-webhook row — use {@link OVERRIDE_FULL_URL} instead.\n     *\n     * ONLY a client carrying a `ContextBaseUrlFilter` reads it. Every other client IGNORES this key\n     * entirely, which is what stops an ambient value re-pointing every other client in the same\n     * fan-out loop at a partner's server. Installing that ONE filter IS the opt-in, so\n     * `grep -rn ContextBaseUrlFilter` enumerates every client that can be re-pointed at all.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire, and that is load-bearing. This value\n     *   names where THIS hop goes. If it travelled, the callee would inherit it and re-point ITS\n     *   own outbound calls at the same host — one partner-supplied URL turning into an SSRF pivot\n     *   across the whole call tree. It is per-hop, always.\n     * - `isLogged` TRUE → the destination of a partner delivery is exactly what you want in the log\n     *   line when one fails.\n     *\n     * UNTRUSTED, necessarily: it comes from a database column a partner edited. That is precisely\n     * why re-pointing a request ARMS the framework's SSRF guard, automatically, rather than trusting\n     * it — the guard sits beneath every app filter and reads the fact that the request was moved.\n     */\n    static readonly OVERRIDE_BASE_URL = ContextKey.untrusted<string>(\n        'overrideBaseUrl',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The COMPLETE url — host, path AND query — ONE outbound call should be sent to, verbatim. The\n     * sibling of {@link OVERRIDE_BASE_URL} for the other shape of runtime destination: a partner\n     * that does not implement our contract at their own host, but hands us one opaque url to POST\n     * to (`https://hooks.partner.example/in/abc?token=xyz`, straight out of a webhook row). With a\n     * base-URL override the contract's path would be appended to it and the url would be wrong; with\n     * this one the contract's path is NOT appended and nothing is inserted.\n     *\n     * ```ts\n     * RequestContext.run(() => {\n     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_FULL_URL, webhook.url);\n     *     return partnerWebhookClient.deliver(envelope);\n     * });\n     * ```\n     *\n     * ONLY a client carrying a `ContextFullUrlFilter` reads it, for exactly the reasons given on\n     * {@link OVERRIDE_BASE_URL}: installing that filter IS the opt-in, and every other client ignores\n     * the key. Not transferred over the wire (per-hop, or it becomes an SSRF pivot across the call\n     * tree), logged (it is what you want in a failed-delivery log line), and UNTRUSTED (a partner\n     * edited it) — which is why re-pointing at it arms the framework's SSRF guard automatically.\n     */\n    static readonly OVERRIDE_FULL_URL = ContextKey.untrusted<string>(\n        'overrideFullUrl',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * NO CREDENTIAL KEYS LIVE HERE.\n     *\n     * `authorization` and `x-webpieces-shared-secret` used to be ContextKeys. That made them\n     * TRANSFERRED keys, so the inbound transfer copied them off the request into the\n     * RequestContext, and every outbound RPC call and enqueued Cloud Task then carried the\n     * caller's credential onward — to services that had no business seeing it.\n     *\n     * A credential belongs to ONE request hop. It is read straight off the {@link HttpRequest}\n     * by the framework AuthFilter, and written straight onto the outbound request by the client\n     * that mints it (NodeProxyClient, GcpTaskInvoker, InMemoryTaskInvoker). It never enters the\n     * magic context, so nothing can propagate it by accident.\n     *\n     * An app that genuinely wants a credential to travel can still register its own ContextKey for\n     * it — but that is now an explicit, visible decision rather than the default.\n     */\n\n    /**\n     * All core context keys (the platform DEFAULT_HEADERS set). A `static readonly` CONSTANT, not a\n     * method: it is compile-time data — a list of the key definitions above — read once at the startup\n     * composition root (`HeaderRegistry.configure` / `HeaderRegistry.DEFAULT_HEADERS`). A method here\n     * would be un-injectable behavior the DI design graph can't reach; a constant is honest data.\n     */\n    static readonly ALL_HEADERS: AnyContextKey[] = [\n        WebpiecesCoreHeaders.REQUEST_ID,\n        WebpiecesCoreHeaders.REQUEST_ID_SOURCE,\n        WebpiecesCoreHeaders.CLIENT_VERSION,\n        WebpiecesCoreHeaders.ACTION_ID,\n        WebpiecesCoreHeaders.USER_ID,\n        WebpiecesCoreHeaders.ORG_ID,\n        WebpiecesCoreHeaders.USER_ROLES,\n        WebpiecesCoreHeaders.RECORDING,\n        WebpiecesCoreHeaders.API_CALL_INFO,\n        WebpiecesCoreHeaders.HTTP_METHOD,\n        WebpiecesCoreHeaders.REQUEST_PATH,\n        WebpiecesCoreHeaders.CONTROLLER,\n        WebpiecesCoreHeaders.METHOD,\n        WebpiecesCoreHeaders.OVERRIDE_BASE_URL,\n        WebpiecesCoreHeaders.OVERRIDE_FULL_URL,\n    ];\n}\n"]}

package/src/http/WebpiecesDefaultFailureClassifier.d.ts

@@ -14,10 +14,14 @@ import { FailureClassifier } from './FailureClassifier';
  *
  * SERVER — a healthy server correctly rejecting a CLIENT'S mistake is metrics NOISE, not a failure:
  * - ApiBadRequestError (400), ApiUnauthorizedError (401), ApiForbiddenError (403),
- *   ApiNotFoundError (404) → the server is fine, the caller erred → NON-failure.
+ *   ApiNotFoundError (404), ApiConflictError (409), ApiPreconditionFailedError (412),
+ *   ApiUnsupportedMediaTypeError (415), ApiUnprocessableError (422), and an ApiCodedError whose
+ *   `isCallerError()` is true (below 500, except 408/429) → the server is fine, the caller erred →
+ *   NON-failure.
  * SERVER — something may actually be WRONG, so SURFACE it (failure):
  * - ApiRequestTimeoutError (408): a 4xx, but the client may NEVER have seen the response — deliberately
- *   absent below, so it counts as a failure. Implementation/dependency failures and non-API errors are failures.
+ *   absent below, so it counts as a failure. Implementation/dependency failures, ApiNotImplementedError
+ *   (501), an ApiCodedError of 500+ (or 408/429), and non-API errors are failures.
  *
  * ApiEndUserError (266): ALWAYS a non-failure, server OR client — an expected "user made a mistake".
  * CLIENT: receiving ANY error except 266 means the outbound call FAILED → failure.

package/src/http/WebpiecesDefaultFailureClassifier.js

@@ -16,10 +16,14 @@ const ApiError_1 = require("../errors/ApiError");
  *
  * SERVER — a healthy server correctly rejecting a CLIENT'S mistake is metrics NOISE, not a failure:
  * - ApiBadRequestError (400), ApiUnauthorizedError (401), ApiForbiddenError (403),
- *   ApiNotFoundError (404) → the server is fine, the caller erred → NON-failure.
+ *   ApiNotFoundError (404), ApiConflictError (409), ApiPreconditionFailedError (412),
+ *   ApiUnsupportedMediaTypeError (415), ApiUnprocessableError (422), and an ApiCodedError whose
+ *   `isCallerError()` is true (below 500, except 408/429) → the server is fine, the caller erred →
+ *   NON-failure.
  * SERVER — something may actually be WRONG, so SURFACE it (failure):
  * - ApiRequestTimeoutError (408): a 4xx, but the client may NEVER have seen the response — deliberately
- *   absent below, so it counts as a failure. Implementation/dependency failures and non-API errors are failures.
+ *   absent below, so it counts as a failure. Implementation/dependency failures, ApiNotImplementedError
+ *   (501), an ApiCodedError of 500+ (or 408/429), and non-API errors are failures.
  *
  * ApiEndUserError (266): ALWAYS a non-failure, server OR client — an expected "user made a mistake".
  * CLIENT: receiving ANY error except 266 means the outbound call FAILED → failure.
@@ -45,7 +49,12 @@ class WebpiecesDefaultFailureClassifier {
         const healthyRejection = error instanceof ApiError_1.ApiBadRequestError ||
             error instanceof ApiError_1.ApiUnauthorizedError ||
             error instanceof ApiError_1.ApiForbiddenError ||
-            error instanceof ApiError_1.ApiNotFoundError;
+            error instanceof ApiError_1.ApiNotFoundError ||
+            error instanceof ApiError_1.ApiConflictError ||
+            error instanceof ApiError_1.ApiUnprocessableError ||
+            error instanceof ApiError_1.ApiPreconditionFailedError ||
+            error instanceof ApiError_1.ApiUnsupportedMediaTypeError ||
+            (error instanceof ApiError_1.ApiCodedError && error.isCallerError());
         return !healthyRejection;
     }
 }

package/src/http/WebpiecesDefaultFailureClassifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebpiecesDefaultFailureClassifier.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WebpiecesDefaultFailureClassifier.ts"],"names":[],"mappings":";;;AAAA,iDAM4B;AAI5B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,iCAAiC;IAC1C;;;;;OAKG;IACH,SAAS,CAAC,KAAY,EAAE,UAAyB;QAC7C,gEAAgE;QAChE,IAAI,KAAK,YAAY,0BAAe,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,8EAA8E;QAC9E,IAAI,UAAU,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,sFAAsF;QACtF,oGAAoG;QACpG,MAAM,gBAAgB,GAClB,KAAK,YAAY,6BAAkB;YACnC,KAAK,YAAY,+BAAoB;YACrC,KAAK,YAAY,4BAAiB;YAClC,KAAK,YAAY,2BAAgB,CAAC;QACtC,OAAO,CAAC,gBAAgB,CAAC;IAC7B,CAAC;CACJ;AAzBD,8EAyBC;AAED,oFAAoF;AACvE,QAAA,oCAAoC,GAAG,IAAI,iCAAiC,EAAE,CAAC","sourcesContent":["import {\n    ApiBadRequestError,\n    ApiUnauthorizedError,\n    ApiForbiddenError,\n    ApiNotFoundError,\n    ApiEndUserError,\n} from '../errors/ApiError';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { FailureClassifier } from './FailureClassifier';\n\n/**\n * The webpieces built-in {@link FailureClassifier} — the terminal tier, used when no app default and\n * no per-apiClass classifier claims an error. It is the SINGLE SOURCE OF TRUTH for the historical\n * `LogApiCall.isUserError` behavior (which now delegates here), so the classification lives in one\n * place.\n *\n * The question is \"are things WORKING?\", NOT \"was it an HTTP 4xx vs 5xx\" — the two differ (see 408).\n * Classification is by portable Error TYPE, never by transport: this runs over in-process calls,\n * pubsub/queue handlers, and HTTP through one code path and only ever sees a thrown Error. The API\n * classes are portable error types that travel with the throw anywhere, so matching the TYPE works\n * with or without any HTTP in the picture.\n *\n * SERVER — a healthy server correctly rejecting a CLIENT'S mistake is metrics NOISE, not a failure:\n * - ApiBadRequestError (400), ApiUnauthorizedError (401), ApiForbiddenError (403),\n *   ApiNotFoundError (404) → the server is fine, the caller erred → NON-failure.\n * SERVER — something may actually be WRONG, so SURFACE it (failure):\n * - ApiRequestTimeoutError (408): a 4xx, but the client may NEVER have seen the response — deliberately\n *   absent below, so it counts as a failure. Implementation/dependency failures and non-API errors are failures.\n *\n * ApiEndUserError (266): ALWAYS a non-failure, server OR client — an expected \"user made a mistake\".\n * CLIENT: receiving ANY error except 266 means the outbound call FAILED → failure.\n */\nexport class WebpiecesDefaultFailureClassifier implements FailureClassifier {\n    /**\n     * Terminal tier — NEVER returns undefined (a definitive verdict is required so classification\n     * always resolves to a boolean).\n     *\n     * @returns true = failure, false = expected/non-failure\n     */\n    isFailure(error: Error, methodInfo: ApiMethodInfo): boolean {\n        // 266 is the one error that is never a failure, on either side.\n        if (error instanceof ApiEndUserError) {\n            return false;\n        }\n        // A client that RECEIVED any error (except the 266 above) made a failed call.\n        if (methodInfo.side !== 'server') {\n            return true;\n        }\n        // SERVER: only a healthy rejection of the caller's mistake is a non-failure. Note 408\n        // (ApiRequestTimeoutError) is intentionally NOT here — the client may never have seen the response.\n        const healthyRejection =\n            error instanceof ApiBadRequestError ||\n            error instanceof ApiUnauthorizedError ||\n            error instanceof ApiForbiddenError ||\n            error instanceof ApiNotFoundError;\n        return !healthyRejection;\n    }\n}\n\n/** Process-wide built-in instance — stateless, so one shared instance is enough. */\nexport const WEBPIECES_DEFAULT_FAILURE_CLASSIFIER = new WebpiecesDefaultFailureClassifier();\n"]}
+{"version":3,"file":"WebpiecesDefaultFailureClassifier.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WebpiecesDefaultFailureClassifier.ts"],"names":[],"mappings":";;;AAAA,iDAW4B;AAI5B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAa,iCAAiC;IAC1C;;;;;OAKG;IACH,SAAS,CAAC,KAAY,EAAE,UAAyB;QAC7C,gEAAgE;QAChE,IAAI,KAAK,YAAY,0BAAe,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,8EAA8E;QAC9E,IAAI,UAAU,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,sFAAsF;QACtF,oGAAoG;QACpG,MAAM,gBAAgB,GAClB,KAAK,YAAY,6BAAkB;YACnC,KAAK,YAAY,+BAAoB;YACrC,KAAK,YAAY,4BAAiB;YAClC,KAAK,YAAY,2BAAgB;YACjC,KAAK,YAAY,2BAAgB;YACjC,KAAK,YAAY,gCAAqB;YACtC,KAAK,YAAY,qCAA0B;YAC3C,KAAK,YAAY,uCAA4B;YAC7C,CAAC,KAAK,YAAY,wBAAa,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC;QAC9D,OAAO,CAAC,gBAAgB,CAAC;IAC7B,CAAC;CACJ;AA9BD,8EA8BC;AAED,oFAAoF;AACvE,QAAA,oCAAoC,GAAG,IAAI,iCAAiC,EAAE,CAAC","sourcesContent":["import {\n    ApiBadRequestError,\n    ApiUnauthorizedError,\n    ApiForbiddenError,\n    ApiNotFoundError,\n    ApiEndUserError,\n    ApiConflictError,\n    ApiUnprocessableError,\n    ApiPreconditionFailedError,\n    ApiUnsupportedMediaTypeError,\n    ApiCodedError,\n} from '../errors/ApiError';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { FailureClassifier } from './FailureClassifier';\n\n/**\n * The webpieces built-in {@link FailureClassifier} — the terminal tier, used when no app default and\n * no per-apiClass classifier claims an error. It is the SINGLE SOURCE OF TRUTH for the historical\n * `LogApiCall.isUserError` behavior (which now delegates here), so the classification lives in one\n * place.\n *\n * The question is \"are things WORKING?\", NOT \"was it an HTTP 4xx vs 5xx\" — the two differ (see 408).\n * Classification is by portable Error TYPE, never by transport: this runs over in-process calls,\n * pubsub/queue handlers, and HTTP through one code path and only ever sees a thrown Error. The API\n * classes are portable error types that travel with the throw anywhere, so matching the TYPE works\n * with or without any HTTP in the picture.\n *\n * SERVER — a healthy server correctly rejecting a CLIENT'S mistake is metrics NOISE, not a failure:\n * - ApiBadRequestError (400), ApiUnauthorizedError (401), ApiForbiddenError (403),\n *   ApiNotFoundError (404), ApiConflictError (409), ApiPreconditionFailedError (412),\n *   ApiUnsupportedMediaTypeError (415), ApiUnprocessableError (422), and an ApiCodedError whose\n *   `isCallerError()` is true (below 500, except 408/429) → the server is fine, the caller erred →\n *   NON-failure.\n * SERVER — something may actually be WRONG, so SURFACE it (failure):\n * - ApiRequestTimeoutError (408): a 4xx, but the client may NEVER have seen the response — deliberately\n *   absent below, so it counts as a failure. Implementation/dependency failures, ApiNotImplementedError\n *   (501), an ApiCodedError of 500+ (or 408/429), and non-API errors are failures.\n *\n * ApiEndUserError (266): ALWAYS a non-failure, server OR client — an expected \"user made a mistake\".\n * CLIENT: receiving ANY error except 266 means the outbound call FAILED → failure.\n */\nexport class WebpiecesDefaultFailureClassifier implements FailureClassifier {\n    /**\n     * Terminal tier — NEVER returns undefined (a definitive verdict is required so classification\n     * always resolves to a boolean).\n     *\n     * @returns true = failure, false = expected/non-failure\n     */\n    isFailure(error: Error, methodInfo: ApiMethodInfo): boolean {\n        // 266 is the one error that is never a failure, on either side.\n        if (error instanceof ApiEndUserError) {\n            return false;\n        }\n        // A client that RECEIVED any error (except the 266 above) made a failed call.\n        if (methodInfo.side !== 'server') {\n            return true;\n        }\n        // SERVER: only a healthy rejection of the caller's mistake is a non-failure. Note 408\n        // (ApiRequestTimeoutError) is intentionally NOT here — the client may never have seen the response.\n        const healthyRejection =\n            error instanceof ApiBadRequestError ||\n            error instanceof ApiUnauthorizedError ||\n            error instanceof ApiForbiddenError ||\n            error instanceof ApiNotFoundError ||\n            error instanceof ApiConflictError ||\n            error instanceof ApiUnprocessableError ||\n            error instanceof ApiPreconditionFailedError ||\n            error instanceof ApiUnsupportedMediaTypeError ||\n            (error instanceof ApiCodedError && error.isCallerError());\n        return !healthyRejection;\n    }\n}\n\n/** Process-wide built-in instance — stateless, so one shared instance is enough. */\nexport const WEBPIECES_DEFAULT_FAILURE_CLASSIFIER = new WebpiecesDefaultFailureClassifier();\n"]}

package/src/index.d.ts

@@ -81,6 +81,6 @@ export { RecordSerializer, SerializedMap, SerializedError } from './http/recorde
 export { Filter } from './filters/Filter';
 export type { Service } from './filters/Filter';
 export { FilterChain } from './filters/FilterChain';
-export { ApiError, ApiNotFoundError, ApiDependencyError, ApiUnavailableError, ApiDependencyTimeoutError, ApiImplementationError, ApiRateLimitedError, ApiForbiddenError, ApiRequestTimeoutError, ApiEndUserError, ApiBadRequestError, ApiUnauthorizedError, ApiDependencyBackoffError, ApiConnectionError, ApiEndpointNotFoundError, ApiErrorCodec, ApiErrorPayload, ApiErrorBoundary, } from './errors';
-export type { ApiErrorKind } from './errors';
+export { ApiError, ApiNotFoundError, ApiDependencyError, ApiUnavailableError, ApiDependencyTimeoutError, ApiImplementationError, ApiRateLimitedError, ApiForbiddenError, ApiRequestTimeoutError, ApiEndUserError, ApiBadRequestError, ApiUnauthorizedError, ApiDependencyBackoffError, ApiConnectionError, ApiEndpointNotFoundError, ApiConflictError, ApiUnprocessableError, ApiPreconditionFailedError, ApiUnsupportedMediaTypeError, ApiNotImplementedError, ApiCodedError, ApiErrorCodec, ApiErrorPayload, ApiErrorBoundary, } from './errors';
+export type { ApiErrorKind, ApiStatusCode } from './errors';
 export { ApiErrorHttpStatus } from './http/ApiErrorHttpStatus';

package/src/index.js

@@ -11,7 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getIpcEndpoints = exports.getIpcApiId = exports.isInternalApi = exports.WpIpcEndpoint = exports.WpInternal = exports.getHttpParameterDeclarations = exports.QueryParam = exports.PathParam = exports.METADATA_KEYS = exports.validateNoConflictingDecorators = exports.assertEveryWebhookEndpointRetainsRawBody = exports.assertEveryExternalEndpointDeclaresCaller = exports.assertEveryEndpointHasAuthMode = exports.getAuthMode = exports.getAuthMeta = exports.isApiPath = exports.isRawBody = exports.isFormPost = exports.getMaskSpec = exports.getEndpointKinds = exports.getEndpointKind = exports.getEndpointOptions = exports.getEndpoints = exports.getApiPath = exports.MaskLog = exports.WpAuthLocalOnly = exports.WpAuthApiKey = exports.WpAuthWebhook = exports.WpAuthSharedSecret = exports.WpAuthOidc = exports.MISSING_AUTH_DECORATOR_FIX = exports.rolesRequired = exports.WpAuthJwt = exports.WpAuthPublic = exports.Endpoint = exports.ApiPath = exports.GCP_LOG_BUDGET_BYTES = exports.MAX_GCP_LOG_BYTES = exports.LogChunkInfo = exports.LogChunkerImpl = exports.LogChunker = exports.LogManager = exports.ConsoleLoggerFactory = exports.ConsoleLogger = exports.DESIGN_METADATA_KEYS = exports.isDocumentDesign = exports.DocumentDesign = exports.ContextTuple = exports.ContextKey = exports.toError = void 0;
 exports.getEndpointCaller = exports.isExternalSystemKind = exports.ExternalCaller = exports.DEFAULT_CALLER_KIND = exports.EXTERNAL_SYSTEM_KINDS = exports.getQueueName = exports.assertPubSubConventions = exports.assertApiKind = exports.getApiKind = exports.ENDPOINT_KINDS_BY_API_KIND = exports.Queue = exports.PubSub = exports.Rpc = exports.AuthMeta = exports.DtoSchemaBuilder = exports.DtoValidationFailure = exports.ApiJsonSchema = exports.WpResponseDto = exports.WpDtoFieldMetadata = exports.WpDtoMapFieldOptions = exports.WpMcpHeader = exports.WpDtoFieldOptions = exports.WpDtoField = exports.WpDto = exports.getWpMcpAuthJwt = exports.WpMcpJwtAuthMetadata = exports.WpMcpAuthJwt = exports.getWpMcpTools = exports.WpMcpToolMetadata = exports.WpMcpToolHints = exports.WpMcpTool = exports.getStreamingEndpoint = exports.WpStream = exports.StreamWriter = exports.StreamTransportError = exports.StreamEventValidator = exports.StreamingEndpointMetadata = exports.StreamEnvelope = exports.StreamCorrelation = exports.HttpParameterDeclaration = exports.HttpParameterBinding = exports.HttpContractMapper = exports.BoundHttpRequest = exports.RouteMetadataFactory = exports.RouteMetadata = exports.IPC_METADATA_KEYS = exports.assertNotInternalApi = exports.assertInternalApi = exports.getIpcMaskSpec = exports.getIpcEndpointKind = void 0;
 exports.Filter = exports.SerializedError = exports.SerializedMap = exports.RecordSerializer = exports.getDoNotRecordFields = exports.DoNotRecord = exports.RecordedTestCase = exports.RecordedError = exports.RecordedEndpoint = exports.RecorderKeys = exports.ApiMethodInfo = exports.LOG_API_CALL_LOGGER_NAME = exports.ApiCallLogNameImpl = exports.ApiCallLogName = exports.ApiCallInfo = exports.MaskSpec = exports.LogApiCallImpl = exports.ContextMgr = exports.DestinationTrust = exports.WebpiecesCoreHeaders = exports.templateDeriver = exports.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER = exports.WebpiecesDefaultFailureClassifier = exports.KeyedFailureClassifier = exports.HttpResponseDto = exports.HttpResponseStatus = exports.HttpHeader = exports.RuntimeLocality = exports.ServiceInfo = exports.ApiCallTimeoutError = exports.CallContext = exports.CallDeadline = exports.CallRegistry = exports.ClientRegistry = exports.HeaderRegistry = exports.DateTimeUtil = exports.TimeUtil = exports.DateUtil = exports.InstantUtil = exports.NetworkRejectClassifier = 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.SECRETS = exports.Secrets = void 0;
-exports.ApiErrorHttpStatus = exports.ApiErrorBoundary = exports.ApiErrorPayload = exports.ApiErrorCodec = exports.ApiEndpointNotFoundError = exports.ApiConnectionError = exports.ApiDependencyBackoffError = exports.ApiUnauthorizedError = exports.ApiBadRequestError = exports.ApiEndUserError = exports.ApiRequestTimeoutError = exports.ApiForbiddenError = exports.ApiRateLimitedError = exports.ApiImplementationError = exports.ApiDependencyTimeoutError = exports.ApiUnavailableError = exports.ApiDependencyError = exports.ApiNotFoundError = exports.ApiError = exports.FilterChain = void 0;
+exports.ApiErrorHttpStatus = exports.ApiErrorBoundary = exports.ApiErrorPayload = exports.ApiErrorCodec = exports.ApiCodedError = exports.ApiNotImplementedError = exports.ApiUnsupportedMediaTypeError = exports.ApiPreconditionFailedError = exports.ApiUnprocessableError = exports.ApiConflictError = exports.ApiEndpointNotFoundError = exports.ApiConnectionError = exports.ApiDependencyBackoffError = exports.ApiUnauthorizedError = exports.ApiBadRequestError = exports.ApiEndUserError = exports.ApiRequestTimeoutError = exports.ApiForbiddenError = exports.ApiRateLimitedError = exports.ApiImplementationError = exports.ApiDependencyTimeoutError = exports.ApiUnavailableError = exports.ApiDependencyError = exports.ApiNotFoundError = exports.ApiError = exports.FilterChain = void 0;
 var errorUtils_1 = require("./lib/errorUtils");
 Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return errorUtils_1.toError; } });
 var ContextKey_1 = require("./ContextKey");
@@ -276,6 +276,12 @@ Object.defineProperty(exports, "ApiUnauthorizedError", { enumerable: true, get:
 Object.defineProperty(exports, "ApiDependencyBackoffError", { enumerable: true, get: function () { return errors_2.ApiDependencyBackoffError; } });
 Object.defineProperty(exports, "ApiConnectionError", { enumerable: true, get: function () { return errors_2.ApiConnectionError; } });
 Object.defineProperty(exports, "ApiEndpointNotFoundError", { enumerable: true, get: function () { return errors_2.ApiEndpointNotFoundError; } });
+Object.defineProperty(exports, "ApiConflictError", { enumerable: true, get: function () { return errors_2.ApiConflictError; } });
+Object.defineProperty(exports, "ApiUnprocessableError", { enumerable: true, get: function () { return errors_2.ApiUnprocessableError; } });
+Object.defineProperty(exports, "ApiPreconditionFailedError", { enumerable: true, get: function () { return errors_2.ApiPreconditionFailedError; } });
+Object.defineProperty(exports, "ApiUnsupportedMediaTypeError", { enumerable: true, get: function () { return errors_2.ApiUnsupportedMediaTypeError; } });
+Object.defineProperty(exports, "ApiNotImplementedError", { enumerable: true, get: function () { return errors_2.ApiNotImplementedError; } });
+Object.defineProperty(exports, "ApiCodedError", { enumerable: true, get: function () { return errors_2.ApiCodedError; } });
 Object.defineProperty(exports, "ApiErrorCodec", { enumerable: true, get: function () { return errors_2.ApiErrorCodec; } });
 Object.defineProperty(exports, "ApiErrorPayload", { enumerable: true, get: function () { return errors_2.ApiErrorPayload; } });
 Object.defineProperty(exports, "ApiErrorBoundary", { enumerable: true, get: function () { return errors_2.ApiErrorBoundary; } });

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @webpieces/core-util\n *\n * Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n *\n * @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport type {\n    AnyContextKey,\n    AnyTrustedContextKey,\n    AnyUntrustedContextKey,\n    Trust,\n} from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\nexport {\n    LogChunker,\n    LogChunkerImpl,\n    LogChunkInfo,\n    MAX_GCP_LOG_BYTES,\n    GCP_LOG_BUDGET_BYTES,\n} from './logging/LogChunker';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the API error taxonomy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n    ApiPath,\n    Endpoint,\n    // Auth mode decorators (clean service-to-service + user JWT model)\n    WpAuthPublic,\n    WpAuthJwt,\n    rolesRequired,\n    MISSING_AUTH_DECORATOR_FIX,\n    WpAuthOidc,\n    WpAuthSharedSecret,\n    WpAuthWebhook,\n    WpAuthApiKey,\n    WpAuthLocalOnly,\n    MaskLog,\n    getApiPath,\n    getEndpoints,\n    getEndpointOptions,\n    getEndpointKind,\n    getEndpointKinds,\n    getMaskSpec,\n    isFormPost,\n    isRawBody,\n    isApiPath,\n    getAuthMeta,\n    getAuthMode,\n    assertEveryEndpointHasAuthMode,\n    assertEveryExternalEndpointDeclaresCaller,\n    assertEveryWebhookEndpointRetainsRawBody,\n    validateNoConflictingDecorators,\n    METADATA_KEYS,\n} from './http/decorators';\nexport {\n    PathParam,\n    QueryParam,\n    getHttpParameterDeclarations,\n} from './http/http-parameter-decorators';\nexport {\n    WpInternal,\n    WpIpcEndpoint,\n    isInternalApi,\n    getIpcApiId,\n    getIpcEndpoints,\n    getIpcEndpointKind,\n    getIpcMaskSpec,\n    assertInternalApi,\n    assertNotInternalApi,\n    IPC_METADATA_KEYS,\n} from './ipc/IpcDecorators';\nexport type { IpcApiType, IpcEndpointKind, IpcEndpointOptions } from './ipc/IpcDecorators';\n// The runtime representation of ONE route (split out of decorators.ts for file size only).\nexport { RouteMetadata } from './http/RouteMetadata';\nexport { RouteMetadataFactory } from './http/RouteMetadataFactory';\nexport {\n    BoundHttpRequest,\n    HttpContractMapper,\n    HttpParameterBinding,\n    HttpParameterDeclaration,\n} from './http/HttpContract';\nexport {\n    StreamCorrelation,\n    StreamEnvelope,\n    StreamingEndpointMetadata,\n    StreamEventValidator,\n    StreamTransportError,\n    StreamWriter,\n    WpStream,\n    getStreamingEndpoint,\n} from './http/StreamingContract';\nexport type {\n    RequestStream,\n    ResponseStream,\n    StreamEnvelopeKind,\n    StreamFailureOptions,\n} from './http/StreamingContract';\nexport type {\n    ContractHttpMethod,\n    EndpointResponseType,\n    HttpParameterSource,\n    HttpParameterValueType,\n} from './http/HttpContract';\nexport type { EndpointKind, EndpointOptions, ExternalEndpointOptions } from './http/decorators';\nexport { WpMcpTool, WpMcpToolHints, WpMcpToolMetadata, getWpMcpTools } from './mcp/McpMetadata';\nexport type { WpMcpMethodDecorator, WpMcpToolOptions } from './mcp/McpMetadata';\nexport { WpMcpAuthJwt, WpMcpJwtAuthMetadata, getWpMcpAuthJwt } from './mcp/McpAuthMetadata';\nexport {\n    WpDto,\n    WpDtoField,\n    WpDtoFieldOptions,\n    WpMcpHeader,\n    WpDtoMapFieldOptions,\n    WpDtoFieldMetadata,\n    WpResponseDto,\n    ApiJsonSchema,\n    DtoValidationFailure,\n    DtoSchemaBuilder,\n} from './mcp/DtoSchema';\nexport type { DtoClass, DtoElementType, DtoValue } from './mcp/DtoSchema';\n// The TYPE layer of the auth surface — likewise split out of decorators.ts for file size only.\nexport { AuthMeta } from './http/auth-mode';\nexport type {\n    AuthMode,\n    ApiKeyCredential,\n    ApiKeyCredentials,\n    JwtRoles,\n    JwtRequirement,\n} from './http/auth-mode';\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming. Split out of decorators.ts for file size only;\n// one-way dependency api-kind -> decorators, and the barrel keeps the surface identical.\nexport {\n    Rpc,\n    PubSub,\n    Queue,\n    ENDPOINT_KINDS_BY_API_KIND,\n    getApiKind,\n    assertApiKind,\n    assertPubSubConventions,\n    getQueueName,\n} from './http/api-kind';\nexport type { ApiKind } from './http/api-kind';\n// WHO calls an `external` endpoint — the caller declaration @Endpoint(..., 'external', {calledBy})\n// requires, and the reader for it.\nexport {\n    EXTERNAL_SYSTEM_KINDS,\n    DEFAULT_CALLER_KIND,\n    ExternalCaller,\n    isExternalSystemKind,\n    getEndpointCaller,\n} from './http/external-caller';\nexport type { ExternalSystemKind } from './http/external-caller';\n// Client-side shared-secret store (the value THIS service sends per @WpAuthSharedSecret key).\nexport { Secrets, SECRETS } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// Authentication subtype constants.\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 './errors';\n\nexport { NetworkRejectClassifier } from './http/networkReject';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n    InstantDto,\n    DateDto,\n    TimeDto,\n    DateTimeDto,\n    InstantUtil,\n    DateUtil,\n    TimeUtil,\n    DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport { CallRegistry } from './http/CallRegistry';\nexport { CallDeadline } from './http/CallDeadline';\nexport { CallContext } from './http/CallStrategy';\nexport type { Attempt, CallStrategy } from './http/CallStrategy';\nexport { ApiCallTimeoutError } from './http/ApiCallTimeoutError';\nexport type { ServiceUrlDeriver } from './http/ClientRegistry';\n\n// \"What service am I\" — set once at startup, read by the logging backends and by\n// RequestContextHeaders (to stamp requestIdSource on ids this service mints).\nexport { ServiceInfo } from './http/ServiceInfo';\n// \"Where am I running\" — declared once at startup (setupRuntime, from RuntimeSetupOptions.locality).\n// The ONE input to @WpAuthLocalOnly enforcement. Undeclared reads as DEPLOYED (fail safe).\nexport { RuntimeLocality } from './http/RuntimeLocality';\nexport type { Locality } from './http/RuntimeLocality';\n// The ENTIRE HTTP response as pure data — the ONE form both transports (express, fetch) are\n// normalised into, so an ErrorTranslators implementation is written once and serves both.\nexport { HttpHeader, HttpResponseStatus, HttpResponseDto } from './http/HttpResponseDto';\n// Pluggable, bidirectional error translation (app exception <-> the WHOLE response). Set on\n// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.\nexport type { ErrorTranslators } from './http/ErrorTranslators';\n// Pluggable per-client failure classification (is a thrown API-call error a real failure or an\n// expected non-failure?). Registered on ClientRegistry at startup; consulted by LogApiCall.\nexport type { FailureClassifier } from './http/FailureClassifier';\nexport { KeyedFailureClassifier } from './http/FailureClassifier';\nexport {\n    WebpiecesDefaultFailureClassifier,\n    WEBPIECES_DEFAULT_FAILURE_CLASSIFIER,\n} from './http/WebpiecesDefaultFailureClassifier';\nexport { templateDeriver } from './http/templateDeriver';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\n\n// The OUTBOUND half of the trust model: whether a TRUSTED context key may ride to the endpoint being\n// called. Built ONLY from the destination endpoint's AuthMode — see the class doc.\nexport { DestinationTrust } from './http/DestinationTrust';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above). NOT a singleton: construct one per environment\n// with that environment's ApiCallContext — `new LogApiCallImpl(new RequestContextApiCallContext())`\n// on node, `new LogApiCallImpl(new BrowserApiCallContext())` in a browser.\nexport { LogApiCallImpl } from './http/LogApiCall';\n\n// Opt-in field masking for the LogApiCall log path — declare per-api sensitive fields so secrets\n// (OAuth refresh tokens, id-token JWTs) are masked in the logs while the real value stays on the wire.\nexport { MaskSpec } from './http/LogFieldMask';\nexport type { MaskMode } from './http/LogFieldMask';\n\n// The structured `api` tag + the context-writer seam LogApiCall stamps through. The Node\n// RequestContext-backed impl lives in @webpieces/core-context, the browser one in\n// @webpieces/http-client-browser; each is CONSTRUCTED by its package, never installed globally.\nexport { ApiCallInfo } from './http/ApiCallInfo';\nexport type { ApiType, ApiResult } from './http/ApiCallInfo';\n// Console-render bridge: turns LogApiCall's [LogApiCall] bracket into [API.{side}.{phase}] locally.\nexport {\n    ApiCallLogName,\n    ApiCallLogNameImpl,\n    LOG_API_CALL_LOGGER_NAME,\n} from './http/ApiCallLogName';\nexport { ApiMethodInfo } from './http/ApiMethodInfo';\nexport type { ApiSide } from './http/ApiMethodInfo';\nexport type { ApiCallContext } from './http/ApiCallContext';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport {\n    RecordedEndpoint,\n    RecordedError,\n    RecordedTestCase,\n} from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n\n// ---------------------------------------------------------------------------------------------\n// Filter-chain primitives, shared by BOTH chains: the inbound server chain\n// (`Filter<MethodMeta, WpResponse<unknown>>`, @webpieces/http-routing) and the outbound client\n// chain (`Filter<ClientRequest, Response>`, @webpieces/http-client-core). Declared once, here, in\n// the package both depend on — see the class doc for why a second pair would be a shim.\nexport { Filter } from './filters/Filter';\nexport type { Service } from './filters/Filter';\nexport { FilterChain } from './filters/FilterChain';\n\nexport {\n    ApiError,\n    ApiNotFoundError,\n    ApiDependencyError,\n    ApiUnavailableError,\n    ApiDependencyTimeoutError,\n    ApiImplementationError,\n    ApiRateLimitedError,\n    ApiForbiddenError,\n    ApiRequestTimeoutError,\n    ApiEndUserError,\n    ApiBadRequestError,\n    ApiUnauthorizedError,\n    ApiDependencyBackoffError,\n    ApiConnectionError,\n    ApiEndpointNotFoundError,\n    ApiErrorCodec,\n    ApiErrorPayload,\n    ApiErrorBoundary,\n} from './errors';\nexport type { ApiErrorKind } from './errors';\nexport { ApiErrorHttpStatus } from './http/ApiErrorHttpStatus';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @webpieces/core-util\n *\n * Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n *\n * @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport type {\n    AnyContextKey,\n    AnyTrustedContextKey,\n    AnyUntrustedContextKey,\n    Trust,\n} from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\nexport {\n    LogChunker,\n    LogChunkerImpl,\n    LogChunkInfo,\n    MAX_GCP_LOG_BYTES,\n    GCP_LOG_BUDGET_BYTES,\n} from './logging/LogChunker';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the API error taxonomy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n    ApiPath,\n    Endpoint,\n    // Auth mode decorators (clean service-to-service + user JWT model)\n    WpAuthPublic,\n    WpAuthJwt,\n    rolesRequired,\n    MISSING_AUTH_DECORATOR_FIX,\n    WpAuthOidc,\n    WpAuthSharedSecret,\n    WpAuthWebhook,\n    WpAuthApiKey,\n    WpAuthLocalOnly,\n    MaskLog,\n    getApiPath,\n    getEndpoints,\n    getEndpointOptions,\n    getEndpointKind,\n    getEndpointKinds,\n    getMaskSpec,\n    isFormPost,\n    isRawBody,\n    isApiPath,\n    getAuthMeta,\n    getAuthMode,\n    assertEveryEndpointHasAuthMode,\n    assertEveryExternalEndpointDeclaresCaller,\n    assertEveryWebhookEndpointRetainsRawBody,\n    validateNoConflictingDecorators,\n    METADATA_KEYS,\n} from './http/decorators';\nexport {\n    PathParam,\n    QueryParam,\n    getHttpParameterDeclarations,\n} from './http/http-parameter-decorators';\nexport {\n    WpInternal,\n    WpIpcEndpoint,\n    isInternalApi,\n    getIpcApiId,\n    getIpcEndpoints,\n    getIpcEndpointKind,\n    getIpcMaskSpec,\n    assertInternalApi,\n    assertNotInternalApi,\n    IPC_METADATA_KEYS,\n} from './ipc/IpcDecorators';\nexport type { IpcApiType, IpcEndpointKind, IpcEndpointOptions } from './ipc/IpcDecorators';\n// The runtime representation of ONE route (split out of decorators.ts for file size only).\nexport { RouteMetadata } from './http/RouteMetadata';\nexport { RouteMetadataFactory } from './http/RouteMetadataFactory';\nexport {\n    BoundHttpRequest,\n    HttpContractMapper,\n    HttpParameterBinding,\n    HttpParameterDeclaration,\n} from './http/HttpContract';\nexport {\n    StreamCorrelation,\n    StreamEnvelope,\n    StreamingEndpointMetadata,\n    StreamEventValidator,\n    StreamTransportError,\n    StreamWriter,\n    WpStream,\n    getStreamingEndpoint,\n} from './http/StreamingContract';\nexport type {\n    RequestStream,\n    ResponseStream,\n    StreamEnvelopeKind,\n    StreamFailureOptions,\n} from './http/StreamingContract';\nexport type {\n    ContractHttpMethod,\n    EndpointResponseType,\n    HttpParameterSource,\n    HttpParameterValueType,\n} from './http/HttpContract';\nexport type { EndpointKind, EndpointOptions, ExternalEndpointOptions } from './http/decorators';\nexport { WpMcpTool, WpMcpToolHints, WpMcpToolMetadata, getWpMcpTools } from './mcp/McpMetadata';\nexport type { WpMcpMethodDecorator, WpMcpToolOptions } from './mcp/McpMetadata';\nexport { WpMcpAuthJwt, WpMcpJwtAuthMetadata, getWpMcpAuthJwt } from './mcp/McpAuthMetadata';\nexport {\n    WpDto,\n    WpDtoField,\n    WpDtoFieldOptions,\n    WpMcpHeader,\n    WpDtoMapFieldOptions,\n    WpDtoFieldMetadata,\n    WpResponseDto,\n    ApiJsonSchema,\n    DtoValidationFailure,\n    DtoSchemaBuilder,\n} from './mcp/DtoSchema';\nexport type { DtoClass, DtoElementType, DtoValue } from './mcp/DtoSchema';\n// The TYPE layer of the auth surface — likewise split out of decorators.ts for file size only.\nexport { AuthMeta } from './http/auth-mode';\nexport type {\n    AuthMode,\n    ApiKeyCredential,\n    ApiKeyCredentials,\n    JwtRoles,\n    JwtRequirement,\n} from './http/auth-mode';\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming. Split out of decorators.ts for file size only;\n// one-way dependency api-kind -> decorators, and the barrel keeps the surface identical.\nexport {\n    Rpc,\n    PubSub,\n    Queue,\n    ENDPOINT_KINDS_BY_API_KIND,\n    getApiKind,\n    assertApiKind,\n    assertPubSubConventions,\n    getQueueName,\n} from './http/api-kind';\nexport type { ApiKind } from './http/api-kind';\n// WHO calls an `external` endpoint — the caller declaration @Endpoint(..., 'external', {calledBy})\n// requires, and the reader for it.\nexport {\n    EXTERNAL_SYSTEM_KINDS,\n    DEFAULT_CALLER_KIND,\n    ExternalCaller,\n    isExternalSystemKind,\n    getEndpointCaller,\n} from './http/external-caller';\nexport type { ExternalSystemKind } from './http/external-caller';\n// Client-side shared-secret store (the value THIS service sends per @WpAuthSharedSecret key).\nexport { Secrets, SECRETS } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// Authentication subtype constants.\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 './errors';\n\nexport { NetworkRejectClassifier } from './http/networkReject';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n    InstantDto,\n    DateDto,\n    TimeDto,\n    DateTimeDto,\n    InstantUtil,\n    DateUtil,\n    TimeUtil,\n    DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport { CallRegistry } from './http/CallRegistry';\nexport { CallDeadline } from './http/CallDeadline';\nexport { CallContext } from './http/CallStrategy';\nexport type { Attempt, CallStrategy } from './http/CallStrategy';\nexport { ApiCallTimeoutError } from './http/ApiCallTimeoutError';\nexport type { ServiceUrlDeriver } from './http/ClientRegistry';\n\n// \"What service am I\" — set once at startup, read by the logging backends and by\n// RequestContextHeaders (to stamp requestIdSource on ids this service mints).\nexport { ServiceInfo } from './http/ServiceInfo';\n// \"Where am I running\" — declared once at startup (setupRuntime, from RuntimeSetupOptions.locality).\n// The ONE input to @WpAuthLocalOnly enforcement. Undeclared reads as DEPLOYED (fail safe).\nexport { RuntimeLocality } from './http/RuntimeLocality';\nexport type { Locality } from './http/RuntimeLocality';\n// The ENTIRE HTTP response as pure data — the ONE form both transports (express, fetch) are\n// normalised into, so an ErrorTranslators implementation is written once and serves both.\nexport { HttpHeader, HttpResponseStatus, HttpResponseDto } from './http/HttpResponseDto';\n// Pluggable, bidirectional error translation (app exception <-> the WHOLE response). Set on\n// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.\nexport type { ErrorTranslators } from './http/ErrorTranslators';\n// Pluggable per-client failure classification (is a thrown API-call error a real failure or an\n// expected non-failure?). Registered on ClientRegistry at startup; consulted by LogApiCall.\nexport type { FailureClassifier } from './http/FailureClassifier';\nexport { KeyedFailureClassifier } from './http/FailureClassifier';\nexport {\n    WebpiecesDefaultFailureClassifier,\n    WEBPIECES_DEFAULT_FAILURE_CLASSIFIER,\n} from './http/WebpiecesDefaultFailureClassifier';\nexport { templateDeriver } from './http/templateDeriver';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\n\n// The OUTBOUND half of the trust model: whether a TRUSTED context key may ride to the endpoint being\n// called. Built ONLY from the destination endpoint's AuthMode — see the class doc.\nexport { DestinationTrust } from './http/DestinationTrust';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above). NOT a singleton: construct one per environment\n// with that environment's ApiCallContext — `new LogApiCallImpl(new RequestContextApiCallContext())`\n// on node, `new LogApiCallImpl(new BrowserApiCallContext())` in a browser.\nexport { LogApiCallImpl } from './http/LogApiCall';\n\n// Opt-in field masking for the LogApiCall log path — declare per-api sensitive fields so secrets\n// (OAuth refresh tokens, id-token JWTs) are masked in the logs while the real value stays on the wire.\nexport { MaskSpec } from './http/LogFieldMask';\nexport type { MaskMode } from './http/LogFieldMask';\n\n// The structured `api` tag + the context-writer seam LogApiCall stamps through. The Node\n// RequestContext-backed impl lives in @webpieces/core-context, the browser one in\n// @webpieces/http-client-browser; each is CONSTRUCTED by its package, never installed globally.\nexport { ApiCallInfo } from './http/ApiCallInfo';\nexport type { ApiType, ApiResult } from './http/ApiCallInfo';\n// Console-render bridge: turns LogApiCall's [LogApiCall] bracket into [API.{side}.{phase}] locally.\nexport {\n    ApiCallLogName,\n    ApiCallLogNameImpl,\n    LOG_API_CALL_LOGGER_NAME,\n} from './http/ApiCallLogName';\nexport { ApiMethodInfo } from './http/ApiMethodInfo';\nexport type { ApiSide } from './http/ApiMethodInfo';\nexport type { ApiCallContext } from './http/ApiCallContext';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport {\n    RecordedEndpoint,\n    RecordedError,\n    RecordedTestCase,\n} from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n\n// ---------------------------------------------------------------------------------------------\n// Filter-chain primitives, shared by BOTH chains: the inbound server chain\n// (`Filter<MethodMeta, WpResponse<unknown>>`, @webpieces/http-routing) and the outbound client\n// chain (`Filter<ClientRequest, Response>`, @webpieces/http-client-core). Declared once, here, in\n// the package both depend on — see the class doc for why a second pair would be a shim.\nexport { Filter } from './filters/Filter';\nexport type { Service } from './filters/Filter';\nexport { FilterChain } from './filters/FilterChain';\n\nexport {\n    ApiError,\n    ApiNotFoundError,\n    ApiDependencyError,\n    ApiUnavailableError,\n    ApiDependencyTimeoutError,\n    ApiImplementationError,\n    ApiRateLimitedError,\n    ApiForbiddenError,\n    ApiRequestTimeoutError,\n    ApiEndUserError,\n    ApiBadRequestError,\n    ApiUnauthorizedError,\n    ApiDependencyBackoffError,\n    ApiConnectionError,\n    ApiEndpointNotFoundError,\n    ApiConflictError,\n    ApiUnprocessableError,\n    ApiPreconditionFailedError,\n    ApiUnsupportedMediaTypeError,\n    ApiNotImplementedError,\n    ApiCodedError,\n    ApiErrorCodec,\n    ApiErrorPayload,\n    ApiErrorBoundary,\n} from './errors';\nexport type { ApiErrorKind, ApiStatusCode } from './errors';\nexport { ApiErrorHttpStatus } from './http/ApiErrorHttpStatus';\n"]}