@webpieces/core-util 0.4.709 → 0.4.711

package/package.json

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

package/src/http/ApiCallContext.d.ts

@@ -1,26 +1,33 @@
 import { AnyUntrustedContextKey } from '../ContextKey';
 /**
- * ApiCallContext - the tiny seam that lets {@link LogApiCall} (browser-safe, core-util) stamp a
+ * ApiCallContext - the tiny seam that lets {@link LogApiCallImpl} (browser-safe, core-util) stamp a
  * ContextKey (the `api` tag) into the ambient request context WITHOUT importing it.
  *
  * WHY a seam instead of a direct call: the ambient context is `RequestContext` in
  * `@webpieces/core-context`, which is built on Node `async_hooks` (AsyncLocalStorage). core-util —
  * and `ProxyClient`, which runs in a BROWSER bundle — must never import that (it would be a circular
  * dependency, and it would drag Node vocabulary into a browser build). So core-util owns only this
- * interface + a global holder; each environment installs its own impl at startup:
- * - Node server: `setupRuntime` installs a RequestContext-backed impl.
- * - Browser: `ClientHttpBrowserFactory` installs a module-global impl.
+ * interface, and each environment-specific package CONSTRUCTS its own impl and hands it to
+ * {@link LogApiCallImpl}'s constructor:
+ * - Node server inbound: `LogApiFilter` (http-routing) → `RequestContextApiCallContext`.
+ * - Node client outbound: `NodeProxyClient` (http-client-node) and `TaskProxyClient`
+ *   (cloudtasks-client) → `RequestContextApiCallContext`.
+ * - Browser: `BrowserProxyClient` (http-client-browser) → `BrowserApiCallContext`.
  *
- * If NEITHER installs one, {@link ApiCallContextHolder.get} THROWS (loud misconfiguration, in the
- * webpieces spirit) — see its message. There is deliberately no silent no-op default.
+ * There is deliberately NO process-global holder and no startup install: the context is a REQUIRED
+ * constructor argument, so "nobody set it up" is a compile error rather than a runtime throw on the
+ * first real call. That is what lets a plain NestJS/Express host use `@webpieces/http-client-node` or
+ * `@webpieces/cloudtasks-client` with no webpieces STARTUP INSTALL — it only has to run the call
+ * inside a `RequestContext.run(...)` scope, which such a host already opens per request. (The other
+ * process-globals those clients read — HeaderRegistry, LogManager, a ClientRegistry mapping or
+ * deriver — are unchanged by this and still apply.)
  *
- * This mirrors the existing global-singleton-configured-at-startup pattern (LogManager,
- * HeaderRegistry): behavior is an interface (per CLAUDE.md), the holder is the global seam.
+ * Per CLAUDE.md this is behavior, hence an interface; the impls are ordinary classes.
  */
 export interface ApiCallContext {
     /**
      * True when there is a context to stamp into (a live Node RequestContext scope; a browser is always
-     * active). {@link LogApiCall} throws if this is false — an api call with nowhere to tag is a bug.
+     * active). {@link LogApiCallImpl} throws if this is false — an api call with nowhere to tag is a bug.
      */
     isActive(): boolean;
     /**
@@ -33,28 +40,9 @@ export interface ApiCallContext {
      */
     set(contextKey: AnyUntrustedContextKey, value: unknown): void;
     /**
-     * Clear one ContextKey. {@link LogApiCall} calls set → log → remove as one SYNCHRONOUS span, so the
+     * Clear one ContextKey. {@link LogApiCallImpl} calls set → log → remove as one SYNCHRONOUS span, so the
      * tag is never held across `await`. That is what makes a single browser global safe: single-threaded,
      * nothing can interleave between set and remove, so a concurrent call can never clobber the slot.
      */
     remove(contextKey: AnyUntrustedContextKey): void;
 }
-/**
- * ApiCallContextHolder - the process-wide holder for the active {@link ApiCallContext}.
- *
- * Configured exactly like {@link LogManager}: the environment calls {@link ApiCallContextHolder.install}
- * at startup. Until then {@link get} THROWS, so a forgotten setup fails loudly rather than silently
- * dropping the `api` tag off every log line.
- */
-export declare class ApiCallContextHolder {
-    private static current;
-    /** Install the environment's ApiCallContext (Node: RequestContext-backed; browser: module-global). */
-    static install(ctx: ApiCallContext): void;
-    /** True once an ApiCallContext has been installed (used by tests to probe the unset state). */
-    static isInstalled(): boolean;
-    /**
-     * The active ApiCallContext. Throws if nothing was installed — a one-time setup call is required:
-     * `setupRuntime()` does it on a Node server; building `ClientHttpBrowserFactory` does it in a browser.
-     */
-    static get(): ApiCallContext;
-}

package/src/http/ApiCallContext.js

@@ -1,39 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiCallContextHolder = void 0;
-/**
- * ApiCallContextHolder - the process-wide holder for the active {@link ApiCallContext}.
- *
- * Configured exactly like {@link LogManager}: the environment calls {@link ApiCallContextHolder.install}
- * at startup. Until then {@link get} THROWS, so a forgotten setup fails loudly rather than silently
- * dropping the `api` tag off every log line.
- */
-class ApiCallContextHolder {
-    static current;
-    /** Install the environment's ApiCallContext (Node: RequestContext-backed; browser: module-global). */
-    // webpieces-disable no-function-outside-class -- static global seam, configured once at startup (like LogManager.setFactory)
-    static install(ctx) {
-        ApiCallContextHolder.current = ctx;
-    }
-    /** True once an ApiCallContext has been installed (used by tests to probe the unset state). */
-    // webpieces-disable no-function-outside-class -- static global seam accessor (like HeaderRegistry.isConfigured)
-    static isInstalled() {
-        return ApiCallContextHolder.current !== undefined;
-    }
-    /**
-     * The active ApiCallContext. Throws if nothing was installed — a one-time setup call is required:
-     * `setupRuntime()` does it on a Node server; building `ClientHttpBrowserFactory` does it in a browser.
-     */
-    // webpieces-disable no-function-outside-class -- static global seam accessor (like LogManager/HeaderRegistry.get), not DI-injected
-    static get() {
-        if (!ApiCallContextHolder.current) {
-            throw new Error('ApiCallContext is not installed — LogApiCall cannot tag API-call logs. Set it up ONCE ' +
-                'at startup: on a Node server, setupRuntime() installs it for you; in a browser, construct ' +
-                'ClientHttpBrowserFactory once at startup. (This is the same one-time setup as ' +
-                'HeaderRegistry.configure / LogManager.setFactory.)');
-        }
-        return ApiCallContextHolder.current;
-    }
-}
-exports.ApiCallContextHolder = ApiCallContextHolder;
 //# sourceMappingURL=ApiCallContext.js.map

package/src/http/ApiCallContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiCallContext.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallContext.ts"],"names":[],"mappings":";;;AA8CA;;;;;;GAMG;AACH,MAAa,oBAAoB;IACrB,MAAM,CAAC,OAAO,CAA6B;IAEnD,sGAAsG;IACtG,6HAA6H;IAC7H,MAAM,CAAC,OAAO,CAAC,GAAmB;QAC9B,oBAAoB,CAAC,OAAO,GAAG,GAAG,CAAC;IACvC,CAAC;IAED,+FAA+F;IAC/F,gHAAgH;IAChH,MAAM,CAAC,WAAW;QACd,OAAO,oBAAoB,CAAC,OAAO,KAAK,SAAS,CAAC;IACtD,CAAC;IAED;;;OAGG;IACH,mIAAmI;IACnI,MAAM,CAAC,GAAG;QACN,IAAI,CAAC,oBAAoB,CAAC,OAAO,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACX,wFAAwF;gBACxF,4FAA4F;gBAC5F,gFAAgF;gBAChF,oDAAoD,CACvD,CAAC;QACN,CAAC;QACD,OAAO,oBAAoB,CAAC,OAAO,CAAC;IACxC,CAAC;CACJ;AA/BD,oDA+BC","sourcesContent":["import { AnyUntrustedContextKey } from '../ContextKey';\n\n/**\n * ApiCallContext - the tiny seam that lets {@link LogApiCall} (browser-safe, core-util) stamp a\n * ContextKey (the `api` tag) into the ambient request context WITHOUT importing it.\n *\n * WHY a seam instead of a direct call: the ambient context is `RequestContext` in\n * `@webpieces/core-context`, which is built on Node `async_hooks` (AsyncLocalStorage). core-util —\n * and `ProxyClient`, which runs in a BROWSER bundle — must never import that (it would be a circular\n * dependency, and it would drag Node vocabulary into a browser build). So core-util owns only this\n * interface + a global holder; each environment installs its own impl at startup:\n * - Node server: `setupRuntime` installs a RequestContext-backed impl.\n * - Browser: `ClientHttpBrowserFactory` installs a module-global impl.\n *\n * If NEITHER installs one, {@link ApiCallContextHolder.get} THROWS (loud misconfiguration, in the\n * webpieces spirit) — see its message. There is deliberately no silent no-op default.\n *\n * This mirrors the existing global-singleton-configured-at-startup pattern (LogManager,\n * HeaderRegistry): behavior is an interface (per CLAUDE.md), the holder is the global seam.\n */\nexport interface ApiCallContext {\n    /**\n     * True when there is a context to stamp into (a live Node RequestContext scope; a browser is always\n     * active). {@link LogApiCall} throws if this is false — an api call with nowhere to tag is a bug.\n     */\n    isActive(): boolean;\n\n    /**\n     * Stamp one UNTRUSTED ContextKey → value into the ambient context. Untrusted by type on purpose:\n     * this seam is reachable from browser-side client code, so if it accepted a trusted key it would\n     * be a side door for forging a proven identity. The one key it actually stamps\n     * ({@link WebpiecesCoreHeaders.API_CALL_INFO}) is a log tag, which is untrusted by nature.\n     * The logger reads it back off the context\n     * (server: RequestContext.buildStructuredLogFields; browser: its own store) during the log emit.\n     */\n    // webpieces-disable no-any-unknown -- a context value is heterogeneous (the api struct here; strings elsewhere)\n    set(contextKey: AnyUntrustedContextKey, value: unknown): void;\n\n    /**\n     * Clear one ContextKey. {@link LogApiCall} calls set → log → remove as one SYNCHRONOUS span, so the\n     * tag is never held across `await`. That is what makes a single browser global safe: single-threaded,\n     * nothing can interleave between set and remove, so a concurrent call can never clobber the slot.\n     */\n    remove(contextKey: AnyUntrustedContextKey): void;\n}\n\n/**\n * ApiCallContextHolder - the process-wide holder for the active {@link ApiCallContext}.\n *\n * Configured exactly like {@link LogManager}: the environment calls {@link ApiCallContextHolder.install}\n * at startup. Until then {@link get} THROWS, so a forgotten setup fails loudly rather than silently\n * dropping the `api` tag off every log line.\n */\nexport class ApiCallContextHolder {\n    private static current: ApiCallContext | undefined;\n\n    /** Install the environment's ApiCallContext (Node: RequestContext-backed; browser: module-global). */\n    // webpieces-disable no-function-outside-class -- static global seam, configured once at startup (like LogManager.setFactory)\n    static install(ctx: ApiCallContext): void {\n        ApiCallContextHolder.current = ctx;\n    }\n\n    /** True once an ApiCallContext has been installed (used by tests to probe the unset state). */\n    // webpieces-disable no-function-outside-class -- static global seam accessor (like HeaderRegistry.isConfigured)\n    static isInstalled(): boolean {\n        return ApiCallContextHolder.current !== undefined;\n    }\n\n    /**\n     * The active ApiCallContext. Throws if nothing was installed — a one-time setup call is required:\n     * `setupRuntime()` does it on a Node server; building `ClientHttpBrowserFactory` does it in a browser.\n     */\n    // webpieces-disable no-function-outside-class -- static global seam accessor (like LogManager/HeaderRegistry.get), not DI-injected\n    static get(): ApiCallContext {\n        if (!ApiCallContextHolder.current) {\n            throw new Error(\n                'ApiCallContext is not installed — LogApiCall cannot tag API-call logs. Set it up ONCE ' +\n                'at startup: on a Node server, setupRuntime() installs it for you; in a browser, construct ' +\n                'ClientHttpBrowserFactory once at startup. (This is the same one-time setup as ' +\n                'HeaderRegistry.configure / LogManager.setFactory.)',\n            );\n        }\n        return ApiCallContextHolder.current;\n    }\n}\n"]}
+{"version":3,"file":"ApiCallContext.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallContext.ts"],"names":[],"mappings":"","sourcesContent":["import { AnyUntrustedContextKey } from '../ContextKey';\n\n/**\n * ApiCallContext - the tiny seam that lets {@link LogApiCallImpl} (browser-safe, core-util) stamp a\n * ContextKey (the `api` tag) into the ambient request context WITHOUT importing it.\n *\n * WHY a seam instead of a direct call: the ambient context is `RequestContext` in\n * `@webpieces/core-context`, which is built on Node `async_hooks` (AsyncLocalStorage). core-util —\n * and `ProxyClient`, which runs in a BROWSER bundle — must never import that (it would be a circular\n * dependency, and it would drag Node vocabulary into a browser build). So core-util owns only this\n * interface, and each environment-specific package CONSTRUCTS its own impl and hands it to\n * {@link LogApiCallImpl}'s constructor:\n * - Node server inbound: `LogApiFilter` (http-routing) → `RequestContextApiCallContext`.\n * - Node client outbound: `NodeProxyClient` (http-client-node) and `TaskProxyClient`\n *   (cloudtasks-client) → `RequestContextApiCallContext`.\n * - Browser: `BrowserProxyClient` (http-client-browser) → `BrowserApiCallContext`.\n *\n * There is deliberately NO process-global holder and no startup install: the context is a REQUIRED\n * constructor argument, so \"nobody set it up\" is a compile error rather than a runtime throw on the\n * first real call. That is what lets a plain NestJS/Express host use `@webpieces/http-client-node` or\n * `@webpieces/cloudtasks-client` with no webpieces STARTUP INSTALL — it only has to run the call\n * inside a `RequestContext.run(...)` scope, which such a host already opens per request. (The other\n * process-globals those clients read — HeaderRegistry, LogManager, a ClientRegistry mapping or\n * deriver — are unchanged by this and still apply.)\n *\n * Per CLAUDE.md this is behavior, hence an interface; the impls are ordinary classes.\n */\nexport interface ApiCallContext {\n    /**\n     * True when there is a context to stamp into (a live Node RequestContext scope; a browser is always\n     * active). {@link LogApiCallImpl} throws if this is false — an api call with nowhere to tag is a bug.\n     */\n    isActive(): boolean;\n\n    /**\n     * Stamp one UNTRUSTED ContextKey → value into the ambient context. Untrusted by type on purpose:\n     * this seam is reachable from browser-side client code, so if it accepted a trusted key it would\n     * be a side door for forging a proven identity. The one key it actually stamps\n     * ({@link WebpiecesCoreHeaders.API_CALL_INFO}) is a log tag, which is untrusted by nature.\n     * The logger reads it back off the context\n     * (server: RequestContext.buildStructuredLogFields; browser: its own store) during the log emit.\n     */\n    // webpieces-disable no-any-unknown -- a context value is heterogeneous (the api struct here; strings elsewhere)\n    set(contextKey: AnyUntrustedContextKey, value: unknown): void;\n\n    /**\n     * Clear one ContextKey. {@link LogApiCallImpl} calls set → log → remove as one SYNCHRONOUS span, so the\n     * tag is never held across `await`. That is what makes a single browser global safe: single-threaded,\n     * nothing can interleave between set and remove, so a concurrent call can never clobber the slot.\n     */\n    remove(contextKey: AnyUntrustedContextKey): void;\n}\n"]}

package/src/http/ApiCallInfo.d.ts

@@ -1,7 +1,7 @@
 import { ApiMethodInfo } from './ApiMethodInfo';
 /**
  * ApiCallInfo - the structured tag stamped into RequestContext around every API call
- * (by {@link LogApiCall}), so ANY log line emitted during the call inherits a filterable
+ * (by {@link LogApiCallImpl}), so ANY log line emitted during the call inherits a filterable
  * `api` object rather than only the req/resp text lines.
  *
  * The node logging backends (winston/bunyan) read this struct out of context via
@@ -33,7 +33,7 @@ import { ApiMethodInfo } from './ApiMethodInfo';
 export type ApiType = 'request' | 'response';
 /**
  * Response outcome. 'success' covers 2xx AND user errors (400/401/403/404/266 — a successfully
- * handled "you made a mistake"); 'failure' is a genuine server error. See {@link LogApiCall.isUserError}.
+ * handled "you made a mistake"); 'failure' is a genuine server error. See {@link LogApiCallImpl.isUserError}.
  */
 export type ApiResult = 'success' | 'failure';
 /** Re-exported from {@link ApiMethodInfo} (its true home) so existing `ApiSide` imports keep working. */
@@ -53,7 +53,7 @@ export declare class ApiCallInfo {
      * There is deliberately no `statusCode` beside this. LogApiCall runs deep in the stack over
      * in-process calls, pubsub handlers, and cloud-task enqueues — none of which have an HTTP
      * status — and business logic must not know about HTTP. `result` (see {@link ApiResult}) is
-     * the transport-neutral outcome, exactly as {@link LogApiCall.isUserError} classifies by
+     * the transport-neutral outcome, exactly as {@link LogApiCallImpl.isUserError} classifies by
      * portable Error TYPE rather than by status code.
      */
     readonly durationMs?: number | undefined;
@@ -84,7 +84,7 @@ export declare class ApiCallInfo {
      * There is deliberately no `statusCode` beside this. LogApiCall runs deep in the stack over
      * in-process calls, pubsub handlers, and cloud-task enqueues — none of which have an HTTP
      * status — and business logic must not know about HTTP. `result` (see {@link ApiResult}) is
-     * the transport-neutral outcome, exactly as {@link LogApiCall.isUserError} classifies by
+     * the transport-neutral outcome, exactly as {@link LogApiCallImpl.isUserError} classifies by
      * portable Error TYPE rather than by status code.
      */
     durationMs?: number | undefined, 

package/src/http/ApiCallInfo.js

@@ -22,7 +22,7 @@ class ApiCallInfo {
      * There is deliberately no `statusCode` beside this. LogApiCall runs deep in the stack over
      * in-process calls, pubsub handlers, and cloud-task enqueues — none of which have an HTTP
      * status — and business logic must not know about HTTP. `result` (see {@link ApiResult}) is
-     * the transport-neutral outcome, exactly as {@link LogApiCall.isUserError} classifies by
+     * the transport-neutral outcome, exactly as {@link LogApiCallImpl.isUserError} classifies by
      * portable Error TYPE rather than by status code.
      */
     durationMs, 

package/src/http/ApiCallInfo.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiCallInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallInfo.ts"],"names":[],"mappings":";;;AA6CA,MAAa,WAAW;IAIP;IACA;IAEA;IAYA;IAUA;IAGA;IA/Bb;IACI;oCACgC;IACvB,MAAqB,EACrB,IAAa;IACtB,sDAAsD;IAC7C,MAAkB;IAC3B;;;;;;;;;;OAUG;IACM,UAAmB;IAC5B;;;;;;;;OAQG;IACM,WAAoB;IAC7B;yFACqF;IAC5E,YAAqB;QA5BrB,WAAM,GAAN,MAAM,CAAe;QACrB,SAAI,GAAJ,IAAI,CAAS;QAEb,WAAM,GAAN,MAAM,CAAY;QAYlB,eAAU,GAAV,UAAU,CAAS;QAUnB,gBAAW,GAAX,WAAW,CAAS;QAGpB,iBAAY,GAAZ,YAAY,CAAS;IAC/B,CAAC;CACP;AAlCD,kCAkCC","sourcesContent":["import { ApiMethodInfo } from './ApiMethodInfo';\n\n/**\n * ApiCallInfo - the structured tag stamped into RequestContext around every API call\n * (by {@link LogApiCall}), so ANY log line emitted during the call inherits a filterable\n * `api` object rather than only the req/resp text lines.\n *\n * The node logging backends (winston/bunyan) read this struct out of context via\n * `RequestContext.buildStructuredLogFields()` and emit it AS AN OBJECT under `jsonPayload.api`,\n * which unlocks GCP Cloud Logging filters like:\n * - `jsonPayload.api.method.side=\"client\"`     — every outbound call this process made\n * - `jsonPayload.api.method.side=\"server\"`      — every inbound call it handled\n * - `jsonPayload.api.method.apiClass=\"SaveApi\"` — one logical method, BOTH sides (client + server)\n * - `jsonPayload.api.result=\"failure\"`          — failed exchanges only\n * - `jsonPayload.api.durationMs>1000`           — slow calls, either side\n * - `jsonPayload.api.responseSize>100000`       — the fat responses (the ones that get chunked)\n * - `jsonPayload.api:*`                          — \"API traffic only\" (tracing + the recorder)\n *\n * IMPORTANT: the field names here (and on the nested {@link ApiMethodInfo}) ARE the GCP field names —\n * rename a field and the filter renames with it. The identity lives NESTED under `api.method`\n * (`api.method.{side,apiClass,methodName,controllerName}`); `api.type` and `api.result` sit at the top.\n *\n * NOTE: the request `httpMethod`/`path` are NOT here — an inbound request stamps them as the separate\n * top-level logged keys `jsonPayload.httpMethod` / `jsonPayload.requestPath` (see\n * {@link WebpiecesCoreHeaders} + `RequestContextHeaders.fillFromRequest`). Outbound client calls have\n * no inbound path, so they carry only the `api` identity.\n *\n * Per-hop only: the underlying `API_CALL_INFO` ContextKey is NOT transferred over the wire, so a\n * downstream server stamps its own `side:'server'` rather than inheriting the caller's `side:'client'`.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\n/** Which half of the exchange this tag describes: the outgoing 'request' or the returning 'response'. */\nexport type ApiType = 'request' | 'response';\n\n/**\n * Response outcome. 'success' covers 2xx AND user errors (400/401/403/404/266 — a successfully\n * handled \"you made a mistake\"); 'failure' is a genuine server error. See {@link LogApiCall.isUserError}.\n */\nexport type ApiResult = 'success' | 'failure';\n\n/** Re-exported from {@link ApiMethodInfo} (its true home) so existing `ApiSide` imports keep working. */\nexport type { ApiSide } from './ApiMethodInfo';\n\nexport class ApiCallInfo {\n    constructor(\n        /** The call identity (side, apiClass, methodName, controllerName) — surfaces nested under\n         *  `jsonPayload.api.method`. */\n        readonly method: ApiMethodInfo,\n        readonly type: ApiType,\n        /** Response only — undefined on the 'request' tag. */\n        readonly result?: ApiResult,\n        /**\n         * Wall-clock milliseconds the call took. RESPONSE tag only (undefined on 'request') — a\n         * request has no duration yet. Present on BOTH the success and failure paths, so\n         * `jsonPayload.api.durationMs>1000 AND api.result=\"failure\"` finds slow failures.\n         *\n         * There is deliberately no `statusCode` beside this. LogApiCall runs deep in the stack over\n         * in-process calls, pubsub handlers, and cloud-task enqueues — none of which have an HTTP\n         * status — and business logic must not know about HTTP. `result` (see {@link ApiResult}) is\n         * the transport-neutral outcome, exactly as {@link LogApiCall.isUserError} classifies by\n         * portable Error TYPE rather than by status code.\n         */\n        readonly durationMs?: number,\n        /**\n         * Bytes of the serialized request DTO. Stamped on BOTH tags: the 'request' tag reports it as\n         * soon as it is known, and the 'response' tag repeats it so one record shows the whole\n         * exchange (`api.requestSize` + `api.responseSize` without a join).\n         *\n         * This is the TOTAL size of the body, measured BEFORE any log chunking — chunking is a\n         * transport concern handled by the GCP backends, and a body split across 3 records still\n         * reports its one true size here.\n         */\n        readonly requestSize?: number,\n        /** Bytes of the serialized response. RESPONSE tag only, and only when the call succeeded —\n         *  a thrown error produced no response body to measure. Total size, pre-chunking. */\n        readonly responseSize?: number,\n    ) {}\n}\n"]}
+{"version":3,"file":"ApiCallInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallInfo.ts"],"names":[],"mappings":";;;AA6CA,MAAa,WAAW;IAIP;IACA;IAEA;IAYA;IAUA;IAGA;IA/Bb;IACI;oCACgC;IACvB,MAAqB,EACrB,IAAa;IACtB,sDAAsD;IAC7C,MAAkB;IAC3B;;;;;;;;;;OAUG;IACM,UAAmB;IAC5B;;;;;;;;OAQG;IACM,WAAoB;IAC7B;yFACqF;IAC5E,YAAqB;QA5BrB,WAAM,GAAN,MAAM,CAAe;QACrB,SAAI,GAAJ,IAAI,CAAS;QAEb,WAAM,GAAN,MAAM,CAAY;QAYlB,eAAU,GAAV,UAAU,CAAS;QAUnB,gBAAW,GAAX,WAAW,CAAS;QAGpB,iBAAY,GAAZ,YAAY,CAAS;IAC/B,CAAC;CACP;AAlCD,kCAkCC","sourcesContent":["import { ApiMethodInfo } from './ApiMethodInfo';\n\n/**\n * ApiCallInfo - the structured tag stamped into RequestContext around every API call\n * (by {@link LogApiCallImpl}), so ANY log line emitted during the call inherits a filterable\n * `api` object rather than only the req/resp text lines.\n *\n * The node logging backends (winston/bunyan) read this struct out of context via\n * `RequestContext.buildStructuredLogFields()` and emit it AS AN OBJECT under `jsonPayload.api`,\n * which unlocks GCP Cloud Logging filters like:\n * - `jsonPayload.api.method.side=\"client\"`     — every outbound call this process made\n * - `jsonPayload.api.method.side=\"server\"`      — every inbound call it handled\n * - `jsonPayload.api.method.apiClass=\"SaveApi\"` — one logical method, BOTH sides (client + server)\n * - `jsonPayload.api.result=\"failure\"`          — failed exchanges only\n * - `jsonPayload.api.durationMs>1000`           — slow calls, either side\n * - `jsonPayload.api.responseSize>100000`       — the fat responses (the ones that get chunked)\n * - `jsonPayload.api:*`                          — \"API traffic only\" (tracing + the recorder)\n *\n * IMPORTANT: the field names here (and on the nested {@link ApiMethodInfo}) ARE the GCP field names —\n * rename a field and the filter renames with it. The identity lives NESTED under `api.method`\n * (`api.method.{side,apiClass,methodName,controllerName}`); `api.type` and `api.result` sit at the top.\n *\n * NOTE: the request `httpMethod`/`path` are NOT here — an inbound request stamps them as the separate\n * top-level logged keys `jsonPayload.httpMethod` / `jsonPayload.requestPath` (see\n * {@link WebpiecesCoreHeaders} + `RequestContextHeaders.fillFromRequest`). Outbound client calls have\n * no inbound path, so they carry only the `api` identity.\n *\n * Per-hop only: the underlying `API_CALL_INFO` ContextKey is NOT transferred over the wire, so a\n * downstream server stamps its own `side:'server'` rather than inheriting the caller's `side:'client'`.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\n/** Which half of the exchange this tag describes: the outgoing 'request' or the returning 'response'. */\nexport type ApiType = 'request' | 'response';\n\n/**\n * Response outcome. 'success' covers 2xx AND user errors (400/401/403/404/266 — a successfully\n * handled \"you made a mistake\"); 'failure' is a genuine server error. See {@link LogApiCallImpl.isUserError}.\n */\nexport type ApiResult = 'success' | 'failure';\n\n/** Re-exported from {@link ApiMethodInfo} (its true home) so existing `ApiSide` imports keep working. */\nexport type { ApiSide } from './ApiMethodInfo';\n\nexport class ApiCallInfo {\n    constructor(\n        /** The call identity (side, apiClass, methodName, controllerName) — surfaces nested under\n         *  `jsonPayload.api.method`. */\n        readonly method: ApiMethodInfo,\n        readonly type: ApiType,\n        /** Response only — undefined on the 'request' tag. */\n        readonly result?: ApiResult,\n        /**\n         * Wall-clock milliseconds the call took. RESPONSE tag only (undefined on 'request') — a\n         * request has no duration yet. Present on BOTH the success and failure paths, so\n         * `jsonPayload.api.durationMs>1000 AND api.result=\"failure\"` finds slow failures.\n         *\n         * There is deliberately no `statusCode` beside this. LogApiCall runs deep in the stack over\n         * in-process calls, pubsub handlers, and cloud-task enqueues — none of which have an HTTP\n         * status — and business logic must not know about HTTP. `result` (see {@link ApiResult}) is\n         * the transport-neutral outcome, exactly as {@link LogApiCallImpl.isUserError} classifies by\n         * portable Error TYPE rather than by status code.\n         */\n        readonly durationMs?: number,\n        /**\n         * Bytes of the serialized request DTO. Stamped on BOTH tags: the 'request' tag reports it as\n         * soon as it is known, and the 'response' tag repeats it so one record shows the whole\n         * exchange (`api.requestSize` + `api.responseSize` without a join).\n         *\n         * This is the TOTAL size of the body, measured BEFORE any log chunking — chunking is a\n         * transport concern handled by the GCP backends, and a body split across 3 records still\n         * reports its one true size here.\n         */\n        readonly requestSize?: number,\n        /** Bytes of the serialized response. RESPONSE tag only, and only when the call succeeded —\n         *  a thrown error produced no response body to measure. Total size, pre-chunking. */\n        readonly responseSize?: number,\n    ) {}\n}\n"]}

package/src/http/ApiCallLogName.d.ts

@@ -3,10 +3,10 @@ export declare const LOG_API_CALL_LOGGER_NAME = "LogApiCall";
 /** A value read off a parsed/structured log record — the widest thing a record field can hold. */
 type LogFieldValue = string | number | boolean | object | null | undefined;
 /**
- * ApiCallLogName - the console-render bridge that turns a {@link LogApiCall} line's plain
+ * ApiCallLogName - the console-render bridge that turns a {@link LogApiCallImpl} line's plain
  * `[LogApiCall]` logger bracket into a self-describing `[API.{side}.{phase}]` bracket.
  *
- * WHY: {@link LogApiCall} emits EVERY api req/resp line under the single logger name `LogApiCall`, so
+ * WHY: {@link LogApiCallImpl} emits EVERY api req/resp line under the single logger name `LogApiCall`, so
  * the local console showed the unhelpful `[LogApiCall]` on all of them. But each of those lines already
  * carries the structured {@link ApiCallInfo} `api` tag in context, which knows the `side` (client/server)
  * and whether this is the request or a success/failure response. The console backends (winston
@@ -14,7 +14,7 @@ type LogFieldValue = string | number | boolean | object | null | undefined;
  * lines and render that richer bracket instead — e.g. `[API.client.request]`, `[API.server.success]`,
  * `[API.client.failure]`. GCP is unaffected (it filters on `jsonPayload.api.*`, not the logger name).
  *
- * Singleton, mirroring {@link LogApiCall}: use the exported {@link ApiCallLogName} constant, not `new`.
+ * Singleton, mirroring {@link LogApiCallImpl}: use the exported {@link ApiCallLogName} constant, not `new`.
  * Kept in one place so the two duplicated console formats stay byte-identical, and so the special-cased
  * name matches the logger name LogApiCall actually uses ({@link LOG_API_CALL_LOGGER_NAME}).
  */
@@ -42,7 +42,7 @@ export declare class ApiCallLogNameImpl {
     describe(loggerName: LogFieldValue, api: LogFieldValue): string | undefined;
 }
 /**
- * The process-wide {@link ApiCallLogNameImpl} singleton — mirrors the {@link LogApiCall} export pattern.
+ * The process-wide {@link ApiCallLogNameImpl} singleton — mirrors the {@link LogApiCallImpl} export pattern.
  * Callers use `ApiCallLogName.describe(...)`, never `new`.
  */
 export declare const ApiCallLogName: ApiCallLogNameImpl;

package/src/http/ApiCallLogName.js

@@ -4,10 +4,10 @@ exports.ApiCallLogName = exports.ApiCallLogNameImpl = exports.LOG_API_CALL_LOGGE
 /** The console-render logger name LogApiCall logs under; the backends special-case exactly this name. */
 exports.LOG_API_CALL_LOGGER_NAME = 'LogApiCall';
 /**
- * ApiCallLogName - the console-render bridge that turns a {@link LogApiCall} line's plain
+ * ApiCallLogName - the console-render bridge that turns a {@link LogApiCallImpl} line's plain
  * `[LogApiCall]` logger bracket into a self-describing `[API.{side}.{phase}]` bracket.
  *
- * WHY: {@link LogApiCall} emits EVERY api req/resp line under the single logger name `LogApiCall`, so
+ * WHY: {@link LogApiCallImpl} emits EVERY api req/resp line under the single logger name `LogApiCall`, so
  * the local console showed the unhelpful `[LogApiCall]` on all of them. But each of those lines already
  * carries the structured {@link ApiCallInfo} `api` tag in context, which knows the `side` (client/server)
  * and whether this is the request or a success/failure response. The console backends (winston
@@ -15,7 +15,7 @@ exports.LOG_API_CALL_LOGGER_NAME = 'LogApiCall';
  * lines and render that richer bracket instead — e.g. `[API.client.request]`, `[API.server.success]`,
  * `[API.client.failure]`. GCP is unaffected (it filters on `jsonPayload.api.*`, not the logger name).
  *
- * Singleton, mirroring {@link LogApiCall}: use the exported {@link ApiCallLogName} constant, not `new`.
+ * Singleton, mirroring {@link LogApiCallImpl}: use the exported {@link ApiCallLogName} constant, not `new`.
  * Kept in one place so the two duplicated console formats stay byte-identical, and so the special-cased
  * name matches the logger name LogApiCall actually uses ({@link LOG_API_CALL_LOGGER_NAME}).
  */
@@ -63,7 +63,7 @@ class ApiCallLogNameImpl {
 }
 exports.ApiCallLogNameImpl = ApiCallLogNameImpl;
 /**
- * The process-wide {@link ApiCallLogNameImpl} singleton — mirrors the {@link LogApiCall} export pattern.
+ * The process-wide {@link ApiCallLogNameImpl} singleton — mirrors the {@link LogApiCallImpl} export pattern.
  * Callers use `ApiCallLogName.describe(...)`, never `new`.
  */
 exports.ApiCallLogName = new ApiCallLogNameImpl();

package/src/http/ApiCallLogName.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiCallLogName.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallLogName.ts"],"names":[],"mappings":";;;AAEA,yGAAyG;AAC5F,QAAA,wBAAwB,GAAG,YAAY,CAAC;AAKrD;;;;;;;;;;;;;;;GAeG;AACH,MAAa,kBAAkB;IAE3B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,UAAyB,EAAE,GAAkB;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAC/C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,IAAI,OAAO,GAAG,CAAC;QAC1B,CAAC;QACD,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,UAAyB,EAAE,GAAkB;QAClD,IAAI,UAAU,KAAK,gCAAwB,EAAE,CAAC;YAC1C,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,CAAC,GAAG,YAAY,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,2FAA2F;QAC3F,oFAAoF;QACpF,MAAM,IAAI,GAAG,GAA2B,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAClF,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QACtG,OAAO,OAAO,IAAI,IAAI,KAAK,EAAE,CAAC;IAClC,CAAC;CACJ;AA3CD,gDA2CC;AAED;;;GAGG;AACU,QAAA,cAAc,GAAG,IAAI,kBAAkB,EAAE,CAAC","sourcesContent":["import { ApiCallInfo } from './ApiCallInfo';\n\n/** The console-render logger name LogApiCall logs under; the backends special-case exactly this name. */\nexport const LOG_API_CALL_LOGGER_NAME = 'LogApiCall';\n\n/** A value read off a parsed/structured log record — the widest thing a record field can hold. */\ntype LogFieldValue = string | number | boolean | object | null | undefined;\n\n/**\n * ApiCallLogName - the console-render bridge that turns a {@link LogApiCall} line's plain\n * `[LogApiCall]` logger bracket into a self-describing `[API.{side}.{phase}]` bracket.\n *\n * WHY: {@link LogApiCall} emits EVERY api req/resp line under the single logger name `LogApiCall`, so\n * the local console showed the unhelpful `[LogApiCall]` on all of them. But each of those lines already\n * carries the structured {@link ApiCallInfo} `api` tag in context, which knows the `side` (client/server)\n * and whether this is the request or a success/failure response. The console backends (winston\n * `localPrettyFormat` + bunyan `writeConsole`) call {@link describe} to special-case JUST the LogApiCall\n * lines and render that richer bracket instead — e.g. `[API.client.request]`, `[API.server.success]`,\n * `[API.client.failure]`. GCP is unaffected (it filters on `jsonPayload.api.*`, not the logger name).\n *\n * Singleton, mirroring {@link LogApiCall}: use the exported {@link ApiCallLogName} constant, not `new`.\n * Kept in one place so the two duplicated console formats stay byte-identical, and so the special-cased\n * name matches the logger name LogApiCall actually uses ({@link LOG_API_CALL_LOGGER_NAME}).\n */\nexport class ApiCallLogNameImpl {\n\n    /**\n     * The complete logger bracket for one console line — the single seam both console backends call so\n     * they render byte-identically. A LogApiCall line becomes a self-describing `[API.{side}.{phase}]`\n     * bracket derived from its `api` tag; every other line keeps its plain `[loggerName]` bracket; a line\n     * with no logger name at all (startup / pre-route) renders `''`.\n     *\n     * Phase mapping mirrors {@link ApiCallInfo}: a `request` tag → `request`; a `response` tag →\n     * `failure` when `result:'failure'`, else `success` (which correctly folds handled user errors,\n     * whose result is `success`, into `success`).\n     *\n     * @param loggerName - the record's `loggerName` field (off a parsed/structured log record)\n     * @param api - the record's `api` field (the stamped {@link ApiCallInfo}, or undefined/other)\n     * @returns e.g. `\"[API.client.request]\"`, `\"[MyClass]\"`, or `\"\"`\n     */\n    bracket(loggerName: LogFieldValue, api: LogFieldValue): string {\n        const apiName = this.describe(loggerName, api);\n        if (apiName !== undefined) {\n            return `[${apiName}]`;\n        }\n        return loggerName ? `[${String(loggerName)}]` : '';\n    }\n\n    /**\n     * The self-describing name (no brackets) for a LogApiCall line, e.g. `\"API.client.request\"`, or\n     * `undefined` when this is not a LogApiCall line or its `api` tag is missing/misshapen. Callers use\n     * {@link bracket}; this is factored out for direct testing of the phase mapping.\n     */\n    describe(loggerName: LogFieldValue, api: LogFieldValue): string | undefined {\n        if (loggerName !== LOG_API_CALL_LOGGER_NAME) {\n            return undefined;\n        }\n        if (!(api instanceof Object)) {\n            return undefined;\n        }\n        // The record may be a plain JSON.parse output (bunyan) rather than an ApiCallInfo instance\n        // (winston reads the live object), so read structurally rather than via instanceof.\n        const info = api as Partial<ApiCallInfo>;\n        const side = typeof info.method?.side === 'string' ? info.method.side : 'unknown';\n        const phase = info.type === 'request' ? 'request' : info.result === 'failure' ? 'failure' : 'success';\n        return `API.${side}.${phase}`;\n    }\n}\n\n/**\n * The process-wide {@link ApiCallLogNameImpl} singleton — mirrors the {@link LogApiCall} export pattern.\n * Callers use `ApiCallLogName.describe(...)`, never `new`.\n */\nexport const ApiCallLogName = new ApiCallLogNameImpl();\n"]}
+{"version":3,"file":"ApiCallLogName.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallLogName.ts"],"names":[],"mappings":";;;AAEA,yGAAyG;AAC5F,QAAA,wBAAwB,GAAG,YAAY,CAAC;AAKrD;;;;;;;;;;;;;;;GAeG;AACH,MAAa,kBAAkB;IAE3B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,UAAyB,EAAE,GAAkB;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAC/C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,IAAI,OAAO,GAAG,CAAC;QAC1B,CAAC;QACD,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,UAAyB,EAAE,GAAkB;QAClD,IAAI,UAAU,KAAK,gCAAwB,EAAE,CAAC;YAC1C,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,CAAC,GAAG,YAAY,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,2FAA2F;QAC3F,oFAAoF;QACpF,MAAM,IAAI,GAAG,GAA2B,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAClF,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QACtG,OAAO,OAAO,IAAI,IAAI,KAAK,EAAE,CAAC;IAClC,CAAC;CACJ;AA3CD,gDA2CC;AAED;;;GAGG;AACU,QAAA,cAAc,GAAG,IAAI,kBAAkB,EAAE,CAAC","sourcesContent":["import { ApiCallInfo } from './ApiCallInfo';\n\n/** The console-render logger name LogApiCall logs under; the backends special-case exactly this name. */\nexport const LOG_API_CALL_LOGGER_NAME = 'LogApiCall';\n\n/** A value read off a parsed/structured log record — the widest thing a record field can hold. */\ntype LogFieldValue = string | number | boolean | object | null | undefined;\n\n/**\n * ApiCallLogName - the console-render bridge that turns a {@link LogApiCallImpl} line's plain\n * `[LogApiCall]` logger bracket into a self-describing `[API.{side}.{phase}]` bracket.\n *\n * WHY: {@link LogApiCallImpl} emits EVERY api req/resp line under the single logger name `LogApiCall`, so\n * the local console showed the unhelpful `[LogApiCall]` on all of them. But each of those lines already\n * carries the structured {@link ApiCallInfo} `api` tag in context, which knows the `side` (client/server)\n * and whether this is the request or a success/failure response. The console backends (winston\n * `localPrettyFormat` + bunyan `writeConsole`) call {@link describe} to special-case JUST the LogApiCall\n * lines and render that richer bracket instead — e.g. `[API.client.request]`, `[API.server.success]`,\n * `[API.client.failure]`. GCP is unaffected (it filters on `jsonPayload.api.*`, not the logger name).\n *\n * Singleton, mirroring {@link LogApiCallImpl}: use the exported {@link ApiCallLogName} constant, not `new`.\n * Kept in one place so the two duplicated console formats stay byte-identical, and so the special-cased\n * name matches the logger name LogApiCall actually uses ({@link LOG_API_CALL_LOGGER_NAME}).\n */\nexport class ApiCallLogNameImpl {\n\n    /**\n     * The complete logger bracket for one console line — the single seam both console backends call so\n     * they render byte-identically. A LogApiCall line becomes a self-describing `[API.{side}.{phase}]`\n     * bracket derived from its `api` tag; every other line keeps its plain `[loggerName]` bracket; a line\n     * with no logger name at all (startup / pre-route) renders `''`.\n     *\n     * Phase mapping mirrors {@link ApiCallInfo}: a `request` tag → `request`; a `response` tag →\n     * `failure` when `result:'failure'`, else `success` (which correctly folds handled user errors,\n     * whose result is `success`, into `success`).\n     *\n     * @param loggerName - the record's `loggerName` field (off a parsed/structured log record)\n     * @param api - the record's `api` field (the stamped {@link ApiCallInfo}, or undefined/other)\n     * @returns e.g. `\"[API.client.request]\"`, `\"[MyClass]\"`, or `\"\"`\n     */\n    bracket(loggerName: LogFieldValue, api: LogFieldValue): string {\n        const apiName = this.describe(loggerName, api);\n        if (apiName !== undefined) {\n            return `[${apiName}]`;\n        }\n        return loggerName ? `[${String(loggerName)}]` : '';\n    }\n\n    /**\n     * The self-describing name (no brackets) for a LogApiCall line, e.g. `\"API.client.request\"`, or\n     * `undefined` when this is not a LogApiCall line or its `api` tag is missing/misshapen. Callers use\n     * {@link bracket}; this is factored out for direct testing of the phase mapping.\n     */\n    describe(loggerName: LogFieldValue, api: LogFieldValue): string | undefined {\n        if (loggerName !== LOG_API_CALL_LOGGER_NAME) {\n            return undefined;\n        }\n        if (!(api instanceof Object)) {\n            return undefined;\n        }\n        // The record may be a plain JSON.parse output (bunyan) rather than an ApiCallInfo instance\n        // (winston reads the live object), so read structurally rather than via instanceof.\n        const info = api as Partial<ApiCallInfo>;\n        const side = typeof info.method?.side === 'string' ? info.method.side : 'unknown';\n        const phase = info.type === 'request' ? 'request' : info.result === 'failure' ? 'failure' : 'success';\n        return `API.${side}.${phase}`;\n    }\n}\n\n/**\n * The process-wide {@link ApiCallLogNameImpl} singleton — mirrors the {@link LogApiCallImpl} export pattern.\n * Callers use `ApiCallLogName.describe(...)`, never `new`.\n */\nexport const ApiCallLogName = new ApiCallLogNameImpl();\n"]}

package/src/http/ApiMethodInfo.d.ts

@@ -1,6 +1,6 @@
 /**
  * ApiMethodInfo - the transport-neutral identity of a single API method call, handed to
- * {@link LogApiCall.execute} by every caller (server inbound, http/in-process clients, cloud tasks,
+ * {@link LogApiCallImpl.execute} by every caller (server inbound, http/in-process clients, cloud tasks,
  * and external wrapped clients like the firestore admin client).
  *
  * WHY generic (not RouteMetadata): LogApiCall runs deep in the stack over MANY shapes — HTTP routes,
@@ -30,7 +30,7 @@ export declare class ApiMethodInfo {
      *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */
     readonly controllerName?: string | undefined;
     /** OPTIONAL — which DTO fields to mask in the log lines, and how. Absent = log the DTO
-     *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCall}
+     *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCallImpl}
      *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an
      *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.
      *  Rides the call identity so the spec travels with the api definition, not a global app config. */
@@ -45,7 +45,7 @@ export declare class ApiMethodInfo {
      *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */
     controllerName?: string | undefined, 
     /** OPTIONAL — which DTO fields to mask in the log lines, and how. Absent = log the DTO
-     *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCall}
+     *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCallImpl}
      *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an
      *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.
      *  Rides the call identity so the spec travels with the api definition, not a global app config. */

package/src/http/ApiMethodInfo.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * ApiMethodInfo - the transport-neutral identity of a single API method call, handed to
- * {@link LogApiCall.execute} by every caller (server inbound, http/in-process clients, cloud tasks,
+ * {@link LogApiCallImpl.execute} by every caller (server inbound, http/in-process clients, cloud tasks,
  * and external wrapped clients like the firestore admin client).
  *
  * WHY generic (not RouteMetadata): LogApiCall runs deep in the stack over MANY shapes — HTTP routes,
@@ -35,7 +35,7 @@ class ApiMethodInfo {
      *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */
     controllerName, 
     /** OPTIONAL — which DTO fields to mask in the log lines, and how. Absent = log the DTO
-     *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCall}
+     *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCallImpl}
      *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an
      *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.
      *  Rides the call identity so the spec travels with the api definition, not a global app config. */

package/src/http/ApiMethodInfo.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiMethodInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiMethodInfo.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAOH,MAAa,aAAa;IAET;IAGA;IAEA;IAGA;IAMA;IAfb,YACa,IAAa;IACtB;2FACuF;IAC9E,QAAgB;IACzB,2DAA2D;IAClD,UAAkB;IAC3B;gGAC4F;IACnF,cAAuB;IAChC;;;;wGAIoG;IAC3F,IAAe;QAdf,SAAI,GAAJ,IAAI,CAAS;QAGb,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,eAAU,GAAV,UAAU,CAAQ;QAGlB,mBAAc,GAAd,cAAc,CAAS;QAMvB,SAAI,GAAJ,IAAI,CAAW;IACzB,CAAC;CACP;AAlBD,sCAkBC","sourcesContent":["/**\n * ApiMethodInfo - the transport-neutral identity of a single API method call, handed to\n * {@link LogApiCall.execute} by every caller (server inbound, http/in-process clients, cloud tasks,\n * and external wrapped clients like the firestore admin client).\n *\n * WHY generic (not RouteMetadata): LogApiCall runs deep in the stack over MANY shapes — HTTP routes,\n * pubsub/queue enqueues, and multi-param external clients returning Promise<void>/Promise<unknown>.\n * None of those own an `httpMethod`/`path`, so LogApiCall must not depend on the HTTP-shaped\n * `RouteMetadata`. This carries only what identifies the call.\n *\n * MATCHING is the point of {@link apiClass}: a CLIENT call and the SERVER handler for the same logical\n * method must log the SAME identity so `jsonPayload.api.method.apiClass=\"SaveApi\"` filters both sides\n * together. The API CONTRACT class name (e.g. 'SaveApi') is available on both sides — the client only\n * ever knows it, and the server carries it alongside its impl name — so it, not the server's impl\n * class, is the required key.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\nimport {MaskSpec} from \"./LogFieldMask\";\n\n/** Which end of the exchange this process is: the caller ('client') or the handler ('server'). */\nexport type ApiSide = 'client' | 'server';\n\nexport class ApiMethodInfo {\n    constructor(\n        readonly side: ApiSide,\n        /** REQUIRED — the API CONTRACT class name (e.g. 'SaveApi'). Matches client + server so both\n         *  sides of one logical call filter together via `jsonPayload.api.method.apiClass`. */\n        readonly apiClass: string,\n        /** REQUIRED — the method on the contract (e.g. 'save'). */\n        readonly methodName: string,\n        /** OPTIONAL — server-side impl class (e.g. 'SaveController'). Absent on clients, which have no\n         *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */\n        readonly controllerName?: string,\n        /** OPTIONAL — which DTO fields to mask in the log lines, and how. Absent = log the DTO\n         *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCall}\n         *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an\n         *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.\n         *  Rides the call identity so the spec travels with the api definition, not a global app config. */\n        readonly mask?: MaskSpec,\n    ) {}\n}\n"]}
+{"version":3,"file":"ApiMethodInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiMethodInfo.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAOH,MAAa,aAAa;IAET;IAGA;IAEA;IAGA;IAMA;IAfb,YACa,IAAa;IACtB;2FACuF;IAC9E,QAAgB;IACzB,2DAA2D;IAClD,UAAkB;IAC3B;gGAC4F;IACnF,cAAuB;IAChC;;;;wGAIoG;IAC3F,IAAe;QAdf,SAAI,GAAJ,IAAI,CAAS;QAGb,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,eAAU,GAAV,UAAU,CAAQ;QAGlB,mBAAc,GAAd,cAAc,CAAS;QAMvB,SAAI,GAAJ,IAAI,CAAW;IACzB,CAAC;CACP;AAlBD,sCAkBC","sourcesContent":["/**\n * ApiMethodInfo - the transport-neutral identity of a single API method call, handed to\n * {@link LogApiCallImpl.execute} by every caller (server inbound, http/in-process clients, cloud tasks,\n * and external wrapped clients like the firestore admin client).\n *\n * WHY generic (not RouteMetadata): LogApiCall runs deep in the stack over MANY shapes — HTTP routes,\n * pubsub/queue enqueues, and multi-param external clients returning Promise<void>/Promise<unknown>.\n * None of those own an `httpMethod`/`path`, so LogApiCall must not depend on the HTTP-shaped\n * `RouteMetadata`. This carries only what identifies the call.\n *\n * MATCHING is the point of {@link apiClass}: a CLIENT call and the SERVER handler for the same logical\n * method must log the SAME identity so `jsonPayload.api.method.apiClass=\"SaveApi\"` filters both sides\n * together. The API CONTRACT class name (e.g. 'SaveApi') is available on both sides — the client only\n * ever knows it, and the server carries it alongside its impl name — so it, not the server's impl\n * class, is the required key.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\nimport {MaskSpec} from \"./LogFieldMask\";\n\n/** Which end of the exchange this process is: the caller ('client') or the handler ('server'). */\nexport type ApiSide = 'client' | 'server';\n\nexport class ApiMethodInfo {\n    constructor(\n        readonly side: ApiSide,\n        /** REQUIRED — the API CONTRACT class name (e.g. 'SaveApi'). Matches client + server so both\n         *  sides of one logical call filter together via `jsonPayload.api.method.apiClass`. */\n        readonly apiClass: string,\n        /** REQUIRED — the method on the contract (e.g. 'save'). */\n        readonly methodName: string,\n        /** OPTIONAL — server-side impl class (e.g. 'SaveController'). Absent on clients, which have no\n         *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */\n        readonly controllerName?: string,\n        /** OPTIONAL — which DTO fields to mask in the log lines, and how. Absent = log the DTO\n         *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCallImpl}\n         *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an\n         *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.\n         *  Rides the call identity so the spec travels with the api definition, not a global app config. */\n        readonly mask?: MaskSpec,\n    ) {}\n}\n"]}

package/src/http/LogApiCall.d.ts

@@ -1,22 +1,29 @@
 import { ApiMethodInfo } from "./ApiMethodInfo";
+import { ApiCallContext } from "./ApiCallContext";
 /**
- * LogApiCall - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and
+ * LogApiCallImpl - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and
  * client-side (ProxyClient) for one consistent logging shape across the framework.
  *
  * TWO things happen around each call:
  * 1. Text lines are emitted (the human-readable `[API-...]` patterns below).
  * 2. A structured {@link ApiCallInfo} tag is stamped into the ambient request context via the
- *    {@link ApiCallContextHolder} seam, so EVERY log line emitted during the call (not just the
+ *    {@link ApiCallContext} seam, so EVERY log line emitted during the call (not just the
  *    req/resp lines) inherits a filterable `api` object — surfacing in GCP as
  *    `jsonPayload.api.{method.{side,apiClass,methodName,controllerName},type,result}`.
  *
  * BROWSER-SAFE: this lives in core-util and runs in the browser bundle (via ProxyClient →
  * BrowserProxyClient), so it MUST NOT import `RequestContext` (Node async_hooks, and a circular dep).
- * It stamps through the {@link ApiCallContext} seam instead: `setupRuntime` installs a
- * RequestContext-backed impl on a Node server, and `ClientHttpBrowserFactory` a module-global impl in a
- * browser. If neither ran, {@link ApiCallContextHolder.get} throws (loud misconfiguration).
+ * It stamps through the {@link ApiCallContext} seam instead, and takes that seam as a REQUIRED
+ * CONSTRUCTOR ARGUMENT — there is no process-global holder to install and none to forget. Each
+ * environment-specific package constructs its own:
  *
- * Singleton, mirroring `RequestContext`: use the exported {@link LogApiCall} constant, not `new`.
+ *   LogApiFilter        (@webpieces/http-routing)        -> new LogApiCallImpl(new RequestContextApiCallContext())
+ *   NodeProxyClient     (@webpieces/http-client-node)    -> new LogApiCallImpl(new RequestContextApiCallContext())
+ *   TaskProxyClient     (@webpieces/cloudtasks-client)   -> new LogApiCallImpl(new RequestContextApiCallContext())
+ *   BrowserProxyClient  (@webpieces/http-client-browser) -> new LogApiCallImpl(new BrowserApiCallContext())
+ *
+ * NOT a singleton, deliberately: a shared instance would need a shared context, which is the global
+ * this constructor replaced. Construct one where you know which environment you are in.
  *
  * Logging format patterns:
  * - [API-{side}-req] ClassName.methodName request={...}
@@ -25,6 +32,13 @@ import { ApiMethodInfo } from "./ApiMethodInfo";
  * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (server errors)
  */
 export declare class LogApiCallImpl {
+    private readonly ctx;
+    /**
+     * @param ctx - the environment's {@link ApiCallContext}. REQUIRED, with no default: that is what
+     *   turns "nobody bootstrapped the context" into a compile error instead of a throw on the first
+     *   real call in production.
+     */
+    constructor(ctx: ApiCallContext);
     /**
      * Execute an API call with logging + `api` context-tagging around it.
      *
@@ -49,8 +63,9 @@ export declare class LogApiCallImpl {
      */
     private serialize;
     /**
-     * The ApiCallContext to stamp into. Throws if none was installed at startup, or if there is no
-     * active scope — loud misconfiguration, because an api call with nowhere to tag is a bug.
+     * The ApiCallContext to stamp into. It cannot be MISSING (it is a constructor argument), but it
+     * can be INACTIVE — a Node context used outside any `RequestContext.run(...)` scope. That throws:
+     * an api call with nowhere to tag is a bug.
      */
     private activeContext;
     /**
@@ -80,8 +95,3 @@ export declare class LogApiCallImpl {
      */
     isUserError(error: Error, server: boolean): boolean;
 }
-/**
- * The process-wide {@link LogApiCallImpl} singleton — mirrors the `RequestContext` export pattern.
- * Callers use `LogApiCall.execute(...)`, never `new`.
- */
-export declare const LogApiCall: LogApiCallImpl;

package/src/http/LogApiCall.js

@@ -1,11 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogApiCall = exports.LogApiCallImpl = void 0;
+exports.LogApiCallImpl = void 0;
 const errorUtils_1 = require("../lib/errorUtils");
 const LogManager_1 = require("../logging/LogManager");
 const ApiCallInfo_1 = require("./ApiCallInfo");
 const ApiMethodInfo_1 = require("./ApiMethodInfo");
-const ApiCallContext_1 = require("./ApiCallContext");
 const WebpiecesCoreHeaders_1 = require("./WebpiecesCoreHeaders");
 const ApiCallLogName_1 = require("./ApiCallLogName");
 const ClientRegistry_1 = require("./ClientRegistry");
@@ -14,23 +13,29 @@ const WebpiecesDefaultFailureClassifier_1 = require("./WebpiecesDefaultFailureCl
 // bracket (see ApiCallLogName) — so the name here and the name they match are the one constant.
 const log = LogManager_1.LogManager.getLogger(ApiCallLogName_1.LOG_API_CALL_LOGGER_NAME);
 /**
- * LogApiCall - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and
+ * LogApiCallImpl - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and
  * client-side (ProxyClient) for one consistent logging shape across the framework.
  *
  * TWO things happen around each call:
  * 1. Text lines are emitted (the human-readable `[API-...]` patterns below).
  * 2. A structured {@link ApiCallInfo} tag is stamped into the ambient request context via the
- *    {@link ApiCallContextHolder} seam, so EVERY log line emitted during the call (not just the
+ *    {@link ApiCallContext} seam, so EVERY log line emitted during the call (not just the
  *    req/resp lines) inherits a filterable `api` object — surfacing in GCP as
  *    `jsonPayload.api.{method.{side,apiClass,methodName,controllerName},type,result}`.
  *
  * BROWSER-SAFE: this lives in core-util and runs in the browser bundle (via ProxyClient →
  * BrowserProxyClient), so it MUST NOT import `RequestContext` (Node async_hooks, and a circular dep).
- * It stamps through the {@link ApiCallContext} seam instead: `setupRuntime` installs a
- * RequestContext-backed impl on a Node server, and `ClientHttpBrowserFactory` a module-global impl in a
- * browser. If neither ran, {@link ApiCallContextHolder.get} throws (loud misconfiguration).
+ * It stamps through the {@link ApiCallContext} seam instead, and takes that seam as a REQUIRED
+ * CONSTRUCTOR ARGUMENT — there is no process-global holder to install and none to forget. Each
+ * environment-specific package constructs its own:
  *
- * Singleton, mirroring `RequestContext`: use the exported {@link LogApiCall} constant, not `new`.
+ *   LogApiFilter        (@webpieces/http-routing)        -> new LogApiCallImpl(new RequestContextApiCallContext())
+ *   NodeProxyClient     (@webpieces/http-client-node)    -> new LogApiCallImpl(new RequestContextApiCallContext())
+ *   TaskProxyClient     (@webpieces/cloudtasks-client)   -> new LogApiCallImpl(new RequestContextApiCallContext())
+ *   BrowserProxyClient  (@webpieces/http-client-browser) -> new LogApiCallImpl(new BrowserApiCallContext())
+ *
+ * NOT a singleton, deliberately: a shared instance would need a shared context, which is the global
+ * this constructor replaced. Construct one where you know which environment you are in.
  *
  * Logging format patterns:
  * - [API-{side}-req] ClassName.methodName request={...}
@@ -39,6 +44,15 @@ const log = LogManager_1.LogManager.getLogger(ApiCallLogName_1.LOG_API_CALL_LOGG
  * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (server errors)
  */
 class LogApiCallImpl {
+    ctx;
+    /**
+     * @param ctx - the environment's {@link ApiCallContext}. REQUIRED, with no default: that is what
+     *   turns "nobody bootstrapped the context" into a compile error instead of a throw on the first
+     *   real call in production.
+     */
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
     /**
      * Execute an API call with logging + `api` context-tagging around it.
      *
@@ -111,14 +125,17 @@ class LogApiCallImpl {
         return methodInfo.mask ? methodInfo.mask.stringify(dto) : JSON.stringify(dto);
     }
     /**
-     * The ApiCallContext to stamp into. Throws if none was installed at startup, or if there is no
-     * active scope — loud misconfiguration, because an api call with nowhere to tag is a bug.
+     * The ApiCallContext to stamp into. It cannot be MISSING (it is a constructor argument), but it
+     * can be INACTIVE — a Node context used outside any `RequestContext.run(...)` scope. That throws:
+     * an api call with nowhere to tag is a bug.
      */
     activeContext() {
-        const ctx = ApiCallContext_1.ApiCallContextHolder.get();
+        const ctx = this.ctx;
         if (!ctx.isActive()) {
-            throw new Error('LogApiCall requires an ACTIVE ApiCallContext. On a Node server, run inside the ' +
-                'RequestContext.run(...) a server filter opens; in a browser, build ClientHttpBrowserFactory first.');
+            throw new Error('LogApiCall requires an ACTIVE ApiCallContext. On a Node server, run inside a ' +
+                'RequestContext.run(...) scope — a server filter opens one per request, and a ' +
+                'non-webpieces host must open one around the work that calls a webpieces client. ' +
+                '(A BrowserApiCallContext is always active, so this can only be the Node side.)');
         }
         return ctx;
     }
@@ -169,9 +186,4 @@ class LogApiCallImpl {
     }
 }
 exports.LogApiCallImpl = LogApiCallImpl;
-/**
- * The process-wide {@link LogApiCallImpl} singleton — mirrors the `RequestContext` export pattern.
- * Callers use `LogApiCall.execute(...)`, never `new`.
- */
-exports.LogApiCall = new LogApiCallImpl();
 //# sourceMappingURL=LogApiCall.js.map