@webpieces/core-util 0.3.385 → 0.4.387

package/package.json

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

package/src/http/LogApiCall.d.ts

@@ -1,5 +1,14 @@
 import { RouteMetadata } from "./decorators";
 import { ApiSide } from "./ApiCallInfo";
+/**
+ * Options for {@link LogApiCallImpl.execute}. `allowVoidResponse` opts OUT of the strict
+ * falsy-response guard for callers that legitimately return void/undefined (e.g. a local firestore
+ * wrapper). Defaults to strict so RPC callers keep the safety net.
+ */
+export declare class LogApiCallOptions {
+    allowVoidResponse?: boolean;
+    constructor(allowVoidResponse?: boolean);
+}
 /**
  * LogApiCall - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and
  * client-side (ProxyClient) for one consistent logging shape across the framework.
@@ -33,6 +42,11 @@ export declare class LogApiCallImpl {
      * @param meta - Route metadata with controllerClassName and methodName
      * @param requestDto - The request DTO
      * @param method - The method to execute
+     * @param options - `allowVoidResponse: true` opts OUT of the strict falsy-response guard, for
+     *   callers that legitimately return void/undefined (e.g. a local firestore wrapper whose
+     *   `setDocument` returns void, or a `getDocById` miss returning undefined). Defaults to strict,
+     *   so RPC callers (LogApiFilter, ProxyClient) keep the safety net: an HTTP endpoint returning
+     *   nothing is almost always a bug.
      *
      * Correlation fields (requestId, tenantId, ...) are NOT stamped here — a logging BACKEND owns that,
      * reading RequestContext on every record. What IS stamped here is the per-call `api` tag, and only
@@ -41,7 +55,7 @@ export declare class LogApiCallImpl {
      * it. Cost: only the `[API-*]` req/resp lines carry `api`, not lines emitted mid-call — which is
      * exactly what the GCP filters (`jsonPayload.api.*`) want.
      */
-    execute(side: ApiSide, meta: RouteMetadata, requestDto: any, method: (dto: any) => Promise<any>): Promise<any>;
+    execute(side: ApiSide, meta: RouteMetadata, requestDto: any, method: (dto: any) => Promise<any>, options?: LogApiCallOptions): Promise<any>;
     /**
      * Is this error a NON-failure for HEALTH/METRICS — the process working CORRECTLY (log OTHER, api
      * result:'success') — rather than a real failure to surface (log FAIL, result:'failure')?

package/src/http/LogApiCall.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogApiCall = exports.LogApiCallImpl = void 0;
+exports.LogApiCall = exports.LogApiCallImpl = exports.LogApiCallOptions = void 0;
 const errors_1 = require("./errors");
 const errorUtils_1 = require("../lib/errorUtils");
 const LogManager_1 = require("../logging/LogManager");
@@ -8,6 +8,18 @@ const ApiCallInfo_1 = require("./ApiCallInfo");
 const ApiCallContext_1 = require("./ApiCallContext");
 const WebpiecesCoreHeaders_1 = require("./WebpiecesCoreHeaders");
 const log = LogManager_1.LogManager.getLogger('LogApiCall');
+/**
+ * Options for {@link LogApiCallImpl.execute}. `allowVoidResponse` opts OUT of the strict
+ * falsy-response guard for callers that legitimately return void/undefined (e.g. a local firestore
+ * wrapper). Defaults to strict so RPC callers keep the safety net.
+ */
+class LogApiCallOptions {
+    allowVoidResponse;
+    constructor(allowVoidResponse) {
+        this.allowVoidResponse = allowVoidResponse;
+    }
+}
+exports.LogApiCallOptions = LogApiCallOptions;
 /**
  * LogApiCall - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and
  * client-side (ProxyClient) for one consistent logging shape across the framework.
@@ -41,6 +53,11 @@ class LogApiCallImpl {
      * @param meta - Route metadata with controllerClassName and methodName
      * @param requestDto - The request DTO
      * @param method - The method to execute
+     * @param options - `allowVoidResponse: true` opts OUT of the strict falsy-response guard, for
+     *   callers that legitimately return void/undefined (e.g. a local firestore wrapper whose
+     *   `setDocument` returns void, or a `getDocById` miss returning undefined). Defaults to strict,
+     *   so RPC callers (LogApiFilter, ProxyClient) keep the safety net: an HTTP endpoint returning
+     *   nothing is almost always a bug.
      *
      * Correlation fields (requestId, tenantId, ...) are NOT stamped here — a logging BACKEND owns that,
      * reading RequestContext on every record. What IS stamped here is the per-call `api` tag, and only
@@ -53,7 +70,7 @@ class LogApiCallImpl {
     // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary (matches ProxyClient)
     requestDto, 
     // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary
-    method
+    method, options
     // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary
     ) {
         // Throws if no ApiCallContext was installed at startup, or there is no active scope to stamp
@@ -79,7 +96,7 @@ class LogApiCallImpl {
             if (!requestDto)
                 throw new Error(`Request cannot be null and was from ${cls}.${meta.methodName}`);
             const response = await method(requestDto);
-            if (!response)
+            if (!options?.allowVoidResponse && !response)
                 throw new Error(`Response cannot be null and was from ${cls}.${meta.methodName}`);
             stamp(new ApiCallInfo_1.ApiCallInfo(side, 'response', 'success', meta.path, meta.methodName, cls), () => log.info(`[API-${side}-resp-SUCCESS] ${cls}.${meta.methodName} response=${JSON.stringify(response)}`));
             return response;

package/src/http/LogApiCall.js.map

@@ -1 +1 @@
-{"version":3,"file":"LogApiCall.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/LogApiCall.ts"],"names":[],"mappings":"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","sourcesContent":["import {RouteMetadata} from \"./decorators\";\nimport {\n    HttpBadRequestError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpNotFoundError,\n    HttpUserError,\n} from './errors';\nimport {toError} from \"../lib/errorUtils\";\nimport {LogManager} from \"../logging/LogManager\";\nimport {ApiCallInfo, ApiSide} from \"./ApiCallInfo\";\nimport {ApiCallContextHolder} from \"./ApiCallContext\";\nimport {WebpiecesCoreHeaders} from \"./WebpiecesCoreHeaders\";\n\nconst log = LogManager.getLogger('LogApiCall');\n\n\n/**\n * LogApiCall - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and\n * client-side (ProxyClient) for one consistent logging shape across the framework.\n *\n * TWO things happen around each call:\n * 1. Text lines are emitted (the human-readable `[API-...]` patterns below).\n * 2. A structured {@link ApiCallInfo} tag is stamped into the ambient request context via the\n *    {@link ApiCallContextHolder} seam, so EVERY log line emitted during the call (not just the\n *    req/resp lines) inherits a filterable `api` object — surfacing in GCP as\n *    `jsonPayload.api.{side,type,result,path,method}`.\n *\n * BROWSER-SAFE: this lives in core-util and runs in the browser bundle (via ProxyClient →\n * BrowserProxyClient), so it MUST NOT import `RequestContext` (Node async_hooks, and a circular dep).\n * It stamps through the {@link ApiCallContext} seam instead: `setupRuntime` installs a\n * RequestContext-backed impl on a Node server, and `ClientHttpBrowserFactory` a module-global impl in a\n * browser. If neither ran, {@link ApiCallContextHolder.get} throws (loud misconfiguration).\n *\n * Singleton, mirroring `RequestContext`: use the exported {@link LogApiCall} constant, not `new`.\n *\n * Logging format patterns:\n * - [API-{side}-req] ClassName.methodName request={...}\n * - [API-{side}-resp-SUCCESS] ClassName.methodName response={...}\n * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...}  (user errors)\n * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (server errors)\n */\nexport class LogApiCallImpl {\n\n    /**\n     * Execute an API call with logging + `api` context-tagging around it.\n     *\n     * @param side - 'client' (outbound call this process made) or 'server' (inbound call it handled)\n     * @param meta - Route metadata with controllerClassName and methodName\n     * @param requestDto - The request DTO\n     * @param method - The method to execute\n     *\n     * Correlation fields (requestId, tenantId, ...) are NOT stamped here — a logging BACKEND owns that,\n     * reading RequestContext on every record. What IS stamped here is the per-call `api` tag, and only\n     * for the SYNCHRONOUS span of each log line: set → log → remove. Because the tag is never held across\n     * `await method(...)`, a concurrent browser call (single-threaded, one global slot) can never clobber\n     * it. Cost: only the `[API-*]` req/resp lines carry `api`, not lines emitted mid-call — which is\n     * exactly what the GCP filters (`jsonPayload.api.*`) want.\n     */\n    public async execute(\n        side: ApiSide,\n        meta: RouteMetadata,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary (matches ProxyClient)\n        requestDto: any,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary\n        method: (dto: any) => Promise<any>\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary\n    ): Promise<any> {\n        // Throws if no ApiCallContext was installed at startup, or there is no active scope to stamp\n        // into (loud misconfiguration — an api call with nowhere to tag is a bug).\n        const ctx = ApiCallContextHolder.get();\n        if (!ctx.isActive()) {\n            throw new Error(\n                'LogApiCall requires an ACTIVE ApiCallContext. On a Node server, run inside the ' +\n                'RequestContext.run(...) a server filter opens; in a browser, build ClientHttpBrowserFactory first.',\n            );\n        }\n        const key = WebpiecesCoreHeaders.API_CALL_INFO;\n        const server = side === 'server';\n        const cls = meta.controllerClassName;\n        // set → emit → remove, as ONE synchronous span: the tag is live only while the logger reads it,\n        // never across an await, so a single browser global slot can never be clobbered by a concurrent call.\n        const stamp = (info: ApiCallInfo, emit: () => void): void => {\n            ctx.set(key, info);\n            emit();\n            ctx.remove(key);\n        };\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- LogApiCall logs errors before re-throwing to caller\n        try {\n            stamp(new ApiCallInfo(side, 'request', undefined, meta.path, meta.methodName, cls), () =>\n                log.info(`[API-${side}-req] ${cls}.${meta.methodName} ${meta.path} request=${JSON.stringify(requestDto)}`));\n\n            if(!requestDto)\n                throw new Error(`Request cannot be null and was from ${cls}.${meta.methodName}`);\n\n            const response = await method(requestDto);\n\n            if(!response)\n                throw new Error(`Response cannot be null and was from ${cls}.${meta.methodName}`);\n\n            stamp(new ApiCallInfo(side, 'response', 'success', meta.path, meta.methodName, cls), () =>\n                log.info(`[API-${side}-resp-SUCCESS] ${cls}.${meta.methodName} response=${JSON.stringify(response)}`));\n\n            return response;\n        } catch (err: unknown) {\n            const error = toError(err);\n            const errorType = error.constructor.name;\n            const errorMessage = error.message;\n            // Side-dependent: a 4xx the SERVER raised is a handled non-failure (OTHER); the same 4xx a\n            // CLIENT receives means its call FAILED. HttpUserError (266) is never a failure, either side.\n            const isUser = this.isUserError(error, server);\n\n            stamp(new ApiCallInfo(side, 'response', isUser ? 'success' : 'failure', meta.path, meta.methodName, cls), () =>\n                isUser\n                    ? log.warn(`[API-${side}-resp-OTHER] ${cls}.${meta.methodName} errorType=${errorType}`)\n                    : log.error(`[API-${side}-resp-FAIL] ${cls}.${meta.methodName} errorType=${errorType} error=${errorMessage}`));\n            throw error;\n        }\n    }\n\n    /**\n     * Is this error a NON-failure for HEALTH/METRICS — the process working CORRECTLY (log OTHER, api\n     * result:'success') — rather than a real failure to surface (log FAIL, result:'failure')?\n     *\n     * The question is \"are things WORKING?\", NOT \"was it an HTTP 4xx vs 5xx\" — and the two are not the\n     * same (see 408 below). Classification is by portable Error TYPE, never by transport: LogApiCall runs\n     * deep in the stack (in-process calls, pubsub/queue handlers, HTTP — one code path) and only ever\n     * sees a thrown Error. The Http* classes are poorly named for that (the `Http` prefix is historical),\n     * but they ARE portable error types that travel with the throw anywhere, so matching the TYPE works\n     * with or without any HTTP in the picture. Do NOT swap this for an `error.code` 4xx range check — that\n     * both re-couples to HTTP AND would bury 408.\n     *\n     * SERVER — a healthy server correctly rejecting a CLIENT'S mistake is metrics NOISE, not a failure:\n     * - HttpBadRequestError (400)   \"your request is malformed\"\n     * - HttpUnauthorizedError (401) \"you're not authenticated\"\n     * - HttpForbiddenError (403)    \"authenticated, but not allowed\"\n     * - HttpNotFoundError (404)     \"wrong url / no such entity\" (EndpointNotFoundError is a subclass)\n     *   → the server is fine, the caller erred → result:'success', logged OTHER.\n     *\n     * SERVER — something may actually be WRONG, so SURFACE it (result:'failure', logged FAIL):\n     * - HttpTimeoutError (408): a 4xx, but the client may NEVER have seen the response — deliberately\n     *   absent from the list below so it counts as a failure.\n     * - 500 / 502 / 504 / 598, and any non-Http Error: real failures.\n     *\n     * HttpUserError (266): ALWAYS a non-failure, server OR client — an expected \"user made a mistake\" signal.\n     * CLIENT: receiving ANY error except 266 means the outbound call FAILED → result:'failure'.\n     *\n     * @param error  - The already-normalized error (callers pass toError(err), never a raw catch value)\n     * @param server - True when this side is the SERVER handling an inbound call; false for a CLIENT's outbound call\n     * @returns true if this should be treated as a non-failure (OTHER / result:'success')\n     */\n    isUserError(error: Error, server: boolean): boolean {\n        // 266 is the one error that is never a failure, on either side.\n        if (error instanceof HttpUserError) {\n            return true;\n        }\n        // A client that RECEIVED any error (except the 266 above) made a failed call.\n        if (!server) {\n            return false;\n        }\n        // SERVER: only a healthy rejection of the caller's mistake is a non-failure. Note 408\n        // (HttpTimeoutError) is intentionally NOT here — the client may never have seen the response.\n        return (\n            error instanceof HttpBadRequestError ||\n            error instanceof HttpUnauthorizedError ||\n            error instanceof HttpForbiddenError ||\n            error instanceof HttpNotFoundError\n        );\n    }\n}\n\n/**\n * The process-wide {@link LogApiCallImpl} singleton — mirrors the `RequestContext` export pattern.\n * Callers use `LogApiCall.execute(...)`, never `new`.\n */\nexport const LogApiCall = new LogApiCallImpl();\n"]}
+{"version":3,"file":"LogApiCall.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/LogApiCall.ts"],"names":[],"mappings":";;;AACA,qCAMkB;AAClB,kDAA0C;AAC1C,sDAAiD;AACjD,+CAAmD;AACnD,qDAAsD;AACtD,iEAA4D;AAE5D,MAAM,GAAG,GAAG,uBAAU,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;AAE/C;;;;GAIG;AACH,MAAa,iBAAiB;IAC1B,iBAAiB,CAAW;IAE5B,YAAY,iBAA2B;QACnC,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;IAC/C,CAAC;CACJ;AAND,8CAMC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAa,cAAc;IAEvB;;;;;;;;;;;;;;;;;;;OAmBG;IACI,KAAK,CAAC,OAAO,CAChB,IAAa,EACb,IAAmB;IACnB,2GAA2G;IAC3G,UAAe;IACf,qFAAqF;IACrF,MAAkC,EAClC,OAA2B;IAC3B,qFAAqF;;QAErF,6FAA6F;QAC7F,2EAA2E;QAC3E,MAAM,GAAG,GAAG,qCAAoB,CAAC,GAAG,EAAE,CAAC;QACvC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACX,iFAAiF;gBACjF,oGAAoG,CACvG,CAAC;QACN,CAAC;QACD,MAAM,GAAG,GAAG,2CAAoB,CAAC,aAAa,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,KAAK,QAAQ,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACrC,gGAAgG;QAChG,sGAAsG;QACtG,MAAM,KAAK,GAAG,CAAC,IAAiB,EAAE,IAAgB,EAAQ,EAAE;YACxD,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACnB,IAAI,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC,CAAC;QAEF,qHAAqH;QACrH,IAAI,CAAC;YACD,KAAK,CAAC,IAAI,yBAAW,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CACrF,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,SAAS,GAAG,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,YAAY,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;YAEhH,IAAG,CAAC,UAAU;gBACV,MAAM,IAAI,KAAK,CAAC,uCAAuC,GAAG,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YAErF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;YAE1C,IAAG,CAAC,OAAO,EAAE,iBAAiB,IAAI,CAAC,QAAQ;gBACvC,MAAM,IAAI,KAAK,CAAC,wCAAwC,GAAG,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YAEtF,KAAK,CAAC,IAAI,yBAAW,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CACtF,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,kBAAkB,GAAG,IAAI,IAAI,CAAC,UAAU,aAAa,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;YAE3G,OAAO,QAAQ,CAAC;QACpB,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,oBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC;YACzC,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC;YACnC,2FAA2F;YAC3F,8FAA8F;YAC9F,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAE/C,KAAK,CAAC,IAAI,yBAAW,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAC3G,MAAM;gBACF,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,gBAAgB,GAAG,IAAI,IAAI,CAAC,UAAU,cAAc,SAAS,EAAE,CAAC;gBACvF,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,eAAe,GAAG,IAAI,IAAI,CAAC,UAAU,cAAc,SAAS,UAAU,YAAY,EAAE,CAAC,CAAC,CAAC;YACvH,MAAM,KAAK,CAAC;QAChB,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,WAAW,CAAC,KAAY,EAAE,MAAe;QACrC,gEAAgE;QAChE,IAAI,KAAK,YAAY,sBAAa,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,8EAA8E;QAC9E,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,sFAAsF;QACtF,8FAA8F;QAC9F,OAAO,CACH,KAAK,YAAY,4BAAmB;YACpC,KAAK,YAAY,8BAAqB;YACtC,KAAK,YAAY,2BAAkB;YACnC,KAAK,YAAY,0BAAiB,CACrC,CAAC;IACN,CAAC;CACJ;AAtID,wCAsIC;AAED;;;GAGG;AACU,QAAA,UAAU,GAAG,IAAI,cAAc,EAAE,CAAC","sourcesContent":["import {RouteMetadata} from \"./decorators\";\nimport {\n    HttpBadRequestError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpNotFoundError,\n    HttpUserError,\n} from './errors';\nimport {toError} from \"../lib/errorUtils\";\nimport {LogManager} from \"../logging/LogManager\";\nimport {ApiCallInfo, ApiSide} from \"./ApiCallInfo\";\nimport {ApiCallContextHolder} from \"./ApiCallContext\";\nimport {WebpiecesCoreHeaders} from \"./WebpiecesCoreHeaders\";\n\nconst log = LogManager.getLogger('LogApiCall');\n\n/**\n * Options for {@link LogApiCallImpl.execute}. `allowVoidResponse` opts OUT of the strict\n * falsy-response guard for callers that legitimately return void/undefined (e.g. a local firestore\n * wrapper). Defaults to strict so RPC callers keep the safety net.\n */\nexport class LogApiCallOptions {\n    allowVoidResponse?: boolean;\n\n    constructor(allowVoidResponse?: boolean) {\n        this.allowVoidResponse = allowVoidResponse;\n    }\n}\n\n/**\n * LogApiCall - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and\n * client-side (ProxyClient) for one consistent logging shape across the framework.\n *\n * TWO things happen around each call:\n * 1. Text lines are emitted (the human-readable `[API-...]` patterns below).\n * 2. A structured {@link ApiCallInfo} tag is stamped into the ambient request context via the\n *    {@link ApiCallContextHolder} seam, so EVERY log line emitted during the call (not just the\n *    req/resp lines) inherits a filterable `api` object — surfacing in GCP as\n *    `jsonPayload.api.{side,type,result,path,method}`.\n *\n * BROWSER-SAFE: this lives in core-util and runs in the browser bundle (via ProxyClient →\n * BrowserProxyClient), so it MUST NOT import `RequestContext` (Node async_hooks, and a circular dep).\n * It stamps through the {@link ApiCallContext} seam instead: `setupRuntime` installs a\n * RequestContext-backed impl on a Node server, and `ClientHttpBrowserFactory` a module-global impl in a\n * browser. If neither ran, {@link ApiCallContextHolder.get} throws (loud misconfiguration).\n *\n * Singleton, mirroring `RequestContext`: use the exported {@link LogApiCall} constant, not `new`.\n *\n * Logging format patterns:\n * - [API-{side}-req] ClassName.methodName request={...}\n * - [API-{side}-resp-SUCCESS] ClassName.methodName response={...}\n * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...}  (user errors)\n * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (server errors)\n */\nexport class LogApiCallImpl {\n\n    /**\n     * Execute an API call with logging + `api` context-tagging around it.\n     *\n     * @param side - 'client' (outbound call this process made) or 'server' (inbound call it handled)\n     * @param meta - Route metadata with controllerClassName and methodName\n     * @param requestDto - The request DTO\n     * @param method - The method to execute\n     * @param options - `allowVoidResponse: true` opts OUT of the strict falsy-response guard, for\n     *   callers that legitimately return void/undefined (e.g. a local firestore wrapper whose\n     *   `setDocument` returns void, or a `getDocById` miss returning undefined). Defaults to strict,\n     *   so RPC callers (LogApiFilter, ProxyClient) keep the safety net: an HTTP endpoint returning\n     *   nothing is almost always a bug.\n     *\n     * Correlation fields (requestId, tenantId, ...) are NOT stamped here — a logging BACKEND owns that,\n     * reading RequestContext on every record. What IS stamped here is the per-call `api` tag, and only\n     * for the SYNCHRONOUS span of each log line: set → log → remove. Because the tag is never held across\n     * `await method(...)`, a concurrent browser call (single-threaded, one global slot) can never clobber\n     * it. Cost: only the `[API-*]` req/resp lines carry `api`, not lines emitted mid-call — which is\n     * exactly what the GCP filters (`jsonPayload.api.*`) want.\n     */\n    public async execute(\n        side: ApiSide,\n        meta: RouteMetadata,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary (matches ProxyClient)\n        requestDto: any,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary\n        method: (dto: any) => Promise<any>,\n        options?: LogApiCallOptions\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary\n    ): Promise<any> {\n        // Throws if no ApiCallContext was installed at startup, or there is no active scope to stamp\n        // into (loud misconfiguration — an api call with nowhere to tag is a bug).\n        const ctx = ApiCallContextHolder.get();\n        if (!ctx.isActive()) {\n            throw new Error(\n                'LogApiCall requires an ACTIVE ApiCallContext. On a Node server, run inside the ' +\n                'RequestContext.run(...) a server filter opens; in a browser, build ClientHttpBrowserFactory first.',\n            );\n        }\n        const key = WebpiecesCoreHeaders.API_CALL_INFO;\n        const server = side === 'server';\n        const cls = meta.controllerClassName;\n        // set → emit → remove, as ONE synchronous span: the tag is live only while the logger reads it,\n        // never across an await, so a single browser global slot can never be clobbered by a concurrent call.\n        const stamp = (info: ApiCallInfo, emit: () => void): void => {\n            ctx.set(key, info);\n            emit();\n            ctx.remove(key);\n        };\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- LogApiCall logs errors before re-throwing to caller\n        try {\n            stamp(new ApiCallInfo(side, 'request', undefined, meta.path, meta.methodName, cls), () =>\n                log.info(`[API-${side}-req] ${cls}.${meta.methodName} ${meta.path} request=${JSON.stringify(requestDto)}`));\n\n            if(!requestDto)\n                throw new Error(`Request cannot be null and was from ${cls}.${meta.methodName}`);\n\n            const response = await method(requestDto);\n\n            if(!options?.allowVoidResponse && !response)\n                throw new Error(`Response cannot be null and was from ${cls}.${meta.methodName}`);\n\n            stamp(new ApiCallInfo(side, 'response', 'success', meta.path, meta.methodName, cls), () =>\n                log.info(`[API-${side}-resp-SUCCESS] ${cls}.${meta.methodName} response=${JSON.stringify(response)}`));\n\n            return response;\n        } catch (err: unknown) {\n            const error = toError(err);\n            const errorType = error.constructor.name;\n            const errorMessage = error.message;\n            // Side-dependent: a 4xx the SERVER raised is a handled non-failure (OTHER); the same 4xx a\n            // CLIENT receives means its call FAILED. HttpUserError (266) is never a failure, either side.\n            const isUser = this.isUserError(error, server);\n\n            stamp(new ApiCallInfo(side, 'response', isUser ? 'success' : 'failure', meta.path, meta.methodName, cls), () =>\n                isUser\n                    ? log.warn(`[API-${side}-resp-OTHER] ${cls}.${meta.methodName} errorType=${errorType}`)\n                    : log.error(`[API-${side}-resp-FAIL] ${cls}.${meta.methodName} errorType=${errorType} error=${errorMessage}`));\n            throw error;\n        }\n    }\n\n    /**\n     * Is this error a NON-failure for HEALTH/METRICS — the process working CORRECTLY (log OTHER, api\n     * result:'success') — rather than a real failure to surface (log FAIL, result:'failure')?\n     *\n     * The question is \"are things WORKING?\", NOT \"was it an HTTP 4xx vs 5xx\" — and the two are not the\n     * same (see 408 below). Classification is by portable Error TYPE, never by transport: LogApiCall runs\n     * deep in the stack (in-process calls, pubsub/queue handlers, HTTP — one code path) and only ever\n     * sees a thrown Error. The Http* classes are poorly named for that (the `Http` prefix is historical),\n     * but they ARE portable error types that travel with the throw anywhere, so matching the TYPE works\n     * with or without any HTTP in the picture. Do NOT swap this for an `error.code` 4xx range check — that\n     * both re-couples to HTTP AND would bury 408.\n     *\n     * SERVER — a healthy server correctly rejecting a CLIENT'S mistake is metrics NOISE, not a failure:\n     * - HttpBadRequestError (400)   \"your request is malformed\"\n     * - HttpUnauthorizedError (401) \"you're not authenticated\"\n     * - HttpForbiddenError (403)    \"authenticated, but not allowed\"\n     * - HttpNotFoundError (404)     \"wrong url / no such entity\" (EndpointNotFoundError is a subclass)\n     *   → the server is fine, the caller erred → result:'success', logged OTHER.\n     *\n     * SERVER — something may actually be WRONG, so SURFACE it (result:'failure', logged FAIL):\n     * - HttpTimeoutError (408): a 4xx, but the client may NEVER have seen the response — deliberately\n     *   absent from the list below so it counts as a failure.\n     * - 500 / 502 / 504 / 598, and any non-Http Error: real failures.\n     *\n     * HttpUserError (266): ALWAYS a non-failure, server OR client — an expected \"user made a mistake\" signal.\n     * CLIENT: receiving ANY error except 266 means the outbound call FAILED → result:'failure'.\n     *\n     * @param error  - The already-normalized error (callers pass toError(err), never a raw catch value)\n     * @param server - True when this side is the SERVER handling an inbound call; false for a CLIENT's outbound call\n     * @returns true if this should be treated as a non-failure (OTHER / result:'success')\n     */\n    isUserError(error: Error, server: boolean): boolean {\n        // 266 is the one error that is never a failure, on either side.\n        if (error instanceof HttpUserError) {\n            return true;\n        }\n        // A client that RECEIVED any error (except the 266 above) made a failed call.\n        if (!server) {\n            return false;\n        }\n        // SERVER: only a healthy rejection of the caller's mistake is a non-failure. Note 408\n        // (HttpTimeoutError) is intentionally NOT here — the client may never have seen the response.\n        return (\n            error instanceof HttpBadRequestError ||\n            error instanceof HttpUnauthorizedError ||\n            error instanceof HttpForbiddenError ||\n            error instanceof HttpNotFoundError\n        );\n    }\n}\n\n/**\n * The process-wide {@link LogApiCallImpl} singleton — mirrors the `RequestContext` export pattern.\n * Callers use `LogApiCall.execute(...)`, never `new`.\n */\nexport const LogApiCall = new LogApiCallImpl();\n"]}

package/src/http/decorators.d.ts

@@ -11,7 +11,21 @@ export declare const METADATA_KEYS: {
     API_KIND: string;
     /** Per-method Cloud Tasks queue-name override (set via @Queue). */
     QUEUE_OVERRIDE: string;
+    /** Per-method @Endpoint options (e.g. formPost), parallel to ENDPOINTS. */
+    ENDPOINT_OPTIONS: string;
 };
+/**
+ * Options for a single @Endpoint. Kept in a metadata map PARALLEL to ENDPOINTS so the existing
+ * `Record<methodName, path>` shape every consumer iterates stays unchanged.
+ */
+export interface EndpointOptions {
+    /**
+     * Parse the request body as application/x-www-form-urlencoded (flat key→value) instead of JSON.
+     * For EXTERNAL webhooks (e.g. Twilio) that post form-encoded. The request DTO must be FLAT —
+     * urlencoded has no nesting (unlike JSON). Default false = JSON.
+     */
+    formPost?: boolean;
+}
 /**
  * Route metadata stored per-method at runtime.
  * Used internally by http-routing and http-client as the runtime representation
@@ -26,7 +40,13 @@ export declare class RouteMetadata {
     authMeta?: AuthMeta;
     /** The API contract class name (e.g. 'SaveApi') — distinct from the controller name. */
     apiName?: string;
-    constructor(httpMethod: string, path: string, methodName: string, controllerClassName?: string, authMeta?: AuthMeta, apiName?: string);
+    /**
+     * True when @Endpoint(..., { formPost: true }): the body is application/x-www-form-urlencoded
+     * (flat key→value), not JSON. Rides the route metadata so the per-route body parse can branch
+     * without knowing the apiClass/methodName. Default false = JSON.
+     */
+    readonly formPost: boolean;
+    constructor(httpMethod: string, path: string, methodName: string, controllerClassName?: string, authMeta?: AuthMeta, apiName?: string, formPost?: boolean);
 }
 /**
  * The service-to-service / user auth mode of an endpoint. Discriminated union so
@@ -92,7 +112,7 @@ export declare class AuthMeta {
  */
 export declare function ApiPath(basePath: string): ClassDecorator;
 /**
- * @Endpoint(path) - Method decorator that registers a POST endpoint at the given path.
+ * @Endpoint(path, options?) - Method decorator that registers a POST endpoint at the given path.
  *
  * All endpoints are POST-only (matching gRPC/thrift style).
  *
@@ -100,9 +120,16 @@ export declare function ApiPath(basePath: string): ClassDecorator;
  * ```typescript
  * @Endpoint('/item')
  * save(request: SaveRequest): Promise<SaveResponse> { ... }
+ *
+ * // EXTERNAL webhook posting application/x-www-form-urlencoded (e.g. Twilio):
+ * @Endpoint('/hook', { formPost: true })
+ * inbound(request: InboundRequest): Promise<InboundResponse> { ... }
  * ```
+ *
+ * The path write to ENDPOINTS is UNCHANGED (every consumer iterates `[methodName, path]`); options
+ * ride a PARALLEL ENDPOINT_OPTIONS map so nothing downstream changes shape.
  */
-export declare function Endpoint(path: string): MethodDecorator;
+export declare function Endpoint(path: string, options?: EndpointOptions): MethodDecorator;
 /**
  * Authentication config passed to @Authentication() decorator.
  */
@@ -167,6 +194,15 @@ export declare function getApiPath(apiClass: Function): string | undefined;
  * Returns a record of methodName -> endpoint path.
  */
 export declare function getEndpoints(apiClass: Function): Record<string, string> | undefined;
+/**
+ * Get the @Endpoint options for one method (empty object if the method had no options).
+ */
+export declare function getEndpointOptions(apiClass: Function, methodName: string): EndpointOptions;
+/**
+ * True when the method's @Endpoint declared `{ formPost: true }` — its body is
+ * application/x-www-form-urlencoded (flat), not JSON.
+ */
+export declare function isFormPost(apiClass: Function, methodName: string): boolean;
 /**
  * Check if a class has @ApiPath decorator.
  */

package/src/http/decorators.js

@@ -11,6 +11,8 @@ exports.AuthOidc = AuthOidc;
 exports.AuthSharedSecret = AuthSharedSecret;
 exports.getApiPath = getApiPath;
 exports.getEndpoints = getEndpoints;
+exports.getEndpointOptions = getEndpointOptions;
+exports.isFormPost = isFormPost;
 exports.isApiPath = isApiPath;
 exports.getAuthMeta = getAuthMeta;
 exports.getAuthMode = getAuthMode;
@@ -36,6 +38,8 @@ exports.METADATA_KEYS = {
     API_KIND: 'webpieces:api-kind',
     /** Per-method Cloud Tasks queue-name override (set via @Queue). */
     QUEUE_OVERRIDE: 'webpieces:queue-override',
+    /** Per-method @Endpoint options (e.g. formPost), parallel to ENDPOINTS. */
+    ENDPOINT_OPTIONS: 'webpieces:endpoint-options',
 };
 /**
  * Route metadata stored per-method at runtime.
@@ -51,13 +55,20 @@ class RouteMetadata {
     authMeta;
     /** The API contract class name (e.g. 'SaveApi') — distinct from the controller name. */
     apiName;
-    constructor(httpMethod, path, methodName, controllerClassName, authMeta, apiName) {
+    /**
+     * True when @Endpoint(..., { formPost: true }): the body is application/x-www-form-urlencoded
+     * (flat key→value), not JSON. Rides the route metadata so the per-route body parse can branch
+     * without knowing the apiClass/methodName. Default false = JSON.
+     */
+    formPost;
+    constructor(httpMethod, path, methodName, controllerClassName, authMeta, apiName, formPost = false) {
         this.httpMethod = httpMethod;
         this.path = path;
         this.methodName = methodName;
         this.controllerClassName = controllerClassName;
         this.authMeta = authMeta;
         this.apiName = apiName;
+        this.formPost = formPost;
     }
 }
 exports.RouteMetadata = RouteMetadata;
@@ -109,7 +120,7 @@ function ApiPath(basePath) {
     };
 }
 /**
- * @Endpoint(path) - Method decorator that registers a POST endpoint at the given path.
+ * @Endpoint(path, options?) - Method decorator that registers a POST endpoint at the given path.
  *
  * All endpoints are POST-only (matching gRPC/thrift style).
  *
@@ -117,15 +128,26 @@ function ApiPath(basePath) {
  * ```typescript
  * @Endpoint('/item')
  * save(request: SaveRequest): Promise<SaveResponse> { ... }
+ *
+ * // EXTERNAL webhook posting application/x-www-form-urlencoded (e.g. Twilio):
+ * @Endpoint('/hook', { formPost: true })
+ * inbound(request: InboundRequest): Promise<InboundResponse> { ... }
  * ```
+ *
+ * The path write to ENDPOINTS is UNCHANGED (every consumer iterates `[methodName, path]`); options
+ * ride a PARALLEL ENDPOINT_OPTIONS map so nothing downstream changes shape.
  */
-function Endpoint(path) {
+// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
+function Endpoint(path, options = {}) {
     // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
     return (target, propertyKey, _descriptor) => {
         const metadataTarget = typeof target === 'function' ? target : target.constructor;
         const endpoints = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINTS, metadataTarget) || {};
         endpoints[propertyKey] = path;
         Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINTS, endpoints, metadataTarget);
+        const opts = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_OPTIONS, metadataTarget) || {};
+        opts[propertyKey] = options;
+        Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINT_OPTIONS, opts, metadataTarget);
     };
 }
 /**
@@ -245,6 +267,22 @@ function getApiPath(apiClass) {
 function getEndpoints(apiClass) {
     return Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINTS, apiClass);
 }
+/**
+ * Get the @Endpoint options for one method (empty object if the method had no options).
+ */
+// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints
+function getEndpointOptions(apiClass, methodName) {
+    const opts = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_OPTIONS, apiClass) || {};
+    return opts[methodName] ?? {};
+}
+/**
+ * True when the method's @Endpoint declared `{ formPost: true }` — its body is
+ * application/x-www-form-urlencoded (flat), not JSON.
+ */
+// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints
+function isFormPost(apiClass, methodName) {
+    return getEndpointOptions(apiClass, methodName).formPost === true;
+}
 /**
  * Check if a class has @ApiPath decorator.
  */

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';\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    /** '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};\n\n/**\n * Route metadata stored per-method at runtime.\n * Used internally by http-routing and http-client as the runtime representation\n * of a route. Constructed from @ApiPath + @Endpoint metadata by ProxyClient\n * and ApiRoutingFactory.\n */\nexport class RouteMetadata {\n    httpMethod: string;\n    path: string;\n    methodName: string;\n    controllerClassName?: string;\n    authMeta?: AuthMeta;\n    /** The API contract class name (e.g. 'SaveApi') — distinct from the controller name. */\n    apiName?: string;\n\n    constructor(\n        httpMethod: string,\n        path: string,\n        methodName: string,\n        controllerClassName?: string,\n        authMeta?: AuthMeta,\n        apiName?: string,\n    ) {\n        this.httpMethod = httpMethod;\n        this.path = path;\n        this.methodName = methodName;\n        this.controllerClassName = controllerClassName;\n        this.authMeta = authMeta;\n        this.apiName = apiName;\n    }\n}\n\n/**\n * The service-to-service / user auth mode of an endpoint. Discriminated union so\n * a filter can `switch (mode.kind)` and get the data it needs, exhaustively.\n *\n * - `public`        → no auth check\n * - `jwt`           → user-facing JWT (optionally role-gated), validated by the app AuthFilter\n * - `oidc`          → Google OIDC service-to-service (Cloud Tasks delivery / cross-service RPC);\n *                     `callers` is the allow-list of caller service accounts ('self' = this service's SA)\n * - `shared-secret` → constant-time compare of a header against the secret bound for `secretKey`\n */\n/**\n * JwtRequirement - the endpoint's JWT authorization requirement, OPAQUE to the framework. The\n * default JwtHook.authorizeJwt enforces `roles` (any-of; empty = any authenticated user); apps\n * add their OWN fields (inOrg, tenant, feature, ...) via @Auth({...}) and override authorizeJwt to\n * enforce them. This is the pluggable seam: the framework authenticates, the app authorizes.\n */\nexport interface JwtRequirement {\n    roles?: string[];\n    // webpieces-disable no-any-unknown -- app-defined authorization fields (inOrg, tenant, ...)\n    [field: string]: unknown;\n}\n\nexport type AuthMode =\n    | { kind: 'public' }\n    | { kind: 'jwt'; requirement: JwtRequirement }\n    | { kind: 'oidc'; callers: string[] }\n    | { kind: 'shared-secret'; secretKey: string };\n\n/**\n * Auth metadata attached to a class or method via one of the auth decorators\n * (@Public / @AuthJwt / @AuthOidc / @AuthSharedSecret) or the legacy @Authentication.\n *\n * Carries a discriminated {@link AuthMode}. The `authenticated`/`roles` getters are\n * kept for back-compat with readers that only understand the user-JWT model\n * (e.g. the example AuthFilter).\n */\nexport class AuthMeta {\n    mode: AuthMode;\n\n    constructor(mode: AuthMode) {\n        this.mode = mode;\n    }\n\n    /** True for every non-public mode (jwt, oidc, shared-secret). */\n    get authenticated(): boolean {\n        return this.mode.kind !== 'public';\n    }\n\n    /** JWT roles, or empty for non-jwt modes (back-compat convenience over the requirement). */\n    get roles(): string[] {\n        return this.mode.kind === 'jwt' ? (this.mode.requirement.roles ?? []) : [];\n    }\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 * @Authentication({authenticated: true})\n * @ApiPath('/api/save')\n * abstract class SaveApi {\n *   @Endpoint('/item')\n *   save(request: SaveRequest): Promise<SaveResponse> { ... }\n * }\n * ```\n */\nexport function ApiPath(basePath: string): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\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) - Method decorator that registers a POST endpoint at the given path.\n *\n * All endpoints are POST-only (matching gRPC/thrift style).\n *\n * Usage:\n * ```typescript\n * @Endpoint('/item')\n * save(request: SaveRequest): Promise<SaveResponse> { ... }\n * ```\n */\nexport function Endpoint(path: string): 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}\n\n/**\n * Authentication config passed to @Authentication() decorator.\n */\nexport class AuthenticationConfig {\n    authenticated: boolean;\n    roles?: string[];\n\n    constructor(authenticated: boolean, roles?: string[]) {\n        this.authenticated = authenticated;\n        this.roles = roles;\n    }\n}\n\n/**\n * @Authentication(config) - Class or method decorator for auth requirements.\n *\n * Single decorator replaces @Public/@Authenticated/@Roles:\n * - @Authentication({authenticated: false}) → public, no auth check\n * - @Authentication({authenticated: true}) → requires authentication\n * - @Authentication({authenticated: true, roles: ['admin']}) → requires auth + roles\n *\n * Class-level is required. Methods can override class-level.\n * Throws if authenticated=false but roles are specified (contradictory).\n */\nexport function Authentication(config: AuthenticationConfig): ClassDecorator & MethodDecorator {\n    // Validate: can't be public with roles\n    if (!config.authenticated && config.roles && config.roles.length > 0) {\n        throw new Error(\n            `Invalid @Authentication config: authenticated=false but roles=${JSON.stringify(config.roles)}. ` +\n            `Cannot require roles on a public endpoint. Set authenticated=true or remove roles.`\n        );\n    }\n\n    const mode: AuthMode = config.authenticated\n        ? { kind: 'jwt', requirement: { roles: config.roles ?? [] } }\n        : { kind: 'public' };\n    return defineAuthMode(mode);\n}\n\n/**\n * Shared implementation for every auth decorator: stores an {@link AuthMeta} for\n * the given {@link AuthMode} at class- or method-level, rejecting a second auth\n * decorator on the same target.\n */\nfunction defineAuthMode(mode: AuthMode): ClassDecorator & 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            // Method decorator\n            const metadataTarget = typeof target === 'function' ? target : target.constructor;\n            validateNoConflictingDecorators(metadataTarget, propertyKey as string);\n            Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, metadataTarget, propertyKey);\n        } else {\n            // Class decorator\n            validateNoConflictingDecorators(target, undefined);\n            Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, target);\n        }\n    };\n}\n\n/**\n * @Public() - endpoint requires no authentication. Class- or method-level.\n */\nexport function Public(): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'public' });\n}\n\n/**\n * @AuthJwt(...roles) - user-facing JWT auth, optionally role-gated. The app-level\n * AuthFilter validates the token; roles=[] means \"any authenticated user\".\n */\nexport function AuthJwt(...roles: string[]): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'jwt', requirement: { roles } });\n}\n\n/**\n * @Auth(requirement) - user-facing JWT auth with an APP-DEFINED authorization requirement beyond\n * roles, e.g. `@Auth({ inOrg: true })` or `@Auth({ roles: ['admin'], tenantScoped: true })`. The\n * framework authenticates the JWT (JwtHook.parseJwt), then hands `requirement` + the parsed\n * values to JwtHook.authorizeJwt — which the app overrides to enforce its own policy. This is\n * how clients plug in their own JWT security without touching the framework.\n */\nexport function Auth(requirement: JwtRequirement): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'jwt', requirement });\n}\n\n/**\n * @AuthOidc(...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 (`@AuthOidc('svc-a')`) only when you want\n * an additional app-level allow-list as defense-in-depth.\n */\nexport function AuthOidc(...callers: string[]): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'oidc', callers });\n}\n\n/**\n * @AuthSharedSecret(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 */\nexport function AuthSharedSecret(key: string): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'shared-secret', secretKey: key });\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 * 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 auth metadata for a specific method, falling back to class-level auth.\n * Method-level auth takes precedence over class-level auth.\n */\nexport function getAuthMeta(apiClass: Function, methodName?: string): AuthMeta | undefined {\n    // Check method-level first\n    if (methodName) {\n        const methodAuth = Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName);\n        if (methodAuth) {\n            return methodAuth;\n        }\n    }\n\n    // Fall back to class-level\n    return Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass);\n}\n\n/**\n * Get the auth mode for a method (falling back to class-level), or undefined.\n * Convenience wrapper over getAuthMeta for callers that only want the mode.\n */\nexport function getAuthMode(apiClass: Function, methodName?: string): AuthMode | undefined {\n    return getAuthMeta(apiClass, methodName)?.mode;\n}\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 @Authentication/@Public/@Auth* decorator.\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                `Add @Public(), @AuthJwt(...), @AuthOidc(...) or @AuthSharedSecret(...) ` +\n                `to the class or method.`,\n            );\n        }\n    }\n}\n\n// ============================================================\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming\n// ============================================================\n\n/**\n * API kind. 'rpc' = synchronous request/response (http-client ↔ ApiRoutingFactory).\n * 'pubsub' = fire-and-forget cloud task; the enqueue client (cloudtasks-client)\n * schedules a Cloud Task that is later delivered to the SAME controller endpoint.\n */\nexport type ApiKind = 'rpc' | 'pubsub';\n\n/**\n * @Rpc() - marks an API class as synchronous request/response (the default kind).\n * Present mostly for symmetry/readability; an undecorated API is treated as 'rpc'.\n */\nexport function Rpc(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'rpc' as ApiKind, target);\n    };\n}\n\n/**\n * @PubSub() - marks an API class as fire-and-forget over Cloud Tasks. Every method\n * MUST return Promise<void> (a compile-time contract on the abstract API). The\n * enqueue client and the controller share this one class, exactly like RPC.\n */\nexport function PubSub(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'pubsub' as ApiKind, target);\n    };\n}\n\n/**\n * @Queue(name) - override the Cloud Tasks queue name for a @PubSub method. Default\n * (no decorator) is `${ApiClassName}-${methodName}`, matched 1:1 by Terraform.\n */\nexport function Queue(name: string): 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        const overrides: Record<string, string> =\n            Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, metadataTarget) || {};\n        overrides[propertyKey as string] = name;\n        Reflect.defineMetadata(METADATA_KEYS.QUEUE_OVERRIDE, overrides, metadataTarget);\n    };\n}\n\n/**\n * Get the API kind. Defaults to 'rpc' when neither @Rpc nor @PubSub is present.\n */\nexport function getApiKind(apiClass: Function): ApiKind {\n    return (Reflect.getMetadata(METADATA_KEYS.API_KIND, apiClass) as ApiKind) ?? 'rpc';\n}\n\n/**\n * Assert the API class is of the expected kind (used by the clients: the RPC\n * client rejects a @PubSub api and vice-versa).\n * @throws Error if the kind doesn't match.\n */\nexport function assertApiKind(apiClass: Function, expected: ApiKind): void {\n    const actual = getApiKind(apiClass);\n    if (actual !== expected) {\n        const apiName = apiClass.name || 'Unknown';\n        throw new Error(\n            `API ${apiName} is @${actual === 'pubsub' ? 'PubSub' : 'Rpc'} but a ` +\n            `${expected === 'pubsub' ? '@PubSub (cloud task)' : '@Rpc'} API was required here.`,\n        );\n    }\n}\n\n/**\n * Validate @PubSub conventions at wiring time: the class must be @ApiPath + @PubSub\n * and declare at least one endpoint. (Return-type is Promise<void>, a compile-time\n * contract — TS erases types at runtime so it cannot be re-checked here.)\n * @throws Error if conventions are violated.\n */\nexport function assertPubSubConventions(apiClass: Function): void {\n    assertApiKind(apiClass, 'pubsub');\n    const apiName = apiClass.name || 'Unknown';\n    if (!isApiPath(apiClass)) {\n        throw new Error(`@PubSub API ${apiName} must also be decorated with @ApiPath()`);\n    }\n    const endpoints = getEndpoints(apiClass) || {};\n    if (Object.keys(endpoints).length === 0) {\n        throw new Error(`@PubSub API ${apiName} declares no @Endpoint methods`);\n    }\n}\n\n/**\n * Resolve the Cloud Tasks queue name for a @PubSub method: the @Queue override if\n * present, else `${ApiClassName}-${methodName}`.\n */\nexport function getQueueName(apiClass: Function, methodName: string): string {\n    const overrides: Record<string, string> =\n        Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, apiClass) || {};\n    return overrides[methodName] ?? `${apiClass.name || 'Unknown'}-${methodName}`;\n}\n\n/**\n * Validate that a class/method doesn't have conflicting auth decorators.\n * @throws Error if multiple @Authentication decorators are found on the same target.\n */\nexport function validateNoConflictingDecorators(apiClass: Function, methodName: string | undefined): 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 ? `method '${methodName}' of ${targetName}` : `class ${targetName}`;\n        throw new Error(\n            `Conflicting @Authentication on ${location}. ` +\n            `Only one @Authentication() decorator allowed per target.`\n        );\n    }\n}\n"]}
+{"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';\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    /** '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};\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/**\n * Route metadata stored per-method at runtime.\n * Used internally by http-routing and http-client as the runtime representation\n * of a route. Constructed from @ApiPath + @Endpoint metadata by ProxyClient\n * and ApiRoutingFactory.\n */\nexport class RouteMetadata {\n    httpMethod: string;\n    path: string;\n    methodName: string;\n    controllerClassName?: string;\n    authMeta?: AuthMeta;\n    /** The API contract class name (e.g. 'SaveApi') — distinct from the controller name. */\n    apiName?: string;\n    /**\n     * True when @Endpoint(..., { formPost: true }): the body is application/x-www-form-urlencoded\n     * (flat key→value), not JSON. Rides the route metadata so the per-route body parse can branch\n     * without knowing the apiClass/methodName. Default false = JSON.\n     */\n    readonly formPost: boolean;\n\n    constructor(\n        httpMethod: string,\n        path: string,\n        methodName: string,\n        controllerClassName?: string,\n        authMeta?: AuthMeta,\n        apiName?: string,\n        formPost: boolean = false,\n    ) {\n        this.httpMethod = httpMethod;\n        this.path = path;\n        this.methodName = methodName;\n        this.controllerClassName = controllerClassName;\n        this.authMeta = authMeta;\n        this.apiName = apiName;\n        this.formPost = formPost;\n    }\n}\n\n/**\n * The service-to-service / user auth mode of an endpoint. Discriminated union so\n * a filter can `switch (mode.kind)` and get the data it needs, exhaustively.\n *\n * - `public`        → no auth check\n * - `jwt`           → user-facing JWT (optionally role-gated), validated by the app AuthFilter\n * - `oidc`          → Google OIDC service-to-service (Cloud Tasks delivery / cross-service RPC);\n *                     `callers` is the allow-list of caller service accounts ('self' = this service's SA)\n * - `shared-secret` → constant-time compare of a header against the secret bound for `secretKey`\n */\n/**\n * JwtRequirement - the endpoint's JWT authorization requirement, OPAQUE to the framework. The\n * default JwtHook.authorizeJwt enforces `roles` (any-of; empty = any authenticated user); apps\n * add their OWN fields (inOrg, tenant, feature, ...) via @Auth({...}) and override authorizeJwt to\n * enforce them. This is the pluggable seam: the framework authenticates, the app authorizes.\n */\nexport interface JwtRequirement {\n    roles?: string[];\n    // webpieces-disable no-any-unknown -- app-defined authorization fields (inOrg, tenant, ...)\n    [field: string]: unknown;\n}\n\nexport type AuthMode =\n    | { kind: 'public' }\n    | { kind: 'jwt'; requirement: JwtRequirement }\n    | { kind: 'oidc'; callers: string[] }\n    | { kind: 'shared-secret'; secretKey: string };\n\n/**\n * Auth metadata attached to a class or method via one of the auth decorators\n * (@Public / @AuthJwt / @AuthOidc / @AuthSharedSecret) or the legacy @Authentication.\n *\n * Carries a discriminated {@link AuthMode}. The `authenticated`/`roles` getters are\n * kept for back-compat with readers that only understand the user-JWT model\n * (e.g. the example AuthFilter).\n */\nexport class AuthMeta {\n    mode: AuthMode;\n\n    constructor(mode: AuthMode) {\n        this.mode = mode;\n    }\n\n    /** True for every non-public mode (jwt, oidc, shared-secret). */\n    get authenticated(): boolean {\n        return this.mode.kind !== 'public';\n    }\n\n    /** JWT roles, or empty for non-jwt modes (back-compat convenience over the requirement). */\n    get roles(): string[] {\n        return this.mode.kind === 'jwt' ? (this.mode.requirement.roles ?? []) : [];\n    }\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 * @Authentication({authenticated: true})\n * @ApiPath('/api/save')\n * abstract class SaveApi {\n *   @Endpoint('/item')\n *   save(request: SaveRequest): Promise<SaveResponse> { ... }\n * }\n * ```\n */\nexport function ApiPath(basePath: string): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\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, options?) - Method decorator that registers a POST endpoint at the given path.\n *\n * All endpoints are POST-only (matching gRPC/thrift style).\n *\n * Usage:\n * ```typescript\n * @Endpoint('/item')\n * save(request: SaveRequest): Promise<SaveResponse> { ... }\n *\n * // EXTERNAL webhook posting application/x-www-form-urlencoded (e.g. Twilio):\n * @Endpoint('/hook', { formPost: true })\n * inbound(request: InboundRequest): Promise<InboundResponse> { ... }\n * ```\n *\n * The path write to ENDPOINTS is UNCHANGED (every consumer iterates `[methodName, path]`); options\n * ride a PARALLEL ENDPOINT_OPTIONS map so nothing downstream changes shape.\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(path: string, options: EndpointOptions = {}): 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 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}\n\n/**\n * Authentication config passed to @Authentication() decorator.\n */\nexport class AuthenticationConfig {\n    authenticated: boolean;\n    roles?: string[];\n\n    constructor(authenticated: boolean, roles?: string[]) {\n        this.authenticated = authenticated;\n        this.roles = roles;\n    }\n}\n\n/**\n * @Authentication(config) - Class or method decorator for auth requirements.\n *\n * Single decorator replaces @Public/@Authenticated/@Roles:\n * - @Authentication({authenticated: false}) → public, no auth check\n * - @Authentication({authenticated: true}) → requires authentication\n * - @Authentication({authenticated: true, roles: ['admin']}) → requires auth + roles\n *\n * Class-level is required. Methods can override class-level.\n * Throws if authenticated=false but roles are specified (contradictory).\n */\nexport function Authentication(config: AuthenticationConfig): ClassDecorator & MethodDecorator {\n    // Validate: can't be public with roles\n    if (!config.authenticated && config.roles && config.roles.length > 0) {\n        throw new Error(\n            `Invalid @Authentication config: authenticated=false but roles=${JSON.stringify(config.roles)}. ` +\n            `Cannot require roles on a public endpoint. Set authenticated=true or remove roles.`\n        );\n    }\n\n    const mode: AuthMode = config.authenticated\n        ? { kind: 'jwt', requirement: { roles: config.roles ?? [] } }\n        : { kind: 'public' };\n    return defineAuthMode(mode);\n}\n\n/**\n * Shared implementation for every auth decorator: stores an {@link AuthMeta} for\n * the given {@link AuthMode} at class- or method-level, rejecting a second auth\n * decorator on the same target.\n */\nfunction defineAuthMode(mode: AuthMode): ClassDecorator & 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            // Method decorator\n            const metadataTarget = typeof target === 'function' ? target : target.constructor;\n            validateNoConflictingDecorators(metadataTarget, propertyKey as string);\n            Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, metadataTarget, propertyKey);\n        } else {\n            // Class decorator\n            validateNoConflictingDecorators(target, undefined);\n            Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, target);\n        }\n    };\n}\n\n/**\n * @Public() - endpoint requires no authentication. Class- or method-level.\n */\nexport function Public(): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'public' });\n}\n\n/**\n * @AuthJwt(...roles) - user-facing JWT auth, optionally role-gated. The app-level\n * AuthFilter validates the token; roles=[] means \"any authenticated user\".\n */\nexport function AuthJwt(...roles: string[]): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'jwt', requirement: { roles } });\n}\n\n/**\n * @Auth(requirement) - user-facing JWT auth with an APP-DEFINED authorization requirement beyond\n * roles, e.g. `@Auth({ inOrg: true })` or `@Auth({ roles: ['admin'], tenantScoped: true })`. The\n * framework authenticates the JWT (JwtHook.parseJwt), then hands `requirement` + the parsed\n * values to JwtHook.authorizeJwt — which the app overrides to enforce its own policy. This is\n * how clients plug in their own JWT security without touching the framework.\n */\nexport function Auth(requirement: JwtRequirement): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'jwt', requirement });\n}\n\n/**\n * @AuthOidc(...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 (`@AuthOidc('svc-a')`) only when you want\n * an additional app-level allow-list as defense-in-depth.\n */\nexport function AuthOidc(...callers: string[]): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'oidc', callers });\n}\n\n/**\n * @AuthSharedSecret(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 */\nexport function AuthSharedSecret(key: string): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'shared-secret', secretKey: key });\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 * 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 * 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 * 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 auth metadata for a specific method, falling back to class-level auth.\n * Method-level auth takes precedence over class-level auth.\n */\nexport function getAuthMeta(apiClass: Function, methodName?: string): AuthMeta | undefined {\n    // Check method-level first\n    if (methodName) {\n        const methodAuth = Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName);\n        if (methodAuth) {\n            return methodAuth;\n        }\n    }\n\n    // Fall back to class-level\n    return Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass);\n}\n\n/**\n * Get the auth mode for a method (falling back to class-level), or undefined.\n * Convenience wrapper over getAuthMeta for callers that only want the mode.\n */\nexport function getAuthMode(apiClass: Function, methodName?: string): AuthMode | undefined {\n    return getAuthMeta(apiClass, methodName)?.mode;\n}\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 @Authentication/@Public/@Auth* decorator.\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                `Add @Public(), @AuthJwt(...), @AuthOidc(...) or @AuthSharedSecret(...) ` +\n                `to the class or method.`,\n            );\n        }\n    }\n}\n\n// ============================================================\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming\n// ============================================================\n\n/**\n * API kind. 'rpc' = synchronous request/response (http-client ↔ ApiRoutingFactory).\n * 'pubsub' = fire-and-forget cloud task; the enqueue client (cloudtasks-client)\n * schedules a Cloud Task that is later delivered to the SAME controller endpoint.\n */\nexport type ApiKind = 'rpc' | 'pubsub';\n\n/**\n * @Rpc() - marks an API class as synchronous request/response (the default kind).\n * Present mostly for symmetry/readability; an undecorated API is treated as 'rpc'.\n */\nexport function Rpc(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'rpc' as ApiKind, target);\n    };\n}\n\n/**\n * @PubSub() - marks an API class as fire-and-forget over Cloud Tasks. Every method\n * MUST return Promise<void> (a compile-time contract on the abstract API). The\n * enqueue client and the controller share this one class, exactly like RPC.\n */\nexport function PubSub(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'pubsub' as ApiKind, target);\n    };\n}\n\n/**\n * @Queue(name) - override the Cloud Tasks queue name for a @PubSub method. Default\n * (no decorator) is `${ApiClassName}-${methodName}`, matched 1:1 by Terraform.\n */\nexport function Queue(name: string): 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        const overrides: Record<string, string> =\n            Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, metadataTarget) || {};\n        overrides[propertyKey as string] = name;\n        Reflect.defineMetadata(METADATA_KEYS.QUEUE_OVERRIDE, overrides, metadataTarget);\n    };\n}\n\n/**\n * Get the API kind. Defaults to 'rpc' when neither @Rpc nor @PubSub is present.\n */\nexport function getApiKind(apiClass: Function): ApiKind {\n    return (Reflect.getMetadata(METADATA_KEYS.API_KIND, apiClass) as ApiKind) ?? 'rpc';\n}\n\n/**\n * Assert the API class is of the expected kind (used by the clients: the RPC\n * client rejects a @PubSub api and vice-versa).\n * @throws Error if the kind doesn't match.\n */\nexport function assertApiKind(apiClass: Function, expected: ApiKind): void {\n    const actual = getApiKind(apiClass);\n    if (actual !== expected) {\n        const apiName = apiClass.name || 'Unknown';\n        throw new Error(\n            `API ${apiName} is @${actual === 'pubsub' ? 'PubSub' : 'Rpc'} but a ` +\n            `${expected === 'pubsub' ? '@PubSub (cloud task)' : '@Rpc'} API was required here.`,\n        );\n    }\n}\n\n/**\n * Validate @PubSub conventions at wiring time: the class must be @ApiPath + @PubSub\n * and declare at least one endpoint. (Return-type is Promise<void>, a compile-time\n * contract — TS erases types at runtime so it cannot be re-checked here.)\n * @throws Error if conventions are violated.\n */\nexport function assertPubSubConventions(apiClass: Function): void {\n    assertApiKind(apiClass, 'pubsub');\n    const apiName = apiClass.name || 'Unknown';\n    if (!isApiPath(apiClass)) {\n        throw new Error(`@PubSub API ${apiName} must also be decorated with @ApiPath()`);\n    }\n    const endpoints = getEndpoints(apiClass) || {};\n    if (Object.keys(endpoints).length === 0) {\n        throw new Error(`@PubSub API ${apiName} declares no @Endpoint methods`);\n    }\n}\n\n/**\n * Resolve the Cloud Tasks queue name for a @PubSub method: the @Queue override if\n * present, else `${ApiClassName}-${methodName}`.\n */\nexport function getQueueName(apiClass: Function, methodName: string): string {\n    const overrides: Record<string, string> =\n        Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, apiClass) || {};\n    return overrides[methodName] ?? `${apiClass.name || 'Unknown'}-${methodName}`;\n}\n\n/**\n * Validate that a class/method doesn't have conflicting auth decorators.\n * @throws Error if multiple @Authentication decorators are found on the same target.\n */\nexport function validateNoConflictingDecorators(apiClass: Function, methodName: string | undefined): 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 ? `method '${methodName}' of ${targetName}` : `class ${targetName}`;\n        throw new Error(\n            `Conflicting @Authentication on ${location}. ` +\n            `Only one @Authentication() decorator allowed per target.`\n        );\n    }\n}\n"]}

package/src/index.d.ts

@@ -15,8 +15,8 @@ export type { LoggerFactory } from './logging/LoggerFactory';
 export { ConsoleLogger } from './logging/ConsoleLogger';
 export { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';
 export { LogManager } from './logging/LogManager';
-export { ApiPath, Endpoint, Authentication, AuthenticationConfig, Public, AuthJwt, Auth, AuthOidc, AuthSharedSecret, Rpc, PubSub, Queue, getApiPath, getEndpoints, isApiPath, getAuthMeta, getAuthMode, assertEveryEndpointHasAuthMode, getApiKind, assertApiKind, assertPubSubConventions, getQueueName, validateNoConflictingDecorators, AuthMeta, RouteMetadata, METADATA_KEYS, } from './http/decorators';
-export type { AuthMode, ApiKind, JwtRequirement } from './http/decorators';
+export { ApiPath, Endpoint, Authentication, AuthenticationConfig, Public, AuthJwt, Auth, AuthOidc, AuthSharedSecret, Rpc, PubSub, Queue, getApiPath, getEndpoints, getEndpointOptions, isFormPost, isApiPath, getAuthMeta, getAuthMode, assertEveryEndpointHasAuthMode, getApiKind, assertApiKind, assertPubSubConventions, getQueueName, validateNoConflictingDecorators, AuthMeta, RouteMetadata, METADATA_KEYS, } from './http/decorators';
+export type { AuthMode, ApiKind, JwtRequirement, EndpointOptions } from './http/decorators';
 export { Secrets } from './http/Secrets';
 export { ValidateImplementation } from './http/validators';
 export { ProtocolError, HttpError, HttpNotFoundError, EndpointNotFoundError, HttpBadRequestError, HttpUnauthorizedError, HttpForbiddenError, HttpTimeoutError, HttpBadGatewayError, HttpGatewayTimeoutError, HttpInternalServerError, HttpVendorError, HttpUserError, ENTITY_NOT_FOUND, WRONG_LOGIN_TYPE, WRONG_LOGIN, NOT_APPROVED, EMAIL_NOT_CONFIRMED, WRONG_DOMAIN, WRONG_COMPANY, NO_REG_CODE, } from './http/errors';
@@ -31,7 +31,7 @@ export { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';
 export { ContextReader } from './http/ContextReader';
 export type { ContextRead, StructuredContextRead } from './http/ContextReader';
 export { ContextMgr } from './http/ContextMgr';
-export { LogApiCall, LogApiCallImpl } from './http/LogApiCall';
+export { LogApiCall, LogApiCallImpl, LogApiCallOptions } from './http/LogApiCall';
 export { ApiCallInfo } from './http/ApiCallInfo';
 export type { ApiSide, ApiType, ApiResult } from './http/ApiCallInfo';
 export { ApiCallContextHolder } from './http/ApiCallContext';

package/src/index.js

@@ -8,8 +8,8 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENTITY_NOT_FOUND = exports.HttpUserError = exports.HttpVendorError = exports.HttpInternalServerError = exports.HttpGatewayTimeoutError = exports.HttpBadGatewayError = exports.HttpTimeoutError = exports.HttpForbiddenError = exports.HttpUnauthorizedError = exports.HttpBadRequestError = exports.EndpointNotFoundError = exports.HttpNotFoundError = exports.HttpError = exports.ProtocolError = exports.Secrets = exports.METADATA_KEYS = exports.RouteMetadata = exports.AuthMeta = exports.validateNoConflictingDecorators = exports.getQueueName = exports.assertPubSubConventions = exports.assertApiKind = exports.getApiKind = exports.assertEveryEndpointHasAuthMode = exports.getAuthMode = exports.getAuthMeta = exports.isApiPath = exports.getEndpoints = exports.getApiPath = exports.Queue = exports.PubSub = exports.Rpc = exports.AuthSharedSecret = exports.AuthOidc = exports.Auth = exports.AuthJwt = exports.Public = exports.AuthenticationConfig = exports.Authentication = exports.Endpoint = exports.ApiPath = exports.LogManager = exports.ConsoleLoggerFactory = exports.ConsoleLogger = exports.DESIGN_METADATA_KEYS = exports.isDocumentDesign = exports.DocumentDesign = exports.ContextTuple = exports.ContextKey = exports.toError = void 0;
-exports.SerializedError = exports.SerializedMap = exports.RecordSerializer = exports.getDoNotRecordFields = exports.DoNotRecord = exports.RecordedTestCase = exports.RecordedError = exports.RecordedEndpoint = exports.RecorderKeys = exports.ApiCallContextHolder = exports.ApiCallInfo = exports.LogApiCallImpl = exports.LogApiCall = exports.ContextMgr = exports.WebpiecesCoreHeaders = exports.templateDeriver = exports.ErrorWireForm = exports.ClientRegistry = exports.HeaderRegistry = exports.DateTimeUtil = exports.TimeUtil = exports.DateUtil = exports.InstantUtil = exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = void 0;
+exports.HttpVendorError = exports.HttpInternalServerError = exports.HttpGatewayTimeoutError = exports.HttpBadGatewayError = exports.HttpTimeoutError = exports.HttpForbiddenError = exports.HttpUnauthorizedError = exports.HttpBadRequestError = exports.EndpointNotFoundError = exports.HttpNotFoundError = exports.HttpError = exports.ProtocolError = exports.Secrets = exports.METADATA_KEYS = exports.RouteMetadata = exports.AuthMeta = exports.validateNoConflictingDecorators = exports.getQueueName = exports.assertPubSubConventions = exports.assertApiKind = exports.getApiKind = exports.assertEveryEndpointHasAuthMode = exports.getAuthMode = exports.getAuthMeta = exports.isApiPath = exports.isFormPost = exports.getEndpointOptions = exports.getEndpoints = exports.getApiPath = exports.Queue = exports.PubSub = exports.Rpc = exports.AuthSharedSecret = exports.AuthOidc = exports.Auth = exports.AuthJwt = exports.Public = exports.AuthenticationConfig = exports.Authentication = exports.Endpoint = exports.ApiPath = exports.LogManager = exports.ConsoleLoggerFactory = exports.ConsoleLogger = exports.DESIGN_METADATA_KEYS = exports.isDocumentDesign = exports.DocumentDesign = exports.ContextTuple = exports.ContextKey = exports.toError = void 0;
+exports.SerializedError = exports.SerializedMap = exports.RecordSerializer = exports.getDoNotRecordFields = exports.DoNotRecord = exports.RecordedTestCase = exports.RecordedError = exports.RecordedEndpoint = exports.RecorderKeys = exports.ApiCallContextHolder = exports.ApiCallInfo = exports.LogApiCallOptions = exports.LogApiCallImpl = exports.LogApiCall = exports.ContextMgr = exports.WebpiecesCoreHeaders = exports.templateDeriver = exports.ErrorWireForm = exports.ClientRegistry = exports.HeaderRegistry = exports.DateTimeUtil = exports.TimeUtil = exports.DateUtil = exports.InstantUtil = exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = exports.ENTITY_NOT_FOUND = exports.HttpUserError = void 0;
 var errorUtils_1 = require("./lib/errorUtils");
 Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return errorUtils_1.toError; } });
 var ContextKey_1 = require("./ContextKey");
@@ -52,6 +52,8 @@ Object.defineProperty(exports, "PubSub", { enumerable: true, get: function () {
 Object.defineProperty(exports, "Queue", { enumerable: true, get: function () { return decorators_1.Queue; } });
 Object.defineProperty(exports, "getApiPath", { enumerable: true, get: function () { return decorators_1.getApiPath; } });
 Object.defineProperty(exports, "getEndpoints", { enumerable: true, get: function () { return decorators_1.getEndpoints; } });
+Object.defineProperty(exports, "getEndpointOptions", { enumerable: true, get: function () { return decorators_1.getEndpointOptions; } });
+Object.defineProperty(exports, "isFormPost", { enumerable: true, get: function () { return decorators_1.isFormPost; } });
 Object.defineProperty(exports, "isApiPath", { enumerable: true, get: function () { return decorators_1.isApiPath; } });
 Object.defineProperty(exports, "getAuthMeta", { enumerable: true, get: function () { return decorators_1.getAuthMeta; } });
 Object.defineProperty(exports, "getAuthMode", { enumerable: true, get: function () { return decorators_1.getAuthMode; } });
@@ -119,6 +121,7 @@ Object.defineProperty(exports, "ContextMgr", { enumerable: true, get: function (
 var LogApiCall_1 = require("./http/LogApiCall");
 Object.defineProperty(exports, "LogApiCall", { enumerable: true, get: function () { return LogApiCall_1.LogApiCall; } });
 Object.defineProperty(exports, "LogApiCallImpl", { enumerable: true, get: function () { return LogApiCall_1.LogApiCallImpl; } });
+Object.defineProperty(exports, "LogApiCallOptions", { enumerable: true, get: function () { return LogApiCall_1.LogApiCallOptions; } });
 // The structured `api` tag + the context-writer seam LogApiCall stamps through. The Node
 // RequestContext-backed impl is installed by @webpieces/core-context; the browser gets the no-op.
 var ApiCallInfo_1 = require("./http/ApiCallInfo");

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @webpieces/core-util\n *\n * Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n *\n * @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the HttpError hierarchy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n    ApiPath,\n    Endpoint,\n    Authentication,\n    AuthenticationConfig,\n    // Auth mode decorators (clean service-to-service + user JWT model)\n    Public,\n    AuthJwt,\n    Auth,\n    AuthOidc,\n    AuthSharedSecret,\n    // API kind (RPC vs PubSub/Cloud Tasks) + queue naming\n    Rpc,\n    PubSub,\n    Queue,\n    getApiPath,\n    getEndpoints,\n    isApiPath,\n    getAuthMeta,\n    getAuthMode,\n    assertEveryEndpointHasAuthMode,\n    getApiKind,\n    assertApiKind,\n    assertPubSubConventions,\n    getQueueName,\n    validateNoConflictingDecorators,\n    AuthMeta,\n    RouteMetadata,\n    METADATA_KEYS,\n} from './http/decorators';\nexport type { AuthMode, ApiKind, JwtRequirement } from './http/decorators';\n// Client-side shared-secret store (the value THIS service sends per @AuthSharedSecret key).\nexport { Secrets } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// HTTP errors\nexport {\n    ProtocolError,\n    HttpError,\n    HttpNotFoundError,\n    EndpointNotFoundError,\n    HttpBadRequestError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpTimeoutError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n    HttpInternalServerError,\n    HttpVendorError,\n    HttpUserError,\n    // Error subtype constants\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './http/errors';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n    InstantDto,\n    DateDto,\n    TimeDto,\n    DateTimeDto,\n    InstantUtil,\n    DateUtil,\n    TimeUtil,\n    DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport type { ServiceUrlDeriver } from './http/ClientRegistry';\n// Pluggable, bidirectional error translation (app exception <-> wire form). Registered on\n// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.\nexport { ErrorWireForm } from './http/ErrorTranslation';\nexport type { ErrorTranslation } from './http/ErrorTranslation';\nexport { templateDeriver } from './http/templateDeriver';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\nexport type { ContextRead, StructuredContextRead } from './http/ContextReader';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above). Singleton: use the LogApiCall constant, not `new`.\nexport { LogApiCall, LogApiCallImpl } from './http/LogApiCall';\n\n// The structured `api` tag + the context-writer seam LogApiCall stamps through. The Node\n// RequestContext-backed impl is installed by @webpieces/core-context; the browser gets the no-op.\nexport { ApiCallInfo } from './http/ApiCallInfo';\nexport type { ApiSide, ApiType, ApiResult } from './http/ApiCallInfo';\nexport { ApiCallContextHolder } from './http/ApiCallContext';\nexport type { ApiCallContext } from './http/ApiCallContext';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport { RecordedEndpoint, RecordedError, RecordedTestCase } from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @webpieces/core-util\n *\n * Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n *\n * @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the HttpError hierarchy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n    ApiPath,\n    Endpoint,\n    Authentication,\n    AuthenticationConfig,\n    // Auth mode decorators (clean service-to-service + user JWT model)\n    Public,\n    AuthJwt,\n    Auth,\n    AuthOidc,\n    AuthSharedSecret,\n    // API kind (RPC vs PubSub/Cloud Tasks) + queue naming\n    Rpc,\n    PubSub,\n    Queue,\n    getApiPath,\n    getEndpoints,\n    getEndpointOptions,\n    isFormPost,\n    isApiPath,\n    getAuthMeta,\n    getAuthMode,\n    assertEveryEndpointHasAuthMode,\n    getApiKind,\n    assertApiKind,\n    assertPubSubConventions,\n    getQueueName,\n    validateNoConflictingDecorators,\n    AuthMeta,\n    RouteMetadata,\n    METADATA_KEYS,\n} from './http/decorators';\nexport type { AuthMode, ApiKind, JwtRequirement, EndpointOptions } from './http/decorators';\n// Client-side shared-secret store (the value THIS service sends per @AuthSharedSecret key).\nexport { Secrets } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// HTTP errors\nexport {\n    ProtocolError,\n    HttpError,\n    HttpNotFoundError,\n    EndpointNotFoundError,\n    HttpBadRequestError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpTimeoutError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n    HttpInternalServerError,\n    HttpVendorError,\n    HttpUserError,\n    // Error subtype constants\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './http/errors';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n    InstantDto,\n    DateDto,\n    TimeDto,\n    DateTimeDto,\n    InstantUtil,\n    DateUtil,\n    TimeUtil,\n    DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport type { ServiceUrlDeriver } from './http/ClientRegistry';\n// Pluggable, bidirectional error translation (app exception <-> wire form). Registered on\n// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.\nexport { ErrorWireForm } from './http/ErrorTranslation';\nexport type { ErrorTranslation } from './http/ErrorTranslation';\nexport { templateDeriver } from './http/templateDeriver';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\nexport type { ContextRead, StructuredContextRead } from './http/ContextReader';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above). Singleton: use the LogApiCall constant, not `new`.\nexport { LogApiCall, LogApiCallImpl, LogApiCallOptions } from './http/LogApiCall';\n\n// The structured `api` tag + the context-writer seam LogApiCall stamps through. The Node\n// RequestContext-backed impl is installed by @webpieces/core-context; the browser gets the no-op.\nexport { ApiCallInfo } from './http/ApiCallInfo';\nexport type { ApiSide, ApiType, ApiResult } from './http/ApiCallInfo';\nexport { ApiCallContextHolder } from './http/ApiCallContext';\nexport type { ApiCallContext } from './http/ApiCallContext';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport { RecordedEndpoint, RecordedError, RecordedTestCase } from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n"]}