npm - @webpieces/http-client-core - Versions diffs - 0.4.642 → 0.4.644 - Mend

@webpieces/http-client-core 0.4.642 → 0.4.644

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-client-core",
-  "version": "0.4.642",
+  "version": "0.4.644",
   "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",
@@ -21,6 +21,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-util": "0.4.642"
+    "@webpieces/core-util": "0.4.644"
   }
 }

package/src/ProxyClient.js CHANGED Viewed

@@ -157,7 +157,7 @@ class ProxyClient {
         if (authMode?.kind === 'webhook') {
             throw new Error(`${this.apiName}.${route.methodName} is @AuthWebhook('${authMode.name}') — only ` +
                 `${authMode.name} can call it, because only ${authMode.name} can produce the signature ` +
-                `its WebhookHook verifies. It is not callable from a webpieces client.`);
+                `its WebhookAuthCallback verifies. It is not callable from a webpieces client.`);
         }
         // Resolved per call (memoized underneath on a server), so building a client stayed synchronous.
         const baseUrl = await this.resolveBaseUrl();

package/src/ProxyClient.js.map CHANGED Viewed

	@@ -1 +1 @@
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 isFormPost,\n isRawBody,\n getMaskSpec,\n AuthMeta,\n DestinationTrust,\n RouteMetadata,\n ProtocolError,\n LogApiCall,\n LogApiCallImpl,\n ApiMethodInfo,\n toError,\n NetworkRejectClassifier,\n} from '@webpieces/core-util';\nimport { ApiPrototype } from './ApiPrototype';\nimport { ClientErrorTranslator } from './ClientErrorTranslator';\nimport { RequestOutcome } from './RequestOutcome';\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 // Stateless + dependency-free, so the browser bundle keeps no DI on the fetch path.\n private readonly networkRejectClassifier = new NetworkRejectClassifier();\n\n constructor(protected readonly logApiCall: LogApiCallImpl = 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 /\n Context headers to put on the wire. Server reads RequestContext; browser reads its store.\n \n `destination` is derived from THIS route's auth mode and decides whether TRUSTED context keys\n * (`x-user-id`, `x-org-id`, `x-webpieces-roles`) may ride along — see {@link DestinationTrust}.\n * It is a required argument on purpose: a defaulted \"send everything\" would put the permissive\n * answer one keystroke away and make the safe one opt-in.\n \n RENAMED from `outboundHeaders()` in the same change that added `destination`, and the rename IS\n * the migration. TypeScript accepts an override that declares FEWER parameters than its base, so a\n * downstream `protected override outboundHeaders(): Map<string, string>` would have kept compiling\n * and silently ignored the gate — the permissive behaviour surviving as a second spelling. Against\n * the NEW name that subclass fails twice over: `override` names a member the base no longer has,\n * and this abstract member is left unimplemented.\n /\n protected abstract outboundContextHeaders(destination: DestinationTrust): 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 // apiClass = the CONTRACT name (this.apiName, e.g. 'SaveApi') so this client log line MATCHES\n // the server's for the same call. A client has no impl class, so controllerName is omitted.\n const info = new ApiMethodInfo('client', this.apiName, route.methodName, undefined, route.mask);\n return this.logApiCall.execute(info, 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 /\n Fires immediately BEFORE `fetch`, once per RPC — the progress \"start marker\". Symmetric with\n * {@link onRequestEnd}: every start is followed by exactly one end, on every path, so a listener\n * can drive a counter (bar on / bar off) without leaking a permanently-spinning bar.\n \n The default is a no-op, so every existing subclass is unaffected.\n /\n protected onRequestStart(_route: RouteMetadata): void {}\n\n /\n Fires exactly ONCE after the call settles, on EVERY path (2xx, HTTP error, network reject) —\n * the \"stop marker\", carrying how it settled.\n \n Subsumes the older header-only hook: this is the ONLY place the `fetch` Response — and thus its\n * `Headers` — exists, so an app that needs to read a response header (e.g. a server-version stamp\n * for client↔server version matching) reads `outcome.headers`, still BEFORE the body is consumed\n * and on both the ok and error paths. `outcome.ok`/`outcome.error` add the success-or-error\n * signal the header-only seam could not give.\n \n The default is a no-op, so every existing subclass is unaffected.\n /\n protected onRequestEnd(_route: RouteMetadata, _outcome: RequestOutcome): 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 const formPost = isFormPost(apiPrototype, methodName);\n this.routeMap.set(\n methodName,\n new RouteMetadata(\n 'POST', fullPath, methodName, this.apiName, authMeta, undefined, formPost,\n getMaskSpec(apiPrototype, methodName), isRawBody(apiPrototype, methodName),\n ),\n );\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 // FAIL FAST: formPost endpoints exist ONLY for EXTERNAL inbound webhooks (e.g. Twilio is the\n // caller — there is no webpieces client for them). This proxy JSON.stringifies the body, so\n // calling one would silently send a wrong-encoded body. Refuse it here — PER METHOD, at call\n // time — so an API mixing normal + formPost endpoints still gives a working client for the\n // normal ones; only calling the formPost method throws.\n if (route.formPost) {\n throw new Error(\n `${this.apiName}.${route.methodName} is @Endpoint(..., { formPost: true }) — the ` +\n `webpieces client does not support calling form-encoded endpoints yet. formPost is ` +\n `for EXTERNAL inbound webhooks (e.g. Twilio) only. If this endpoint needs a ` +\n `service-to-service client, set formPost:false (or remove it) so it uses JSON.`,\n );\n }\n // FAIL FAST, same shape and same reason: an @AuthWebhook endpoint is verified by the VENDOR's\n // signature over the request, which no webpieces client can produce. Refusing here — per\n // method, at call time — means an api that mixes webhook + normal endpoints still yields a\n // working client for the normal ones.\n const authMode = route.authMeta?.mode;\n if (authMode?.kind === 'webhook') {\n throw new Error(\n `${this.apiName}.${route.methodName} is @AuthWebhook('${authMode.name}') — only ` +\n `${authMode.name} can call it, because only ${authMode.name} can produce the signature ` +\n `its WebhookHook verifies. It is not callable from a webpieces client.`,\n );\n }\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. The\n // destination's own auth mode decides whether trusted keys are part of that set.\n const contextHeaders = this.outboundContextHeaders(DestinationTrust.forAuthMode(route.authMeta?.mode));\n for (const entry of contextHeaders.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, route);\n };\n\n return await this.execute(route, requestDto, method);\n }\n\n /\n Execute the fetch request and handle response.\n \n Brackets the call with the lifecycle seam: {@link onRequestStart} once before `fetch`, then\n * {@link onRequestEnd} exactly once on each of the three ways a call can settle. The end hook\n * fires BEFORE the throw on both failure paths, so a listener always sees the stop marker even\n * though the caller sees an exception.\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, route: RouteMetadata): Promise<unknown> {\n this.onRequestStart(route);\n\n // A network reject (offline, DNS, CORS preflight) means no Response ever existed, so there is\n // no status and no headers to report — only status 0 and the failure itself. toNetworkError\n // turns that reject into a typed OfflineError (a genuine bug passes through untouched), and we\n // classify BEFORE onRequestEnd so a lifecycle listener sees the SAME typed error the caller will.\n let response: Response;\n // webpieces-disable no-unmanaged-exceptions -- translate a network reject into a lifecycle END, then rethrow\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n // webpieces-disable no-fetch -- this IS the generated-client implementation the rule points everyone to\n response = await fetch(url, options);\n } catch (err: unknown) {\n const error = toError(err);\n const networkError = this.networkRejectClassifier.toNetworkError(error, url);\n this.onRequestEnd(route, new RequestOutcome(false, 0, undefined, networkError));\n throw networkError;\n }\n\n if (response.ok) {\n // webpieces-disable no-unmanaged-exceptions -- a malformed 2xx body must still report the END marker\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n const body = await response.json();\n this.onRequestEnd(route, new RequestOutcome(true, response.status, response.headers));\n return body;\n } catch (err: unknown) {\n const error = toError(err);\n this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, error));\n throw error;\n }\n }\n\n // Handle errors (non-2xx responses): parse ProtocolError from the response body and\n // reconstruct the appropriate HttpError subclass. The headers still reach the seam here, so\n // a version (or any future) header is observed even on error responses.\n //\n // The parse is GUARDED because a non-2xx body is not always ours: an infra 502/504 (load\n // balancer, proxy) returns HTML, and `response.json()` throws on it. Unguarded, the END\n // marker would never fire for exactly the 5xx case the seam exists to catch — the caller\n // would see the throw while the app's progress bar span never closed. Either way the caller\n // still gets the same failure it always got; only the lifecycle report is new.\n //\n // `translated` is the HttpError subclass ClientErrorTranslator picked, and translateError\n // RETURNS Error — so nothing in this seam is ever `unknown`.\n let translated: Error;\n // webpieces-disable no-unmanaged-exceptions -- a non-JSON error body must still report the END marker\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n const protocolError = (await response.json()) as ProtocolError;\n translated = ClientErrorTranslator.translateError(response, protocolError);\n } catch (err: unknown) {\n const error = toError(err);\n // The error body was not ours (e.g. an infra 502 serving HTML), so there was no\n // ProtocolError to translate — report the parse failure itself as the outcome.\n this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, error));\n throw error;\n }\n\n this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, translated));\n throw translated;\n }\n}\n"]}
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 isFormPost,\n isRawBody,\n getMaskSpec,\n AuthMeta,\n DestinationTrust,\n RouteMetadata,\n ProtocolError,\n LogApiCall,\n LogApiCallImpl,\n ApiMethodInfo,\n toError,\n NetworkRejectClassifier,\n} from '@webpieces/core-util';\nimport { ApiPrototype } from './ApiPrototype';\nimport { ClientErrorTranslator } from './ClientErrorTranslator';\nimport { RequestOutcome } from './RequestOutcome';\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 // Stateless + dependency-free, so the browser bundle keeps no DI on the fetch path.\n private readonly networkRejectClassifier = new NetworkRejectClassifier();\n\n constructor(protected readonly logApiCall: LogApiCallImpl = 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 /\n Context headers to put on the wire. Server reads RequestContext; browser reads its store.\n \n `destination` is derived from THIS route's auth mode and decides whether TRUSTED context keys\n * (`x-user-id`, `x-org-id`, `x-webpieces-roles`) may ride along — see {@link DestinationTrust}.\n * It is a required argument on purpose: a defaulted \"send everything\" would put the permissive\n * answer one keystroke away and make the safe one opt-in.\n \n RENAMED from `outboundHeaders()` in the same change that added `destination`, and the rename IS\n * the migration. TypeScript accepts an override that declares FEWER parameters than its base, so a\n * downstream `protected override outboundHeaders(): Map<string, string>` would have kept compiling\n * and silently ignored the gate — the permissive behaviour surviving as a second spelling. Against\n * the NEW name that subclass fails twice over: `override` names a member the base no longer has,\n * and this abstract member is left unimplemented.\n /\n protected abstract outboundContextHeaders(destination: DestinationTrust): 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 // apiClass = the CONTRACT name (this.apiName, e.g. 'SaveApi') so this client log line MATCHES\n // the server's for the same call. A client has no impl class, so controllerName is omitted.\n const info = new ApiMethodInfo('client', this.apiName, route.methodName, undefined, route.mask);\n return this.logApiCall.execute(info, 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 /\n Fires immediately BEFORE `fetch`, once per RPC — the progress \"start marker\". Symmetric with\n * {@link onRequestEnd}: every start is followed by exactly one end, on every path, so a listener\n * can drive a counter (bar on / bar off) without leaking a permanently-spinning bar.\n \n The default is a no-op, so every existing subclass is unaffected.\n /\n protected onRequestStart(_route: RouteMetadata): void {}\n\n /\n Fires exactly ONCE after the call settles, on EVERY path (2xx, HTTP error, network reject) —\n * the \"stop marker\", carrying how it settled.\n \n Subsumes the older header-only hook: this is the ONLY place the `fetch` Response — and thus its\n * `Headers` — exists, so an app that needs to read a response header (e.g. a server-version stamp\n * for client↔server version matching) reads `outcome.headers`, still BEFORE the body is consumed\n * and on both the ok and error paths. `outcome.ok`/`outcome.error` add the success-or-error\n * signal the header-only seam could not give.\n \n The default is a no-op, so every existing subclass is unaffected.\n /\n protected onRequestEnd(_route: RouteMetadata, _outcome: RequestOutcome): 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 const formPost = isFormPost(apiPrototype, methodName);\n this.routeMap.set(\n methodName,\n new RouteMetadata(\n 'POST', fullPath, methodName, this.apiName, authMeta, undefined, formPost,\n getMaskSpec(apiPrototype, methodName), isRawBody(apiPrototype, methodName),\n ),\n );\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 // FAIL FAST: formPost endpoints exist ONLY for EXTERNAL inbound webhooks (e.g. Twilio is the\n // caller — there is no webpieces client for them). This proxy JSON.stringifies the body, so\n // calling one would silently send a wrong-encoded body. Refuse it here — PER METHOD, at call\n // time — so an API mixing normal + formPost endpoints still gives a working client for the\n // normal ones; only calling the formPost method throws.\n if (route.formPost) {\n throw new Error(\n `${this.apiName}.${route.methodName} is @Endpoint(..., { formPost: true }) — the ` +\n `webpieces client does not support calling form-encoded endpoints yet. formPost is ` +\n `for EXTERNAL inbound webhooks (e.g. Twilio) only. If this endpoint needs a ` +\n `service-to-service client, set formPost:false (or remove it) so it uses JSON.`,\n );\n }\n // FAIL FAST, same shape and same reason: an @AuthWebhook endpoint is verified by the VENDOR's\n // signature over the request, which no webpieces client can produce. Refusing here — per\n // method, at call time — means an api that mixes webhook + normal endpoints still yields a\n // working client for the normal ones.\n const authMode = route.authMeta?.mode;\n if (authMode?.kind === 'webhook') {\n throw new Error(\n `${this.apiName}.${route.methodName} is @AuthWebhook('${authMode.name}') — only ` +\n `${authMode.name} can call it, because only ${authMode.name} can produce the signature ` +\n `its WebhookAuthCallback verifies. It is not callable from a webpieces client.`,\n );\n }\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. The\n // destination's own auth mode decides whether trusted keys are part of that set.\n const contextHeaders = this.outboundContextHeaders(DestinationTrust.forAuthMode(route.authMeta?.mode));\n for (const entry of contextHeaders.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, route);\n };\n\n return await this.execute(route, requestDto, method);\n }\n\n /\n Execute the fetch request and handle response.\n \n Brackets the call with the lifecycle seam: {@link onRequestStart} once before `fetch`, then\n * {@link onRequestEnd} exactly once on each of the three ways a call can settle. The end hook\n * fires BEFORE the throw on both failure paths, so a listener always sees the stop marker even\n * though the caller sees an exception.\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, route: RouteMetadata): Promise<unknown> {\n this.onRequestStart(route);\n\n // A network reject (offline, DNS, CORS preflight) means no Response ever existed, so there is\n // no status and no headers to report — only status 0 and the failure itself. toNetworkError\n // turns that reject into a typed OfflineError (a genuine bug passes through untouched), and we\n // classify BEFORE onRequestEnd so a lifecycle listener sees the SAME typed error the caller will.\n let response: Response;\n // webpieces-disable no-unmanaged-exceptions -- translate a network reject into a lifecycle END, then rethrow\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n // webpieces-disable no-fetch -- this IS the generated-client implementation the rule points everyone to\n response = await fetch(url, options);\n } catch (err: unknown) {\n const error = toError(err);\n const networkError = this.networkRejectClassifier.toNetworkError(error, url);\n this.onRequestEnd(route, new RequestOutcome(false, 0, undefined, networkError));\n throw networkError;\n }\n\n if (response.ok) {\n // webpieces-disable no-unmanaged-exceptions -- a malformed 2xx body must still report the END marker\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n const body = await response.json();\n this.onRequestEnd(route, new RequestOutcome(true, response.status, response.headers));\n return body;\n } catch (err: unknown) {\n const error = toError(err);\n this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, error));\n throw error;\n }\n }\n\n // Handle errors (non-2xx responses): parse ProtocolError from the response body and\n // reconstruct the appropriate HttpError subclass. The headers still reach the seam here, so\n // a version (or any future) header is observed even on error responses.\n //\n // The parse is GUARDED because a non-2xx body is not always ours: an infra 502/504 (load\n // balancer, proxy) returns HTML, and `response.json()` throws on it. Unguarded, the END\n // marker would never fire for exactly the 5xx case the seam exists to catch — the caller\n // would see the throw while the app's progress bar span never closed. Either way the caller\n // still gets the same failure it always got; only the lifecycle report is new.\n //\n // `translated` is the HttpError subclass ClientErrorTranslator picked, and translateError\n // RETURNS Error — so nothing in this seam is ever `unknown`.\n let translated: Error;\n // webpieces-disable no-unmanaged-exceptions -- a non-JSON error body must still report the END marker\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n const protocolError = (await response.json()) as ProtocolError;\n translated = ClientErrorTranslator.translateError(response, protocolError);\n } catch (err: unknown) {\n const error = toError(err);\n // The error body was not ours (e.g. an infra 502 serving HTML), so there was no\n // ProtocolError to translate — report the parse failure itself as the outcome.\n this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, error));\n throw error;\n }\n\n this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, translated));\n throw translated;\n }\n}\n"]}