@webpieces/core-util 0.4.956 → 0.4.958

package/src/http/ErrorLadderCompileAssertions.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ClientRegistry_1 = require("./ClientRegistry");
+const ApiMethodInfo_1 = require("./ApiMethodInfo");
+const CallStrategy_1 = require("./CallStrategy");
+const HttpEndpointOptions_1 = require("./HttpEndpointOptions");
+/**
+ * Compiled by tsc (spec files are not), never executed. Pins the ONE spelling of the error ladder:
+ * every registration states its `CallScope`, and the unscoped spellings it replaced do not compile.
+ * tsc fails the build with TS2578 if any of these ever starts compiling again.
+ */
+class ErrorLadderCompileAssertions {
+    scopeIsRequired(translator, classifier) {
+        // @ts-expect-error setErrorTranslator(t) became setErrorTranslator(t, 'ALL') — the scope is required
+        ClientRegistry_1.ClientRegistry.setErrorTranslator(translator);
+        // @ts-expect-error setDefaultErrorClassifier(c) became setErrorClassifier(c, 'ALL')
+        ClientRegistry_1.ClientRegistry.setDefaultErrorClassifier(classifier);
+        // @ts-expect-error addErrorClassifier(new KeyedErrorClassifier('XApi', c)) became setErrorClassifier(c, XApi)
+        ClientRegistry_1.ClientRegistry.addErrorClassifier(classifier);
+        // @ts-expect-error the scope is required — setErrorClassifier(c, 'ALL')
+        ClientRegistry_1.ClientRegistry.setErrorClassifier(classifier);
+        // @ts-expect-error getErrorTranslator() became getErrorTranslator(api, methodName)
+        ClientRegistry_1.ClientRegistry.getErrorTranslator();
+    }
+    allHasNoMethod(translator, classifier) {
+        // @ts-expect-error ALL cannot select a method
+        ClientRegistry_1.ClientRegistry.setErrorTranslator(translator, 'ALL', 'work');
+        // @ts-expect-error ALL cannot select a method
+        ClientRegistry_1.ClientRegistry.setErrorClassifier(classifier, 'ALL', 'work');
+    }
+    callIdentityStatesItsContract() {
+        // @ts-expect-error ApiMethodInfo's contract CLASS is required (pass undefined only when there is none)
+        void new ApiMethodInfo_1.ApiMethodInfo('client', 'SaveApi', 'save');
+        // @ts-expect-error CallContext's contract CLASS is required (pass undefined only when there is none)
+        void new CallStrategy_1.CallContext('SaveApi', 'save', HttpEndpointOptions_1.WRITE);
+    }
+    keyedByClassNeverByName(classifier) {
+        // @ts-expect-error the ladder is keyed by the contract CLASS, never its name
+        ClientRegistry_1.ClientRegistry.setErrorClassifier(classifier, 'SaveApi');
+    }
+}
+//# sourceMappingURL=ErrorLadderCompileAssertions.js.map

package/src/http/ErrorLadderCompileAssertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorLadderCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ErrorLadderCompileAssertions.ts"],"names":[],"mappings":";;AAAA,qDAAkD;AAGlD,mDAAgD;AAChD,iDAA6C;AAC7C,+DAA8C;AAE9C;;;;GAIG;AACH,MAAM,4BAA4B;IAC9B,eAAe,CAAC,UAA2B,EAAE,UAA2B;QACpE,qGAAqG;QACrG,+BAAc,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAC9C,oFAAoF;QACpF,+BAAc,CAAC,yBAAyB,CAAC,UAAU,CAAC,CAAC;QACrD,8GAA8G;QAC9G,+BAAc,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAC9C,wEAAwE;QACxE,+BAAc,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAC9C,mFAAmF;QACnF,+BAAc,CAAC,kBAAkB,EAAE,CAAC;IACxC,CAAC;IAED,cAAc,CAAC,UAA2B,EAAE,UAA2B;QACnE,8CAA8C;QAC9C,+BAAc,CAAC,kBAAkB,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC7D,8CAA8C;QAC9C,+BAAc,CAAC,kBAAkB,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACjE,CAAC;IAED,6BAA6B;QACzB,uGAAuG;QACvG,KAAK,IAAI,6BAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QACpD,qGAAqG;QACrG,KAAK,IAAI,0BAAW,CAAC,SAAS,EAAE,MAAM,EAAE,2BAAK,CAAC,CAAC;IACnD,CAAC;IAED,uBAAuB,CAAC,UAA2B;QAC/C,6EAA6E;QAC7E,+BAAc,CAAC,kBAAkB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAC7D,CAAC;CACJ","sourcesContent":["import { ClientRegistry } from './ClientRegistry';\nimport { ErrorClassifier } from './ErrorClassifier';\nimport { ErrorTranslator } from './ErrorTranslator';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { CallContext } from './CallStrategy';\nimport { WRITE } from './HttpEndpointOptions';\n\n/**\n * Compiled by tsc (spec files are not), never executed. Pins the ONE spelling of the error ladder:\n * every registration states its `CallScope`, and the unscoped spellings it replaced do not compile.\n * tsc fails the build with TS2578 if any of these ever starts compiling again.\n */\nclass ErrorLadderCompileAssertions {\n    scopeIsRequired(translator: ErrorTranslator, classifier: ErrorClassifier): void {\n        // @ts-expect-error setErrorTranslator(t) became setErrorTranslator(t, 'ALL') — the scope is required\n        ClientRegistry.setErrorTranslator(translator);\n        // @ts-expect-error setDefaultErrorClassifier(c) became setErrorClassifier(c, 'ALL')\n        ClientRegistry.setDefaultErrorClassifier(classifier);\n        // @ts-expect-error addErrorClassifier(new KeyedErrorClassifier('XApi', c)) became setErrorClassifier(c, XApi)\n        ClientRegistry.addErrorClassifier(classifier);\n        // @ts-expect-error the scope is required — setErrorClassifier(c, 'ALL')\n        ClientRegistry.setErrorClassifier(classifier);\n        // @ts-expect-error getErrorTranslator() became getErrorTranslator(api, methodName)\n        ClientRegistry.getErrorTranslator();\n    }\n\n    allHasNoMethod(translator: ErrorTranslator, classifier: ErrorClassifier): void {\n        // @ts-expect-error ALL cannot select a method\n        ClientRegistry.setErrorTranslator(translator, 'ALL', 'work');\n        // @ts-expect-error ALL cannot select a method\n        ClientRegistry.setErrorClassifier(classifier, 'ALL', 'work');\n    }\n\n    callIdentityStatesItsContract(): void {\n        // @ts-expect-error ApiMethodInfo's contract CLASS is required (pass undefined only when there is none)\n        void new ApiMethodInfo('client', 'SaveApi', 'save');\n        // @ts-expect-error CallContext's contract CLASS is required (pass undefined only when there is none)\n        void new CallContext('SaveApi', 'save', WRITE);\n    }\n\n    keyedByClassNeverByName(classifier: ErrorClassifier): void {\n        // @ts-expect-error the ladder is keyed by the contract CLASS, never its name\n        ClientRegistry.setErrorClassifier(classifier, 'SaveApi');\n    }\n}\n"]}

package/src/http/ErrorTranslator.d.ts

@@ -4,8 +4,12 @@ import { HttpResponseDto } from './HttpResponseDto';
  * ErrorTranslator - ONE symmetric place an app owns HTTP error translation, in BOTH directions, over
  * the WHOLE response.
  *
- * An app implements this ONCE and registers it ONCE per process via
- * {@link ClientRegistry.setErrorTranslator} — on the server AND in the browser. Its `toWire` runs on
+ * An app implements this ONCE and registers it per process via
+ * `ClientRegistry.setErrorTranslator(t, 'ALL')` — on the server AND in the browser. A contract whose
+ * errors travel in a DIFFERENT wire format (a vendor's own 4xx body, or the error body an inbound
+ * vendor expects back) gets its own translator on the same `CallScope` ladder as `CallRegistry`'s
+ * strategy and timeout: `setErrorTranslator(t, VendorApi)` or `setErrorTranslator(t, VendorApi,
+ * 'method')`, resolved method -> API -> ALL -> webpieces default. Its `toWire` runs on
  * the SERVER (`ExpressWrapper.handleError`) and its `fromWire` runs on every CLIENT in that process
  * (`ClientErrorTranslator.throwIfFailure`, shared by `http-client-node` and `http-client-browser`).
  * The payoff is type symmetry across the wire: the server throws `OrderNotFoundError` and the caller
@@ -13,7 +17,7 @@ import { HttpResponseDto } from './HttpResponseDto';
  *
  * # THERE IS ALWAYS A TRANSLATOR
  *
- * {@link ClientRegistry.getErrorTranslator} is non-optional and starts life holding
+ * {@link ClientRegistry.getErrorTranslator} is non-optional: below every rung of the ladder sits
  * {@link WebpiecesDefaultErrorTranslator}. So no caller anywhere asks "did anyone register one" —
  * every call site is ONE unconditional line. A registered app translator REPLACES the default and
  * declines by DELEGATING to it:
@@ -89,7 +93,7 @@ import { HttpResponseDto } from './HttpResponseDto';
  * }
  *
  * // startup, ONCE per process (server AND browser)
- * ClientRegistry.setErrorTranslator(new OrderErrorTranslator());
+ * ClientRegistry.setErrorTranslator(new OrderErrorTranslator(), 'ALL');
  * ```
  */
 export interface ErrorTranslator {

package/src/http/ErrorTranslator.js.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorTranslator.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ErrorTranslator.ts"],"names":[],"mappings":"","sourcesContent":["import { ClientRole } from '../errors/ClientRole';\nimport { HttpResponseDto } from './HttpResponseDto';\n\n/**\n * ErrorTranslator - ONE symmetric place an app owns HTTP error translation, in BOTH directions, over\n * the WHOLE response.\n *\n * An app implements this ONCE and registers it ONCE per process via\n * {@link ClientRegistry.setErrorTranslator} — on the server AND in the browser. Its `toWire` runs on\n * the SERVER (`ExpressWrapper.handleError`) and its `fromWire` runs on every CLIENT in that process\n * (`ClientErrorTranslator.throwIfFailure`, shared by `http-client-node` and `http-client-browser`).\n * The payoff is type symmetry across the wire: the server throws `OrderNotFoundError` and the caller\n * CATCHES `OrderNotFoundError`, instead of decoding a status code by hand at every call site.\n *\n * # THERE IS ALWAYS A TRANSLATOR\n *\n * {@link ClientRegistry.getErrorTranslator} is non-optional and starts life holding\n * {@link WebpiecesDefaultErrorTranslator}. So no caller anywhere asks \"did anyone register one\" —\n * every call site is ONE unconditional line. A registered app translator REPLACES the default and\n * declines by DELEGATING to it:\n *\n * ```ts\n * private readonly fallback = new WebpiecesDefaultErrorTranslator();\n * ```\n *\n * That is one call, it is visible at the call site, and it composes: an app that wants to DECORATE\n * the default rather than replace it does so by calling it and editing the result. A `next` parameter\n * was considered and rejected — it buys nothing this does not, and it puts the framework back in the\n * business of sequencing somebody else's precedence.\n *\n * # Both halves speak {@link HttpResponseDto}, and that is the point\n *\n * `toWire` PRODUCES exactly what `fromWire` CONSUMES. Reading the two methods against each other in\n * one file is what makes a mistake visible, which is why this is one object rather than two\n * separately-registered functions.\n *\n * # The whole response, not a status plus a body\n *\n * The previous contract could express only `(statusCode, protocolError)`, so an app could not put its\n * own trace id, `Retry-After`, `WWW-Authenticate` or a cookie on an error response. A translator now\n * returns the status code, the reason phrase, the header LIST and the body — everything.\n *\n * # `toWire` RETURNS a response; `fromWire` THROWS\n *\n * They are mirrors, not twins. `toWire` is called inside a catch and its whole job is to produce a\n * value, so it returns one. `fromWire` is called on a response the caller is about to be handed, and\n * its whole job is to stop that from happening, so it THROWS and is typed `void`. Returning an\n * `Error` the caller then has to remember to throw was the previous shape and it is exactly the bug\n * class this deletes: a `void` return cannot be silently dropped.\n *\n * There is exactly ONE registered ErrorTranslator per process (a `set`, not an `add` to a list):\n * precedence between an app's own layers is the APP's to compose explicitly inside its `toWire`,\n * rather than something hidden in registration order inside the framework.\n *\n * # Not covered: 404 / unknown route\n *\n * A request that matches no route has no route context and never reaches this seam. That is\n * deliberate and out of scope.\n *\n * This is a business-logic contract (methods, not data), so it is an interface per the webpieces\n * guidelines.\n *\n * ```ts\n * class OrderErrorPayload {\n *     constructor(public message: string, public errorCode: string) {}\n * }\n *\n * export class OrderErrorTranslator implements ErrorTranslator {\n *     private readonly fallback = new WebpiecesDefaultErrorTranslator();\n *\n *     toWire(error: Error): HttpResponseDto {\n *         if (!(error instanceof OrderNotFoundError)) {\n *             return this.fallback.toWire(error);        // not mine -> webpieces default\n *         }\n *         const body = new OrderErrorPayload(error.message, 'ORDER_NOT_FOUND');\n *         return new HttpResponseDto(\n *             new HttpResponseStatus(460, 'Order Not Found'),\n *             [new HttpHeader('x-order-trace', error.traceId)],\n *             body,\n *         );\n *     }\n *\n *     fromWire(response: HttpResponseDto, role: ClientRole): void {\n *         if (response.status.code !== 460) {\n *             this.fallback.fromWire(response, role);    // not mine -> webpieces default\n *             return;\n *         }\n *         throw new OrderNotFoundError(String(response.body));\n *     }\n * }\n *\n * // startup, ONCE per process (server AND browser)\n * ClientRegistry.setErrorTranslator(new OrderErrorTranslator());\n * ```\n */\nexport interface ErrorTranslator {\n    /**\n     * SERVER: exception -> the ENTIRE response (status code, reason phrase, headers, body). Always a\n     * response, never `undefined`; decline by returning\n     * `new WebpiecesDefaultErrorTranslator().toWire(error)`.\n     */\n    toWire(error: Error): HttpResponseDto;\n\n    /**\n     * CLIENT: the ENTIRE response -> a THROW. Receives the SAME shape `toWire` produces, normalised\n     * from whichever transport read it.\n     *\n     * Called for EVERY response, including a 2xx — deliberately, so an app whose 200 body signals\n     * failure can turn it into a throw. Returning normally means \"let this response through\"; the\n     * webpieces default returns normally for any 2xx that is not 266 and throws otherwise. Decline by\n     * calling `new WebpiecesDefaultErrorTranslator().fromWire(response, role)`.\n     *\n     * `role` is WHO is receiving ({@link ClientRole}): the end-user client or a server. The client\n     * that read the response passes the role ITS setup declared (`ClientConfig`), so one translator\n     * registered in a process serves every client there. It decides what a received 401 means; pass\n     * it through unchanged when declining.\n     *\n     * A non-2xx response can never reach a typed caller even if an app translator forgets to throw:\n     * `ClientErrorTranslator.throwIfFailure` applies the webpieces default behind it. That is bug\n     * containment, not a \"was one registered\" branch.\n     */\n    fromWire(response: HttpResponseDto, role: ClientRole): void;\n}\n"]}
+{"version":3,"file":"ErrorTranslator.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ErrorTranslator.ts"],"names":[],"mappings":"","sourcesContent":["import { ClientRole } from '../errors/ClientRole';\nimport { HttpResponseDto } from './HttpResponseDto';\n\n/**\n * ErrorTranslator - ONE symmetric place an app owns HTTP error translation, in BOTH directions, over\n * the WHOLE response.\n *\n * An app implements this ONCE and registers it per process via\n * `ClientRegistry.setErrorTranslator(t, 'ALL')` — on the server AND in the browser. A contract whose\n * errors travel in a DIFFERENT wire format (a vendor's own 4xx body, or the error body an inbound\n * vendor expects back) gets its own translator on the same `CallScope` ladder as `CallRegistry`'s\n * strategy and timeout: `setErrorTranslator(t, VendorApi)` or `setErrorTranslator(t, VendorApi,\n * 'method')`, resolved method -> API -> ALL -> webpieces default. Its `toWire` runs on\n * the SERVER (`ExpressWrapper.handleError`) and its `fromWire` runs on every CLIENT in that process\n * (`ClientErrorTranslator.throwIfFailure`, shared by `http-client-node` and `http-client-browser`).\n * The payoff is type symmetry across the wire: the server throws `OrderNotFoundError` and the caller\n * CATCHES `OrderNotFoundError`, instead of decoding a status code by hand at every call site.\n *\n * # THERE IS ALWAYS A TRANSLATOR\n *\n * {@link ClientRegistry.getErrorTranslator} is non-optional: below every rung of the ladder sits\n * {@link WebpiecesDefaultErrorTranslator}. So no caller anywhere asks \"did anyone register one\" —\n * every call site is ONE unconditional line. A registered app translator REPLACES the default and\n * declines by DELEGATING to it:\n *\n * ```ts\n * private readonly fallback = new WebpiecesDefaultErrorTranslator();\n * ```\n *\n * That is one call, it is visible at the call site, and it composes: an app that wants to DECORATE\n * the default rather than replace it does so by calling it and editing the result. A `next` parameter\n * was considered and rejected — it buys nothing this does not, and it puts the framework back in the\n * business of sequencing somebody else's precedence.\n *\n * # Both halves speak {@link HttpResponseDto}, and that is the point\n *\n * `toWire` PRODUCES exactly what `fromWire` CONSUMES. Reading the two methods against each other in\n * one file is what makes a mistake visible, which is why this is one object rather than two\n * separately-registered functions.\n *\n * # The whole response, not a status plus a body\n *\n * The previous contract could express only `(statusCode, protocolError)`, so an app could not put its\n * own trace id, `Retry-After`, `WWW-Authenticate` or a cookie on an error response. A translator now\n * returns the status code, the reason phrase, the header LIST and the body — everything.\n *\n * # `toWire` RETURNS a response; `fromWire` THROWS\n *\n * They are mirrors, not twins. `toWire` is called inside a catch and its whole job is to produce a\n * value, so it returns one. `fromWire` is called on a response the caller is about to be handed, and\n * its whole job is to stop that from happening, so it THROWS and is typed `void`. Returning an\n * `Error` the caller then has to remember to throw was the previous shape and it is exactly the bug\n * class this deletes: a `void` return cannot be silently dropped.\n *\n * There is exactly ONE registered ErrorTranslator per process (a `set`, not an `add` to a list):\n * precedence between an app's own layers is the APP's to compose explicitly inside its `toWire`,\n * rather than something hidden in registration order inside the framework.\n *\n * # Not covered: 404 / unknown route\n *\n * A request that matches no route has no route context and never reaches this seam. That is\n * deliberate and out of scope.\n *\n * This is a business-logic contract (methods, not data), so it is an interface per the webpieces\n * guidelines.\n *\n * ```ts\n * class OrderErrorPayload {\n *     constructor(public message: string, public errorCode: string) {}\n * }\n *\n * export class OrderErrorTranslator implements ErrorTranslator {\n *     private readonly fallback = new WebpiecesDefaultErrorTranslator();\n *\n *     toWire(error: Error): HttpResponseDto {\n *         if (!(error instanceof OrderNotFoundError)) {\n *             return this.fallback.toWire(error);        // not mine -> webpieces default\n *         }\n *         const body = new OrderErrorPayload(error.message, 'ORDER_NOT_FOUND');\n *         return new HttpResponseDto(\n *             new HttpResponseStatus(460, 'Order Not Found'),\n *             [new HttpHeader('x-order-trace', error.traceId)],\n *             body,\n *         );\n *     }\n *\n *     fromWire(response: HttpResponseDto, role: ClientRole): void {\n *         if (response.status.code !== 460) {\n *             this.fallback.fromWire(response, role);    // not mine -> webpieces default\n *             return;\n *         }\n *         throw new OrderNotFoundError(String(response.body));\n *     }\n * }\n *\n * // startup, ONCE per process (server AND browser)\n * ClientRegistry.setErrorTranslator(new OrderErrorTranslator(), 'ALL');\n * ```\n */\nexport interface ErrorTranslator {\n    /**\n     * SERVER: exception -> the ENTIRE response (status code, reason phrase, headers, body). Always a\n     * response, never `undefined`; decline by returning\n     * `new WebpiecesDefaultErrorTranslator().toWire(error)`.\n     */\n    toWire(error: Error): HttpResponseDto;\n\n    /**\n     * CLIENT: the ENTIRE response -> a THROW. Receives the SAME shape `toWire` produces, normalised\n     * from whichever transport read it.\n     *\n     * Called for EVERY response, including a 2xx — deliberately, so an app whose 200 body signals\n     * failure can turn it into a throw. Returning normally means \"let this response through\"; the\n     * webpieces default returns normally for any 2xx that is not 266 and throws otherwise. Decline by\n     * calling `new WebpiecesDefaultErrorTranslator().fromWire(response, role)`.\n     *\n     * `role` is WHO is receiving ({@link ClientRole}): the end-user client or a server. The client\n     * that read the response passes the role ITS setup declared (`ClientConfig`), so one translator\n     * registered in a process serves every client there. It decides what a received 401 means; pass\n     * it through unchanged when declining.\n     *\n     * A non-2xx response can never reach a typed caller even if an app translator forgets to throw:\n     * `ClientErrorTranslator.throwIfFailure` applies the webpieces default behind it. That is bug\n     * containment, not a \"was one registered\" branch.\n     */\n    fromWire(response: HttpResponseDto, role: ClientRole): void;\n}\n"]}

package/src/http/ExternalContextKeys.d.ts

@@ -0,0 +1,31 @@
+import 'reflect-metadata';
+import { AnyContextKey } from '../ContextKey';
+/**
+ * `@ExternalContextKeys(...keys)` — the ONLY request-context keys an `EXTERNAL_OUTBOUND` client sends
+ * to the outside system it calls.
+ *
+ * WHY a per-CONTRACT list and not a flag on the `ContextKey`: a global "send to vendors" flag would
+ * send Toast's restaurant id to Clover. Which context a vendor may see is a fact about THAT vendor's
+ * API, so it is declared on that vendor's contract. Without this, an outbound client sends nothing
+ * of ours — not `x-request-id`, not any `x-webpieces-*` key, not an app's untrusted transferred keys —
+ * because a vendor is somebody else's process.
+ *
+ * On the CLASS it applies to every endpoint; on a METHOD it ADDS keys for that method only. A listed
+ * key with no value in the request context makes the client throw BEFORE any I/O: the vendor needs it
+ * (it is how the call is routed, e.g. a merchant id), and a request without it is a bug in our code.
+ * Every listed key must declare an `httpHeader` — that is its wire name.
+ *
+ * ```ts
+ * @ApiPath('')
+ * @ExternalContextKeys(WebpiecesCoreHeaders.REQUEST_ID)
+ * export abstract class PartnerWebhookApi { ... }
+ * ```
+ */
+export declare function ExternalContextKeys(...keys: AnyContextKey[]): ClassDecorator & MethodDecorator;
+/**
+ * The keys one method sends: the class-level list, then the method's additions, de-duplicated.
+ * Empty when the contract declares none.
+ */
+export declare function getExternalContextKeys(apiClass: Function, methodName: string): AnyContextKey[];
+/** True when the class or any of its methods carries `@ExternalContextKeys`. */
+export declare function declaresExternalContextKeys(apiClass: Function): boolean;

package/src/http/ExternalContextKeys.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalContextKeys = ExternalContextKeys;
+exports.getExternalContextKeys = getExternalContextKeys;
+exports.declaresExternalContextKeys = declaresExternalContextKeys;
+require("reflect-metadata");
+/** Class-level keys: every endpoint of the contract sends them. */
+const CLASS_KEYS = 'webpieces:external-context-keys:class';
+/** Method-level keys, `methodName -> keys`: ADDED to the class-level ones for that method only. */
+const METHOD_KEYS = 'webpieces:external-context-keys:method';
+/**
+ * `@ExternalContextKeys(...keys)` — the ONLY request-context keys an `EXTERNAL_OUTBOUND` client sends
+ * to the outside system it calls.
+ *
+ * WHY a per-CONTRACT list and not a flag on the `ContextKey`: a global "send to vendors" flag would
+ * send Toast's restaurant id to Clover. Which context a vendor may see is a fact about THAT vendor's
+ * API, so it is declared on that vendor's contract. Without this, an outbound client sends nothing
+ * of ours — not `x-request-id`, not any `x-webpieces-*` key, not an app's untrusted transferred keys —
+ * because a vendor is somebody else's process.
+ *
+ * On the CLASS it applies to every endpoint; on a METHOD it ADDS keys for that method only. A listed
+ * key with no value in the request context makes the client throw BEFORE any I/O: the vendor needs it
+ * (it is how the call is routed, e.g. a merchant id), and a request without it is a bug in our code.
+ * Every listed key must declare an `httpHeader` — that is its wire name.
+ *
+ * ```ts
+ * @ApiPath('')
+ * @ExternalContextKeys(WebpiecesCoreHeaders.REQUEST_ID)
+ * export abstract class PartnerWebhookApi { ... }
+ * ```
+ */
+// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
+function ExternalContextKeys(...keys) {
+    if (keys.length === 0) {
+        throw new Error('@ExternalContextKeys(...) requires at least one ContextKey.');
+    }
+    for (const key of keys) {
+        if (key.httpHeader === undefined || key.httpHeader === '') {
+            throw new Error(`@ExternalContextKeys: ContextKey '${key.name}' declares no httpHeader, so it has no wire name to send it under.`);
+        }
+    }
+    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
+    return (target, propertyKey) => {
+        if (propertyKey === undefined) {
+            Reflect.defineMetadata(CLASS_KEYS, [...keys], target);
+            return;
+        }
+        const metadataTarget = typeof target === 'function' ? target : target.constructor;
+        const all = {
+            ...(Reflect.getMetadata(METHOD_KEYS, metadataTarget) ?? {}),
+        };
+        all[propertyKey] = [...keys];
+        Reflect.defineMetadata(METHOD_KEYS, all, metadataTarget);
+    };
+}
+/**
+ * The keys one method sends: the class-level list, then the method's additions, de-duplicated.
+ * Empty when the contract declares none.
+ */
+// webpieces-disable no-function-outside-class -- reflect-metadata reader paired with the decorator
+function getExternalContextKeys(apiClass, methodName) {
+    const classKeys = Reflect.getMetadata(CLASS_KEYS, apiClass) ?? [];
+    const methodKeys = (Reflect.getMetadata(METHOD_KEYS, apiClass) ?? {})[methodName] ?? [];
+    const merged = [];
+    for (const key of [...classKeys, ...methodKeys]) {
+        if (!merged.includes(key))
+            merged.push(key);
+    }
+    return merged;
+}
+/** True when the class or any of its methods carries `@ExternalContextKeys`. */
+// webpieces-disable no-function-outside-class -- reflect-metadata reader paired with the decorator
+function declaresExternalContextKeys(apiClass) {
+    return (Reflect.hasMetadata(CLASS_KEYS, apiClass) ||
+        Object.keys(Reflect.getMetadata(METHOD_KEYS, apiClass) ?? {}).length > 0);
+}
+//# sourceMappingURL=ExternalContextKeys.js.map

package/src/http/ExternalContextKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalContextKeys.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ExternalContextKeys.ts"],"names":[],"mappings":";;AA8BA,kDAwBC;AAOD,wDASC;AAID,kEAKC;AA/ED,4BAA0B;AAG1B,mEAAmE;AACnE,MAAM,UAAU,GAAG,uCAAuC,CAAC;AAC3D,mGAAmG;AACnG,MAAM,WAAW,GAAG,wCAAwC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,2GAA2G;AAC3G,SAAgB,mBAAmB,CAAC,GAAG,IAAqB;IACxD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACnF,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,KAAK,EAAE,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CACX,qCAAqC,GAAG,CAAC,IAAI,oEAAoE,CACpH,CAAC;QACN,CAAC;IACL,CAAC;IACD,kFAAkF;IAClF,OAAO,CAAC,MAAW,EAAE,WAA6B,EAAQ,EAAE;QACxD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;YACtD,OAAO;QACX,CAAC;QACD,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;QAClF,MAAM,GAAG,GAAoC;YACzC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;SAC9D,CAAC;QACF,GAAG,CAAC,WAAqB,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QACvC,OAAO,CAAC,cAAc,CAAC,WAAW,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC;IAC7D,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,mGAAmG;AACnG,SAAgB,sBAAsB,CAAC,QAAkB,EAAE,UAAkB;IACzE,MAAM,SAAS,GAAoB,OAAO,CAAC,WAAW,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnF,MAAM,UAAU,GACZ,CAAC,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IACzE,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,SAAS,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED,gFAAgF;AAChF,mGAAmG;AACnG,SAAgB,2BAA2B,CAAC,QAAkB;IAC1D,OAAO,CACH,OAAO,CAAC,WAAW,CAAC,UAAU,EAAE,QAAQ,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAC3E,CAAC;AACN,CAAC","sourcesContent":["import 'reflect-metadata';\nimport { AnyContextKey } from '../ContextKey';\n\n/** Class-level keys: every endpoint of the contract sends them. */\nconst CLASS_KEYS = 'webpieces:external-context-keys:class';\n/** Method-level keys, `methodName -> keys`: ADDED to the class-level ones for that method only. */\nconst METHOD_KEYS = 'webpieces:external-context-keys:method';\n\n/**\n * `@ExternalContextKeys(...keys)` — the ONLY request-context keys an `EXTERNAL_OUTBOUND` client sends\n * to the outside system it calls.\n *\n * WHY a per-CONTRACT list and not a flag on the `ContextKey`: a global \"send to vendors\" flag would\n * send Toast's restaurant id to Clover. Which context a vendor may see is a fact about THAT vendor's\n * API, so it is declared on that vendor's contract. Without this, an outbound client sends nothing\n * of ours — not `x-request-id`, not any `x-webpieces-*` key, not an app's untrusted transferred keys —\n * because a vendor is somebody else's process.\n *\n * On the CLASS it applies to every endpoint; on a METHOD it ADDS keys for that method only. A listed\n * key with no value in the request context makes the client throw BEFORE any I/O: the vendor needs it\n * (it is how the call is routed, e.g. a merchant id), and a request without it is a bug in our code.\n * Every listed key must declare an `httpHeader` — that is its wire name.\n *\n * ```ts\n * @ApiPath('')\n * @ExternalContextKeys(WebpiecesCoreHeaders.REQUEST_ID)\n * export abstract class PartnerWebhookApi { ... }\n * ```\n */\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function ExternalContextKeys(...keys: AnyContextKey[]): ClassDecorator & MethodDecorator {\n    if (keys.length === 0) {\n        throw new Error('@ExternalContextKeys(...) requires at least one ContextKey.');\n    }\n    for (const key of keys) {\n        if (key.httpHeader === undefined || key.httpHeader === '') {\n            throw new Error(\n                `@ExternalContextKeys: ContextKey '${key.name}' declares no httpHeader, so it has no wire name to send it under.`,\n            );\n        }\n    }\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey?: string | symbol): void => {\n        if (propertyKey === undefined) {\n            Reflect.defineMetadata(CLASS_KEYS, [...keys], target);\n            return;\n        }\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n        const all: Record<string, AnyContextKey[]> = {\n            ...(Reflect.getMetadata(METHOD_KEYS, metadataTarget) ?? {}),\n        };\n        all[propertyKey as string] = [...keys];\n        Reflect.defineMetadata(METHOD_KEYS, all, metadataTarget);\n    };\n}\n\n/**\n * The keys one method sends: the class-level list, then the method's additions, de-duplicated.\n * Empty when the contract declares none.\n */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader paired with the decorator\nexport function getExternalContextKeys(apiClass: Function, methodName: string): AnyContextKey[] {\n    const classKeys: AnyContextKey[] = Reflect.getMetadata(CLASS_KEYS, apiClass) ?? [];\n    const methodKeys: AnyContextKey[] =\n        (Reflect.getMetadata(METHOD_KEYS, apiClass) ?? {})[methodName] ?? [];\n    const merged: AnyContextKey[] = [];\n    for (const key of [...classKeys, ...methodKeys]) {\n        if (!merged.includes(key)) merged.push(key);\n    }\n    return merged;\n}\n\n/** True when the class or any of its methods carries `@ExternalContextKeys`. */\n// webpieces-disable no-function-outside-class -- reflect-metadata reader paired with the decorator\nexport function declaresExternalContextKeys(apiClass: Function): boolean {\n    return (\n        Reflect.hasMetadata(CLASS_KEYS, apiClass) ||\n        Object.keys(Reflect.getMetadata(METHOD_KEYS, apiClass) ?? {}).length > 0\n    );\n}\n"]}

package/src/http/HttpContract.d.ts

@@ -1,30 +1,61 @@
 /** Nominal backing keeps raw string literals out of endpoint declarations. */
 declare enum HttpMethodValue {
     GET = "GET",
-    POST = "POST"
+    POST = "POST",
+    PUT = "PUT",
+    PATCH = "PATCH",
+    DELETE = "DELETE"
 }
 /** Short, statically importable decorator arguments. Raw strings do not satisfy {@link HttpMethod}. */
 export declare const GET = HttpMethodValue.GET;
 export declare const POST = HttpMethodValue.POST;
-/** HTTP verbs currently supported by generated Webpieces request/response contracts. */
-export type HttpMethod = typeof GET | typeof POST;
+export declare const PUT = HttpMethodValue.PUT;
+export declare const PATCH = HttpMethodValue.PATCH;
+export declare const DELETE = HttpMethodValue.DELETE;
+/** HTTP verbs supported by generated Webpieces request/response contracts. */
+export type HttpMethod = typeof GET | typeof POST | typeof PUT | typeof PATCH | typeof DELETE;
+/** Every verb, in declaration order — the one list validators and messages enumerate. */
+export declare const HTTP_METHODS: readonly HttpMethod[];
+/**
+ * The ONE rule for "may this verb carry a request body": POST, PUT and PATCH do; GET and DELETE do
+ * not. Every client serializer, route validator, scanner and document renderer asks this, instead of
+ * each re-deciding it with its own `=== 'POST'` check (which is how a sixth copy drifts).
+ */
+export declare function verbCarriesBody(method: string): boolean;
+/** Runtime backstop for JavaScript and `as any` callers of `@Endpoint`. */
+export declare function isHttpMethod(value: unknown): value is HttpMethod;
 /** Whether a generated client returns the response body or the whole transport-neutral response. */
 export type EndpointResponseType = 'body' | 'full';
-/** The wire source for one explicitly mapped scalar/list method parameter. */
-export type HttpParameterSource = 'path' | 'query';
+/**
+ * The wire source for one explicitly mapped method parameter: a `{placeholder}`, one named query key,
+ * or (`@QueryString()`, EXTERNAL_OUTBOUND contracts only) the whole query string as a {@link QueryParams}.
+ */
+export type HttpParameterSource = 'path' | 'query' | 'query-map';
+/**
+ * The ITEM type of a list query parameter, declared as `@QueryParam('ids', Number)`: TypeScript's
+ * design metadata erases `number[]` to `Array`, so without it every item arrives as a string.
+ */
+export type HttpQueryItemType = typeof String | typeof Number | typeof Boolean;
 /** Runtime conversion supported for path/query values after TypeScript design metadata is read. */
 export type HttpParameterValueType = 'string' | 'number' | 'boolean' | 'array' | 'unknown';
 /** Metadata written by `@PathParam` / `@QueryParam` before route construction knows the value type. */
 export declare class HttpParameterDeclaration {
     readonly index: number;
     readonly source: HttpParameterSource;
+    /** The wire name; `''` for a `query-map`, which binds every key. */
     readonly wireName: string;
-    constructor(index: number, source: HttpParameterSource, wireName: string);
+    /** `@QueryParam('ids', Number)`: the item type of a list query parameter. */
+    readonly itemType?: HttpQueryItemType | undefined;
+    constructor(index: number, source: HttpParameterSource, 
+    /** The wire name; `''` for a `query-map`, which binds every key. */
+    wireName: string, 
+    /** `@QueryParam('ids', Number)`: the item type of a list query parameter. */
+    itemType?: HttpQueryItemType | undefined);
 }
 /** Fully resolved parameter metadata carried by every server and client route. */
 export declare class HttpParameterBinding extends HttpParameterDeclaration {
     readonly valueType: HttpParameterValueType;
-    constructor(index: number, source: HttpParameterSource, wireName: string, valueType: HttpParameterValueType);
+    constructor(index: number, source: HttpParameterSource, wireName: string, valueType: HttpParameterValueType, itemType?: HttpQueryItemType);
 }
 /** Result of mapping one API method call to its HTTP path/query/body. */
 export declare class BoundHttpRequest {
@@ -41,8 +72,15 @@ export declare class BoundHttpRequest {
 export declare class HttpContractMapper {
     /** API arguments -> encoded relative URL + body. */
     static toWire(pathTemplate: string, bindings: readonly HttpParameterBinding[], bodyParameterIndex: number | undefined, args: readonly unknown[]): BoundHttpRequest;
+    /** One `@QueryString()` argument -> repeated `key=value` pairs, in insertion order. */
+    private static appendQueryMap;
     /** Decoded path/query/body -> API arguments in declaration order. */
     static fromWire(bindings: readonly HttpParameterBinding[], bodyParameterIndex: number | undefined, body: unknown, pathValues: ReadonlyMap<string, string | readonly string[]>, queryValues: ReadonlyMap<string, string | readonly string[]>): unknown[];
+    /** Every decoded query key -> a {@link QueryParams}, the inverse of {@link appendQueryMap}. */
+    private static queryMapOf;
     private static convert;
+    /** A list query parameter's items, as its declared item type (`@QueryParam('ids', Number)`). */
+    private static convertItems;
+    private static convertScalar;
 }
 export {};

package/src/http/HttpContract.js

@@ -1,33 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpContractMapper = exports.BoundHttpRequest = exports.HttpParameterBinding = exports.HttpParameterDeclaration = exports.POST = exports.GET = void 0;
+exports.HttpContractMapper = exports.BoundHttpRequest = exports.HttpParameterBinding = exports.HttpParameterDeclaration = exports.HTTP_METHODS = exports.DELETE = exports.PATCH = exports.PUT = exports.POST = exports.GET = void 0;
+exports.verbCarriesBody = verbCarriesBody;
+exports.isHttpMethod = isHttpMethod;
 const ApiError_1 = require("../errors/ApiError");
+const QueryParams_1 = require("./QueryParams");
 /** Nominal backing keeps raw string literals out of endpoint declarations. */
 var HttpMethodValue;
 (function (HttpMethodValue) {
     HttpMethodValue["GET"] = "GET";
     HttpMethodValue["POST"] = "POST";
+    HttpMethodValue["PUT"] = "PUT";
+    HttpMethodValue["PATCH"] = "PATCH";
+    HttpMethodValue["DELETE"] = "DELETE";
 })(HttpMethodValue || (HttpMethodValue = {}));
 /** Short, statically importable decorator arguments. Raw strings do not satisfy {@link HttpMethod}. */
 exports.GET = HttpMethodValue.GET;
 exports.POST = HttpMethodValue.POST;
+exports.PUT = HttpMethodValue.PUT;
+exports.PATCH = HttpMethodValue.PATCH;
+exports.DELETE = HttpMethodValue.DELETE;
+/** Every verb, in declaration order — the one list validators and messages enumerate. */
+exports.HTTP_METHODS = [exports.GET, exports.POST, exports.PUT, exports.PATCH, exports.DELETE];
+/**
+ * The ONE rule for "may this verb carry a request body": POST, PUT and PATCH do; GET and DELETE do
+ * not. Every client serializer, route validator, scanner and document renderer asks this, instead of
+ * each re-deciding it with its own `=== 'POST'` check (which is how a sixth copy drifts).
+ */
+// webpieces-disable no-function-outside-class -- pure predicate shared by DI-free browser and server runtimes
+function verbCarriesBody(method) {
+    return method === exports.POST || method === exports.PUT || method === exports.PATCH;
+}
+/** Runtime backstop for JavaScript and `as any` callers of `@Endpoint`. */
+// webpieces-disable no-function-outside-class -- pure guard shared by decorators and readers; webpieces-disable no-any-unknown -- untrusted runtime value is narrowed to an HTTP method
+function isHttpMethod(value) {
+    return exports.HTTP_METHODS.includes(value);
+}
 /** Metadata written by `@PathParam` / `@QueryParam` before route construction knows the value type. */
 class HttpParameterDeclaration {
     index;
     source;
     wireName;
-    constructor(index, source, wireName) {
+    itemType;
+    constructor(index, source, 
+    /** The wire name; `''` for a `query-map`, which binds every key. */
+    wireName, 
+    /** `@QueryParam('ids', Number)`: the item type of a list query parameter. */
+    itemType) {
         this.index = index;
         this.source = source;
         this.wireName = wireName;
+        this.itemType = itemType;
     }
 }
 exports.HttpParameterDeclaration = HttpParameterDeclaration;
 /** Fully resolved parameter metadata carried by every server and client route. */
 class HttpParameterBinding extends HttpParameterDeclaration {
     valueType;
-    constructor(index, source, wireName, valueType) {
-        super(index, source, wireName);
+    constructor(index, source, wireName, valueType, itemType) {
+        super(index, source, wireName, itemType);
         this.valueType = valueType;
     }
 }
@@ -70,6 +101,10 @@ class HttpContractMapper {
             }
             if (value === undefined || value === null)
                 continue;
+            if (binding.source === 'query-map') {
+                this.appendQueryMap(binding, value, query);
+                continue;
+            }
             const values = Array.isArray(value) ? value : [value];
             for (const item of values) {
                 if (item === undefined || item === null)
@@ -83,6 +118,18 @@ class HttpContractMapper {
         const suffix = query.length === 0 ? '' : `${path.includes('?') ? '&' : '?'}${query.join('&')}`;
         return new BoundHttpRequest(`${path}${suffix}`, bodyParameterIndex === undefined ? undefined : args[bodyParameterIndex]);
     }
+    /** One `@QueryString()` argument -> repeated `key=value` pairs, in insertion order. */
+    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper; webpieces-disable no-any-unknown -- the argument's type is erased at the generic boundary
+    static appendQueryMap(binding, value, query) {
+        if (!(value instanceof QueryParams_1.QueryParams)) {
+            throw new ApiError_1.ApiBadRequestError(`Argument ${binding.index} is @QueryString() and must be a QueryParams, received ${typeof value}.`);
+        }
+        for (const key of value.keys()) {
+            for (const item of value.getAll(key)) {
+                query.push(`${encodeURIComponent(key)}=${encodeURIComponent(item)}`);
+            }
+        }
+    }
     /** Decoded path/query/body -> API arguments in declaration order. */
     // webpieces-disable no-function-outside-class -- pure inverse mapper paired with toWire
     static fromWire(bindings, bodyParameterIndex, 
@@ -95,6 +142,10 @@ class HttpContractMapper {
         if (bodyParameterIndex !== undefined)
             args[bodyParameterIndex] = body;
         for (const binding of bindings) {
+            if (binding.source === 'query-map') {
+                args[binding.index] = this.queryMapOf(queryValues);
+                continue;
+            }
             const values = binding.source === 'path' ? pathValues : queryValues;
             const raw = values.get(binding.wireName);
             if (raw === undefined) {
@@ -108,18 +159,45 @@ class HttpContractMapper {
         }
         return args;
     }
+    /** Every decoded query key -> a {@link QueryParams}, the inverse of {@link appendQueryMap}. */
+    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper
+    static queryMapOf(queryValues) {
+        const params = new QueryParams_1.QueryParams();
+        for (const entry of queryValues.entries()) {
+            const raw = entry[1];
+            for (const item of Array.isArray(raw) ? raw : [raw])
+                params.add(entry[0], item);
+        }
+        return params;
+    }
     // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper
     static convert(binding, raw) {
         const values = Array.isArray(raw) ? raw : [raw];
         if (binding.valueType === 'array')
-            return [...values];
+            return this.convertItems(binding, values);
         if (values.length !== 1) {
             throw new ApiError_1.ApiBadRequestError(`Parameter '${binding.wireName}' was repeated but is not declared as an array.`);
         }
         const value = values[0];
-        switch (binding.valueType) {
+        return this.convertScalar(binding, value);
+    }
+    /** A list query parameter's items, as its declared item type (`@QueryParam('ids', Number)`). */
+    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper
+    static convertItems(binding, values) {
+        if (binding.itemType === Number) {
+            return values.map((item) => this.convertScalar(binding, item, 'number'));
+        }
+        if (binding.itemType === Boolean) {
+            return values.map((item) => this.convertScalar(binding, item, 'boolean'));
+        }
+        return [...values];
+    }
+    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper
+    static convertScalar(binding, value, valueType = binding.valueType) {
+        switch (valueType) {
             case 'string':
             case 'unknown':
+            case 'array':
                 return value;
             case 'number': {
                 if (value.trim() === '') {

package/src/http/HttpContract.js.map

@@ -1 +1 @@
-{"version":3,"file":"HttpContract.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HttpContract.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiBadRequestError } from '../errors/ApiError';\n\n/** Nominal backing keeps raw string literals out of endpoint declarations. */\nenum HttpMethodValue {\n    GET = 'GET',\n    POST = 'POST',\n}\n\n/** Short, statically importable decorator arguments. Raw strings do not satisfy {@link HttpMethod}. */\nexport const GET = HttpMethodValue.GET;\nexport const POST = HttpMethodValue.POST;\n\n/** HTTP verbs currently supported by generated Webpieces request/response contracts. */\nexport type HttpMethod = typeof GET | typeof POST;\n\n/** Whether a generated client returns the response body or the whole transport-neutral response. */\nexport type EndpointResponseType = 'body' | 'full';\n\n/** The wire source for one explicitly mapped scalar/list method parameter. */\nexport type HttpParameterSource = 'path' | 'query';\n\n/** Runtime conversion supported for path/query values after TypeScript design metadata is read. */\nexport type HttpParameterValueType = 'string' | 'number' | 'boolean' | 'array' | 'unknown';\n\n/** Concrete runtime values produced for path/query parameters. */\ntype ConvertedHttpParameter = string | number | boolean | readonly string[];\n\n/** Metadata written by `@PathParam` / `@QueryParam` before route construction knows the value type. */\nexport class HttpParameterDeclaration {\n    constructor(\n        public readonly index: number,\n        public readonly source: HttpParameterSource,\n        public readonly wireName: string,\n    ) {}\n}\n\n/** Fully resolved parameter metadata carried by every server and client route. */\nexport class HttpParameterBinding extends HttpParameterDeclaration {\n    constructor(\n        index: number,\n        source: HttpParameterSource,\n        wireName: string,\n        public readonly valueType: HttpParameterValueType,\n    ) {\n        super(index, source, wireName);\n    }\n}\n\n/** Result of mapping one API method call to its HTTP path/query/body. */\nexport class BoundHttpRequest {\n    constructor(\n        public readonly path: string,\n        // webpieces-disable no-any-unknown -- the contract owns the request body type\n        public readonly body: unknown,\n    ) {}\n}\n\n/**\n * The single path/query/body mapper shared by generated clients and the incoming server adapter.\n * Java Webpieces' `HttpsJsonClientInvokeHandler` is the reference model: explicit wire names,\n * encoded placeholders, omitted null query values, and repeated list keys. This port deliberately\n * fixes Java's list-query overwrite bug and never depends on compiled JavaScript parameter names.\n */\nexport class HttpContractMapper {\n    /** API arguments -> encoded relative URL + body. */\n    // webpieces-disable no-function-outside-class -- pure cross-runtime mapper used by DI-free browser clients and server adapters\n    static toWire(\n        pathTemplate: string,\n        bindings: readonly HttpParameterBinding[],\n        bodyParameterIndex: number | undefined,\n        // webpieces-disable no-any-unknown -- arbitrary API method parameters cross this generic boundary\n        args: readonly unknown[],\n    ): BoundHttpRequest {\n        let path = pathTemplate;\n        const query: string[] = [];\n\n        for (const binding of bindings) {\n            const value = args[binding.index];\n            if (binding.source === 'path') {\n                if (value === undefined || value === null) {\n                    throw new ApiBadRequestError(\n                        `Missing path parameter '${binding.wireName}' at argument ${binding.index}.`,\n                    );\n                }\n                const token = `{${binding.wireName}}`;\n                path = path.split(token).join(encodeURIComponent(String(value)));\n                continue;\n            }\n\n            if (value === undefined || value === null) continue;\n            const values = Array.isArray(value) ? value : [value];\n            for (const item of values) {\n                if (item === undefined || item === null) continue;\n                query.push(\n                    `${encodeURIComponent(binding.wireName)}=${encodeURIComponent(String(item))}`,\n                );\n            }\n        }\n\n        if (/\\{[^{}]+\\}/.test(path)) {\n            throw new ApiBadRequestError(\n                `Not every path placeholder was supplied for '${pathTemplate}'.`,\n            );\n        }\n        const suffix =\n            query.length === 0 ? '' : `${path.includes('?') ? '&' : '?'}${query.join('&')}`;\n        return new BoundHttpRequest(\n            `${path}${suffix}`,\n            bodyParameterIndex === undefined ? undefined : args[bodyParameterIndex],\n        );\n    }\n\n    /** Decoded path/query/body -> API arguments in declaration order. */\n    // webpieces-disable no-function-outside-class -- pure inverse mapper paired with toWire\n    static fromWire(\n        bindings: readonly HttpParameterBinding[],\n        bodyParameterIndex: number | undefined,\n        // webpieces-disable no-any-unknown -- the contract owns the request body type\n        body: unknown,\n        pathValues: ReadonlyMap<string, string | readonly string[]>,\n        queryValues: ReadonlyMap<string, string | readonly string[]>,\n    ): unknown[] {\n        const highestBinding = bindings.reduce(\n            (highest: number, binding: HttpParameterBinding) => Math.max(highest, binding.index),\n            -1,\n        );\n        const argCount = Math.max(highestBinding, bodyParameterIndex ?? -1) + 1;\n        // webpieces-disable no-any-unknown -- API argument types are erased at the shared wire boundary\n        const args = new Array<unknown>(argCount);\n        if (bodyParameterIndex !== undefined) args[bodyParameterIndex] = body;\n\n        for (const binding of bindings) {\n            const values = binding.source === 'path' ? pathValues : queryValues;\n            const raw = values.get(binding.wireName);\n            if (raw === undefined) {\n                if (binding.source === 'path') {\n                    throw new ApiBadRequestError(`Missing path parameter '${binding.wireName}'.`);\n                }\n                args[binding.index] = undefined;\n                continue;\n            }\n            args[binding.index] = this.convert(binding, raw);\n        }\n        return args;\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper\n    private static convert(\n        binding: HttpParameterBinding,\n        raw: string | readonly string[],\n    ): ConvertedHttpParameter {\n        const values = Array.isArray(raw) ? raw : [raw];\n        if (binding.valueType === 'array') return [...values];\n        if (values.length !== 1) {\n            throw new ApiBadRequestError(\n                `Parameter '${binding.wireName}' was repeated but is not declared as an array.`,\n            );\n        }\n        const value = values[0];\n        switch (binding.valueType) {\n            case 'string':\n            case 'unknown':\n                return value;\n            case 'number': {\n                if (value.trim() === '') {\n                    throw new ApiBadRequestError(\n                        `Parameter '${binding.wireName}' must be a number.`,\n                    );\n                }\n                const parsed = Number(value);\n                if (!Number.isFinite(parsed)) {\n                    throw new ApiBadRequestError(\n                        `Parameter '${binding.wireName}' must be a number.`,\n                    );\n                }\n                return parsed;\n            }\n            case 'boolean':\n                if (value === 'true') return true;\n                if (value === 'false') return false;\n                throw new ApiBadRequestError(\n                    `Parameter '${binding.wireName}' must be 'true' or 'false'.`,\n                );\n        }\n    }\n}\n"]}
+{"version":3,"file":"HttpContract.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HttpContract.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiBadRequestError } from '../errors/ApiError';\nimport { QueryParams } from './QueryParams';\n\n/** Nominal backing keeps raw string literals out of endpoint declarations. */\nenum HttpMethodValue {\n    GET = 'GET',\n    POST = 'POST',\n    PUT = 'PUT',\n    PATCH = 'PATCH',\n    DELETE = 'DELETE',\n}\n\n/** Short, statically importable decorator arguments. Raw strings do not satisfy {@link HttpMethod}. */\nexport const GET = HttpMethodValue.GET;\nexport const POST = HttpMethodValue.POST;\nexport const PUT = HttpMethodValue.PUT;\nexport const PATCH = HttpMethodValue.PATCH;\nexport const DELETE = HttpMethodValue.DELETE;\n\n/** HTTP verbs supported by generated Webpieces request/response contracts. */\nexport type HttpMethod = typeof GET | typeof POST | typeof PUT | typeof PATCH | typeof DELETE;\n\n/** Every verb, in declaration order — the one list validators and messages enumerate. */\nexport const HTTP_METHODS: readonly HttpMethod[] = [GET, POST, PUT, PATCH, DELETE];\n\n/**\n * The ONE rule for \"may this verb carry a request body\": POST, PUT and PATCH do; GET and DELETE do\n * not. Every client serializer, route validator, scanner and document renderer asks this, instead of\n * each re-deciding it with its own `=== 'POST'` check (which is how a sixth copy drifts).\n */\n// webpieces-disable no-function-outside-class -- pure predicate shared by DI-free browser and server runtimes\nexport function verbCarriesBody(method: string): boolean {\n    return method === POST || method === PUT || method === PATCH;\n}\n\n/** Runtime backstop for JavaScript and `as any` callers of `@Endpoint`. */\n// webpieces-disable no-function-outside-class -- pure guard shared by decorators and readers; webpieces-disable no-any-unknown -- untrusted runtime value is narrowed to an HTTP method\nexport function isHttpMethod(value: unknown): value is HttpMethod {\n    return (HTTP_METHODS as readonly unknown[]).includes(value);\n}\n\n/** Whether a generated client returns the response body or the whole transport-neutral response. */\nexport type EndpointResponseType = 'body' | 'full';\n\n/**\n * The wire source for one explicitly mapped method parameter: a `{placeholder}`, one named query key,\n * or (`@QueryString()`, EXTERNAL_OUTBOUND contracts only) the whole query string as a {@link QueryParams}.\n */\nexport type HttpParameterSource = 'path' | 'query' | 'query-map';\n\n/**\n * The ITEM type of a list query parameter, declared as `@QueryParam('ids', Number)`: TypeScript's\n * design metadata erases `number[]` to `Array`, so without it every item arrives as a string.\n */\nexport type HttpQueryItemType = typeof String | typeof Number | typeof Boolean;\n\n/** Runtime conversion supported for path/query values after TypeScript design metadata is read. */\nexport type HttpParameterValueType = 'string' | 'number' | 'boolean' | 'array' | 'unknown';\n\n/** Concrete runtime values produced for path/query parameters. */\ntype ConvertedHttpParameter =\n    | string\n    | number\n    | boolean\n    | readonly string[]\n    | readonly number[]\n    | readonly boolean[]\n    | QueryParams;\n\n/** Metadata written by `@PathParam` / `@QueryParam` before route construction knows the value type. */\nexport class HttpParameterDeclaration {\n    constructor(\n        public readonly index: number,\n        public readonly source: HttpParameterSource,\n        /** The wire name; `''` for a `query-map`, which binds every key. */\n        public readonly wireName: string,\n        /** `@QueryParam('ids', Number)`: the item type of a list query parameter. */\n        public readonly itemType?: HttpQueryItemType,\n    ) {}\n}\n\n/** Fully resolved parameter metadata carried by every server and client route. */\nexport class HttpParameterBinding extends HttpParameterDeclaration {\n    constructor(\n        index: number,\n        source: HttpParameterSource,\n        wireName: string,\n        public readonly valueType: HttpParameterValueType,\n        itemType?: HttpQueryItemType,\n    ) {\n        super(index, source, wireName, itemType);\n    }\n}\n\n/** Result of mapping one API method call to its HTTP path/query/body. */\nexport class BoundHttpRequest {\n    constructor(\n        public readonly path: string,\n        // webpieces-disable no-any-unknown -- the contract owns the request body type\n        public readonly body: unknown,\n    ) {}\n}\n\n/**\n * The single path/query/body mapper shared by generated clients and the incoming server adapter.\n * Java Webpieces' `HttpsJsonClientInvokeHandler` is the reference model: explicit wire names,\n * encoded placeholders, omitted null query values, and repeated list keys. This port deliberately\n * fixes Java's list-query overwrite bug and never depends on compiled JavaScript parameter names.\n */\nexport class HttpContractMapper {\n    /** API arguments -> encoded relative URL + body. */\n    // webpieces-disable no-function-outside-class -- pure cross-runtime mapper used by DI-free browser clients and server adapters\n    static toWire(\n        pathTemplate: string,\n        bindings: readonly HttpParameterBinding[],\n        bodyParameterIndex: number | undefined,\n        // webpieces-disable no-any-unknown -- arbitrary API method parameters cross this generic boundary\n        args: readonly unknown[],\n    ): BoundHttpRequest {\n        let path = pathTemplate;\n        const query: string[] = [];\n\n        for (const binding of bindings) {\n            const value = args[binding.index];\n            if (binding.source === 'path') {\n                if (value === undefined || value === null) {\n                    throw new ApiBadRequestError(\n                        `Missing path parameter '${binding.wireName}' at argument ${binding.index}.`,\n                    );\n                }\n                const token = `{${binding.wireName}}`;\n                path = path.split(token).join(encodeURIComponent(String(value)));\n                continue;\n            }\n\n            if (value === undefined || value === null) continue;\n            if (binding.source === 'query-map') {\n                this.appendQueryMap(binding, value, query);\n                continue;\n            }\n            const values = Array.isArray(value) ? value : [value];\n            for (const item of values) {\n                if (item === undefined || item === null) continue;\n                query.push(\n                    `${encodeURIComponent(binding.wireName)}=${encodeURIComponent(String(item))}`,\n                );\n            }\n        }\n\n        if (/\\{[^{}]+\\}/.test(path)) {\n            throw new ApiBadRequestError(\n                `Not every path placeholder was supplied for '${pathTemplate}'.`,\n            );\n        }\n        const suffix =\n            query.length === 0 ? '' : `${path.includes('?') ? '&' : '?'}${query.join('&')}`;\n        return new BoundHttpRequest(\n            `${path}${suffix}`,\n            bodyParameterIndex === undefined ? undefined : args[bodyParameterIndex],\n        );\n    }\n\n    /** One `@QueryString()` argument -> repeated `key=value` pairs, in insertion order. */\n    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper; webpieces-disable no-any-unknown -- the argument's type is erased at the generic boundary\n    private static appendQueryMap(binding: HttpParameterBinding, value: unknown, query: string[]): void {\n        if (!(value instanceof QueryParams)) {\n            throw new ApiBadRequestError(\n                `Argument ${binding.index} is @QueryString() and must be a QueryParams, received ${typeof value}.`,\n            );\n        }\n        for (const key of value.keys()) {\n            for (const item of value.getAll(key)) {\n                query.push(`${encodeURIComponent(key)}=${encodeURIComponent(item)}`);\n            }\n        }\n    }\n\n    /** Decoded path/query/body -> API arguments in declaration order. */\n    // webpieces-disable no-function-outside-class -- pure inverse mapper paired with toWire\n    static fromWire(\n        bindings: readonly HttpParameterBinding[],\n        bodyParameterIndex: number | undefined,\n        // webpieces-disable no-any-unknown -- the contract owns the request body type\n        body: unknown,\n        pathValues: ReadonlyMap<string, string | readonly string[]>,\n        queryValues: ReadonlyMap<string, string | readonly string[]>,\n    ): unknown[] {\n        const highestBinding = bindings.reduce(\n            (highest: number, binding: HttpParameterBinding) => Math.max(highest, binding.index),\n            -1,\n        );\n        const argCount = Math.max(highestBinding, bodyParameterIndex ?? -1) + 1;\n        // webpieces-disable no-any-unknown -- API argument types are erased at the shared wire boundary\n        const args = new Array<unknown>(argCount);\n        if (bodyParameterIndex !== undefined) args[bodyParameterIndex] = body;\n\n        for (const binding of bindings) {\n            if (binding.source === 'query-map') {\n                args[binding.index] = this.queryMapOf(queryValues);\n                continue;\n            }\n            const values = binding.source === 'path' ? pathValues : queryValues;\n            const raw = values.get(binding.wireName);\n            if (raw === undefined) {\n                if (binding.source === 'path') {\n                    throw new ApiBadRequestError(`Missing path parameter '${binding.wireName}'.`);\n                }\n                args[binding.index] = undefined;\n                continue;\n            }\n            args[binding.index] = this.convert(binding, raw);\n        }\n        return args;\n    }\n\n    /** Every decoded query key -> a {@link QueryParams}, the inverse of {@link appendQueryMap}. */\n    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper\n    private static queryMapOf(queryValues: ReadonlyMap<string, string | readonly string[]>): QueryParams {\n        const params = new QueryParams();\n        for (const entry of queryValues.entries()) {\n            const raw = entry[1];\n            for (const item of Array.isArray(raw) ? raw : [raw]) params.add(entry[0], item);\n        }\n        return params;\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper\n    private static convert(\n        binding: HttpParameterBinding,\n        raw: string | readonly string[],\n    ): ConvertedHttpParameter {\n        const values = Array.isArray(raw) ? raw : [raw];\n        if (binding.valueType === 'array') return this.convertItems(binding, values);\n        if (values.length !== 1) {\n            throw new ApiBadRequestError(\n                `Parameter '${binding.wireName}' was repeated but is not declared as an array.`,\n            );\n        }\n        const value = values[0];\n        return this.convertScalar(binding, value);\n    }\n\n    /** A list query parameter's items, as its declared item type (`@QueryParam('ids', Number)`). */\n    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper\n    private static convertItems(\n        binding: HttpParameterBinding,\n        values: readonly string[],\n    ): readonly string[] | readonly number[] | readonly boolean[] {\n        if (binding.itemType === Number) {\n            return values.map((item: string) => this.convertScalar(binding, item, 'number') as number);\n        }\n        if (binding.itemType === Boolean) {\n            return values.map((item: string) => this.convertScalar(binding, item, 'boolean') as boolean);\n        }\n        return [...values];\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static wire mapper\n    private static convertScalar(\n        binding: HttpParameterBinding,\n        value: string,\n        valueType: HttpParameterValueType = binding.valueType,\n    ): string | number | boolean {\n        switch (valueType) {\n            case 'string':\n            case 'unknown':\n            case 'array':\n                return value;\n            case 'number': {\n                if (value.trim() === '') {\n                    throw new ApiBadRequestError(\n                        `Parameter '${binding.wireName}' must be a number.`,\n                    );\n                }\n                const parsed = Number(value);\n                if (!Number.isFinite(parsed)) {\n                    throw new ApiBadRequestError(\n                        `Parameter '${binding.wireName}' must be a number.`,\n                    );\n                }\n                return parsed;\n            }\n            case 'boolean':\n                if (value === 'true') return true;\n                if (value === 'false') return false;\n                throw new ApiBadRequestError(\n                    `Parameter '${binding.wireName}' must be 'true' or 'false'.`,\n                );\n        }\n    }\n}\n"]}

package/src/http/HttpEndpointOptions.d.ts

@@ -12,20 +12,39 @@ export declare const WRITE_IDEMPOTENT = EndpointOperationValue.WRITE_IDEMPOTENT;
 export declare const WRITE = EndpointOperationValue.WRITE;
 /** The side-effect contract callers use to decide whether repeating an operation is safe. */
 export type EndpointOperation = typeof READ | typeof WRITE_IDEMPOTENT | typeof WRITE;
+/** Nominal backing for {@link EndpointOptions.responseBody}. */
+declare enum ResponseBodyValue {
+    NONE = "none"
+}
+/** `@Endpoint(..., { responseBody: NONE })` — the success response carries 0 bytes. */
+export declare const NONE = ResponseBodyValue.NONE;
+/** The one response-body declaration an endpoint can make; absent means a JSON body. */
+export type ResponseBodyKind = typeof NONE;
 /** Options for one `@Endpoint`, stored parallel to the method-to-path metadata. */
 export interface EndpointOptions {
     /** Return only a JSON body (default), or the full transport-neutral status/header/body value. */
     responseType?: EndpointResponseType;
+    /**
+     * `NONE`: this method returns `Promise<void>` and its success response is 0 BYTES. Our server
+     * answers `204 No Content` with no body and no Content-Type, and every client (node, browser,
+     * in-process) resolves `undefined` — while still ACCEPTING `{}`, an empty `200` or a `204`,
+     * because a vendor whose spec documents no body may still send one.
+     *
+     * WHY a declaration: `design:returntype` of an async method is just `Promise`, so the runtime
+     * cannot see `void`. The architecture scan checks this option agrees with the declared
+     * `Promise<void>` in both directions, so it cannot drift from the signature.
+     */
+    responseBody?: ResponseBodyKind;
     /**
      * Parse the request body as application/x-www-form-urlencoded instead of JSON. The request
      * DTO must be flat; urlencoded has no nesting. Default false = JSON.
      */
     formPost?: boolean;
     /**
-     * Retain the verbatim request bytes and absolute URL for a `webhook(...)` callback to verify.
+     * Retain the verbatim request bytes and absolute URL for a `vendorAuth(...)` hook to verify.
      * This is retention, not new buffering: the Express adapter already accumulates the body.
      *
-     * `webhook(...)` requires this option at wiring time. It combines with `formPost` for vendors
+     * A served `vendorAuth(...)` endpoint requires this option at wiring time. It combines with `formPost` for vendors
      * that sign flat form bodies, e.g. `{ formPost: true, rawBody: true }`.
      */
     rawBody?: boolean;
@@ -134,7 +153,7 @@ export interface EndpointOptions {
      */
     openWorld?: boolean;
 }
-/** An external endpoint must also identify the outside system that calls it. */
+/** An EXTERNAL_INBOUND endpoint must also identify the outside system that calls it. */
 export interface ExternalEndpointOptions extends EndpointOptions {
     /** The outside system (`'twilio'`) — graph identity, not display text. */
     calledBy: string;