@webpieces/core-util 0.4.761 → 0.4.763

package/src/http/ErrorTranslators.d.ts

@@ -38,14 +38,16 @@ import { HttpResponseDto } from './HttpResponseDto';
  * guidelines.
  *
  * ```ts
+ * class OrderErrorPayload {
+ *     constructor(public message: string, public errorCode: string) {}
+ * }
+ *
  * export class OrderErrorTranslators implements ErrorTranslators {
  *     toWire(error: Error): HttpResponseDto | undefined {
  *         if (!(error instanceof OrderNotFoundError)) {
  *             return undefined;              // not mine -> webpieces default
  *         }
- *         const body = new ProtocolError();
- *         body.message = error.message;
- *         body.errorCode = 'ORDER_NOT_FOUND';
+ *         const body = new OrderErrorPayload(error.message, 'ORDER_NOT_FOUND');
  *         return new HttpResponseDto(
  *             new HttpResponseStatus(460, 'Order Not Found'),
  *             [new HttpHeader('x-order-trace', error.traceId)],

package/src/http/ErrorTranslators.js.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorTranslators.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ErrorTranslators.ts"],"names":[],"mappings":"","sourcesContent":["import { HttpResponseDto } from './HttpResponseDto';\n\n/**\n * ErrorTranslators - ONE symmetric place an app owns error translation, in BOTH directions, over the\n * WHOLE response.\n *\n * An app implements this ONCE and registers it ONCE per process via\n * {@link ClientRegistry.setErrorTranslators} — on the server AND in the browser. Its `toWire` runs on\n * the SERVER (`ExpressWrapper.handleError`) and its `fromWire` runs on every CLIENT in that process\n * (`ClientErrorTranslator.translateError`, shared by `http-client-node` and `http-client-browser`).\n * The payoff is type symmetry across the wire: the server throws `OrderNotFoundError` and the caller\n * CATCHES `OrderNotFoundError`, instead of decoding a status code by hand at every call site.\n *\n * # Both halves speak {@link HttpResponseDto}, and that is the point\n *\n * `toWire` PRODUCES exactly what `fromWire` CONSUMES. Reading the two methods against each other in\n * one file is what makes a mistake visible, which is why this is one object rather than two\n * separately-registered functions.\n *\n * # The whole response, not a status plus a body\n *\n * The previous contract could express only `(statusCode, protocolError)`, so an app could not put its\n * own trace id, `Retry-After`, `WWW-Authenticate` or a cookie on an error response. A translator now\n * returns the status code, the reason phrase, the header LIST and the body — everything.\n *\n * # `undefined` means \"not mine\"\n *\n * Either method returns `undefined` to step aside and let the webpieces default answer. There is\n * exactly ONE registered ErrorTranslators per process (a `set`, not an `add` to a list): precedence\n * between an app's own layers is the APP's to compose explicitly inside its `toWire`, rather than\n * something hidden in registration order inside the framework.\n *\n * # Not covered: 404 / unknown route\n *\n * A request that matches no route has no route context and never reaches this seam. That is\n * deliberate and out of scope.\n *\n * This is a business-logic contract (methods, not data), so it is an interface per the webpieces\n * guidelines.\n *\n * ```ts\n * export class OrderErrorTranslators implements ErrorTranslators {\n *     toWire(error: Error): HttpResponseDto | undefined {\n *         if (!(error instanceof OrderNotFoundError)) {\n *             return undefined;              // not mine -> webpieces default\n *         }\n *         const body = new ProtocolError();\n *         body.message = error.message;\n *         body.errorCode = 'ORDER_NOT_FOUND';\n *         return new HttpResponseDto(\n *             new HttpResponseStatus(460, 'Order Not Found'),\n *             [new HttpHeader('x-order-trace', error.traceId)],\n *             body,\n *         );\n *     }\n *\n *     fromWire(response: HttpResponseDto): Error | undefined {\n *         if (response.status.code !== 460) {\n *             return undefined;              // not mine -> webpieces default\n *         }\n *         return new OrderNotFoundError(String(response.body));\n *     }\n * }\n *\n * // startup, ONCE per process (server AND browser)\n * ClientRegistry.setErrorTranslators(new OrderErrorTranslators());\n * ```\n */\nexport interface ErrorTranslators {\n    /**\n     * SERVER: exception -> the ENTIRE response (status code, reason phrase, headers, body).\n     * `undefined` => this translator does not claim `error`; webpieces' default answers instead.\n     */\n    toWire(error: Error): HttpResponseDto | undefined;\n\n    /**\n     * CLIENT: the ENTIRE response -> a typed exception. Receives the SAME shape `toWire` produces,\n     * normalised from whichever transport read it. `undefined` => not claimed; webpieces' built-in\n     * status-to-type mapping answers instead.\n     */\n    fromWire(response: HttpResponseDto): Error | undefined;\n}\n"]}
+{"version":3,"file":"ErrorTranslators.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ErrorTranslators.ts"],"names":[],"mappings":"","sourcesContent":["import { HttpResponseDto } from './HttpResponseDto';\n\n/**\n * ErrorTranslators - ONE symmetric place an app owns error translation, in BOTH directions, over the\n * WHOLE response.\n *\n * An app implements this ONCE and registers it ONCE per process via\n * {@link ClientRegistry.setErrorTranslators} — on the server AND in the browser. Its `toWire` runs on\n * the SERVER (`ExpressWrapper.handleError`) and its `fromWire` runs on every CLIENT in that process\n * (`ClientErrorTranslator.translateError`, shared by `http-client-node` and `http-client-browser`).\n * The payoff is type symmetry across the wire: the server throws `OrderNotFoundError` and the caller\n * CATCHES `OrderNotFoundError`, instead of decoding a status code by hand at every call site.\n *\n * # Both halves speak {@link HttpResponseDto}, and that is the point\n *\n * `toWire` PRODUCES exactly what `fromWire` CONSUMES. Reading the two methods against each other in\n * one file is what makes a mistake visible, which is why this is one object rather than two\n * separately-registered functions.\n *\n * # The whole response, not a status plus a body\n *\n * The previous contract could express only `(statusCode, protocolError)`, so an app could not put its\n * own trace id, `Retry-After`, `WWW-Authenticate` or a cookie on an error response. A translator now\n * returns the status code, the reason phrase, the header LIST and the body — everything.\n *\n * # `undefined` means \"not mine\"\n *\n * Either method returns `undefined` to step aside and let the webpieces default answer. There is\n * exactly ONE registered ErrorTranslators per process (a `set`, not an `add` to a list): precedence\n * between an app's own layers is the APP's to compose explicitly inside its `toWire`, rather than\n * something hidden in registration order inside the framework.\n *\n * # Not covered: 404 / unknown route\n *\n * A request that matches no route has no route context and never reaches this seam. That is\n * deliberate and out of scope.\n *\n * This is a business-logic contract (methods, not data), so it is an interface per the webpieces\n * guidelines.\n *\n * ```ts\n * class OrderErrorPayload {\n *     constructor(public message: string, public errorCode: string) {}\n * }\n *\n * export class OrderErrorTranslators implements ErrorTranslators {\n *     toWire(error: Error): HttpResponseDto | undefined {\n *         if (!(error instanceof OrderNotFoundError)) {\n *             return undefined;              // not mine -> webpieces default\n *         }\n *         const body = new OrderErrorPayload(error.message, 'ORDER_NOT_FOUND');\n *         return new HttpResponseDto(\n *             new HttpResponseStatus(460, 'Order Not Found'),\n *             [new HttpHeader('x-order-trace', error.traceId)],\n *             body,\n *         );\n *     }\n *\n *     fromWire(response: HttpResponseDto): Error | undefined {\n *         if (response.status.code !== 460) {\n *             return undefined;              // not mine -> webpieces default\n *         }\n *         return new OrderNotFoundError(String(response.body));\n *     }\n * }\n *\n * // startup, ONCE per process (server AND browser)\n * ClientRegistry.setErrorTranslators(new OrderErrorTranslators());\n * ```\n */\nexport interface ErrorTranslators {\n    /**\n     * SERVER: exception -> the ENTIRE response (status code, reason phrase, headers, body).\n     * `undefined` => this translator does not claim `error`; webpieces' default answers instead.\n     */\n    toWire(error: Error): HttpResponseDto | undefined;\n\n    /**\n     * CLIENT: the ENTIRE response -> a typed exception. Receives the SAME shape `toWire` produces,\n     * normalised from whichever transport read it. `undefined` => not claimed; webpieces' built-in\n     * status-to-type mapping answers instead.\n     */\n    fromWire(response: HttpResponseDto): Error | undefined;\n}\n"]}

package/src/http/HttpResponseDto.d.ts

@@ -43,7 +43,7 @@ export declare class HttpResponseStatus {
  * The whole response: status (code + reason), the header LIST, and the body.
  *
  * `body` is `unknown` because it is whatever the app chose to publish. webpieces' OWN default puts a
- * {@link ProtocolError} there, and the built-in client mapping reads it back as one — but an app that
+ * {@link ApiErrorPayload} there, and the built-in client mapping reads it back as one — but an app that
  * owns the whole response owns the body shape too, so the framework does not constrain it.
  */
 export declare class HttpResponseDto {

package/src/http/HttpResponseDto.js

@@ -54,7 +54,7 @@ exports.HttpResponseStatus = HttpResponseStatus;
  * The whole response: status (code + reason), the header LIST, and the body.
  *
  * `body` is `unknown` because it is whatever the app chose to publish. webpieces' OWN default puts a
- * {@link ProtocolError} there, and the built-in client mapping reads it back as one — but an app that
+ * {@link ApiErrorPayload} there, and the built-in client mapping reads it back as one — but an app that
  * owns the whole response owns the body shape too, so the framework does not constrain it.
  */
 class HttpResponseDto {
@@ -62,7 +62,7 @@ class HttpResponseDto {
     headers;
     body;
     constructor(status, headers, 
-    // webpieces-disable no-any-unknown -- the app owns the body shape when it owns the response; webpieces' own default puts a ProtocolError here, an app puts whatever it publishes
+    // webpieces-disable no-any-unknown -- the app owns the body shape when it owns the response; webpieces' own default puts a ApiErrorPayload here, an app puts whatever it publishes
     body) {
         this.status = status;
         this.headers = headers;

package/src/http/HttpResponseDto.js.map

@@ -1 +1 @@
-{"version":3,"file":"HttpResponseDto.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HttpResponseDto.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAa,UAAU;IAEC;IACA;IAFpB,YACoB,IAAY,EACZ,KAAa;QADb,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAQ;IAC9B,CAAC;CACP;AALD,gCAKC;AAED,4FAA4F;AAC5F,MAAa,kBAAkB;IAEP;IACA;IAFpB,YACoB,IAAY,EACZ,MAAc;QADd,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;IAC/B,CAAC;CACP;AALD,gDAKC;AAED;;;;;;GAMG;AACH,MAAa,eAAe;IAEJ;IACA;IAEA;IAJpB,YACoB,MAA0B,EAC1B,OAA8B;IAC9C,iLAAiL;IACjK,IAAa;QAHb,WAAM,GAAN,MAAM,CAAoB;QAC1B,YAAO,GAAP,OAAO,CAAuB;QAE9B,SAAI,GAAJ,IAAI,CAAS;IAC9B,CAAC;CACP;AAPD,0CAOC","sourcesContent":["/**\n * HttpResponseDto - the ENTIRE HTTP response, as pure data, in the ONE form webpieces speaks.\n *\n * Modelled on java webpieces' `http/http1_1-parser/.../api/dto/` (`HttpPayload` -> `HttpMessage` ->\n * `HttpResponse` -> `HttpResponseStatusLine` -> `HttpResponseStatus`), flattened to the KISS subset\n * this framework actually needs.\n *\n * # Why a DTO at all, instead of handing an app express's `res` or fetch's `Response`\n *\n * Node/express and browser fetch model a response completely differently, and an\n * {@link ErrorTranslators} implementation is registered ONCE and serves BOTH — the server writing a\n * response and every client in the process reading one. So neither transport's object can be the\n * currency. webpieces normalises both into this DTO at its own boundary, and the app only ever sees\n * this. One form, both transports, both directions.\n *\n * # The two properties copied from java deliberately\n *\n * - **Headers are a LIST of `{name, value}`, not a Map.** HTTP permits repeats (`Set-Cookie` is the\n *   everyday one) and a Map silently drops all but the last. The REQUEST side of webpieces-ts\n *   already respects this (`readExpressHeaders` returns `Map<string, string[]>`), so the response\n *   side must not be the half that loses data.\n * - **Status is `{ code, reason }`, not a bare number.** The reason phrase is part of the response\n *   and an app may want its own ('Order Not Found' beside a 460).\n *\n * `HttpVersion` from the java DTO is deliberately OMITTED: express and fetch each own the version,\n * and no app decision depends on it.\n *\n * Pure data, so these are CLASSES with explicit constructors (webpieces guideline: data => classes),\n * and they live in core-util so the identical types reach a node server and a browser bundle.\n */\nexport class HttpHeader {\n    constructor(\n        public readonly name: string,\n        public readonly value: string,\n    ) {}\n}\n\n/** The status line's status: the numeric code AND the reason phrase that goes beside it. */\nexport class HttpResponseStatus {\n    constructor(\n        public readonly code: number,\n        public readonly reason: string,\n    ) {}\n}\n\n/**\n * The whole response: status (code + reason), the header LIST, and the body.\n *\n * `body` is `unknown` because it is whatever the app chose to publish. webpieces' OWN default puts a\n * {@link ProtocolError} there, and the built-in client mapping reads it back as one — but an app that\n * owns the whole response owns the body shape too, so the framework does not constrain it.\n */\nexport class HttpResponseDto {\n    constructor(\n        public readonly status: HttpResponseStatus,\n        public readonly headers: readonly HttpHeader[],\n        // webpieces-disable no-any-unknown -- the app owns the body shape when it owns the response; webpieces' own default puts a ProtocolError here, an app puts whatever it publishes\n        public readonly body: unknown,\n    ) {}\n}\n"]}
+{"version":3,"file":"HttpResponseDto.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HttpResponseDto.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAa,UAAU;IAEC;IACA;IAFpB,YACoB,IAAY,EACZ,KAAa;QADb,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAQ;IAC9B,CAAC;CACP;AALD,gCAKC;AAED,4FAA4F;AAC5F,MAAa,kBAAkB;IAEP;IACA;IAFpB,YACoB,IAAY,EACZ,MAAc;QADd,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;IAC/B,CAAC;CACP;AALD,gDAKC;AAED;;;;;;GAMG;AACH,MAAa,eAAe;IAEJ;IACA;IAEA;IAJpB,YACoB,MAA0B,EAC1B,OAA8B;IAC9C,mLAAmL;IACnK,IAAa;QAHb,WAAM,GAAN,MAAM,CAAoB;QAC1B,YAAO,GAAP,OAAO,CAAuB;QAE9B,SAAI,GAAJ,IAAI,CAAS;IAC9B,CAAC;CACP;AAPD,0CAOC","sourcesContent":["/**\n * HttpResponseDto - the ENTIRE HTTP response, as pure data, in the ONE form webpieces speaks.\n *\n * Modelled on java webpieces' `http/http1_1-parser/.../api/dto/` (`HttpPayload` -> `HttpMessage` ->\n * `HttpResponse` -> `HttpResponseStatusLine` -> `HttpResponseStatus`), flattened to the KISS subset\n * this framework actually needs.\n *\n * # Why a DTO at all, instead of handing an app express's `res` or fetch's `Response`\n *\n * Node/express and browser fetch model a response completely differently, and an\n * {@link ErrorTranslators} implementation is registered ONCE and serves BOTH — the server writing a\n * response and every client in the process reading one. So neither transport's object can be the\n * currency. webpieces normalises both into this DTO at its own boundary, and the app only ever sees\n * this. One form, both transports, both directions.\n *\n * # The two properties copied from java deliberately\n *\n * - **Headers are a LIST of `{name, value}`, not a Map.** HTTP permits repeats (`Set-Cookie` is the\n *   everyday one) and a Map silently drops all but the last. The REQUEST side of webpieces-ts\n *   already respects this (`readExpressHeaders` returns `Map<string, string[]>`), so the response\n *   side must not be the half that loses data.\n * - **Status is `{ code, reason }`, not a bare number.** The reason phrase is part of the response\n *   and an app may want its own ('Order Not Found' beside a 460).\n *\n * `HttpVersion` from the java DTO is deliberately OMITTED: express and fetch each own the version,\n * and no app decision depends on it.\n *\n * Pure data, so these are CLASSES with explicit constructors (webpieces guideline: data => classes),\n * and they live in core-util so the identical types reach a node server and a browser bundle.\n */\nexport class HttpHeader {\n    constructor(\n        public readonly name: string,\n        public readonly value: string,\n    ) {}\n}\n\n/** The status line's status: the numeric code AND the reason phrase that goes beside it. */\nexport class HttpResponseStatus {\n    constructor(\n        public readonly code: number,\n        public readonly reason: string,\n    ) {}\n}\n\n/**\n * The whole response: status (code + reason), the header LIST, and the body.\n *\n * `body` is `unknown` because it is whatever the app chose to publish. webpieces' OWN default puts a\n * {@link ApiErrorPayload} there, and the built-in client mapping reads it back as one — but an app that\n * owns the whole response owns the body shape too, so the framework does not constrain it.\n */\nexport class HttpResponseDto {\n    constructor(\n        public readonly status: HttpResponseStatus,\n        public readonly headers: readonly HttpHeader[],\n        // webpieces-disable no-any-unknown -- the app owns the body shape when it owns the response; webpieces' own default puts a ApiErrorPayload here, an app puts whatever it publishes\n        public readonly body: unknown,\n    ) {}\n}\n"]}

package/src/http/WebpiecesDefaultFailureClassifier.d.ts

@@ -8,18 +8,18 @@ import { FailureClassifier } from './FailureClassifier';
  *
  * The question is "are things WORKING?", NOT "was it an HTTP 4xx vs 5xx" — the two differ (see 408).
  * Classification is by portable Error TYPE, never by transport: this runs over in-process calls,
- * pubsub/queue handlers, and HTTP through one code path and only ever sees a thrown Error. The Http*
+ * pubsub/queue handlers, and HTTP through one code path and only ever sees a thrown Error. The API
  * classes are portable error types that travel with the throw anywhere, so matching the TYPE works
  * with or without any HTTP in the picture.
  *
  * SERVER — a healthy server correctly rejecting a CLIENT'S mistake is metrics NOISE, not a failure:
- * - BadRequestError (400), UnauthorizedError (401), ForbiddenError (403),
- *   NotFoundError (404) → the server is fine, the caller erred → NON-failure.
+ * - ApiBadRequestError (400), ApiUnauthorizedError (401), ApiForbiddenError (403),
+ *   ApiNotFoundError (404) → the server is fine, the caller erred → NON-failure.
  * SERVER — something may actually be WRONG, so SURFACE it (failure):
- * - RequestTimeoutError (408): a 4xx, but the client may NEVER have seen the response — deliberately
- *   absent below, so it counts as a failure. 500/502/504/598 and any non-Http Error: real failures.
+ * - 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.
  *
- * UserError (266): ALWAYS a non-failure, server OR client — an expected "user made a mistake".
+ * 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.
  */
 export declare class WebpiecesDefaultFailureClassifier implements FailureClassifier {

package/src/http/WebpiecesDefaultFailureClassifier.js

@@ -10,18 +10,18 @@ const ApiError_1 = require("../errors/ApiError");
  *
  * The question is "are things WORKING?", NOT "was it an HTTP 4xx vs 5xx" — the two differ (see 408).
  * Classification is by portable Error TYPE, never by transport: this runs over in-process calls,
- * pubsub/queue handlers, and HTTP through one code path and only ever sees a thrown Error. The Http*
+ * pubsub/queue handlers, and HTTP through one code path and only ever sees a thrown Error. The API
  * classes are portable error types that travel with the throw anywhere, so matching the TYPE works
  * with or without any HTTP in the picture.
  *
  * SERVER — a healthy server correctly rejecting a CLIENT'S mistake is metrics NOISE, not a failure:
- * - BadRequestError (400), UnauthorizedError (401), ForbiddenError (403),
- *   NotFoundError (404) → the server is fine, the caller erred → NON-failure.
+ * - ApiBadRequestError (400), ApiUnauthorizedError (401), ApiForbiddenError (403),
+ *   ApiNotFoundError (404) → the server is fine, the caller erred → NON-failure.
  * SERVER — something may actually be WRONG, so SURFACE it (failure):
- * - RequestTimeoutError (408): a 4xx, but the client may NEVER have seen the response — deliberately
- *   absent below, so it counts as a failure. 500/502/504/598 and any non-Http Error: real failures.
+ * - 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.
  *
- * UserError (266): ALWAYS a non-failure, server OR client — an expected "user made a mistake".
+ * 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.
  */
 class WebpiecesDefaultFailureClassifier {
@@ -33,7 +33,7 @@ class WebpiecesDefaultFailureClassifier {
      */
     isFailure(error, methodInfo) {
         // 266 is the one error that is never a failure, on either side.
-        if (error instanceof ApiError_1.UserError) {
+        if (error instanceof ApiError_1.ApiEndUserError) {
             return false;
         }
         // A client that RECEIVED any error (except the 266 above) made a failed call.
@@ -41,11 +41,11 @@ class WebpiecesDefaultFailureClassifier {
             return true;
         }
         // SERVER: only a healthy rejection of the caller's mistake is a non-failure. Note 408
-        // (RequestTimeoutError) is intentionally NOT here — the client may never have seen the response.
-        const healthyRejection = error instanceof ApiError_1.BadRequestError ||
-            error instanceof ApiError_1.UnauthorizedError ||
-            error instanceof ApiError_1.ForbiddenError ||
-            error instanceof ApiError_1.NotFoundError;
+        // (ApiRequestTimeoutError) is intentionally NOT here — the client may never have seen the response.
+        const healthyRejection = error instanceof ApiError_1.ApiBadRequestError ||
+            error instanceof ApiError_1.ApiUnauthorizedError ||
+            error instanceof ApiError_1.ApiForbiddenError ||
+            error instanceof ApiError_1.ApiNotFoundError;
         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,oBAAS,EAAE,CAAC;YAC7B,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,iGAAiG;QACjG,MAAM,gBAAgB,GAClB,KAAK,YAAY,0BAAe;YAChC,KAAK,YAAY,4BAAiB;YAClC,KAAK,YAAY,yBAAc;YAC/B,KAAK,YAAY,wBAAa,CAAC;QACnC,OAAO,CAAC,gBAAgB,CAAC;IAC7B,CAAC;CACJ;AAzBD,8EAyBC;AAED,oFAAoF;AACvE,QAAA,oCAAoC,GAAG,IAAI,iCAAiC,EAAE,CAAC","sourcesContent":["import {\n    BadRequestError,\n    UnauthorizedError,\n    ForbiddenError,\n    NotFoundError,\n    UserError,\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 Http*\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 * - BadRequestError (400), UnauthorizedError (401), ForbiddenError (403),\n *   NotFoundError (404) → the server is fine, the caller erred → NON-failure.\n * SERVER — something may actually be WRONG, so SURFACE it (failure):\n * - RequestTimeoutError (408): a 4xx, but the client may NEVER have seen the response — deliberately\n *   absent below, so it counts as a failure. 500/502/504/598 and any non-Http Error: real failures.\n *\n * UserError (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 UserError) {\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        // (RequestTimeoutError) is intentionally NOT here — the client may never have seen the response.\n        const healthyRejection =\n            error instanceof BadRequestError ||\n            error instanceof UnauthorizedError ||\n            error instanceof ForbiddenError ||\n            error instanceof NotFoundError;\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,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"]}

package/src/http/decorators.d.ts

@@ -300,7 +300,7 @@ export declare function WpAuthApiKey(regime: string, credentials: ApiKeyCredenti
  *
  * WHY IT IS AN AUTH MODE AND NOT A ROUTE-MODULE `if`. Apps hand-rolled this in TWO places kept in
  * sync by a comment: a route module that registered the route only locally, PLUS a
- * `if (env !== 'local') throw new ForbiddenError(...)` at the top of the handler. Neither half
+ * `if (env !== 'local') throw new ApiForbiddenError(...)` at the top of the handler. Neither half
  * was visible on the CONTRACT, so nothing reading the api — a human, a generated client, or an
  * agent — could tell this endpoint from a `@WpAuthPublic` one. Both halves are the framework's job now,
  * driven by this ONE declaration on the contract, which is where every other "who may call this"

package/src/http/decorators.js

@@ -330,7 +330,7 @@ function WpAuthApiKey(regime, credentials) {
  *
  * WHY IT IS AN AUTH MODE AND NOT A ROUTE-MODULE `if`. Apps hand-rolled this in TWO places kept in
  * sync by a comment: a route module that registered the route only locally, PLUS a
- * `if (env !== 'local') throw new ForbiddenError(...)` at the top of the handler. Neither half
+ * `if (env !== 'local') throw new ApiForbiddenError(...)` at the top of the handler. Neither half
  * was visible on the CONTRACT, so nothing reading the api — a human, a generated client, or an
  * agent — could tell this endpoint from a `@WpAuthPublic` one. Both halves are the framework's job now,
  * driven by this ONE declaration on the contract, which is where every other "who may call this"

package/src/http/decorators.js.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/decorators.ts"],"names":[],"mappings":"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","sourcesContent":["import 'reflect-metadata';\nimport { MaskSpec, MaskMode } from './LogFieldMask';\nimport {\n    DEFAULT_CALLER_KIND,\n    ENDPOINT_CALLER_KEY,\n    ExternalCaller,\n    ExternalSystemKind,\n    getEndpointCaller,\n} from './external-caller';\n// The TYPE layer these decorators attach — split out for file size only (see auth-mode.ts).\nimport { ApiKeyCredentials, AuthMeta, AuthMode, JwtRequirement } from './auth-mode';\n\n/**\n * Metadata keys for storing API routing information.\n * These keys are used by both server-side (routing) and client-side (client generation).\n */\nexport const METADATA_KEYS = {\n    API_PATH: 'webpieces:api-path',\n    ENDPOINTS: 'webpieces:endpoints',\n    AUTH_META: 'webpieces:auth-meta',\n    /** Method names carrying one of the canonical authorization decorators. */\n    AUTH_METHODS: 'webpieces:auth-methods',\n    /** 'rpc' (default, sync request/response) vs 'pubsub' (fire-and-forget cloud task). */\n    API_KIND: 'webpieces:api-kind',\n    /** Per-method Cloud Tasks queue-name override (set via @Queue). */\n    QUEUE_OVERRIDE: 'webpieces:queue-override',\n    /** Per-method @Endpoint options (e.g. formPost), parallel to ENDPOINTS. */\n    ENDPOINT_OPTIONS: 'webpieces:endpoint-options',\n    /** Per-method @Endpoint trigger kind (rpc | cloudtasks | cron | external), parallel to ENDPOINTS. */\n    ENDPOINT_KIND: 'webpieces:endpoint-kind',\n    /** Per-method declared external CALLER (only for kind 'external'), parallel to ENDPOINTS. */\n    ENDPOINT_CALLER: ENDPOINT_CALLER_KEY,\n    /** Per-method @MaskLog spec (which DTO fields the LogApiCall path masks). */\n    MASK_LOG: 'webpieces:mask-log',\n};\n\n/**\n * WHAT TRIGGERS an endpoint at runtime — the single fact that decides how the runtime architecture\n * graph draws it, and which Terraform resource must exist for it to ever fire:\n *\n *  - `rpc`        — a caller in this repo (or a browser) calls it synchronously. A direct arrow.\n *  - `cloudtasks` — a producer ENQUEUES it; Cloud Tasks delivers it later. Drawn producer → queue →\n *                   consumer, one queue node per METHOD (see {@link Queue}). Producer and consumer\n *                   being the SAME service is legal and common — the queue decouples them.\n *  - `cron`       — a scheduler fires it on a clock. Nothing in-repo calls it; drawn hanging off a\n *                   clock symbol. Backed by a Cloud Scheduler job.\n *  - `external`   — a system OUTSIDE this repo drives it (a GCP Pub/Sub push subscription, a Twilio\n *                   or Gmail webhook). Drawn as an inbound dashed arrow from that system.\n *\n * Declared PER METHOD, because one api class routinely mixes them: an admin contract can have\n * caller-driven endpoints AND a nightly cron sweep. A class-level marker cannot express that, which\n * is exactly why the graph could not tell these apart before.\n */\nexport type EndpointKind = 'rpc' | 'cloudtasks' | 'cron' | 'external';\n\n/**\n * Options for a single @Endpoint. Kept in a metadata map PARALLEL to ENDPOINTS so the existing\n * `Record<methodName, path>` shape every consumer iterates stays unchanged.\n */\nexport interface EndpointOptions {\n    /**\n     * Parse the request body as application/x-www-form-urlencoded (flat key→value) instead of JSON.\n     * For EXTERNAL webhooks (e.g. Twilio) that post form-encoded. The request DTO must be FLAT —\n     * urlencoded has no nesting (unlike JSON). Default false = JSON.\n     */\n    formPost?: boolean;\n\n    /**\n     * RETAIN the verbatim request bytes + the absolute url the sender addressed, so an\n     * {@link WpAuthWebhook} hook can verify a vendor signature over them (see `RawRequest`).\n     *\n     * Opt-in PER ENDPOINT, sitting beside `formPost` and for the same reason: the cost lands on the\n     * handful of webhook routes rather than on every request in the process. It is retention, not\n     * new buffering — the express adapter already accumulates the whole body, it simply threw it\n     * away once it had parsed a DTO.\n     *\n     * REQUIRED by `@WpAuthWebhook`, checked at wiring time (see\n     * {@link assertEveryWebhookEndpointRetainsRawBody}) rather than left to fail as a 401 in\n     * production: a hook with nothing to verify is a misconfiguration, not a bad request.\n     *\n     * Combines with `formPost` — `{ formPost: true, rawBody: true }` is the Twilio case, where the\n     * hook needs the bytes and the url while the controller still wants the flat parsed DTO.\n     */\n    rawBody?: boolean;\n}\n\n/**\n * Options for an `external` @Endpoint: everything {@link EndpointOptions} carries, PLUS a REQUIRED\n * declaration of WHO is calling. See {@link Endpoint} for why, `external-caller.ts` for identity.\n */\nexport interface ExternalEndpointOptions extends EndpointOptions {\n    /** The outside system that posts here (`'twilio'`) — the graph node IDENTITY, not display text. */\n    calledBy: string;\n    /** What that caller IS; picks the node's shape. Defaults to `'saas'` (see DEFAULT_CALLER_KIND). */\n    callerKind?: ExternalSystemKind;\n}\n\n/**\n * @ApiPath(basePath) - Class decorator that marks a class as an API definition\n * and sets the base path for all endpoints.\n *\n * Usage:\n * ```typescript\n * @ApiPath('/api/save')\n * abstract class SaveApi {\n *   @WpAuthJwt({ roles: ['admin'] })\n *   @Endpoint('/item', 'rpc')\n *   save(request: SaveRequest): Promise<SaveResponse> { ... }\n * }\n * ```\n */\nexport function ApiPath(basePath: string): ClassDecorator {\n    return (target: Function) => {\n        if (Reflect.hasMetadata('webpieces:ipc-api-id', target)) {\n            throw new Error(\n                `Class ${target.name || 'Unknown'} cannot combine @ApiPath with @WpInternal.`,\n            );\n        }\n        Reflect.defineMetadata(METADATA_KEYS.API_PATH, basePath, target);\n\n        // Initialize endpoints map if not exists\n        if (!Reflect.hasMetadata(METADATA_KEYS.ENDPOINTS, target)) {\n            Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, {}, target);\n        }\n    };\n}\n\n/**\n * @Endpoint(path, kind, options?) - Method decorator that registers a POST endpoint at the given\n * path and declares WHAT TRIGGERS it.\n *\n * All endpoints are POST-only (matching gRPC/thrift style).\n *\n * Usage:\n * ```typescript\n * @Endpoint('/item', 'rpc')\n * save(request: SaveRequest): Promise<SaveResponse> { ... }\n *\n * // enqueued by a producer, delivered later by Cloud Tasks:\n * @Endpoint('/send', 'cloudtasks')\n * send(request: SendRequest): Promise<void> { ... }\n *\n * // fired by Cloud Scheduler on a clock, called by nobody in this repo:\n * @Endpoint('/nightly', 'cron')\n * nightly(request: NightlyRequest): Promise<void> { ... }\n *\n * // EXTERNAL webhook posting application/x-www-form-urlencoded (e.g. Twilio):\n * @Endpoint('/hook', 'external', { formPost: true, calledBy: 'twilio' })\n * inbound(request: InboundRequest): Promise<InboundResponse> { ... }\n * ```\n *\n * `kind` is REQUIRED and deliberately positional: it makes every pre-existing single-argument\n * `@Endpoint('/x')` a COMPILE error rather than something a lint rule has to chase, so no endpoint\n * can slip into the runtime architecture graph with its trigger left to guesswork. See\n * {@link EndpointKind} for what each value draws and which Terraform resource backs it.\n *\n * `calledBy` is REQUIRED for `external` FOR EXACTLY THE SAME REASON, enforced by the overloads below:\n * the one box on the runtime graph whose whole job is to say who calls us from outside could only\n * restate OUR OWN contract name, because nothing in the source ever said who the caller was. This is\n * BREAKING for published consumers, intentionally — an existing `@Endpoint(p, 'external', {...})`\n * stops compiling until it names its caller. Migration is one property; see the migration note in\n * `external-caller.ts`. Non-`external` endpoints are completely unaffected.\n *\n * The path write to ENDPOINTS is UNCHANGED (every consumer iterates `[methodName, path]`); kind,\n * options and caller ride PARALLEL ENDPOINT_KIND / ENDPOINT_OPTIONS / ENDPOINT_CALLER maps.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n    path: string,\n    kind: 'external',\n    options: ExternalEndpointOptions,\n): MethodDecorator;\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n    path: string,\n    kind: Exclude<EndpointKind, 'external'>,\n    options?: EndpointOptions,\n): MethodDecorator;\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n    path: string,\n    kind: EndpointKind,\n    options: EndpointOptions = {},\n): MethodDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n\n        const endpoints: Record<string, string> =\n            Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, metadataTarget) || {};\n\n        endpoints[propertyKey as string] = path;\n\n        Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, endpoints, metadataTarget);\n\n        const kinds: Record<string, EndpointKind> =\n            Reflect.getMetadata(METADATA_KEYS.ENDPOINT_KIND, metadataTarget) || {};\n        kinds[propertyKey as string] = kind;\n        Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_KIND, kinds, metadataTarget);\n\n        const opts: Record<string, EndpointOptions> =\n            Reflect.getMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, metadataTarget) || {};\n        opts[propertyKey as string] = options;\n        Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, opts, metadataTarget);\n\n        // ONLY for 'external', mirroring how a queue name is recorded only for the kinds that HAVE\n        // a queue: a caller on an rpc endpoint would be a fact about nothing.\n        const declared = options as ExternalEndpointOptions;\n        if (\n            kind !== 'external' ||\n            typeof declared.calledBy !== 'string' ||\n            declared.calledBy === ''\n        )\n            return;\n        const callers: Record<string, ExternalCaller> =\n            Reflect.getMetadata(METADATA_KEYS.ENDPOINT_CALLER, metadataTarget) || {};\n        callers[propertyKey as string] = new ExternalCaller(\n            declared.callerKind ?? DEFAULT_CALLER_KIND,\n            declared.calledBy,\n        );\n        Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_CALLER, callers, metadataTarget);\n    };\n}\n\n/**\n * @MaskLog(fields) - declare which fields of THIS method's request/response DTOs the\n * {@link LogApiCallImpl} logging path must mask, so a secret riding on a DTO (an OAuth refresh token, an\n * id-token JWT) is never written to the logs in cleartext. The REAL value still travels on the wire\n * untouched — masking lives in the logging path only.\n *\n * ```typescript\n * @Endpoint('/account', 'rpc')\n * @MaskLog({ refreshToken: 'full', accessToken: 'last4', credential: 'full' })\n * getEmailAccount(request: GetEmailAccountRequest): Promise<GetEmailAccountResponse> { ... }\n * ```\n *\n * Matching is by field NAME at any depth (nested objects + array elements), so\n * `response.account.refreshToken` is masked. Declared on the SHARED api contract, so BOTH the client\n * `[API-client-*]` and server `[API-server-*]` lines mask it. The spec is read ONCE at route-build\n * time and rides {@link RouteMetadata.mask}, so an unmasked method pays nothing at call time.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function MaskLog(fields: Record<string, MaskMode>): MethodDecorator {\n    const spec = new MaskSpec(fields);\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n        const specs: Record<string, MaskSpec> =\n            Reflect.getMetadata(METADATA_KEYS.MASK_LOG, metadataTarget) || {};\n        specs[propertyKey as string] = spec;\n        Reflect.defineMetadata(METADATA_KEYS.MASK_LOG, specs, metadataTarget);\n    };\n}\n\n/**\n * The @MaskLog spec for one method, or undefined if the method declared none (the common case — the\n * caller then logs the DTO verbatim on the plain JSON.stringify fast path).\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpointOptions\nexport function getMaskSpec(apiClass: Function, methodName: string): MaskSpec | undefined {\n    const specs: Record<string, MaskSpec> =\n        Reflect.getMetadata(METADATA_KEYS.MASK_LOG, apiClass) || {};\n    return specs[methodName];\n}\n\n/**\n * Shared implementation for every auth decorator. Authorization is deliberately\n * method-only: a class-level default is too easy to miss when reviewing one endpoint.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nfunction defineAuthMode(mode: AuthMode): MethodDecorator {\n    const authMeta = new AuthMeta(mode);\n\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => {\n        if (propertyKey === undefined) {\n            throw new Error(\n                'Authorization decorators are method-only; annotate every @Endpoint explicitly.',\n            );\n        }\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n        if (Reflect.hasMetadata('webpieces:ipc-api-id', metadataTarget)) {\n            throw new Error(\n                `Internal API ${metadataTarget.name || 'Unknown'} cannot use HTTP authorization decorators.`,\n            );\n        }\n        validateNoConflictingDecorators(metadataTarget, propertyKey as string);\n        Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, metadataTarget, propertyKey);\n        const methods = new Set<string>(\n            Reflect.getMetadata(METADATA_KEYS.AUTH_METHODS, metadataTarget) || [],\n        );\n        methods.add(propertyKey as string);\n        Reflect.defineMetadata(METADATA_KEYS.AUTH_METHODS, [...methods], metadataTarget);\n    };\n}\n\n/**\n * @WpAuthPublic(reason) - endpoint intentionally requires no authentication.\n * The non-empty reason makes anonymous exposure an explicit review decision.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthPublic(reason: string): MethodDecorator {\n    if (typeof reason !== 'string' || reason.trim() === '') {\n        throw new Error(\n            '@WpAuthPublic requires a non-empty reason explaining why anonymous access is required.',\n        );\n    }\n    return defineAuthMode({ kind: 'public' });\n}\n\n/**\n * @WpAuthJwt(requirement) - THE user-facing JWT decorator, covering the whole user-JWT axis: the\n * compiler-enforced role decision ({@link JwtRoles}) plus app-defined fields ({@link JwtRequirement}).\n *\n * ```typescript\n * @WpAuthJwt({ roles: ['admin', 'editor'] })          // any-of\n * @WpAuthJwt({ allRolesAllowed: true, inOrg: true })  // wide + an app rule enforced by authorizeJwt\n * ```\n *\n * It absorbed the former `@Auth(requirement)` — same argument, same AuthMode, so two spellings of one\n * decision. One decorator per credential kind now: `@WpAuthPublic` / `@WpAuthJwt` / `@WpAuthOidc` /\n * `@WpAuthSharedSecret` / `@WpAuthLocalOnly`.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthJwt(requirement: JwtRequirement): MethodDecorator {\n    return defineAuthMode({ kind: 'jwt', requirement });\n}\n\n/**\n * The roles an endpoint accepts, or [] when it accepts every authenticated user. The ONE reader of\n * the {@link JwtRoles} union, so no caller has to re-derive \"does absent mean wide?\" — a question\n * whose two plausible answers is how the widest grant kept hiding behind an absent field.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getAuthMode\nexport function rolesRequired(requirement: JwtRequirement): readonly string[] {\n    return requirement.allRolesAllowed === true ? [] : requirement.roles;\n}\n\n/**\n * @WpAuthOidc(...callers) - Google OIDC service-to-service auth (Cloud Tasks delivery / cross-service\n * RPC). `callers` is an OPTIONAL app-level allow-list of caller service accounts.\n *\n * NO args = TRUST THE EDGE: accept any genuine Google-signed OIDC caller, because a PRIVATE Cloud\n * Run service's edge already gates WHO via `run.invoker` IAM (managed in terraform — one source of\n * truth, no hand-synced list in code). If the service is actually PUBLIC, the verifier logs a loud\n * warning (it can't be the gate then). Pass explicit SAs (`@WpAuthOidc('svc-a')`) only when you want\n * an additional app-level allow-list as defense-in-depth.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthOidc(...callers: string[]): MethodDecorator {\n    return defineAuthMode({ kind: 'oidc', callers });\n}\n\n/**\n * @WpAuthSharedSecret(key) - constant-time compare of an inbound header against the secret bound for\n * `key`. `key` is a LOOKUP KEY (not an env var): the server looks up its accepted {@link SharedSecrets}\n * by this key, and each client looks up the value it sends by the SAME key (see {@link Secrets}).\n * For internal callers that cannot mint OIDC tokens.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthSharedSecret(key: string): MethodDecorator {\n    return defineAuthMode({ kind: 'shared-secret', secretKey: key });\n}\n\n/**\n * @WpAuthWebhook(name) - an OUTSIDE vendor signed this request in its OWN scheme; the app's bound\n * `WebhookAuthCallback` proves it. THE mode for every signed inbound webhook — Sentry, GitHub, Stripe, Slack,\n * Twilio — none of which fits the other kinds: no vendor mints Google OIDC tokens, and none sends its\n * secret (they all send a DERIVATION over the request), so `@WpAuthPublic` was the only reachable posture\n * and `calledBy: 'sentry'` stayed a claim rather than a fact.\n *\n * ```typescript\n * @WpAuthWebhook('sentry')\n * @Endpoint('/hook/sentry/issue', 'external', { calledBy: 'sentry', rawBody: true })\n * abstract notify(request: SentryIssueHook): Promise<HookAck>;\n * ```\n *\n * `name` is a bare STRING resolved through DI in the server's container, exactly as\n * `@WpAuthOidc('gmail-push')` already is — never a function reference. An api contract is level 0: a\n * direct reference to a verifier would invert the dependency graph and drag a vendor SDK into the\n * browser bundle that imports the same contract.\n *\n * THE FRAMEWORK IMPLEMENTS NO VENDOR CRYPTO, deliberately. Every vendor ships an official validator\n * (`twilio.validateRequest`, `stripe.webhooks.constructEvent`, `@octokit/webhooks-methods`) and every\n * vendor revises its scheme (Twilio added `bodySHA256` for JSON bodies; Stripe versions its header).\n * Reimplementing five of those is signing up to track five security changelogs forever and to be\n * wrong at the moment being wrong matters. The framework hands the hook enough of the raw request to\n * call the vendor's own library — hence the REQUIRED `{ rawBody: true }` (see\n * {@link EndpointOptions.rawBody}), which is checked at wiring time.\n *\n * FAILS CLOSED: with no `WebhookAuthCallback` bound, every `@WpAuthWebhook` endpoint 401s, matching `JwtHook`.\n * Silently allowing an unverified webhook is the one default that must not exist.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthWebhook(name: string): MethodDecorator {\n    return defineAuthMode({ kind: 'webhook', name });\n}\n\n/**\n * @WpAuthApiKey(regime, credentials) - a CUSTOMER holds the credential. The app's bound `ApiKeyHook`\n * authenticates the inbound request against its own datastore and returns the `ContextTuple` entries\n * the framework seeds into `RequestContext`. THE mode for a partner-facing contract consumed by other\n * companies' codebases (POS vendors, back-office platforms, ETL pipelines).\n *\n * ```typescript\n * @WpAuthApiKey('onetablet-partner', [\n *     { in: 'header', name: 'x-api-key', description: 'The key issued to your integration.' },\n *     { in: 'header', name: 'x-organization-id', description: 'Which of your organizations to act on.' },\n * ])\n * @ApiPath('/management/v1')\n * abstract class ManagementApi { ... }\n * ```\n *\n * `regime` is a bare STRING selecting WHICH key regime this route belongs to, exactly as\n * `@WpAuthSharedSecret(key)` and `@WpAuthWebhook(vendor)` already are — one hook serves several regimes,\n * and an api contract is level 0, so it never references a verifier directly.\n *\n * `credentials` DECLARES where the credential rides ({@link ApiKeyCredential}), so a spec generator\n * reading route auth metadata can emit `components.securitySchemes` instead of a human hand-writing\n * them into a manifest. It is a NON-EMPTY, ORDERED list rather than one credential because a real\n * regime authenticates a PAIR — the key names a customer, a second header names which of that\n * customer's organizations the request acts on, and a mismatch is a 401. Its OpenAPI form is two\n * schemes plus ONE security-requirement object holding BOTH keys (an AND); a LIST of two objects\n * would mean \"either alone suffices\", which is a load-bearing difference a single-credential shape\n * cannot even express. ORDER IS SIGNIFICANT and preserved: it is the order the credentials are\n * presented in the published document.\n *\n * The list can never be EMPTY — a contract that declares a key regime and then names no credential\n * would generate a document with no security block, which is the exact silent failure this argument\n * exists to remove. That is a compile error, not a runtime throw (see {@link JwtRoles}'s non-empty\n * tuple, the same device for the same reason).\n *\n * WHY IT IS NOT `@WpAuthSharedSecret`. Shared-secret declares that AN INTERNAL SERVICE is on the other\n * end, so the framework BELIEVES the trusted context headers that caller forwarded (see\n * `DestinationTrust.forAuthMode` and `AuthFilter.verifiesCaller`). A customer is not an internal\n * service: declaring a partner endpoint `@WpAuthSharedSecret` would let that partner assert someone\n * else's org id on the wire and have it admitted — a privilege escalation. `apikey` therefore sits\n * with `jwt` on the caller-NOT-verified side, where an inbound trusted header is admitted only when\n * the hook independently derived the SAME value.\n *\n * WHY THE HOOK SEES THE REQUEST, NOT ONE TOKEN. A real key regime checks the key TOGETHER WITH a\n * second header (the organization it is acting for), and `JwtHook.parseJwt` — handed one pre-extracted\n * token from one header — physically cannot. `ApiKeyHook.verifyApiKey(regime, request)` gets the whole\n * inbound request instead, so the app owns which headers carry the credential and validates them as a\n * PAIR. `credentials` does NOT change that: the framework reads no header from it and performs no\n * extraction. It is DECLARATION for readers of the contract, and enforcement stays entirely the hook's.\n *\n * FAILS CLOSED: with no `ApiKeyHook` bound, every `@WpAuthApiKey` endpoint 401s, matching `JwtHook` and\n * `WebhookAuthCallback`.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthApiKey(regime: string, credentials: ApiKeyCredentials): MethodDecorator {\n    return defineAuthMode({ kind: 'apikey', regime, credentials });\n}\n\n/**\n * @WpAuthLocalOnly() - this endpoint exists ONLY on a developer's machine. Off-local it is not\n * registered as a route at all, and if it is somehow reached it 404s. Method-only, like every\n * authorization decorator, so every endpoint's posture is visible at the method.\n *\n * ```typescript\n * @WpAuthLocalOnly()\n * @Endpoint('/logs', 'rpc')\n * sendBatch(request: SendLogBatchRequest): Promise<SendLogBatchResponse> { ... }\n * ```\n *\n * WHY IT IS AN AUTH MODE AND NOT A ROUTE-MODULE `if`. Apps hand-rolled this in TWO places kept in\n * sync by a comment: a route module that registered the route only locally, PLUS a\n * `if (env !== 'local') throw new ForbiddenError(...)` at the top of the handler. Neither half\n * was visible on the CONTRACT, so nothing reading the api — a human, a generated client, or an\n * agent — could tell this endpoint from a `@WpAuthPublic` one. Both halves are the framework's job now,\n * driven by this ONE declaration on the contract, which is where every other \"who may call this\"\n * fact already lives.\n *\n * It is DELIBERATELY a peer of @WpAuthPublic / @WpAuthJwt / @WpAuthOidc / @WpAuthSharedSecret / @WpAuthApiKey rather than an\n * option on one of them: one decorator per credential kind, and \"local-only\" is a different kind of\n * gate — it authenticates nobody, it excludes an entire environment.\n *\n * HOW \"local\" IS DECIDED: {@link RuntimeLocality}, declared once at startup (a REQUIRED input to\n * `RuntimeSetupOptions`). Undeclared means DEPLOYED, so a forgotten wiring call refuses the endpoint\n * rather than exposing it.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthLocalOnly(): MethodDecorator {\n    return defineAuthMode({ kind: 'local-only' });\n}\n\n// ============================================================\n// Helper functions\n// ============================================================\n\n/**\n * Get the base path from @ApiPath decorator.\n */\nexport function getApiPath(apiClass: Function): string | undefined {\n    return Reflect.getMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/**\n * Get all endpoints from @Endpoint decorators.\n * Returns a record of methodName -> endpoint path.\n */\nexport function getEndpoints(apiClass: Function): Record<string, string> | undefined {\n    return Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, apiClass);\n}\n\n/**\n * Every method's declared trigger kind, as `methodName -> kind`. Parallel to {@link getEndpoints}.\n * Empty for a class carrying no @Endpoint at all.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointKinds(apiClass: Function): Record<string, EndpointKind> {\n    return Reflect.getMetadata(METADATA_KEYS.ENDPOINT_KIND, apiClass) || {};\n}\n\n/**\n * What triggers ONE method, or undefined when the method carries no @Endpoint.\n *\n * Defaults to nothing rather than to 'rpc': `kind` is a required argument, so a missing entry means\n * \"this is not an endpoint\", never \"an endpoint that forgot to say\". Silently defaulting here would\n * put an undeclared cron or webhook back into the graph as a normal rpc call — the exact blindness\n * the required argument exists to remove.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointKind(apiClass: Function, methodName: string): EndpointKind | undefined {\n    return getEndpointKinds(apiClass)[methodName];\n}\n\n/**\n * Get the @Endpoint options for one method (empty object if the method had no options).\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointOptions(apiClass: Function, methodName: string): EndpointOptions {\n    const opts: Record<string, EndpointOptions> =\n        Reflect.getMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, apiClass) || {};\n    return opts[methodName] ?? {};\n}\n\n/**\n * Fail-fast at wiring time when an `external` endpoint declared no caller. The {@link Endpoint}\n * overloads already make that a COMPILE error; this is the backstop for the ways TS is bypassed —\n * a JS caller, an `as any` options object, a hand-rolled Reflect.defineMetadata.\n * @throws Error naming the first external endpoint with no `calledBy`.\n */\n// webpieces-disable no-function-outside-class -- wiring-time assert, sibling of assertEveryEndpointHasAuthMode\nexport function assertEveryExternalEndpointDeclaresCaller(apiClass: Function): void {\n    const kinds = getEndpointKinds(apiClass);\n    for (const methodName of Object.keys(kinds)) {\n        if (\n            kinds[methodName] !== 'external' ||\n            getEndpointCaller(apiClass, methodName) !== undefined\n        )\n            continue;\n        throw new Error(\n            `External endpoint '${methodName}' in ${apiClass.name || 'Unknown'} declares no caller. Say WHO ` +\n                `posts to it: @Endpoint(path, 'external', { calledBy: '<vendor>' }) — the runtime architecture ` +\n                `graph cannot name an inbound caller it was never told about.`,\n        );\n    }\n}\n\n/**\n * True when the method's @Endpoint declared `{ formPost: true }` — its body is\n * application/x-www-form-urlencoded (flat), not JSON.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function isFormPost(apiClass: Function, methodName: string): boolean {\n    return getEndpointOptions(apiClass, methodName).formPost === true;\n}\n\n/**\n * True when the method's @Endpoint declared `{ rawBody: true }` — the transport must retain the\n * verbatim bytes + absolute url for an {@link WpAuthWebhook} hook to verify.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of isFormPost\nexport function isRawBody(apiClass: Function, methodName: string): boolean {\n    return getEndpointOptions(apiClass, methodName).rawBody === true;\n}\n\n/**\n * Fail-fast at wiring time when an `@WpAuthWebhook` endpoint did not ask the transport to keep the\n * bytes it is supposed to verify. A hook with nothing to verify is a MISCONFIGURATION, and it must\n * surface at startup, naming the fix — not as a 401 in production on exactly the traffic the endpoint\n * exists for.\n *\n * This pairing is a runtime assert rather than a type because the two halves live on DIFFERENT\n * decorators (`@WpAuthWebhook` and `@Endpoint`), and no union over one decorator's argument can say\n * anything about the other's.\n *\n * @throws Error naming the first `@WpAuthWebhook` endpoint missing `{ rawBody: true }`.\n */\n// webpieces-disable no-function-outside-class -- wiring-time assert, sibling of assertEveryEndpointHasAuthMode\nexport function assertEveryWebhookEndpointRetainsRawBody(apiClass: Function): void {\n    const endpoints = getEndpoints(apiClass) || {};\n    for (const methodName of Object.keys(endpoints)) {\n        if (\n            getAuthMode(apiClass, methodName)?.kind !== 'webhook' ||\n            isRawBody(apiClass, methodName)\n        )\n            continue;\n        throw new Error(\n            `Endpoint '${methodName}' in ${apiClass.name || 'Unknown'} is @WpAuthWebhook but its @Endpoint ` +\n                `does not declare { rawBody: true }. A webhook hook verifies a signature over the bytes and ` +\n                `the url the SENDER transmitted, and without that option the transport parses the body and ` +\n                `throws them away — leaving the hook nothing to check.`,\n        );\n    }\n}\n\n/**\n * Check if a class has @ApiPath decorator.\n */\nexport function isApiPath(apiClass: Function): boolean {\n    return Reflect.hasMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/**\n * Get method-level auth metadata. Class-level authorization is forbidden.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader paired with the decorator API\nexport function getAuthMeta(apiClass: Function, methodName: string): AuthMeta | undefined {\n    return Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName);\n}\n\n/**\n * Get the auth mode for a method, or undefined.\n * Convenience wrapper over getAuthMeta for callers that only want the mode.\n */\n// webpieces-disable no-function-outside-class -- typed convenience reader over getAuthMeta\nexport function getAuthMode(apiClass: Function, methodName: string): AuthMode | undefined {\n    return getAuthMeta(apiClass, methodName)?.mode;\n}\n\n/**\n * The ONE prescription for \"this endpoint declares no auth\", shared by the two places that raise it\n * (here and http-routing's ApiRoutingFactory) because they had drifted into teaching different menus.\n * A message teaching an incomplete API is the same defect as an API with two spellings: whichever menu\n * the caller hits becomes the API they believe exists. It leads with the ROLE-GATED member on purpose —\n * the first thing offered should not be the widest grant.\n */\nexport const MISSING_AUTH_DECORATOR_FIX =\n    \"Add one of @WpAuthJwt({roles: ['admin']}) / @WpAuthJwt({allRolesAllowed: true}) / \" +\n    '@WpAuthOidc(...callers) / @WpAuthSharedSecret(key) / ' +\n    \"@WpAuthWebhook('vendor') / @WpAuthApiKey('regime', [{in: 'header', name: 'x-api-key'}]) / \" +\n    \"@WpAuthLocalOnly() / @WpAuthPublic('why anonymous access is required') to \" +\n    'the method.';\n\n/**\n * Fail-fast at wiring time if any endpoint lacks an auth mode. Both the server\n * (ApiRoutingFactory) and the task/rpc clients call this so a missing auth\n * decorator is a startup error, never a silent open endpoint.\n * @throws Error naming the first endpoint with no auth decorator, via {@link MISSING_AUTH_DECORATOR_FIX}.\n */\nexport function assertEveryEndpointHasAuthMode(apiClass: Function): void {\n    const apiName = apiClass.name || 'Unknown';\n    const endpoints = getEndpoints(apiClass) || {};\n    for (const methodName of Object.keys(endpoints)) {\n        if (!getAuthMeta(apiClass, methodName)) {\n            throw new Error(\n                `Endpoint '${methodName}' in ${apiName} has no auth decorator. ` +\n                    MISSING_AUTH_DECORATOR_FIX,\n            );\n        }\n    }\n}\n\n/**\n * Validate that a class/method doesn't have conflicting auth decorators.\n * @throws Error if multiple auth decorators are found on the same target.\n */\n// webpieces-disable no-function-outside-class -- shared decorator metadata validation\nexport function validateNoConflictingDecorators(\n    apiClass: Function,\n    methodName: string | undefined,\n): void {\n    const existing = methodName\n        ? Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName)\n        : Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass);\n\n    if (existing) {\n        const targetName = apiClass.name || 'Unknown';\n        const location = methodName\n            ? `method '${methodName}' of ${targetName}`\n            : `class ${targetName}`;\n        throw new Error(\n            `Conflicting auth decorator on ${location}. ` +\n                `Only one of @WpAuthJwt({...}) / @WpAuthOidc(...) / @WpAuthSharedSecret(...) / ` +\n                `@WpAuthWebhook(...) / @WpAuthApiKey(...) / @WpAuthLocalOnly() / ` +\n                `@WpAuthPublic('reason') is allowed per target.`,\n        );\n    }\n}\n"]}
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/decorators.ts"],"names":[],"mappings":";;;AA+GA,0BAcC;AAsDD,4BA2CC;AAoBD,0BAUC;AAOD,kCAIC;AAsCD,oCAOC;AAgBD,8BAEC;AAQD,sCAEC;AAaD,gCAEC;AASD,gDAEC;AAgCD,sCAEC;AAuDD,oCAEC;AA8BD,0CAEC;AASD,gCAEC;AAMD,oCAEC;AAOD,4CAEC;AAWD,0CAEC;AAMD,gDAIC;AASD,8FAcC;AAOD,gCAEC;AAOD,8BAEC;AAeD,4FAeC;AAKD,8BAEC;AAMD,kCAEC;AAOD,kCAEC;AAsBD,wEAWC;AAOD,0EAoBC;AAnrBD,4BAA0B;AAC1B,iDAAoD;AACpD,uDAM2B;AAC3B,4FAA4F;AAC5F,2CAAoF;AAEpF;;;GAGG;AACU,QAAA,aAAa,GAAG;IACzB,QAAQ,EAAE,oBAAoB;IAC9B,SAAS,EAAE,qBAAqB;IAChC,SAAS,EAAE,qBAAqB;IAChC,2EAA2E;IAC3E,YAAY,EAAE,wBAAwB;IACtC,uFAAuF;IACvF,QAAQ,EAAE,oBAAoB;IAC9B,mEAAmE;IACnE,cAAc,EAAE,0BAA0B;IAC1C,2EAA2E;IAC3E,gBAAgB,EAAE,4BAA4B;IAC9C,qGAAqG;IACrG,aAAa,EAAE,yBAAyB;IACxC,6FAA6F;IAC7F,eAAe,EAAE,qCAAmB;IACpC,6EAA6E;IAC7E,QAAQ,EAAE,oBAAoB;CACjC,CAAC;AA+DF;;;;;;;;;;;;;GAaG;AACH,SAAgB,OAAO,CAAC,QAAgB;IACpC,OAAO,CAAC,MAAgB,EAAE,EAAE;QACxB,IAAI,OAAO,CAAC,WAAW,CAAC,sBAAsB,EAAE,MAAM,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CACX,SAAS,MAAM,CAAC,IAAI,IAAI,SAAS,4CAA4C,CAChF,CAAC;QACN,CAAC;QACD,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAEjE,yCAAyC;QACzC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC;YACxD,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,SAAS,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;QAChE,CAAC;IACL,CAAC,CAAC;AACN,CAAC;AAqDD,2GAA2G;AAC3G,SAAgB,QAAQ,CACpB,IAAY,EACZ,IAAkB,EAClB,UAA2B,EAAE;IAE7B,kFAAkF;IAClF,OAAO,CAAC,MAAW,EAAE,WAA4B,EAAE,WAA+B,EAAE,EAAE;QAClF,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;QAElF,MAAM,SAAS,GACX,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QAEvE,SAAS,CAAC,WAAqB,CAAC,GAAG,IAAI,CAAC;QAExC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;QAE3E,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,aAAa,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QAC3E,KAAK,CAAC,WAAqB,CAAC,GAAG,IAAI,CAAC;QACpC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,aAAa,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;QAE3E,MAAM,IAAI,GACN,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,gBAAgB,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QAC9E,IAAI,CAAC,WAAqB,CAAC,GAAG,OAAO,CAAC;QACtC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,gBAAgB,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QAE7E,2FAA2F;QAC3F,sEAAsE;QACtE,MAAM,QAAQ,GAAG,OAAkC,CAAC;QACpD,IACI,IAAI,KAAK,UAAU;YACnB,OAAO,QAAQ,CAAC,QAAQ,KAAK,QAAQ;YACrC,QAAQ,CAAC,QAAQ,KAAK,EAAE;YAExB,OAAO;QACX,MAAM,OAAO,GACT,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,eAAe,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QAC7E,OAAO,CAAC,WAAqB,CAAC,GAAG,IAAI,gCAAc,CAC/C,QAAQ,CAAC,UAAU,IAAI,qCAAmB,EAC1C,QAAQ,CAAC,QAAQ,CACpB,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,eAAe,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;IACnF,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,2GAA2G;AAC3G,SAAgB,OAAO,CAAC,MAAgC;IACpD,MAAM,IAAI,GAAG,IAAI,uBAAQ,CAAC,MAAM,CAAC,CAAC;IAClC,kFAAkF;IAClF,OAAO,CAAC,MAAW,EAAE,WAA4B,EAAE,WAA+B,EAAE,EAAE;QAClF,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;QAClF,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,QAAQ,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QACtE,KAAK,CAAC,WAAqB,CAAC,GAAG,IAAI,CAAC;QACpC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;IAC1E,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,wGAAwG;AACxG,SAAgB,WAAW,CAAC,QAAkB,EAAE,UAAkB;IAC9D,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IAChE,OAAO,KAAK,CAAC,UAAU,CAAC,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,2GAA2G;AAC3G,SAAS,cAAc,CAAC,IAAc;IAClC,MAAM,QAAQ,GAAG,IAAI,oBAAQ,CAAC,IAAI,CAAC,CAAC;IAEpC,kFAAkF;IAClF,OAAO,CAAC,MAAW,EAAE,WAA6B,EAAE,WAAgC,EAAE,EAAE;QACpF,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACX,gFAAgF,CACnF,CAAC;QACN,CAAC;QACD,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;QAClF,IAAI,OAAO,CAAC,WAAW,CAAC,sBAAsB,EAAE,cAAc,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CACX,gBAAgB,cAAc,CAAC,IAAI,IAAI,SAAS,4CAA4C,CAC/F,CAAC;QACN,CAAC;QACD,+BAA+B,CAAC,cAAc,EAAE,WAAqB,CAAC,CAAC;QACvE,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;QACvF,MAAM,OAAO,GAAG,IAAI,GAAG,CACnB,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,YAAY,EAAE,cAAc,CAAC,IAAI,EAAE,CACxE,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,WAAqB,CAAC,CAAC;QACnC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,YAAY,EAAE,CAAC,GAAG,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC;IACrF,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,2GAA2G;AAC3G,SAAgB,YAAY,CAAC,MAAc;IACvC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACX,wFAAwF,CAC3F,CAAC;IACN,CAAC;IACD,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,2GAA2G;AAC3G,SAAgB,SAAS,CAAC,WAA2B;IACjD,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,iGAAiG;AACjG,SAAgB,aAAa,CAAC,WAA2B;IACrD,OAAO,WAAW,CAAC,eAAe,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC;AACzE,CAAC;AAED;;;;;;;;;GASG;AACH,2GAA2G;AAC3G,SAAgB,UAAU,CAAC,GAAG,OAAiB;IAC3C,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,2GAA2G;AAC3G,SAAgB,kBAAkB,CAAC,GAAW;IAC1C,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,2GAA2G;AAC3G,SAAgB,aAAa,CAAC,IAAY;IACtC,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,2GAA2G;AAC3G,SAAgB,YAAY,CAAC,MAAc,EAAE,WAA8B;IACvE,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,2GAA2G;AAC3G,SAAgB,eAAe;IAC3B,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,+DAA+D;AAC/D,mBAAmB;AACnB,+DAA+D;AAE/D;;GAEG;AACH,SAAgB,UAAU,CAAC,QAAkB;IACzC,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,QAAkB;IAC3C,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,kGAAkG;AAClG,SAAgB,gBAAgB,CAAC,QAAkB;IAC/C,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,aAAa,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;AAC5E,CAAC;AAED;;;;;;;GAOG;AACH,kGAAkG;AAClG,SAAgB,eAAe,CAAC,QAAkB,EAAE,UAAkB;IAClE,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,kGAAkG;AAClG,SAAgB,kBAAkB,CAAC,QAAkB,EAAE,UAAkB;IACrE,MAAM,IAAI,GACN,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,gBAAgB,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IACxE,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,+GAA+G;AAC/G,SAAgB,yCAAyC,CAAC,QAAkB;IACxE,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACzC,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,IACI,KAAK,CAAC,UAAU,CAAC,KAAK,UAAU;YAChC,IAAA,mCAAiB,EAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,SAAS;YAErD,SAAS;QACb,MAAM,IAAI,KAAK,CACX,sBAAsB,UAAU,QAAQ,QAAQ,CAAC,IAAI,IAAI,SAAS,+BAA+B;YAC7F,gGAAgG;YAChG,8DAA8D,CACrE,CAAC;IACN,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,kGAAkG;AAClG,SAAgB,UAAU,CAAC,QAAkB,EAAE,UAAkB;IAC7D,OAAO,kBAAkB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,gGAAgG;AAChG,SAAgB,SAAS,CAAC,QAAkB,EAAE,UAAkB;IAC5D,OAAO,kBAAkB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,+GAA+G;AAC/G,SAAgB,wCAAwC,CAAC,QAAkB;IACvE,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/C,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9C,IACI,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,IAAI,KAAK,SAAS;YACrD,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC;YAE/B,SAAS;QACb,MAAM,IAAI,KAAK,CACX,aAAa,UAAU,QAAQ,QAAQ,CAAC,IAAI,IAAI,SAAS,uCAAuC;YAC5F,6FAA6F;YAC7F,4FAA4F;YAC5F,uDAAuD,CAC9D,CAAC;IACN,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,SAAS,CAAC,QAAkB;IACxC,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,uGAAuG;AACvG,SAAgB,WAAW,CAAC,QAAkB,EAAE,UAAkB;IAC9D,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,2FAA2F;AAC3F,SAAgB,WAAW,CAAC,QAAkB,EAAE,UAAkB;IAC9D,OAAO,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,IAAI,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACU,QAAA,0BAA0B,GACnC,oFAAoF;IACpF,uDAAuD;IACvD,4FAA4F;IAC5F,4EAA4E;IAC5E,aAAa,CAAC;AAElB;;;;;GAKG;AACH,SAAgB,8BAA8B,CAAC,QAAkB;IAC7D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,CAAC;IAC3C,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/C,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9C,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACX,aAAa,UAAU,QAAQ,OAAO,0BAA0B;gBAC5D,kCAA0B,CACjC,CAAC;QACN,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,sFAAsF;AACtF,SAAgB,+BAA+B,CAC3C,QAAkB,EAClB,UAA8B;IAE9B,MAAM,QAAQ,GAAG,UAAU;QACvB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC;QACpE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAE7D,IAAI,QAAQ,EAAE,CAAC;QACX,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,CAAC;QAC9C,MAAM,QAAQ,GAAG,UAAU;YACvB,CAAC,CAAC,WAAW,UAAU,QAAQ,UAAU,EAAE;YAC3C,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACX,iCAAiC,QAAQ,IAAI;YACzC,gFAAgF;YAChF,kEAAkE;YAClE,gDAAgD,CACvD,CAAC;IACN,CAAC;AACL,CAAC","sourcesContent":["import 'reflect-metadata';\nimport { MaskSpec, MaskMode } from './LogFieldMask';\nimport {\n    DEFAULT_CALLER_KIND,\n    ENDPOINT_CALLER_KEY,\n    ExternalCaller,\n    ExternalSystemKind,\n    getEndpointCaller,\n} from './external-caller';\n// The TYPE layer these decorators attach — split out for file size only (see auth-mode.ts).\nimport { ApiKeyCredentials, AuthMeta, AuthMode, JwtRequirement } from './auth-mode';\n\n/**\n * Metadata keys for storing API routing information.\n * These keys are used by both server-side (routing) and client-side (client generation).\n */\nexport const METADATA_KEYS = {\n    API_PATH: 'webpieces:api-path',\n    ENDPOINTS: 'webpieces:endpoints',\n    AUTH_META: 'webpieces:auth-meta',\n    /** Method names carrying one of the canonical authorization decorators. */\n    AUTH_METHODS: 'webpieces:auth-methods',\n    /** 'rpc' (default, sync request/response) vs 'pubsub' (fire-and-forget cloud task). */\n    API_KIND: 'webpieces:api-kind',\n    /** Per-method Cloud Tasks queue-name override (set via @Queue). */\n    QUEUE_OVERRIDE: 'webpieces:queue-override',\n    /** Per-method @Endpoint options (e.g. formPost), parallel to ENDPOINTS. */\n    ENDPOINT_OPTIONS: 'webpieces:endpoint-options',\n    /** Per-method @Endpoint trigger kind (rpc | cloudtasks | cron | external), parallel to ENDPOINTS. */\n    ENDPOINT_KIND: 'webpieces:endpoint-kind',\n    /** Per-method declared external CALLER (only for kind 'external'), parallel to ENDPOINTS. */\n    ENDPOINT_CALLER: ENDPOINT_CALLER_KEY,\n    /** Per-method @MaskLog spec (which DTO fields the LogApiCall path masks). */\n    MASK_LOG: 'webpieces:mask-log',\n};\n\n/**\n * WHAT TRIGGERS an endpoint at runtime — the single fact that decides how the runtime architecture\n * graph draws it, and which Terraform resource must exist for it to ever fire:\n *\n *  - `rpc`        — a caller in this repo (or a browser) calls it synchronously. A direct arrow.\n *  - `cloudtasks` — a producer ENQUEUES it; Cloud Tasks delivers it later. Drawn producer → queue →\n *                   consumer, one queue node per METHOD (see {@link Queue}). Producer and consumer\n *                   being the SAME service is legal and common — the queue decouples them.\n *  - `cron`       — a scheduler fires it on a clock. Nothing in-repo calls it; drawn hanging off a\n *                   clock symbol. Backed by a Cloud Scheduler job.\n *  - `external`   — a system OUTSIDE this repo drives it (a GCP Pub/Sub push subscription, a Twilio\n *                   or Gmail webhook). Drawn as an inbound dashed arrow from that system.\n *\n * Declared PER METHOD, because one api class routinely mixes them: an admin contract can have\n * caller-driven endpoints AND a nightly cron sweep. A class-level marker cannot express that, which\n * is exactly why the graph could not tell these apart before.\n */\nexport type EndpointKind = 'rpc' | 'cloudtasks' | 'cron' | 'external';\n\n/**\n * Options for a single @Endpoint. Kept in a metadata map PARALLEL to ENDPOINTS so the existing\n * `Record<methodName, path>` shape every consumer iterates stays unchanged.\n */\nexport interface EndpointOptions {\n    /**\n     * Parse the request body as application/x-www-form-urlencoded (flat key→value) instead of JSON.\n     * For EXTERNAL webhooks (e.g. Twilio) that post form-encoded. The request DTO must be FLAT —\n     * urlencoded has no nesting (unlike JSON). Default false = JSON.\n     */\n    formPost?: boolean;\n\n    /**\n     * RETAIN the verbatim request bytes + the absolute url the sender addressed, so an\n     * {@link WpAuthWebhook} hook can verify a vendor signature over them (see `RawRequest`).\n     *\n     * Opt-in PER ENDPOINT, sitting beside `formPost` and for the same reason: the cost lands on the\n     * handful of webhook routes rather than on every request in the process. It is retention, not\n     * new buffering — the express adapter already accumulates the whole body, it simply threw it\n     * away once it had parsed a DTO.\n     *\n     * REQUIRED by `@WpAuthWebhook`, checked at wiring time (see\n     * {@link assertEveryWebhookEndpointRetainsRawBody}) rather than left to fail as a 401 in\n     * production: a hook with nothing to verify is a misconfiguration, not a bad request.\n     *\n     * Combines with `formPost` — `{ formPost: true, rawBody: true }` is the Twilio case, where the\n     * hook needs the bytes and the url while the controller still wants the flat parsed DTO.\n     */\n    rawBody?: boolean;\n}\n\n/**\n * Options for an `external` @Endpoint: everything {@link EndpointOptions} carries, PLUS a REQUIRED\n * declaration of WHO is calling. See {@link Endpoint} for why, `external-caller.ts` for identity.\n */\nexport interface ExternalEndpointOptions extends EndpointOptions {\n    /** The outside system that posts here (`'twilio'`) — the graph node IDENTITY, not display text. */\n    calledBy: string;\n    /** What that caller IS; picks the node's shape. Defaults to `'saas'` (see DEFAULT_CALLER_KIND). */\n    callerKind?: ExternalSystemKind;\n}\n\n/**\n * @ApiPath(basePath) - Class decorator that marks a class as an API definition\n * and sets the base path for all endpoints.\n *\n * Usage:\n * ```typescript\n * @ApiPath('/api/save')\n * abstract class SaveApi {\n *   @WpAuthJwt({ roles: ['admin'] })\n *   @Endpoint('/item', 'rpc')\n *   save(request: SaveRequest): Promise<SaveResponse> { ... }\n * }\n * ```\n */\nexport function ApiPath(basePath: string): ClassDecorator {\n    return (target: Function) => {\n        if (Reflect.hasMetadata('webpieces:ipc-api-id', target)) {\n            throw new Error(\n                `Class ${target.name || 'Unknown'} cannot combine @ApiPath with @WpInternal.`,\n            );\n        }\n        Reflect.defineMetadata(METADATA_KEYS.API_PATH, basePath, target);\n\n        // Initialize endpoints map if not exists\n        if (!Reflect.hasMetadata(METADATA_KEYS.ENDPOINTS, target)) {\n            Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, {}, target);\n        }\n    };\n}\n\n/**\n * @Endpoint(path, kind, options?) - Method decorator that registers a POST endpoint at the given\n * path and declares WHAT TRIGGERS it.\n *\n * All endpoints are POST-only (matching gRPC/thrift style).\n *\n * Usage:\n * ```typescript\n * @Endpoint('/item', 'rpc')\n * save(request: SaveRequest): Promise<SaveResponse> { ... }\n *\n * // enqueued by a producer, delivered later by Cloud Tasks:\n * @Endpoint('/send', 'cloudtasks')\n * send(request: SendRequest): Promise<void> { ... }\n *\n * // fired by Cloud Scheduler on a clock, called by nobody in this repo:\n * @Endpoint('/nightly', 'cron')\n * nightly(request: NightlyRequest): Promise<void> { ... }\n *\n * // EXTERNAL webhook posting application/x-www-form-urlencoded (e.g. Twilio):\n * @Endpoint('/hook', 'external', { formPost: true, calledBy: 'twilio' })\n * inbound(request: InboundRequest): Promise<InboundResponse> { ... }\n * ```\n *\n * `kind` is REQUIRED and deliberately positional: it makes every pre-existing single-argument\n * `@Endpoint('/x')` a COMPILE error rather than something a lint rule has to chase, so no endpoint\n * can slip into the runtime architecture graph with its trigger left to guesswork. See\n * {@link EndpointKind} for what each value draws and which Terraform resource backs it.\n *\n * `calledBy` is REQUIRED for `external` FOR EXACTLY THE SAME REASON, enforced by the overloads below:\n * the one box on the runtime graph whose whole job is to say who calls us from outside could only\n * restate OUR OWN contract name, because nothing in the source ever said who the caller was. This is\n * BREAKING for published consumers, intentionally — an existing `@Endpoint(p, 'external', {...})`\n * stops compiling until it names its caller. Migration is one property; see the migration note in\n * `external-caller.ts`. Non-`external` endpoints are completely unaffected.\n *\n * The path write to ENDPOINTS is UNCHANGED (every consumer iterates `[methodName, path]`); kind,\n * options and caller ride PARALLEL ENDPOINT_KIND / ENDPOINT_OPTIONS / ENDPOINT_CALLER maps.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n    path: string,\n    kind: 'external',\n    options: ExternalEndpointOptions,\n): MethodDecorator;\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n    path: string,\n    kind: Exclude<EndpointKind, 'external'>,\n    options?: EndpointOptions,\n): MethodDecorator;\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n    path: string,\n    kind: EndpointKind,\n    options: EndpointOptions = {},\n): MethodDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n\n        const endpoints: Record<string, string> =\n            Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, metadataTarget) || {};\n\n        endpoints[propertyKey as string] = path;\n\n        Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, endpoints, metadataTarget);\n\n        const kinds: Record<string, EndpointKind> =\n            Reflect.getMetadata(METADATA_KEYS.ENDPOINT_KIND, metadataTarget) || {};\n        kinds[propertyKey as string] = kind;\n        Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_KIND, kinds, metadataTarget);\n\n        const opts: Record<string, EndpointOptions> =\n            Reflect.getMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, metadataTarget) || {};\n        opts[propertyKey as string] = options;\n        Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, opts, metadataTarget);\n\n        // ONLY for 'external', mirroring how a queue name is recorded only for the kinds that HAVE\n        // a queue: a caller on an rpc endpoint would be a fact about nothing.\n        const declared = options as ExternalEndpointOptions;\n        if (\n            kind !== 'external' ||\n            typeof declared.calledBy !== 'string' ||\n            declared.calledBy === ''\n        )\n            return;\n        const callers: Record<string, ExternalCaller> =\n            Reflect.getMetadata(METADATA_KEYS.ENDPOINT_CALLER, metadataTarget) || {};\n        callers[propertyKey as string] = new ExternalCaller(\n            declared.callerKind ?? DEFAULT_CALLER_KIND,\n            declared.calledBy,\n        );\n        Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_CALLER, callers, metadataTarget);\n    };\n}\n\n/**\n * @MaskLog(fields) - declare which fields of THIS method's request/response DTOs the\n * {@link LogApiCallImpl} logging path must mask, so a secret riding on a DTO (an OAuth refresh token, an\n * id-token JWT) is never written to the logs in cleartext. The REAL value still travels on the wire\n * untouched — masking lives in the logging path only.\n *\n * ```typescript\n * @Endpoint('/account', 'rpc')\n * @MaskLog({ refreshToken: 'full', accessToken: 'last4', credential: 'full' })\n * getEmailAccount(request: GetEmailAccountRequest): Promise<GetEmailAccountResponse> { ... }\n * ```\n *\n * Matching is by field NAME at any depth (nested objects + array elements), so\n * `response.account.refreshToken` is masked. Declared on the SHARED api contract, so BOTH the client\n * `[API-client-*]` and server `[API-server-*]` lines mask it. The spec is read ONCE at route-build\n * time and rides {@link RouteMetadata.mask}, so an unmasked method pays nothing at call time.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function MaskLog(fields: Record<string, MaskMode>): MethodDecorator {\n    const spec = new MaskSpec(fields);\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n        const specs: Record<string, MaskSpec> =\n            Reflect.getMetadata(METADATA_KEYS.MASK_LOG, metadataTarget) || {};\n        specs[propertyKey as string] = spec;\n        Reflect.defineMetadata(METADATA_KEYS.MASK_LOG, specs, metadataTarget);\n    };\n}\n\n/**\n * The @MaskLog spec for one method, or undefined if the method declared none (the common case — the\n * caller then logs the DTO verbatim on the plain JSON.stringify fast path).\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpointOptions\nexport function getMaskSpec(apiClass: Function, methodName: string): MaskSpec | undefined {\n    const specs: Record<string, MaskSpec> =\n        Reflect.getMetadata(METADATA_KEYS.MASK_LOG, apiClass) || {};\n    return specs[methodName];\n}\n\n/**\n * Shared implementation for every auth decorator. Authorization is deliberately\n * method-only: a class-level default is too easy to miss when reviewing one endpoint.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nfunction defineAuthMode(mode: AuthMode): MethodDecorator {\n    const authMeta = new AuthMeta(mode);\n\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => {\n        if (propertyKey === undefined) {\n            throw new Error(\n                'Authorization decorators are method-only; annotate every @Endpoint explicitly.',\n            );\n        }\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n        if (Reflect.hasMetadata('webpieces:ipc-api-id', metadataTarget)) {\n            throw new Error(\n                `Internal API ${metadataTarget.name || 'Unknown'} cannot use HTTP authorization decorators.`,\n            );\n        }\n        validateNoConflictingDecorators(metadataTarget, propertyKey as string);\n        Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, metadataTarget, propertyKey);\n        const methods = new Set<string>(\n            Reflect.getMetadata(METADATA_KEYS.AUTH_METHODS, metadataTarget) || [],\n        );\n        methods.add(propertyKey as string);\n        Reflect.defineMetadata(METADATA_KEYS.AUTH_METHODS, [...methods], metadataTarget);\n    };\n}\n\n/**\n * @WpAuthPublic(reason) - endpoint intentionally requires no authentication.\n * The non-empty reason makes anonymous exposure an explicit review decision.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthPublic(reason: string): MethodDecorator {\n    if (typeof reason !== 'string' || reason.trim() === '') {\n        throw new Error(\n            '@WpAuthPublic requires a non-empty reason explaining why anonymous access is required.',\n        );\n    }\n    return defineAuthMode({ kind: 'public' });\n}\n\n/**\n * @WpAuthJwt(requirement) - THE user-facing JWT decorator, covering the whole user-JWT axis: the\n * compiler-enforced role decision ({@link JwtRoles}) plus app-defined fields ({@link JwtRequirement}).\n *\n * ```typescript\n * @WpAuthJwt({ roles: ['admin', 'editor'] })          // any-of\n * @WpAuthJwt({ allRolesAllowed: true, inOrg: true })  // wide + an app rule enforced by authorizeJwt\n * ```\n *\n * It absorbed the former `@Auth(requirement)` — same argument, same AuthMode, so two spellings of one\n * decision. One decorator per credential kind now: `@WpAuthPublic` / `@WpAuthJwt` / `@WpAuthOidc` /\n * `@WpAuthSharedSecret` / `@WpAuthLocalOnly`.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthJwt(requirement: JwtRequirement): MethodDecorator {\n    return defineAuthMode({ kind: 'jwt', requirement });\n}\n\n/**\n * The roles an endpoint accepts, or [] when it accepts every authenticated user. The ONE reader of\n * the {@link JwtRoles} union, so no caller has to re-derive \"does absent mean wide?\" — a question\n * whose two plausible answers is how the widest grant kept hiding behind an absent field.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getAuthMode\nexport function rolesRequired(requirement: JwtRequirement): readonly string[] {\n    return requirement.allRolesAllowed === true ? [] : requirement.roles;\n}\n\n/**\n * @WpAuthOidc(...callers) - Google OIDC service-to-service auth (Cloud Tasks delivery / cross-service\n * RPC). `callers` is an OPTIONAL app-level allow-list of caller service accounts.\n *\n * NO args = TRUST THE EDGE: accept any genuine Google-signed OIDC caller, because a PRIVATE Cloud\n * Run service's edge already gates WHO via `run.invoker` IAM (managed in terraform — one source of\n * truth, no hand-synced list in code). If the service is actually PUBLIC, the verifier logs a loud\n * warning (it can't be the gate then). Pass explicit SAs (`@WpAuthOidc('svc-a')`) only when you want\n * an additional app-level allow-list as defense-in-depth.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthOidc(...callers: string[]): MethodDecorator {\n    return defineAuthMode({ kind: 'oidc', callers });\n}\n\n/**\n * @WpAuthSharedSecret(key) - constant-time compare of an inbound header against the secret bound for\n * `key`. `key` is a LOOKUP KEY (not an env var): the server looks up its accepted {@link SharedSecrets}\n * by this key, and each client looks up the value it sends by the SAME key (see {@link Secrets}).\n * For internal callers that cannot mint OIDC tokens.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthSharedSecret(key: string): MethodDecorator {\n    return defineAuthMode({ kind: 'shared-secret', secretKey: key });\n}\n\n/**\n * @WpAuthWebhook(name) - an OUTSIDE vendor signed this request in its OWN scheme; the app's bound\n * `WebhookAuthCallback` proves it. THE mode for every signed inbound webhook — Sentry, GitHub, Stripe, Slack,\n * Twilio — none of which fits the other kinds: no vendor mints Google OIDC tokens, and none sends its\n * secret (they all send a DERIVATION over the request), so `@WpAuthPublic` was the only reachable posture\n * and `calledBy: 'sentry'` stayed a claim rather than a fact.\n *\n * ```typescript\n * @WpAuthWebhook('sentry')\n * @Endpoint('/hook/sentry/issue', 'external', { calledBy: 'sentry', rawBody: true })\n * abstract notify(request: SentryIssueHook): Promise<HookAck>;\n * ```\n *\n * `name` is a bare STRING resolved through DI in the server's container, exactly as\n * `@WpAuthOidc('gmail-push')` already is — never a function reference. An api contract is level 0: a\n * direct reference to a verifier would invert the dependency graph and drag a vendor SDK into the\n * browser bundle that imports the same contract.\n *\n * THE FRAMEWORK IMPLEMENTS NO VENDOR CRYPTO, deliberately. Every vendor ships an official validator\n * (`twilio.validateRequest`, `stripe.webhooks.constructEvent`, `@octokit/webhooks-methods`) and every\n * vendor revises its scheme (Twilio added `bodySHA256` for JSON bodies; Stripe versions its header).\n * Reimplementing five of those is signing up to track five security changelogs forever and to be\n * wrong at the moment being wrong matters. The framework hands the hook enough of the raw request to\n * call the vendor's own library — hence the REQUIRED `{ rawBody: true }` (see\n * {@link EndpointOptions.rawBody}), which is checked at wiring time.\n *\n * FAILS CLOSED: with no `WebhookAuthCallback` bound, every `@WpAuthWebhook` endpoint 401s, matching `JwtHook`.\n * Silently allowing an unverified webhook is the one default that must not exist.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthWebhook(name: string): MethodDecorator {\n    return defineAuthMode({ kind: 'webhook', name });\n}\n\n/**\n * @WpAuthApiKey(regime, credentials) - a CUSTOMER holds the credential. The app's bound `ApiKeyHook`\n * authenticates the inbound request against its own datastore and returns the `ContextTuple` entries\n * the framework seeds into `RequestContext`. THE mode for a partner-facing contract consumed by other\n * companies' codebases (POS vendors, back-office platforms, ETL pipelines).\n *\n * ```typescript\n * @WpAuthApiKey('onetablet-partner', [\n *     { in: 'header', name: 'x-api-key', description: 'The key issued to your integration.' },\n *     { in: 'header', name: 'x-organization-id', description: 'Which of your organizations to act on.' },\n * ])\n * @ApiPath('/management/v1')\n * abstract class ManagementApi { ... }\n * ```\n *\n * `regime` is a bare STRING selecting WHICH key regime this route belongs to, exactly as\n * `@WpAuthSharedSecret(key)` and `@WpAuthWebhook(vendor)` already are — one hook serves several regimes,\n * and an api contract is level 0, so it never references a verifier directly.\n *\n * `credentials` DECLARES where the credential rides ({@link ApiKeyCredential}), so a spec generator\n * reading route auth metadata can emit `components.securitySchemes` instead of a human hand-writing\n * them into a manifest. It is a NON-EMPTY, ORDERED list rather than one credential because a real\n * regime authenticates a PAIR — the key names a customer, a second header names which of that\n * customer's organizations the request acts on, and a mismatch is a 401. Its OpenAPI form is two\n * schemes plus ONE security-requirement object holding BOTH keys (an AND); a LIST of two objects\n * would mean \"either alone suffices\", which is a load-bearing difference a single-credential shape\n * cannot even express. ORDER IS SIGNIFICANT and preserved: it is the order the credentials are\n * presented in the published document.\n *\n * The list can never be EMPTY — a contract that declares a key regime and then names no credential\n * would generate a document with no security block, which is the exact silent failure this argument\n * exists to remove. That is a compile error, not a runtime throw (see {@link JwtRoles}'s non-empty\n * tuple, the same device for the same reason).\n *\n * WHY IT IS NOT `@WpAuthSharedSecret`. Shared-secret declares that AN INTERNAL SERVICE is on the other\n * end, so the framework BELIEVES the trusted context headers that caller forwarded (see\n * `DestinationTrust.forAuthMode` and `AuthFilter.verifiesCaller`). A customer is not an internal\n * service: declaring a partner endpoint `@WpAuthSharedSecret` would let that partner assert someone\n * else's org id on the wire and have it admitted — a privilege escalation. `apikey` therefore sits\n * with `jwt` on the caller-NOT-verified side, where an inbound trusted header is admitted only when\n * the hook independently derived the SAME value.\n *\n * WHY THE HOOK SEES THE REQUEST, NOT ONE TOKEN. A real key regime checks the key TOGETHER WITH a\n * second header (the organization it is acting for), and `JwtHook.parseJwt` — handed one pre-extracted\n * token from one header — physically cannot. `ApiKeyHook.verifyApiKey(regime, request)` gets the whole\n * inbound request instead, so the app owns which headers carry the credential and validates them as a\n * PAIR. `credentials` does NOT change that: the framework reads no header from it and performs no\n * extraction. It is DECLARATION for readers of the contract, and enforcement stays entirely the hook's.\n *\n * FAILS CLOSED: with no `ApiKeyHook` bound, every `@WpAuthApiKey` endpoint 401s, matching `JwtHook` and\n * `WebhookAuthCallback`.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthApiKey(regime: string, credentials: ApiKeyCredentials): MethodDecorator {\n    return defineAuthMode({ kind: 'apikey', regime, credentials });\n}\n\n/**\n * @WpAuthLocalOnly() - this endpoint exists ONLY on a developer's machine. Off-local it is not\n * registered as a route at all, and if it is somehow reached it 404s. Method-only, like every\n * authorization decorator, so every endpoint's posture is visible at the method.\n *\n * ```typescript\n * @WpAuthLocalOnly()\n * @Endpoint('/logs', 'rpc')\n * sendBatch(request: SendLogBatchRequest): Promise<SendLogBatchResponse> { ... }\n * ```\n *\n * WHY IT IS AN AUTH MODE AND NOT A ROUTE-MODULE `if`. Apps hand-rolled this in TWO places kept in\n * sync by a comment: a route module that registered the route only locally, PLUS a\n * `if (env !== 'local') throw new ApiForbiddenError(...)` at the top of the handler. Neither half\n * was visible on the CONTRACT, so nothing reading the api — a human, a generated client, or an\n * agent — could tell this endpoint from a `@WpAuthPublic` one. Both halves are the framework's job now,\n * driven by this ONE declaration on the contract, which is where every other \"who may call this\"\n * fact already lives.\n *\n * It is DELIBERATELY a peer of @WpAuthPublic / @WpAuthJwt / @WpAuthOidc / @WpAuthSharedSecret / @WpAuthApiKey rather than an\n * option on one of them: one decorator per credential kind, and \"local-only\" is a different kind of\n * gate — it authenticates nobody, it excludes an entire environment.\n *\n * HOW \"local\" IS DECIDED: {@link RuntimeLocality}, declared once at startup (a REQUIRED input to\n * `RuntimeSetupOptions`). Undeclared means DEPLOYED, so a forgotten wiring call refuses the endpoint\n * rather than exposing it.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthLocalOnly(): MethodDecorator {\n    return defineAuthMode({ kind: 'local-only' });\n}\n\n// ============================================================\n// Helper functions\n// ============================================================\n\n/**\n * Get the base path from @ApiPath decorator.\n */\nexport function getApiPath(apiClass: Function): string | undefined {\n    return Reflect.getMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/**\n * Get all endpoints from @Endpoint decorators.\n * Returns a record of methodName -> endpoint path.\n */\nexport function getEndpoints(apiClass: Function): Record<string, string> | undefined {\n    return Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, apiClass);\n}\n\n/**\n * Every method's declared trigger kind, as `methodName -> kind`. Parallel to {@link getEndpoints}.\n * Empty for a class carrying no @Endpoint at all.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointKinds(apiClass: Function): Record<string, EndpointKind> {\n    return Reflect.getMetadata(METADATA_KEYS.ENDPOINT_KIND, apiClass) || {};\n}\n\n/**\n * What triggers ONE method, or undefined when the method carries no @Endpoint.\n *\n * Defaults to nothing rather than to 'rpc': `kind` is a required argument, so a missing entry means\n * \"this is not an endpoint\", never \"an endpoint that forgot to say\". Silently defaulting here would\n * put an undeclared cron or webhook back into the graph as a normal rpc call — the exact blindness\n * the required argument exists to remove.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointKind(apiClass: Function, methodName: string): EndpointKind | undefined {\n    return getEndpointKinds(apiClass)[methodName];\n}\n\n/**\n * Get the @Endpoint options for one method (empty object if the method had no options).\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointOptions(apiClass: Function, methodName: string): EndpointOptions {\n    const opts: Record<string, EndpointOptions> =\n        Reflect.getMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, apiClass) || {};\n    return opts[methodName] ?? {};\n}\n\n/**\n * Fail-fast at wiring time when an `external` endpoint declared no caller. The {@link Endpoint}\n * overloads already make that a COMPILE error; this is the backstop for the ways TS is bypassed —\n * a JS caller, an `as any` options object, a hand-rolled Reflect.defineMetadata.\n * @throws Error naming the first external endpoint with no `calledBy`.\n */\n// webpieces-disable no-function-outside-class -- wiring-time assert, sibling of assertEveryEndpointHasAuthMode\nexport function assertEveryExternalEndpointDeclaresCaller(apiClass: Function): void {\n    const kinds = getEndpointKinds(apiClass);\n    for (const methodName of Object.keys(kinds)) {\n        if (\n            kinds[methodName] !== 'external' ||\n            getEndpointCaller(apiClass, methodName) !== undefined\n        )\n            continue;\n        throw new Error(\n            `External endpoint '${methodName}' in ${apiClass.name || 'Unknown'} declares no caller. Say WHO ` +\n                `posts to it: @Endpoint(path, 'external', { calledBy: '<vendor>' }) — the runtime architecture ` +\n                `graph cannot name an inbound caller it was never told about.`,\n        );\n    }\n}\n\n/**\n * True when the method's @Endpoint declared `{ formPost: true }` — its body is\n * application/x-www-form-urlencoded (flat), not JSON.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function isFormPost(apiClass: Function, methodName: string): boolean {\n    return getEndpointOptions(apiClass, methodName).formPost === true;\n}\n\n/**\n * True when the method's @Endpoint declared `{ rawBody: true }` — the transport must retain the\n * verbatim bytes + absolute url for an {@link WpAuthWebhook} hook to verify.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of isFormPost\nexport function isRawBody(apiClass: Function, methodName: string): boolean {\n    return getEndpointOptions(apiClass, methodName).rawBody === true;\n}\n\n/**\n * Fail-fast at wiring time when an `@WpAuthWebhook` endpoint did not ask the transport to keep the\n * bytes it is supposed to verify. A hook with nothing to verify is a MISCONFIGURATION, and it must\n * surface at startup, naming the fix — not as a 401 in production on exactly the traffic the endpoint\n * exists for.\n *\n * This pairing is a runtime assert rather than a type because the two halves live on DIFFERENT\n * decorators (`@WpAuthWebhook` and `@Endpoint`), and no union over one decorator's argument can say\n * anything about the other's.\n *\n * @throws Error naming the first `@WpAuthWebhook` endpoint missing `{ rawBody: true }`.\n */\n// webpieces-disable no-function-outside-class -- wiring-time assert, sibling of assertEveryEndpointHasAuthMode\nexport function assertEveryWebhookEndpointRetainsRawBody(apiClass: Function): void {\n    const endpoints = getEndpoints(apiClass) || {};\n    for (const methodName of Object.keys(endpoints)) {\n        if (\n            getAuthMode(apiClass, methodName)?.kind !== 'webhook' ||\n            isRawBody(apiClass, methodName)\n        )\n            continue;\n        throw new Error(\n            `Endpoint '${methodName}' in ${apiClass.name || 'Unknown'} is @WpAuthWebhook but its @Endpoint ` +\n                `does not declare { rawBody: true }. A webhook hook verifies a signature over the bytes and ` +\n                `the url the SENDER transmitted, and without that option the transport parses the body and ` +\n                `throws them away — leaving the hook nothing to check.`,\n        );\n    }\n}\n\n/**\n * Check if a class has @ApiPath decorator.\n */\nexport function isApiPath(apiClass: Function): boolean {\n    return Reflect.hasMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/**\n * Get method-level auth metadata. Class-level authorization is forbidden.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader paired with the decorator API\nexport function getAuthMeta(apiClass: Function, methodName: string): AuthMeta | undefined {\n    return Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName);\n}\n\n/**\n * Get the auth mode for a method, or undefined.\n * Convenience wrapper over getAuthMeta for callers that only want the mode.\n */\n// webpieces-disable no-function-outside-class -- typed convenience reader over getAuthMeta\nexport function getAuthMode(apiClass: Function, methodName: string): AuthMode | undefined {\n    return getAuthMeta(apiClass, methodName)?.mode;\n}\n\n/**\n * The ONE prescription for \"this endpoint declares no auth\", shared by the two places that raise it\n * (here and http-routing's ApiRoutingFactory) because they had drifted into teaching different menus.\n * A message teaching an incomplete API is the same defect as an API with two spellings: whichever menu\n * the caller hits becomes the API they believe exists. It leads with the ROLE-GATED member on purpose —\n * the first thing offered should not be the widest grant.\n */\nexport const MISSING_AUTH_DECORATOR_FIX =\n    \"Add one of @WpAuthJwt({roles: ['admin']}) / @WpAuthJwt({allRolesAllowed: true}) / \" +\n    '@WpAuthOidc(...callers) / @WpAuthSharedSecret(key) / ' +\n    \"@WpAuthWebhook('vendor') / @WpAuthApiKey('regime', [{in: 'header', name: 'x-api-key'}]) / \" +\n    \"@WpAuthLocalOnly() / @WpAuthPublic('why anonymous access is required') to \" +\n    'the method.';\n\n/**\n * Fail-fast at wiring time if any endpoint lacks an auth mode. Both the server\n * (ApiRoutingFactory) and the task/rpc clients call this so a missing auth\n * decorator is a startup error, never a silent open endpoint.\n * @throws Error naming the first endpoint with no auth decorator, via {@link MISSING_AUTH_DECORATOR_FIX}.\n */\nexport function assertEveryEndpointHasAuthMode(apiClass: Function): void {\n    const apiName = apiClass.name || 'Unknown';\n    const endpoints = getEndpoints(apiClass) || {};\n    for (const methodName of Object.keys(endpoints)) {\n        if (!getAuthMeta(apiClass, methodName)) {\n            throw new Error(\n                `Endpoint '${methodName}' in ${apiName} has no auth decorator. ` +\n                    MISSING_AUTH_DECORATOR_FIX,\n            );\n        }\n    }\n}\n\n/**\n * Validate that a class/method doesn't have conflicting auth decorators.\n * @throws Error if multiple auth decorators are found on the same target.\n */\n// webpieces-disable no-function-outside-class -- shared decorator metadata validation\nexport function validateNoConflictingDecorators(\n    apiClass: Function,\n    methodName: string | undefined,\n): void {\n    const existing = methodName\n        ? Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName)\n        : Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass);\n\n    if (existing) {\n        const targetName = apiClass.name || 'Unknown';\n        const location = methodName\n            ? `method '${methodName}' of ${targetName}`\n            : `class ${targetName}`;\n        throw new Error(\n            `Conflicting auth decorator on ${location}. ` +\n                `Only one of @WpAuthJwt({...}) / @WpAuthOidc(...) / @WpAuthSharedSecret(...) / ` +\n                `@WpAuthWebhook(...) / @WpAuthApiKey(...) / @WpAuthLocalOnly() / ` +\n                `@WpAuthPublic('reason') is allowed per target.`,\n        );\n    }\n}\n"]}

package/src/http/networkReject.d.ts

@@ -1,5 +1,5 @@
 /**
- * Decides whether a thrown error is a transport reject and, if so, mints the typed {@link OfflineError}
+ * Decides whether a thrown error is a transport reject and, if so, mints the typed {@link ApiConnectionError}
  * for it. Stateless and dependency-free, so a caller can `new` it directly on the browser fetch path
  * (instance methods, not static — webpieces wires behaviour into injectable classes, and a static
  * method is just a module-scope function wearing a class as a namespace).
@@ -12,7 +12,7 @@ export declare class NetworkRejectClassifier {
      */
     isNetworkRejectError(error: Error): boolean;
     /**
-     * If `error` is a transport reject, return an {@link OfflineError} that names `url` and preserves
+     * If `error` is a transport reject, return an {@link ApiConnectionError} that names `url` and preserves
      * the original as `cause`. Otherwise return `error` UNTOUCHED — a genuine bug keeps its own type
      * and stack, so a defect is never silently relabelled as "offline".
      */

package/src/http/networkReject.js

@@ -5,14 +5,14 @@ exports.NetworkRejectClassifier = void 0;
  * Centralised classifier for transport rejects — the ONE place in the framework that decides
  * "the request never reached a server" (offline, DNS, connection refused, CORS preflight).
  *
- * Browser-safe: zero node imports, no framework deps beyond {@link OfflineError}. It runs identically
+ * Browser-safe: zero node imports, no framework deps beyond {@link ApiConnectionError}. It runs identically
  * in an Angular bundle and on Cloud Run.
  *
  * WHY here and not in each app: the browser-wording list below is inherently incomplete and drifts as
  * engines reword their messages. Kept in one module, an app never writes it, and a new wording is
  * fixed exactly once — here — instead of in every consumer's copy of the same fragile string match.
  */
-const errors_1 = require("./errors");
+const errors_1 = require("../errors");
 /**
  * Node/undici system codes that mean the connection never established (or dropped mid-flight before
  * any HTTP response). A real, stable code beats message text, so these are checked FIRST.
@@ -47,7 +47,7 @@ const BROWSER_REJECT_MESSAGES = [
  */
 const MAX_CAUSE_DEPTH = 5;
 /**
- * Decides whether a thrown error is a transport reject and, if so, mints the typed {@link OfflineError}
+ * Decides whether a thrown error is a transport reject and, if so, mints the typed {@link ApiConnectionError}
  * for it. Stateless and dependency-free, so a caller can `new` it directly on the browser fetch path
  * (instance methods, not static — webpieces wires behaviour into injectable classes, and a static
  * method is just a module-scope function wearing a class as a namespace).
@@ -62,13 +62,13 @@ class NetworkRejectClassifier {
         return this.hasNodeSystemCode(error) || this.hasBrowserRejectMessage(error);
     }
     /**
-     * If `error` is a transport reject, return an {@link OfflineError} that names `url` and preserves
+     * If `error` is a transport reject, return an {@link ApiConnectionError} that names `url` and preserves
      * the original as `cause`. Otherwise return `error` UNTOUCHED — a genuine bug keeps its own type
      * and stack, so a defect is never silently relabelled as "offline".
      */
     toNetworkError(error, url) {
         if (this.isNetworkRejectError(error)) {
-            return new errors_1.OfflineError(`Request to ${url} never reached a server (offline / network reject)`, error);
+            return new errors_1.ApiConnectionError(`Request to ${url} never reached a server (offline / network reject)`, error);
         }
         return error;
     }

package/src/http/networkReject.js.map

@@ -1 +1 @@
-{"version":3,"file":"networkReject.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/networkReject.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACH,qCAAwC;AAWxC;;;GAGG;AACH,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC;IACnD,cAAc;IACd,WAAW;IACX,WAAW;IACX,YAAY;IACZ,OAAO;IACP,WAAW;IACX,yBAAyB;IACzB,aAAa;IACb,cAAc;CACjB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,uBAAuB,GAAsB;IAC/C,iBAAiB;IACjB,gDAAgD;IAChD,aAAa;IACb,iCAAiC;IACjC,qCAAqC;IACrC,wBAAwB;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;;;;GAKG;AACH,MAAa,uBAAuB;IAChC;;;;OAIG;IACH,oBAAoB,CAAC,KAAY;QAC7B,OAAO,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAChF,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,KAAY,EAAE,GAAW;QACpC,IAAI,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,OAAO,IAAI,qBAAY,CAAC,cAAc,GAAG,oDAAoD,EAAE,KAAK,CAAC,CAAC;QAC1G,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;OAGG;IACK,iBAAiB,CAAC,KAAY;QAClC,IAAI,OAAO,GAAsB,KAAK,CAAC;QACvC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,eAAe,IAAI,OAAO,KAAK,SAAS,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAChF,MAAM,IAAI,GAAI,OAAuB,CAAC,IAAI,CAAC;YAC3C,IAAI,IAAI,KAAK,SAAS,IAAI,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpD,OAAO,IAAI,CAAC;YAChB,CAAC;YACD,0FAA0F;YAC1F,uFAAuF;YACvF,0DAA0D;YAC1D,OAAO,GAAG,OAAO,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACzE,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,qFAAqF;IAC7E,uBAAuB,CAAC,KAAY;QACxC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACxF,CAAC;CACJ;AA9CD,0DA8CC","sourcesContent":["/**\n * Centralised classifier for transport rejects — the ONE place in the framework that decides\n * \"the request never reached a server\" (offline, DNS, connection refused, CORS preflight).\n *\n * Browser-safe: zero node imports, no framework deps beyond {@link OfflineError}. It runs identically\n * in an Angular bundle and on Cloud Run.\n *\n * WHY here and not in each app: the browser-wording list below is inherently incomplete and drifts as\n * engines reword their messages. Kept in one module, an app never writes it, and a new wording is\n * fixed exactly once — here — instead of in every consumer's copy of the same fragile string match.\n */\nimport { OfflineError } from './errors';\n\n/**\n * The error shape this classifier reads for the node/undici code. `Error.cause` (ES2022) is already\n * on the base type — typed `unknown` there — so we only add the optional `code`; a plain `Error`\n * narrows to this safely since we only ever READ the field.\n */\ninterface CausedError extends Error {\n    code?: string;\n}\n\n/**\n * Node/undici system codes that mean the connection never established (or dropped mid-flight before\n * any HTTP response). A real, stable code beats message text, so these are checked FIRST.\n */\nconst NODE_SYSTEM_CODES: ReadonlySet<string> = new Set([\n    'ECONNREFUSED',\n    'ENOTFOUND',\n    'EAI_AGAIN',\n    'ECONNRESET',\n    'EPIPE',\n    'ETIMEDOUT',\n    'UND_ERR_CONNECT_TIMEOUT',\n    'ENETUNREACH',\n    'EHOSTUNREACH',\n]);\n\n/**\n * Browser `fetch` reject wordings. Substring tests, not equality: zone.js (Angular) may append the\n * request hostname to the message. This list is expected to grow as engines/locales reword.\n */\nconst BROWSER_REJECT_MESSAGES: readonly string[] = [\n    'Failed to fetch',\n    'NetworkError when attempting to fetch resource',\n    'Load failed',\n    'The network connection was lost',\n    'loading dynamically imported module',\n    'Network request failed',\n];\n\n/**\n * undici's thrown `TypeError: fetch failed` carries the useful system code one or two `cause` levels\n * down, so the code check MUST walk the chain — but a self-referential chain would spin forever, so\n * the walk is depth-capped.\n */\nconst MAX_CAUSE_DEPTH = 5;\n\n/**\n * Decides whether a thrown error is a transport reject and, if so, mints the typed {@link OfflineError}\n * for it. Stateless and dependency-free, so a caller can `new` it directly on the browser fetch path\n * (instance methods, not static — webpieces wires behaviour into injectable classes, and a static\n * method is just a module-scope function wearing a class as a namespace).\n */\nexport class NetworkRejectClassifier {\n    /**\n     * Classify an error as a transport reject (\"the request never reached a server\").\n     *\n     * Node/undici system codes are checked first (a stable code beats text), then browser wordings.\n     */\n    isNetworkRejectError(error: Error): boolean {\n        return this.hasNodeSystemCode(error) || this.hasBrowserRejectMessage(error);\n    }\n\n    /**\n     * If `error` is a transport reject, return an {@link OfflineError} that names `url` and preserves\n     * the original as `cause`. Otherwise return `error` UNTOUCHED — a genuine bug keeps its own type\n     * and stack, so a defect is never silently relabelled as \"offline\".\n     */\n    toNetworkError(error: Error, url: string): Error {\n        if (this.isNetworkRejectError(error)) {\n            return new OfflineError(`Request to ${url} never reached a server (offline / network reject)`, error);\n        }\n        return error;\n    }\n\n    /**\n     * True if this error (or any error up its `cause` chain, to {@link MAX_CAUSE_DEPTH}) carries a\n     * node/undici system code meaning the transport never delivered a response.\n     */\n    private hasNodeSystemCode(error: Error): boolean {\n        let current: Error | undefined = error;\n        for (let depth = 0; depth <= MAX_CAUSE_DEPTH && current !== undefined; depth += 1) {\n            const code = (current as CausedError).code;\n            if (code !== undefined && NODE_SYSTEM_CODES.has(code)) {\n                return true;\n            }\n            // Error.cause is `unknown`; only an Error carries the message/code we can read next, so a\n            // non-Error cause (or none) ends the walk. undici's nested reject IS an Error, so this\n            // still reaches the ECONNREFUSED it hangs one level down.\n            current = current.cause instanceof Error ? current.cause : undefined;\n        }\n        return false;\n    }\n\n    /** True if the error message contains any known browser transport-reject wording. */\n    private hasBrowserRejectMessage(error: Error): boolean {\n        const message = error.message;\n        return BROWSER_REJECT_MESSAGES.some((wording: string) => message.includes(wording));\n    }\n}\n"]}
+{"version":3,"file":"networkReject.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/networkReject.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACH,sCAA+C;AAW/C;;;GAGG;AACH,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC;IACnD,cAAc;IACd,WAAW;IACX,WAAW;IACX,YAAY;IACZ,OAAO;IACP,WAAW;IACX,yBAAyB;IACzB,aAAa;IACb,cAAc;CACjB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,uBAAuB,GAAsB;IAC/C,iBAAiB;IACjB,gDAAgD;IAChD,aAAa;IACb,iCAAiC;IACjC,qCAAqC;IACrC,wBAAwB;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;;;;GAKG;AACH,MAAa,uBAAuB;IAChC;;;;OAIG;IACH,oBAAoB,CAAC,KAAY;QAC7B,OAAO,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAChF,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,KAAY,EAAE,GAAW;QACpC,IAAI,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,OAAO,IAAI,2BAAkB,CACzB,cAAc,GAAG,oDAAoD,EACrE,KAAK,CACR,CAAC;QACN,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;OAGG;IACK,iBAAiB,CAAC,KAAY;QAClC,IAAI,OAAO,GAAsB,KAAK,CAAC;QACvC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,eAAe,IAAI,OAAO,KAAK,SAAS,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAChF,MAAM,IAAI,GAAI,OAAuB,CAAC,IAAI,CAAC;YAC3C,IAAI,IAAI,KAAK,SAAS,IAAI,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpD,OAAO,IAAI,CAAC;YAChB,CAAC;YACD,0FAA0F;YAC1F,uFAAuF;YACvF,0DAA0D;YAC1D,OAAO,GAAG,OAAO,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACzE,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,qFAAqF;IAC7E,uBAAuB,CAAC,KAAY;QACxC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACxF,CAAC;CACJ;AAjDD,0DAiDC","sourcesContent":["/**\n * Centralised classifier for transport rejects — the ONE place in the framework that decides\n * \"the request never reached a server\" (offline, DNS, connection refused, CORS preflight).\n *\n * Browser-safe: zero node imports, no framework deps beyond {@link ApiConnectionError}. It runs identically\n * in an Angular bundle and on Cloud Run.\n *\n * WHY here and not in each app: the browser-wording list below is inherently incomplete and drifts as\n * engines reword their messages. Kept in one module, an app never writes it, and a new wording is\n * fixed exactly once — here — instead of in every consumer's copy of the same fragile string match.\n */\nimport { ApiConnectionError } from '../errors';\n\n/**\n * The error shape this classifier reads for the node/undici code. `Error.cause` (ES2022) is already\n * on the base type — typed `unknown` there — so we only add the optional `code`; a plain `Error`\n * narrows to this safely since we only ever READ the field.\n */\ninterface CausedError extends Error {\n    code?: string;\n}\n\n/**\n * Node/undici system codes that mean the connection never established (or dropped mid-flight before\n * any HTTP response). A real, stable code beats message text, so these are checked FIRST.\n */\nconst NODE_SYSTEM_CODES: ReadonlySet<string> = new Set([\n    'ECONNREFUSED',\n    'ENOTFOUND',\n    'EAI_AGAIN',\n    'ECONNRESET',\n    'EPIPE',\n    'ETIMEDOUT',\n    'UND_ERR_CONNECT_TIMEOUT',\n    'ENETUNREACH',\n    'EHOSTUNREACH',\n]);\n\n/**\n * Browser `fetch` reject wordings. Substring tests, not equality: zone.js (Angular) may append the\n * request hostname to the message. This list is expected to grow as engines/locales reword.\n */\nconst BROWSER_REJECT_MESSAGES: readonly string[] = [\n    'Failed to fetch',\n    'NetworkError when attempting to fetch resource',\n    'Load failed',\n    'The network connection was lost',\n    'loading dynamically imported module',\n    'Network request failed',\n];\n\n/**\n * undici's thrown `TypeError: fetch failed` carries the useful system code one or two `cause` levels\n * down, so the code check MUST walk the chain — but a self-referential chain would spin forever, so\n * the walk is depth-capped.\n */\nconst MAX_CAUSE_DEPTH = 5;\n\n/**\n * Decides whether a thrown error is a transport reject and, if so, mints the typed {@link ApiConnectionError}\n * for it. Stateless and dependency-free, so a caller can `new` it directly on the browser fetch path\n * (instance methods, not static — webpieces wires behaviour into injectable classes, and a static\n * method is just a module-scope function wearing a class as a namespace).\n */\nexport class NetworkRejectClassifier {\n    /**\n     * Classify an error as a transport reject (\"the request never reached a server\").\n     *\n     * Node/undici system codes are checked first (a stable code beats text), then browser wordings.\n     */\n    isNetworkRejectError(error: Error): boolean {\n        return this.hasNodeSystemCode(error) || this.hasBrowserRejectMessage(error);\n    }\n\n    /**\n     * If `error` is a transport reject, return an {@link ApiConnectionError} that names `url` and preserves\n     * the original as `cause`. Otherwise return `error` UNTOUCHED — a genuine bug keeps its own type\n     * and stack, so a defect is never silently relabelled as \"offline\".\n     */\n    toNetworkError(error: Error, url: string): Error {\n        if (this.isNetworkRejectError(error)) {\n            return new ApiConnectionError(\n                `Request to ${url} never reached a server (offline / network reject)`,\n                error,\n            );\n        }\n        return error;\n    }\n\n    /**\n     * True if this error (or any error up its `cause` chain, to {@link MAX_CAUSE_DEPTH}) carries a\n     * node/undici system code meaning the transport never delivered a response.\n     */\n    private hasNodeSystemCode(error: Error): boolean {\n        let current: Error | undefined = error;\n        for (let depth = 0; depth <= MAX_CAUSE_DEPTH && current !== undefined; depth += 1) {\n            const code = (current as CausedError).code;\n            if (code !== undefined && NODE_SYSTEM_CODES.has(code)) {\n                return true;\n            }\n            // Error.cause is `unknown`; only an Error carries the message/code we can read next, so a\n            // non-Error cause (or none) ends the walk. undici's nested reject IS an Error, so this\n            // still reaches the ECONNREFUSED it hangs one level down.\n            current = current.cause instanceof Error ? current.cause : undefined;\n        }\n        return false;\n    }\n\n    /** True if the error message contains any known browser transport-reject wording. */\n    private hasBrowserRejectMessage(error: Error): boolean {\n        const message = error.message;\n        return BROWSER_REJECT_MESSAGES.some((wording: string) => message.includes(wording));\n    }\n}\n"]}

package/src/index.d.ts

@@ -30,7 +30,7 @@ export { EXTERNAL_SYSTEM_KINDS, DEFAULT_CALLER_KIND, ExternalCaller, isExternalS
 export type { ExternalSystemKind } from './http/external-caller';
 export { Secrets, SECRETS } from './http/Secrets';
 export { ValidateImplementation } from './http/validators';
-export { ProtocolError, HttpError, HttpNotFoundError, EndpointNotFoundError, HttpBadRequestError, HttpUnauthorizedError, HttpForbiddenError, HttpTimeoutError, HttpBadGatewayError, HttpServiceUnavailableError, HttpGatewayTimeoutError, HttpInternalServerError, HttpTooManyRequestsError, HttpVendorError, HttpUserError, OfflineError, ENTITY_NOT_FOUND, WRONG_LOGIN_TYPE, WRONG_LOGIN, NOT_APPROVED, EMAIL_NOT_CONFIRMED, WRONG_DOMAIN, WRONG_COMPANY, NO_REG_CODE, } from './http/errors';
+export { ENTITY_NOT_FOUND, WRONG_LOGIN_TYPE, WRONG_LOGIN, NOT_APPROVED, EMAIL_NOT_CONFIRMED, WRONG_DOMAIN, WRONG_COMPANY, NO_REG_CODE, } from './errors';
 export { NetworkRejectClassifier } from './http/networkReject';
 export { InstantDto, DateDto, TimeDto, DateTimeDto, InstantUtil, DateUtil, TimeUtil, DateTimeUtil, } from './http/datetime';
 export { HeaderRegistry } from './http/HeaderRegistry';
@@ -39,7 +39,7 @@ export { CallRegistry } from './http/CallRegistry';
 export { CallDeadline } from './http/CallDeadline';
 export { CallContext } from './http/CallStrategy';
 export type { Attempt, CallStrategy } from './http/CallStrategy';
-export { TimeoutError } from './http/TimeoutError';
+export { ApiCallTimeoutError } from './http/ApiCallTimeoutError';
 export type { ServiceUrlDeriver } from './http/ClientRegistry';
 export { ServiceInfo } from './http/ServiceInfo';
 export { RuntimeLocality } from './http/RuntimeLocality';
@@ -70,5 +70,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, NotFoundError, BadGatewayError, ServiceUnavailableError, GatewayTimeoutError, InternalError, TooManyRequestsError, ForbiddenError, RequestTimeoutError, UserError, BadRequestError, UnauthorizedError, VendorError, ApiErrorCodec, ApiErrorPayload, } from './errors';
-export { HttpErrorStatus } from './http/HttpErrorStatus';
+export { ApiError, ApiNotFoundError, ApiDependencyError, ApiUnavailableError, ApiDependencyTimeoutError, ApiImplementationError, ApiRateLimitedError, ApiForbiddenError, ApiRequestTimeoutError, ApiEndUserError, ApiBadRequestError, ApiUnauthorizedError, ApiDependencyBackoffError, ApiConnectionError, ApiEndpointNotFoundError, ApiErrorCodec, ApiErrorPayload, } from './errors';
+export type { ApiErrorKind } from './errors';
+export { ApiErrorHttpStatus } from './http/ApiErrorHttpStatus';