@webpieces/http-client-core 0.0.0-dev

package/README.md

@@ -0,0 +1,17 @@
+# @webpieces/http-client-core
+
+The isomorphic engine behind the webpieces HTTP clients. You almost certainly want one of:
+
+- **[@webpieces/http-client-node](../http-client-node)** — server-side: inversify-wired, reads
+  `RequestContext`, mints OIDC / shared-secret delivery auth, resolves Cloud Run URLs from a
+  service name.
+- **[@webpieces/http-client-browser](../http-client-browser)** — browser: DI-free (React or
+  Angular), app-managed context store, no AsyncLocalStorage.
+
+This package holds what they share: `ProxyClient` (contract decorators → HTTP request),
+`buildClientProxy` (the typed `Proxy` trap), `ClientTarget`, and `ClientErrorTranslator`.
+
+The one seam between the two environments is `OutboundHeaders` (in `@webpieces/core-util`):
+`RequestContextHeaders` on the server, `ContextMgr` in a browser. Keeping that a seam is what
+lets this package depend on nothing but `core-util`, so no node-only import can reach a browser
+bundle.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@webpieces/http-client-core",
+  "version": "0.0.0-dev",
+  "description": "Isomorphic core of the webpieces HTTP client: the decorator-driven ProxyClient, error translation, and the Proxy trap shared by http-client-node and http-client-browser",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/http/http-client-core"
+  },
+  "keywords": [
+    "webpieces",
+    "http",
+    "client"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@webpieces/core-util": "workspace:*"
+  }
+}

package/src/ApiPrototype.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type representing a class constructor whose prototype is T — the shared API contract class,
+ * carrying the @ApiPath/@Endpoint/@Auth* decorators that both the client and the server read.
+ */
+export type ApiPrototype<T> = Function & {
+    prototype: T;
+};

package/src/ApiPrototype.js

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

package/src/ApiPrototype.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiPrototype.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/ApiPrototype.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Type representing a class constructor whose prototype is T — the shared API contract class,\n * carrying the @ApiPath/@Endpoint/@Auth* decorators that both the client and the server read.\n */\nexport type ApiPrototype<T> = Function & { prototype: T };\n"]}

package/src/ClientErrorTranslator.d.ts

@@ -0,0 +1,37 @@
+import { ProtocolError } from '@webpieces/core-util';
+/**
+ * ClientErrorTranslator - Translates HTTP error responses to HttpError exceptions.
+ *
+ * This is the CLIENT-SIDE reverse of ExpressWrapper.handleError() on the server.
+ * It reconstructs typed HttpError exceptions from ProtocolError JSON responses.
+ *
+ * Architecture:
+ * - Server: HttpError → ExpressWrapper.handleError() → ProtocolError JSON
+ * - Client: ProtocolError JSON → ClientErrorTranslator.translateError() → HttpError
+ *
+ * This achieves symmetric error handling - server throws typed exceptions,
+ * client receives typed exceptions.
+ */
+export declare class ClientErrorTranslator {
+    /**
+     * Parse error response and reconstruct appropriate HttpError subclass.
+     *
+     * Maps HTTP status codes to error types (symmetric with server):
+     * - 400 → HttpBadRequestError (with field, guiAlertMessage)
+     * - 266 → HttpUserError (with errorCode) - 2xx code for user validation
+     * - 401 → HttpUnauthorizedError
+     * - 403 → HttpForbiddenError
+     * - 404 → HttpNotFoundError
+     * - 408 → HttpTimeoutError
+     * - 500 → HttpInternalServerError
+     * - 502 → HttpBadGatewayError
+     * - 504 → HttpGatewayTimeoutError
+     * - 598 → HttpVendorError (with waitSeconds) - custom status code
+     * - other → generic HttpError
+     *
+     * @param response - Fetch Response object
+     * @param protocolError - Parsed ProtocolError from response body
+     * @returns HttpError subclass instance
+     */
+    static translateError(response: Response, protocolError: ProtocolError): Error;
+}

package/src/ClientErrorTranslator.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientErrorTranslator = void 0;
+const core_util_1 = require("@webpieces/core-util");
+/**
+ * ClientErrorTranslator - Translates HTTP error responses to HttpError exceptions.
+ *
+ * This is the CLIENT-SIDE reverse of ExpressWrapper.handleError() on the server.
+ * It reconstructs typed HttpError exceptions from ProtocolError JSON responses.
+ *
+ * Architecture:
+ * - Server: HttpError → ExpressWrapper.handleError() → ProtocolError JSON
+ * - Client: ProtocolError JSON → ClientErrorTranslator.translateError() → HttpError
+ *
+ * This achieves symmetric error handling - server throws typed exceptions,
+ * client receives typed exceptions.
+ */
+class ClientErrorTranslator {
+    /**
+     * Parse error response and reconstruct appropriate HttpError subclass.
+     *
+     * Maps HTTP status codes to error types (symmetric with server):
+     * - 400 → HttpBadRequestError (with field, guiAlertMessage)
+     * - 266 → HttpUserError (with errorCode) - 2xx code for user validation
+     * - 401 → HttpUnauthorizedError
+     * - 403 → HttpForbiddenError
+     * - 404 → HttpNotFoundError
+     * - 408 → HttpTimeoutError
+     * - 500 → HttpInternalServerError
+     * - 502 → HttpBadGatewayError
+     * - 504 → HttpGatewayTimeoutError
+     * - 598 → HttpVendorError (with waitSeconds) - custom status code
+     * - other → generic HttpError
+     *
+     * @param response - Fetch Response object
+     * @param protocolError - Parsed ProtocolError from response body
+     * @returns HttpError subclass instance
+     */
+    static translateError(response, protocolError) {
+        const statusCode = response.status;
+        const message = protocolError.message || response.statusText || 'Unknown error';
+        const subType = protocolError.subType;
+        // Map status codes to error types (symmetric with server's ExpressWrapper.handleError())
+        switch (statusCode) {
+            case 400:
+                return new core_util_1.HttpBadRequestError(message, protocolError.field, protocolError.guiAlertMessage);
+            case 266: // HttpUserError - 2xx code for user validation errors
+                return new core_util_1.HttpUserError(message, protocolError.errorCode);
+            case 401:
+                return new core_util_1.HttpUnauthorizedError(message, subType);
+            case 403:
+                return new core_util_1.HttpForbiddenError(message);
+            case 404:
+                return new core_util_1.HttpNotFoundError(message);
+            case 408:
+                return new core_util_1.HttpTimeoutError(message);
+            case 500:
+                return new core_util_1.HttpInternalServerError(message);
+            case 502:
+                return new core_util_1.HttpBadGatewayError(message);
+            case 504:
+                return new core_util_1.HttpGatewayTimeoutError(message);
+            case 598: // HttpVendorError - custom status code for vendor/external service errors
+                return new core_util_1.HttpVendorError(message, protocolError.waitSeconds);
+            default:
+                // Unknown status code - return generic HttpError
+                return new Error(` could not translate statusCode=${statusCode}`);
+        }
+    }
+}
+exports.ClientErrorTranslator = ClientErrorTranslator;
+//# sourceMappingURL=ClientErrorTranslator.js.map

package/src/ClientErrorTranslator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientErrorTranslator.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/ClientErrorTranslator.ts"],"names":[],"mappings":";;;AAAA,oDAa8B;AAE9B;;;;;;;;;;;;GAYG;AACH,MAAa,qBAAqB;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,cAAc,CAAC,QAAkB,EAAE,aAA4B;QAClE,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;QACnC,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,QAAQ,CAAC,UAAU,IAAI,eAAe,CAAC;QAChF,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;QAEtC,yFAAyF;QACzF,QAAQ,UAAU,EAAE,CAAC;YACjB,KAAK,GAAG;gBACJ,OAAO,IAAI,+BAAmB,CAC1B,OAAO,EACP,aAAa,CAAC,KAAK,EACnB,aAAa,CAAC,eAAe,CAChC,CAAC;YAEN,KAAK,GAAG,EAAE,sDAAsD;gBAC5D,OAAO,IAAI,yBAAa,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;YAE/D,KAAK,GAAG;gBACJ,OAAO,IAAI,iCAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAEvD,KAAK,GAAG;gBACJ,OAAO,IAAI,8BAAkB,CAAC,OAAO,CAAC,CAAC;YAE3C,KAAK,GAAG;gBACJ,OAAO,IAAI,6BAAiB,CAAC,OAAO,CAAC,CAAC;YAE1C,KAAK,GAAG;gBACJ,OAAO,IAAI,4BAAgB,CAAC,OAAO,CAAC,CAAC;YAEzC,KAAK,GAAG;gBACJ,OAAO,IAAI,mCAAuB,CAAC,OAAO,CAAC,CAAC;YAEhD,KAAK,GAAG;gBACJ,OAAO,IAAI,+BAAmB,CAAC,OAAO,CAAC,CAAC;YAE5C,KAAK,GAAG;gBACJ,OAAO,IAAI,mCAAuB,CAAC,OAAO,CAAC,CAAC;YAEhD,KAAK,GAAG,EAAE,0EAA0E;gBAChF,OAAO,IAAI,2BAAe,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;YAEnE;gBACI,iDAAiD;gBACjD,OAAO,IAAI,KAAK,CAAC,mCAAmC,UAAU,EAAE,CAAC,CAAC;QAC1E,CAAC;IACL,CAAC;CACJ;AAnED,sDAmEC","sourcesContent":["import {\n    ProtocolError,\n    HttpError,\n    HttpBadRequestError,\n    HttpUserError,\n    HttpVendorError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpNotFoundError,\n    HttpTimeoutError,\n    HttpInternalServerError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n} from '@webpieces/core-util';\n\n/**\n * ClientErrorTranslator - Translates HTTP error responses to HttpError exceptions.\n *\n * This is the CLIENT-SIDE reverse of ExpressWrapper.handleError() on the server.\n * It reconstructs typed HttpError exceptions from ProtocolError JSON responses.\n *\n * Architecture:\n * - Server: HttpError → ExpressWrapper.handleError() → ProtocolError JSON\n * - Client: ProtocolError JSON → ClientErrorTranslator.translateError() → HttpError\n *\n * This achieves symmetric error handling - server throws typed exceptions,\n * client receives typed exceptions.\n */\nexport class ClientErrorTranslator {\n    /**\n     * Parse error response and reconstruct appropriate HttpError subclass.\n     *\n     * Maps HTTP status codes to error types (symmetric with server):\n     * - 400 → HttpBadRequestError (with field, guiAlertMessage)\n     * - 266 → HttpUserError (with errorCode) - 2xx code for user validation\n     * - 401 → HttpUnauthorizedError\n     * - 403 → HttpForbiddenError\n     * - 404 → HttpNotFoundError\n     * - 408 → HttpTimeoutError\n     * - 500 → HttpInternalServerError\n     * - 502 → HttpBadGatewayError\n     * - 504 → HttpGatewayTimeoutError\n     * - 598 → HttpVendorError (with waitSeconds) - custom status code\n     * - other → generic HttpError\n     *\n     * @param response - Fetch Response object\n     * @param protocolError - Parsed ProtocolError from response body\n     * @returns HttpError subclass instance\n     */\n    static translateError(response: Response, protocolError: ProtocolError): Error {\n        const statusCode = response.status;\n        const message = protocolError.message || response.statusText || 'Unknown error';\n        const subType = protocolError.subType;\n\n        // Map status codes to error types (symmetric with server's ExpressWrapper.handleError())\n        switch (statusCode) {\n            case 400:\n                return new HttpBadRequestError(\n                    message,\n                    protocolError.field,\n                    protocolError.guiAlertMessage,\n                );\n\n            case 266: // HttpUserError - 2xx code for user validation errors\n                return new HttpUserError(message, protocolError.errorCode);\n\n            case 401:\n                return new HttpUnauthorizedError(message, subType);\n\n            case 403:\n                return new HttpForbiddenError(message);\n\n            case 404:\n                return new HttpNotFoundError(message);\n\n            case 408:\n                return new HttpTimeoutError(message);\n\n            case 500:\n                return new HttpInternalServerError(message);\n\n            case 502:\n                return new HttpBadGatewayError(message);\n\n            case 504:\n                return new HttpGatewayTimeoutError(message);\n\n            case 598: // HttpVendorError - custom status code for vendor/external service errors\n                return new HttpVendorError(message, protocolError.waitSeconds);\n\n            default:\n                // Unknown status code - return generic HttpError\n                return new Error(` could not translate statusCode=${statusCode}`);\n        }\n    }\n}\n"]}

package/src/ProxyClient.d.ts

@@ -0,0 +1,79 @@
+import { AuthMeta, RouteMetadata, LogApiCall } from '@webpieces/core-util';
+import { ApiPrototype } from './ApiPrototype';
+/**
+ * ProxyClient - the HTTP call engine behind one API contract's client proxy.
+ *
+ * Contains ONLY what a browser can run: the route map built from the contract's decorators, URL
+ * assembly, `fetch`, error translation, and logging. It holds no context object, no credentials,
+ * and no recorder — it ASKS ITSELF for those through the hooks below, and each subclass answers
+ * from its own environment.
+ *
+ * That is why the class is abstract rather than parameterized by a collaborator: a shared
+ * header-provider seam would drag Node's AsyncLocalStorage vocabulary into a browser bundle and the
+ * browser's store vocabulary into a server, and neither has any use for the other.
+ *
+ *   NodeProxyClient    (@webpieces/http-client-node)    -> RequestContext, Secrets, mintIdToken, recording
+ *   BrowserProxyClient (@webpieces/http-client-browser) -> an app-held store, no credentials, no recording
+ *
+ * TWO-PHASE: collaborators arrive on the subclass constructor (so a DI container can supply them),
+ * while the per-client state — which contract, which target — arrives on the subclass's `init`,
+ * which calls {@link initRoutes}. That is what lets a factory hold a `Provider<ProxyClient>` and
+ * hand out a fresh, independently-configured client per contract.
+ */
+export declare abstract class ProxyClient {
+    protected readonly logApiCall: LogApiCall;
+    private routeMap;
+    private apiName;
+    constructor(logApiCall?: LogApiCall);
+    /** The callee's base URL. Async because a server may derive it from container metadata. */
+    protected abstract resolveBaseUrl(): Promise<string>;
+    /** Context headers to put on the wire. Server reads RequestContext; browser reads its store. */
+    protected abstract outboundHeaders(): Map<string, string>;
+    /**
+     * Attach the endpoint's outbound credential. Service-to-service auth (@AuthOidc bearer,
+     * @AuthSharedSecret value) is a SERVER concept; a browser has neither a minter nor a Secrets
+     * store, so it attaches nothing and its user JWT simply travels as a transferred context key.
+     */
+    protected attachOutboundAuth(_route: RouteMetadata, _baseUrl: string, _httpHeaders: Record<string, string>): Promise<void>;
+    /**
+     * Run the call. The default just logs it. Test-case RECORDING is a server concept, so
+     * NodeProxyClient overrides this to capture the call when a recorder is in the context.
+     *
+     * Context fields are NOT passed in: a logging backend stamps them onto every record itself.
+     */
+    protected execute(route: RouteMetadata, requestDto: unknown, method: () => Promise<unknown>): Promise<unknown>;
+    /**
+     * Reject, at bind time, an endpoint this environment cannot satisfy — e.g. a browser cannot
+     * mint the OIDC token an @AuthOidc endpoint demands. Surfacing it here beats failing on the
+     * first call in production. The default accepts everything.
+     */
+    protected assertEndpointSupported(_authMeta: AuthMeta | undefined, _methodName: string): void;
+    /**
+     * Bind this client to one API contract: read @ApiPath/@Endpoint/@Auth* off the prototype and
+     * build the route map once. Each subclass's `init(api, config)` stores its own config, then
+     * calls this.
+     *
+     * @throws Error if the prototype lacks @ApiPath, or declares an endpoint this environment
+     *         cannot satisfy (see {@link assertEndpointSupported}).
+     */
+    protected initRoutes(apiPrototype: ApiPrototype<object>): void;
+    /** The contract's class name, for logs and recordings. */
+    protected contractName(): string;
+    /** Check if a route exists for the given method name. */
+    hasRoute(methodName: string): boolean;
+    /**
+     * Get route metadata for a method name.
+     * @throws Error if no route found
+     */
+    getRoute(methodName: string): RouteMetadata;
+    /**
+     * Make an HTTP request based on route metadata and arguments.
+     *
+     * All endpoints are POST-only. The request body is the first argument.
+     */
+    makeRequest(route: RouteMetadata, args: any[]): Promise<any>;
+    /**
+     * Execute the fetch request and handle response.
+     */
+    private executeFetch;
+}

package/src/ProxyClient.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyClient = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const ClientErrorTranslator_1 = require("./ClientErrorTranslator");
+/**
+ * ProxyClient - the HTTP call engine behind one API contract's client proxy.
+ *
+ * Contains ONLY what a browser can run: the route map built from the contract's decorators, URL
+ * assembly, `fetch`, error translation, and logging. It holds no context object, no credentials,
+ * and no recorder — it ASKS ITSELF for those through the hooks below, and each subclass answers
+ * from its own environment.
+ *
+ * That is why the class is abstract rather than parameterized by a collaborator: a shared
+ * header-provider seam would drag Node's AsyncLocalStorage vocabulary into a browser bundle and the
+ * browser's store vocabulary into a server, and neither has any use for the other.
+ *
+ *   NodeProxyClient    (@webpieces/http-client-node)    -> RequestContext, Secrets, mintIdToken, recording
+ *   BrowserProxyClient (@webpieces/http-client-browser) -> an app-held store, no credentials, no recording
+ *
+ * TWO-PHASE: collaborators arrive on the subclass constructor (so a DI container can supply them),
+ * while the per-client state — which contract, which target — arrives on the subclass's `init`,
+ * which calls {@link initRoutes}. That is what lets a factory hold a `Provider<ProxyClient>` and
+ * hand out a fresh, independently-configured client per contract.
+ */
+class ProxyClient {
+    logApiCall;
+    // Assigned by initRoutes(), which every subclass's init() calls immediately after construction.
+    routeMap;
+    apiName;
+    constructor(logApiCall = new core_util_1.LogApiCall()) {
+        this.logApiCall = logApiCall;
+    }
+    /**
+     * Attach the endpoint's outbound credential. Service-to-service auth (@AuthOidc bearer,
+     * @AuthSharedSecret value) is a SERVER concept; a browser has neither a minter nor a Secrets
+     * store, so it attaches nothing and its user JWT simply travels as a transferred context key.
+     */
+    async attachOutboundAuth(_route, _baseUrl, _httpHeaders) { }
+    /**
+     * Run the call. The default just logs it. Test-case RECORDING is a server concept, so
+     * NodeProxyClient overrides this to capture the call when a recorder is in the context.
+     *
+     * Context fields are NOT passed in: a logging backend stamps them onto every record itself.
+     */
+    // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary
+    async execute(route, requestDto, 
+    // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary
+    method) {
+        return this.logApiCall.execute('CLIENT', route, requestDto, method);
+    }
+    /**
+     * Reject, at bind time, an endpoint this environment cannot satisfy — e.g. a browser cannot
+     * mint the OIDC token an @AuthOidc endpoint demands. Surfacing it here beats failing on the
+     * first call in production. The default accepts everything.
+     */
+    assertEndpointSupported(_authMeta, _methodName) { }
+    // ---------------------------------------------------------------- contract binding
+    /**
+     * Bind this client to one API contract: read @ApiPath/@Endpoint/@Auth* off the prototype and
+     * build the route map once. Each subclass's `init(api, config)` stores its own config, then
+     * calls this.
+     *
+     * @throws Error if the prototype lacks @ApiPath, or declares an endpoint this environment
+     *         cannot satisfy (see {@link assertEndpointSupported}).
+     */
+    initRoutes(apiPrototype) {
+        if (!(0, core_util_1.isApiPath)(apiPrototype)) {
+            const className = apiPrototype.name || 'Unknown';
+            throw new Error(`Class ${className} must be decorated with @ApiPath()`);
+        }
+        const basePath = (0, core_util_1.getApiPath)(apiPrototype);
+        const endpoints = (0, core_util_1.getEndpoints)(apiPrototype) || {};
+        // apiName as the class name so client logs read "SaveApi.save", not "undefined.save"
+        this.apiName = apiPrototype.name || 'UnknownApi';
+        this.routeMap = new Map();
+        for (const [methodName, endpointPath] of Object.entries(endpoints)) {
+            const fullPath = basePath + endpointPath;
+            // Capture the endpoint's auth mode so the client can mint delivery auth per
+            // @AuthOidc / @AuthSharedSecret, exactly as the server verifies it.
+            const authMeta = (0, core_util_1.getAuthMeta)(apiPrototype, methodName);
+            this.assertEndpointSupported(authMeta, methodName);
+            this.routeMap.set(methodName, new core_util_1.RouteMetadata('POST', fullPath, methodName, this.apiName, authMeta));
+        }
+    }
+    /** The contract's class name, for logs and recordings. */
+    contractName() {
+        return this.apiName;
+    }
+    /** Check if a route exists for the given method name. */
+    hasRoute(methodName) {
+        return this.routeMap.has(methodName);
+    }
+    /**
+     * Get route metadata for a method name.
+     * @throws Error if no route found
+     */
+    getRoute(methodName) {
+        const route = this.routeMap.get(methodName);
+        if (!route) {
+            throw new Error(`No route found for method ${methodName}`);
+        }
+        return route;
+    }
+    // ---------------------------------------------------------------- the call
+    /**
+     * Make an HTTP request based on route metadata and arguments.
+     *
+     * All endpoints are POST-only. The request body is the first argument.
+     */
+    // webpieces-disable no-any-unknown -- proxy method: the request DTO (args) + response are erased at the client boundary
+    async makeRequest(route, args) {
+        // Resolved per call (memoized underneath on a server), so building a client stayed synchronous.
+        const baseUrl = await this.resolveBaseUrl();
+        const url = `${baseUrl}${route.path}`;
+        const httpHeaders = {
+            'Content-Type': 'application/json',
+        };
+        // Transferred context, request-id chained. The server impl throws here when there is no
+        // active RequestContext — an outbound call with no trace is a bug, not a default.
+        const outboundHeaders = this.outboundHeaders();
+        for (const entry of outboundHeaders.entries()) {
+            httpHeaders[entry[0]] = entry[1];
+        }
+        await this.attachOutboundAuth(route, baseUrl, httpHeaders);
+        const options = {
+            method: route.httpMethod,
+            headers: httpHeaders,
+        };
+        // POST body is the first argument as JSON
+        // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary
+        let requestDto;
+        if (args.length > 0) {
+            requestDto = args[0];
+            options.body = JSON.stringify(requestDto);
+        }
+        // Wrap fetch in a method for LogApiCall.execute
+        // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary
+        const method = async () => {
+            return this.executeFetch(url, options);
+        };
+        return await this.execute(route, requestDto, method);
+    }
+    /**
+     * Execute the fetch request and handle response.
+     */
+    // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary
+    async executeFetch(url, options) {
+        // webpieces-disable no-fetch -- this IS the generated-client implementation the rule points everyone to
+        const response = await fetch(url, options);
+        if (response.ok) {
+            return await response.json();
+        }
+        // Handle errors (non-2xx responses): parse ProtocolError from the response body and
+        // reconstruct the appropriate HttpError subclass.
+        const protocolError = (await response.json());
+        throw ClientErrorTranslator_1.ClientErrorTranslator.translateError(response, protocolError);
+    }
+}
+exports.ProxyClient = ProxyClient;
+//# sourceMappingURL=ProxyClient.js.map

package/src/ProxyClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyClient.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/ProxyClient.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    isApiPath,\n    getApiPath,\n    getEndpoints,\n    getAuthMeta,\n    AuthMeta,\n    RouteMetadata,\n    ProtocolError,\n    LogApiCall,\n} from '@webpieces/core-util';\nimport { ApiPrototype } from './ApiPrototype';\nimport { ClientErrorTranslator } from './ClientErrorTranslator';\n\n/**\n * ProxyClient - the HTTP call engine behind one API contract's client proxy.\n *\n * Contains ONLY what a browser can run: the route map built from the contract's decorators, URL\n * assembly, `fetch`, error translation, and logging. It holds no context object, no credentials,\n * and no recorder — it ASKS ITSELF for those through the hooks below, and each subclass answers\n * from its own environment.\n *\n * That is why the class is abstract rather than parameterized by a collaborator: a shared\n * header-provider seam would drag Node's AsyncLocalStorage vocabulary into a browser bundle and the\n * browser's store vocabulary into a server, and neither has any use for the other.\n *\n *   NodeProxyClient    (@webpieces/http-client-node)    -> RequestContext, Secrets, mintIdToken, recording\n *   BrowserProxyClient (@webpieces/http-client-browser) -> an app-held store, no credentials, no recording\n *\n * TWO-PHASE: collaborators arrive on the subclass constructor (so a DI container can supply them),\n * while the per-client state — which contract, which target — arrives on the subclass's `init`,\n * which calls {@link initRoutes}. That is what lets a factory hold a `Provider<ProxyClient>` and\n * hand out a fresh, independently-configured client per contract.\n */\nexport abstract class ProxyClient {\n    // Assigned by initRoutes(), which every subclass's init() calls immediately after construction.\n    private routeMap!: Map<string, RouteMetadata>;\n    private apiName!: string;\n\n    constructor(protected readonly logApiCall: LogApiCall = new LogApiCall()) {}\n\n    // ---------------------------------------------------------------- environment hooks\n\n    /** The callee's base URL. Async because a server may derive it from container metadata. */\n    protected abstract resolveBaseUrl(): Promise<string>;\n\n    /** Context headers to put on the wire. Server reads RequestContext; browser reads its store. */\n    protected abstract outboundHeaders(): Map<string, string>;\n\n    /**\n     * Attach the endpoint's outbound credential. Service-to-service auth (@AuthOidc bearer,\n     * @AuthSharedSecret value) is a SERVER concept; a browser has neither a minter nor a Secrets\n     * store, so it attaches nothing and its user JWT simply travels as a transferred context key.\n     */\n    protected async attachOutboundAuth(\n        _route: RouteMetadata,\n        _baseUrl: string,\n        _httpHeaders: Record<string, string>,\n    ): Promise<void> {}\n\n    /**\n     * Run the call. The default just logs it. Test-case RECORDING is a server concept, so\n     * NodeProxyClient overrides this to capture the call when a recorder is in the context.\n     *\n     * Context fields are NOT passed in: a logging backend stamps them onto every record itself.\n     */\n    // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    protected async execute(\n        route: RouteMetadata,\n        requestDto: unknown,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n        method: () => Promise<unknown>,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    ): Promise<unknown> {\n        return this.logApiCall.execute('CLIENT', route, requestDto, method);\n    }\n\n    /**\n     * Reject, at bind time, an endpoint this environment cannot satisfy — e.g. a browser cannot\n     * mint the OIDC token an @AuthOidc endpoint demands. Surfacing it here beats failing on the\n     * first call in production. The default accepts everything.\n     */\n    protected assertEndpointSupported(_authMeta: AuthMeta | undefined, _methodName: string): void {}\n\n    // ---------------------------------------------------------------- contract binding\n\n    /**\n     * Bind this client to one API contract: read @ApiPath/@Endpoint/@Auth* off the prototype and\n     * build the route map once. Each subclass's `init(api, config)` stores its own config, then\n     * calls this.\n     *\n     * @throws Error if the prototype lacks @ApiPath, or declares an endpoint this environment\n     *         cannot satisfy (see {@link assertEndpointSupported}).\n     */\n    protected initRoutes(apiPrototype: ApiPrototype<object>): void {\n        if (!isApiPath(apiPrototype)) {\n            const className = apiPrototype.name || 'Unknown';\n            throw new Error(`Class ${className} must be decorated with @ApiPath()`);\n        }\n\n        const basePath = getApiPath(apiPrototype)!;\n        const endpoints = getEndpoints(apiPrototype) || {};\n\n        // apiName as the class name so client logs read \"SaveApi.save\", not \"undefined.save\"\n        this.apiName = apiPrototype.name || 'UnknownApi';\n\n        this.routeMap = new Map<string, RouteMetadata>();\n        for (const [methodName, endpointPath] of Object.entries(endpoints)) {\n            const fullPath = basePath + endpointPath;\n            // Capture the endpoint's auth mode so the client can mint delivery auth per\n            // @AuthOidc / @AuthSharedSecret, exactly as the server verifies it.\n            const authMeta = getAuthMeta(apiPrototype, methodName);\n            this.assertEndpointSupported(authMeta, methodName);\n            this.routeMap.set(methodName, new RouteMetadata('POST', fullPath, methodName, this.apiName, authMeta));\n        }\n    }\n\n    /** The contract's class name, for logs and recordings. */\n    protected contractName(): string {\n        return this.apiName;\n    }\n\n    /** Check if a route exists for the given method name. */\n    hasRoute(methodName: string): boolean {\n        return this.routeMap.has(methodName);\n    }\n\n    /**\n     * Get route metadata for a method name.\n     * @throws Error if no route found\n     */\n    getRoute(methodName: string): RouteMetadata {\n        const route = this.routeMap.get(methodName);\n        if (!route) {\n            throw new Error(`No route found for method ${methodName}`);\n        }\n        return route;\n    }\n\n    // ---------------------------------------------------------------- the call\n\n    /**\n     * Make an HTTP request based on route metadata and arguments.\n     *\n     * All endpoints are POST-only. The request body is the first argument.\n     */\n    // webpieces-disable no-any-unknown -- proxy method: the request DTO (args) + response are erased at the client boundary\n    async makeRequest(route: RouteMetadata, args: any[]): Promise<any> {\n        // Resolved per call (memoized underneath on a server), so building a client stayed synchronous.\n        const baseUrl = await this.resolveBaseUrl();\n        const url = `${baseUrl}${route.path}`;\n\n        const httpHeaders: Record<string, string> = {\n            'Content-Type': 'application/json',\n        };\n\n        // Transferred context, request-id chained. The server impl throws here when there is no\n        // active RequestContext — an outbound call with no trace is a bug, not a default.\n        const outboundHeaders = this.outboundHeaders();\n        for (const entry of outboundHeaders.entries()) {\n            httpHeaders[entry[0]] = entry[1];\n        }\n\n        await this.attachOutboundAuth(route, baseUrl, httpHeaders);\n\n        const options: RequestInit = {\n            method: route.httpMethod,\n            headers: httpHeaders,\n        };\n\n        // POST body is the first argument as JSON\n        // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary\n        let requestDto: unknown;\n        if (args.length > 0) {\n            requestDto = args[0];\n            options.body = JSON.stringify(requestDto);\n        }\n\n        // Wrap fetch in a method for LogApiCall.execute\n        // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary\n        const method = async (): Promise<unknown> => {\n            return this.executeFetch(url, options);\n        };\n\n        return await this.execute(route, requestDto, method);\n    }\n\n    /**\n     * Execute the fetch request and handle response.\n     */\n    // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary\n    private async executeFetch(url: string, options: RequestInit): Promise<unknown> {\n        // webpieces-disable no-fetch -- this IS the generated-client implementation the rule points everyone to\n        const response = await fetch(url, options);\n\n        if (response.ok) {\n            return await response.json();\n        }\n\n        // Handle errors (non-2xx responses): parse ProtocolError from the response body and\n        // reconstruct the appropriate HttpError subclass.\n        const protocolError = (await response.json()) as ProtocolError;\n        throw ClientErrorTranslator.translateError(response, protocolError);\n    }\n}\n"]}

package/src/buildClientProxy.d.ts

@@ -0,0 +1,8 @@
+import { ApiPrototype } from './ApiPrototype';
+import { ProxyClient } from './ProxyClient';
+/**
+ * Wrap an already-init'd {@link ProxyClient} in the typed Proxy that IS the client: every
+ * `@Endpoint` method call becomes an HTTP request. Shared by the browser and Node factories so
+ * the two environments cannot drift on framework-inspection behavior.
+ */
+export declare function buildClientProxy<T extends object>(apiPrototype: ApiPrototype<T>, proxyClient: ProxyClient): T;

package/src/buildClientProxy.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildClientProxy = buildClientProxy;
+/**
+ * Properties accessed by DI frameworks (Angular, Vue), debuggers, Promise checks, and serializers.
+ * These should return undefined instead of throwing, allowing frameworks to inspect the proxy.
+ *
+ * Why this exists:
+ * - Angular's injector profiler accesses `constructor` after useFactory returns
+ * - Promise.resolve() checks for `then` to detect thenables
+ * - JSON.stringify checks for `toJSON`
+ * - Debuggers access `prototype`, `__proto__`, etc.
+ */
+const FRAMEWORK_INSPECTION_PROPERTIES = new Set([
+    'constructor', // Angular DI profiler, class inspection
+    'prototype', // Prototype chain inspection
+    '__proto__', // Legacy prototype access
+    'name', // Angular isNotFound() check, function/class name inspection
+    'then', // Promise/thenable detection
+    'catch', // Promise check
+    'finally', // Promise check
+    'toJSON', // JSON.stringify
+    'valueOf', // Type coercion
+    'toString', // String coercion
+    'nodeType', // DOM element check
+    'tagName', // DOM element check
+    '$$typeof', // React element/component check
+    '$typeof', // React internal
+    '_isVue', // Vue internal
+    'ngOnInit', // Angular lifecycle hook check
+    'ngOnDestroy', // Angular lifecycle hook check
+    'ngOnChanges', // Angular lifecycle hook check
+    'asymmetricMatch', // Jest matcher protocol
+]);
+/**
+ * Wrap an already-init'd {@link ProxyClient} in the typed Proxy that IS the client: every
+ * `@Endpoint` method call becomes an HTTP request. Shared by the browser and Node factories so
+ * the two environments cannot drift on framework-inspection behavior.
+ */
+// webpieces-disable no-function-outside-class -- returns a Proxy; it holds no state a class could own
+function buildClientProxy(apiPrototype, proxyClient) {
+    return new Proxy({}, {
+        get(target, prop) {
+            // Symbols (Symbol.toStringTag, Symbol.iterator, etc.) - throw for now to learn if this happens
+            if (typeof prop !== 'string') {
+                throw new Error(`Proxy accessed with non-string property: ${String(prop)} (type: ${typeof prop}). ` +
+                    `Please report this so we can add it to the whitelist.`);
+            }
+            // Framework inspection properties - return undefined to allow inspection WITHOUT
+            // throwing. This is critical for Angular DI, Promise checks, etc.
+            if (FRAMEWORK_INSPECTION_PROPERTIES.has(prop)) {
+                return undefined;
+            }
+            if (!proxyClient.hasRoute(prop)) {
+                // For unknown properties (likely typos), throw a helpful error
+                throw new Error(`No route found for method '${prop}' on ${apiPrototype.name || 'Unknown'}. ` +
+                    `Check for typos or ensure the method has @Endpoint() decorator.`);
+            }
+            const route = proxyClient.getRoute(prop);
+            // webpieces-disable no-any-unknown -- request DTO types are erased at the proxy boundary
+            return async (...args) => {
+                return proxyClient.makeRequest(route, args);
+            };
+        },
+    });
+}
+//# sourceMappingURL=buildClientProxy.js.map

package/src/buildClientProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildClientProxy.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/buildClientProxy.ts"],"names":[],"mappings":";;AA+CA,4CAiCC;AAvED;;;;;;;;;GASG;AACH,MAAM,+BAA+B,GAAG,IAAI,GAAG,CAAC;IAC5C,aAAa,EAAM,wCAAwC;IAC3D,WAAW,EAAQ,6BAA6B;IAChD,WAAW,EAAQ,0BAA0B;IAC7C,MAAM,EAAa,6DAA6D;IAChF,MAAM,EAAa,6BAA6B;IAChD,OAAO,EAAY,gBAAgB;IACnC,SAAS,EAAU,gBAAgB;IACnC,QAAQ,EAAW,iBAAiB;IACpC,SAAS,EAAU,gBAAgB;IACnC,UAAU,EAAS,kBAAkB;IACrC,UAAU,EAAS,oBAAoB;IACvC,SAAS,EAAU,oBAAoB;IACvC,UAAU,EAAS,gCAAgC;IACnD,SAAS,EAAU,iBAAiB;IACpC,QAAQ,EAAW,eAAe;IAClC,UAAU,EAAS,+BAA+B;IAClD,aAAa,EAAM,+BAA+B;IAClD,aAAa,EAAM,+BAA+B;IAClD,iBAAiB,EAAE,wBAAwB;CAC9C,CAAC,CAAC;AAEH;;;;GAIG;AACH,sGAAsG;AACtG,SAAgB,gBAAgB,CAAmB,YAA6B,EAAE,WAAwB;IACtG,OAAO,IAAI,KAAK,CAAC,EAAO,EAAE;QACtB,GAAG,CAAC,MAAS,EAAE,IAAqB;YAChC,+FAA+F;YAC/F,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CACX,4CAA4C,MAAM,CAAC,IAAI,CAAC,WAAW,OAAO,IAAI,KAAK;oBACnF,uDAAuD,CAC1D,CAAC;YACN,CAAC;YAED,iFAAiF;YACjF,kEAAkE;YAClE,IAAI,+BAA+B,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5C,OAAO,SAAS,CAAC;YACrB,CAAC;YAED,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,+DAA+D;gBAC/D,MAAM,IAAI,KAAK,CACX,8BAA8B,IAAI,QAAQ,YAAY,CAAC,IAAI,IAAI,SAAS,IAAI;oBAC5E,iEAAiE,CACpE,CAAC;YACN,CAAC;YAED,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAEzC,yFAAyF;YACzF,OAAO,KAAK,EAAE,GAAG,IAAW,EAAE,EAAE;gBAC5B,OAAO,WAAW,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAChD,CAAC,CAAC;QACN,CAAC;KACJ,CAAC,CAAC;AACP,CAAC","sourcesContent":["import { ApiPrototype } from './ApiPrototype';\nimport { ProxyClient } from './ProxyClient';\n\n/**\n * Return type for the Proxy get trap — either an async method or undefined for framework inspection.\n */\n// webpieces-disable no-any-unknown -- Proxy get trap returns generic response promises\ntype ProxyGetResult = (...args: never[]) => Promise<unknown>;\n\n/**\n * Properties accessed by DI frameworks (Angular, Vue), debuggers, Promise checks, and serializers.\n * These should return undefined instead of throwing, allowing frameworks to inspect the proxy.\n *\n * Why this exists:\n * - Angular's injector profiler accesses `constructor` after useFactory returns\n * - Promise.resolve() checks for `then` to detect thenables\n * - JSON.stringify checks for `toJSON`\n * - Debuggers access `prototype`, `__proto__`, etc.\n */\nconst FRAMEWORK_INSPECTION_PROPERTIES = new Set([\n    'constructor',     // Angular DI profiler, class inspection\n    'prototype',       // Prototype chain inspection\n    '__proto__',       // Legacy prototype access\n    'name',            // Angular isNotFound() check, function/class name inspection\n    'then',            // Promise/thenable detection\n    'catch',           // Promise check\n    'finally',         // Promise check\n    'toJSON',          // JSON.stringify\n    'valueOf',         // Type coercion\n    'toString',        // String coercion\n    'nodeType',        // DOM element check\n    'tagName',         // DOM element check\n    '$$typeof',        // React element/component check\n    '$typeof',         // React internal\n    '_isVue',          // Vue internal\n    'ngOnInit',        // Angular lifecycle hook check\n    'ngOnDestroy',     // Angular lifecycle hook check\n    'ngOnChanges',     // Angular lifecycle hook check\n    'asymmetricMatch', // Jest matcher protocol\n]);\n\n/**\n * Wrap an already-init'd {@link ProxyClient} in the typed Proxy that IS the client: every\n * `@Endpoint` method call becomes an HTTP request. Shared by the browser and Node factories so\n * the two environments cannot drift on framework-inspection behavior.\n */\n// webpieces-disable no-function-outside-class -- returns a Proxy; it holds no state a class could own\nexport function buildClientProxy<T extends object>(apiPrototype: ApiPrototype<T>, proxyClient: ProxyClient): T {\n    return new Proxy({} as T, {\n        get(target: T, prop: string | symbol): ProxyGetResult | undefined {\n            // Symbols (Symbol.toStringTag, Symbol.iterator, etc.) - throw for now to learn if this happens\n            if (typeof prop !== 'string') {\n                throw new Error(\n                    `Proxy accessed with non-string property: ${String(prop)} (type: ${typeof prop}). ` +\n                    `Please report this so we can add it to the whitelist.`\n                );\n            }\n\n            // Framework inspection properties - return undefined to allow inspection WITHOUT\n            // throwing. This is critical for Angular DI, Promise checks, etc.\n            if (FRAMEWORK_INSPECTION_PROPERTIES.has(prop)) {\n                return undefined;\n            }\n\n            if (!proxyClient.hasRoute(prop)) {\n                // For unknown properties (likely typos), throw a helpful error\n                throw new Error(\n                    `No route found for method '${prop}' on ${apiPrototype.name || 'Unknown'}. ` +\n                    `Check for typos or ensure the method has @Endpoint() decorator.`\n                );\n            }\n\n            const route = proxyClient.getRoute(prop);\n\n            // webpieces-disable no-any-unknown -- request DTO types are erased at the proxy boundary\n            return async (...args: any[]) => {\n                return proxyClient.makeRequest(route, args);\n            };\n        },\n    });\n}\n"]}

package/src/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @webpieces/http-client-core
+ *
+ * The ISOMORPHIC core of the webpieces HTTP client — everything that reads an API contract's
+ * decorators and turns a method call into an HTTP request, with no opinion about where the
+ * magic context comes from or whether a DI container exists.
+ *
+ * You almost certainly want one of its two environment packages instead:
+ * - Server:  @webpieces/http-client-node    (inversify-wired, reads RequestContext, mints OIDC)
+ * - Browser: @webpieces/http-client-browser (no DI — React or Angular, app-managed context store)
+ *
+ * Architecture:
+ * ```
+ * http-api (defines the contract)
+ *    ^
+ *    +-- http-routing (server: contract -> handlers)
+ *    +-- http-client-core (contract -> HTTP requests)   <- YOU ARE HERE
+ *          +-- http-client-node     (RequestContext + Secrets + OIDC + inversify factory)
+ *          +-- http-client-browser  (app-held store + plain factory, no DI)
+ * ```
+ *
+ * There is no context/credential/recording seam here at all: ProxyClient is ABSTRACT and asks its
+ * subclass for the base URL, the context headers, the log map, the outbound credential, and the
+ * recorder. Nothing server-only (RequestContext, Secrets, mintIdToken, TestCaseRecorder) can reach
+ * a browser bundle, and nothing browser-only (a ContextReader store) reaches a server.
+ */
+export { ProxyClient } from './ProxyClient';
+export type { ApiPrototype } from './ApiPrototype';
+export { buildClientProxy } from './buildClientProxy';
+export { ClientErrorTranslator } from './ClientErrorTranslator';

package/src/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * @webpieces/http-client-core
+ *
+ * The ISOMORPHIC core of the webpieces HTTP client — everything that reads an API contract's
+ * decorators and turns a method call into an HTTP request, with no opinion about where the
+ * magic context comes from or whether a DI container exists.
+ *
+ * You almost certainly want one of its two environment packages instead:
+ * - Server:  @webpieces/http-client-node    (inversify-wired, reads RequestContext, mints OIDC)
+ * - Browser: @webpieces/http-client-browser (no DI — React or Angular, app-managed context store)
+ *
+ * Architecture:
+ * ```
+ * http-api (defines the contract)
+ *    ^
+ *    +-- http-routing (server: contract -> handlers)
+ *    +-- http-client-core (contract -> HTTP requests)   <- YOU ARE HERE
+ *          +-- http-client-node     (RequestContext + Secrets + OIDC + inversify factory)
+ *          +-- http-client-browser  (app-held store + plain factory, no DI)
+ * ```
+ *
+ * There is no context/credential/recording seam here at all: ProxyClient is ABSTRACT and asks its
+ * subclass for the base URL, the context headers, the log map, the outbound credential, and the
+ * recorder. Nothing server-only (RequestContext, Secrets, mintIdToken, TestCaseRecorder) can reach
+ * a browser bundle, and nothing browser-only (a ContextReader store) reaches a server.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientErrorTranslator = exports.buildClientProxy = exports.ProxyClient = void 0;
+var ProxyClient_1 = require("./ProxyClient");
+Object.defineProperty(exports, "ProxyClient", { enumerable: true, get: function () { return ProxyClient_1.ProxyClient; } });
+var buildClientProxy_1 = require("./buildClientProxy");
+Object.defineProperty(exports, "buildClientProxy", { enumerable: true, get: function () { return buildClientProxy_1.buildClientProxy; } });
+var ClientErrorTranslator_1 = require("./ClientErrorTranslator");
+Object.defineProperty(exports, "ClientErrorTranslator", { enumerable: true, get: function () { return ClientErrorTranslator_1.ClientErrorTranslator; } });
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAEH,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AAEpB,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AACzB,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA","sourcesContent":["/**\n * @webpieces/http-client-core\n *\n * The ISOMORPHIC core of the webpieces HTTP client — everything that reads an API contract's\n * decorators and turns a method call into an HTTP request, with no opinion about where the\n * magic context comes from or whether a DI container exists.\n *\n * You almost certainly want one of its two environment packages instead:\n * - Server:  @webpieces/http-client-node    (inversify-wired, reads RequestContext, mints OIDC)\n * - Browser: @webpieces/http-client-browser (no DI — React or Angular, app-managed context store)\n *\n * Architecture:\n * ```\n * http-api (defines the contract)\n *    ^\n *    +-- http-routing (server: contract -> handlers)\n *    +-- http-client-core (contract -> HTTP requests)   <- YOU ARE HERE\n *          +-- http-client-node     (RequestContext + Secrets + OIDC + inversify factory)\n *          +-- http-client-browser  (app-held store + plain factory, no DI)\n * ```\n *\n * There is no context/credential/recording seam here at all: ProxyClient is ABSTRACT and asks its\n * subclass for the base URL, the context headers, the log map, the outbound credential, and the\n * recorder. Nothing server-only (RequestContext, Secrets, mintIdToken, TestCaseRecorder) can reach\n * a browser bundle, and nothing browser-only (a ContextReader store) reaches a server.\n */\n\nexport { ProxyClient } from './ProxyClient';\nexport type { ApiPrototype } from './ApiPrototype';\nexport { buildClientProxy } from './buildClientProxy';\nexport { ClientErrorTranslator } from './ClientErrorTranslator';\n"]}