@webpieces/core-util 0.4.957 → 0.4.959

package/src/http/DestinationTrust.js.map

@@ -1 +1 @@
-{"version":3,"file":"DestinationTrust.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/DestinationTrust.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAa,gBAAgB;IAeY;IAdrC;;;;OAIG;IACK,MAAM,CAAU,eAAe,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAErE;;;;OAIG;IACK,MAAM,CAAU,oBAAoB,GAAG,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAE3E,YAAqC,cAAuB;QAAvB,mBAAc,GAAd,cAAc,CAAS;IAAG,CAAC;IAEhE;;;;OAIG;IACH,qSAAqS;IACrS,MAAM,CAAC,WAAW,CAAC,IAA0B;QACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,OAAO,gBAAgB,CAAC,oBAAoB,CAAC;QACjD,CAAC;QACD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,MAAM,CAAC;YACZ,KAAK,eAAe;gBAChB,OAAO,gBAAgB,CAAC,eAAe,CAAC;YAC5C,KAAK,KAAK,CAAC;YACX,KAAK,QAAQ,CAAC;YACd,+EAA+E;YAC/E,oFAAoF;YACpF,mFAAmF;YACnF,yFAAyF;YACzF,mDAAmD;YACnD,KAAK,SAAS,CAAC;YACf,qFAAqF;YACrF,uFAAuF;YACvF,uFAAuF;YACvF,4FAA4F;YAC5F,iCAAiC;YACjC,KAAK,QAAQ;gBACb,4EAA4E;gBAC5E,uFAAuF;gBACvF,wFAAwF;gBACxF,iFAAiF;gBAC7E,OAAO,gBAAgB,CAAC,oBAAoB,CAAC;QACrD,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,GAAkB;QACrB,OAAO,IAAI,CAAC,cAAc,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;IACnD,CAAC;;AAzEL,4CA0EC","sourcesContent":["import { AnyContextKey } from '../ContextKey';\nimport { AuthMode } from './auth-mode';\n\n/**\n * DestinationTrust - the OUTBOUND half of the trust model: may a TRUSTED context key\n * ({@link ContextKey.trusted}) ride to the endpoint we are about to call?\n *\n * ## Why the client has to answer this at all\n *\n * The server already decided (see `PendingWireTrust`): an inbound `x-user-id` is admitted only on a\n * route that verified WHO called it — `oidcSameProject()` / `oidcSvcs(...)` / `sharedSecret(...)`. On a `jwt()` or `@WpAuthPublic`\n * route the same header must match what the authenticator independently derived, or the request is\n * REJECTED with a 401.\n *\n * That rule is correct, and it means a client that ships `x-user-id` to a `@WpAuthPublic` endpoint is\n * building a request the callee is obliged to reject. Before this class the outbound builders\n * forwarded EVERY transferred key with no idea what the destination was, so an internal service\n * calling another service's public or JWT endpoint 401'd itself. The fix belongs on the producing\n * side: don't send what cannot possibly be believed.\n *\n * ## Why it is a class with a private constructor and no boolean parameter\n *\n * `buildOutboundHeaders(sendTrusted = true)` would have been three characters of work and exactly the\n * \"widening that is an ABSENCE rather than a token\" `.claude/rules/no-backwards-compat.md` rejects — the\n * permissive answer would be\n * what you get by not typing anything. There is no way to build a DestinationTrust except from the\n * destination endpoint's own {@link AuthMode}, so the caller cannot assert a posture the route does\n * not actually have, and `grep -rn DestinationTrust.forAuthMode` lists every place the question is\n * asked. The two instances are PRIVATE for the same reason: exposing them would be a second spelling\n * that skips the derivation.\n *\n * Per CLAUDE.md: data-only structure, so a class rather than an interface or a bare boolean.\n */\nexport class DestinationTrust {\n    /**\n     * The destination authenticates its CALLER (oidcSameProject() / oidcSvcs(...) / sharedSecret(...)), so it is entitled to\n     * believe context WE vouch for — this is the service-to-service identity propagation that trusted\n     * keys keep an `httpHeader` for.\n     */\n    private static readonly VERIFIES_CALLER = new DestinationTrust(true);\n\n    /**\n     * The destination cannot tell us from a browser with curl (jwt() / @WpAuthPublic / webhook(...) /\n     * apiKey(...) / @WpLocalOnly / an endpoint with no declared mode), so trusted keys are omitted.\n     * Untrusted keys still travel.\n     */\n    private static readonly CANNOT_VERIFY_CALLER = new DestinationTrust(false);\n\n    private constructor(private readonly verifiesCaller: boolean) {}\n\n    /**\n     * The ONLY way to obtain one: state the destination endpoint's auth mode. `undefined` (an\n     * endpoint that declared no mode) is treated as un-verifying, i.e. the SAFE answer — an absent\n     * declaration must never be the widest one.\n     */\n    // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor, exactly as ContextKey.trusted/untrusted do: the destination's auth mode must be part of the CALL, and a DI-injected instance method would let a caller hold one without ever naming a route\n    static forAuthMode(mode: AuthMode | undefined): DestinationTrust {\n        if (mode === undefined) {\n            return DestinationTrust.CANNOT_VERIFY_CALLER;\n        }\n        switch (mode.kind) {\n            case 'oidc':\n            case 'shared-secret':\n                return DestinationTrust.VERIFIES_CALLER;\n            case 'jwt':\n            case 'public':\n            // webhook(...) authenticates an OUTSIDE VENDOR, which is not the same thing as\n            // authenticating a peer in this repo. The vendor knows nothing of webpieces context\n            // headers and would never send one, so there is no identity to propagate in either\n            // direction — and a webpieces client cannot call such an endpoint anyway (it cannot mint\n            // the vendor's signature). Trusted keys stay home.\n            case 'webhook':\n            // apiKey(...) authenticates a CUSTOMER, not a peer service. The holder of the key is\n            // another company's codebase, so nothing it forwards may be believed, and no webpieces\n            // client can call it anyway (the framework extracts no api-key header — the app's hook\n            // owns which headers carry the credential; the contract's `credentials` list only DESCRIBES\n            // them). Trusted keys stay home.\n            case 'apikey':\n            // @WpLocalOnly authenticates NOBODY — it gates on the environment, not on a\n            // credential — so a browser with curl on the same laptop is indistinguishable from us.\n            // Same bucket as public/jwt. (This switch has NO `default` on purpose: adding a kind to\n            // AuthMode is a compile error here rather than a silent permissive fallthrough.)\n                return DestinationTrust.CANNOT_VERIFY_CALLER;\n        }\n    }\n\n    /**\n     * May this key cross the boundary between us and this destination? Untrusted keys always may —\n     * nobody was ever going to make a security decision on them. A trusted key may only when we and\n     * the destination authenticate each other.\n     *\n     * ONE method answers BOTH directions, deliberately, because it is one question:\n     *\n     * - OUTBOUND (`buildOutboundHeaders`): may we SEND a trusted key there? Only when the destination\n     *   will authenticate US, because that is the only case its `AuthFilter` will admit it.\n     * - RESPONSE (`acceptResponseHeaders`): may we BELIEVE a trusted key that came BACK? Only from a\n     *   destination this client authenticated to — an `oidcSameProject()` / `oidcSvcs(...)` / `sharedSecret(...)` peer is a\n     *   service in our own trust domain, while a `@WpAuthPublic` / `jwt()` / partner endpoint is\n     *   somebody else's process whose response headers are an assertion, not a proof.\n     *\n     * A second, identically-bodied `believesResponsesFrom(key)` would be two spellings of one\n     * decision — the shim shape `.claude/rules/no-backwards-compat.md` rejects — so the direction\n     * lives in the CALLER's name and the rule lives here, once.\n     */\n    allows(key: AnyContextKey): boolean {\n        return this.verifiesCaller || !key.isTrusted();\n    }\n}\n"]}
+{"version":3,"file":"DestinationTrust.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/DestinationTrust.ts"],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAa,gBAAgB;IAgBJ;IAMA;IArBrB;;;;OAIG;IACK,MAAM,CAAU,eAAe,GAAG,IAAI,gBAAgB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAEhF;;;;OAIG;IACK,MAAM,CAAU,oBAAoB,GAAG,IAAI,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAEtF,YACqB,cAAuB;IACxC;;;;OAIG;IACc,YAAkD;QANlD,mBAAc,GAAd,cAAc,CAAS;QAMvB,iBAAY,GAAZ,YAAY,CAAsC;IACpE,CAAC;IAEJ;;;;;;OAMG;IACH,wGAAwG;IACxG,MAAM,CAAC,QAAQ,CAAC,KAAoB;QAChC,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;YACzB,OAAO,IAAI,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,gBAAgB,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC;IAED;;;;OAIG;IACH,UAAU;QACN,OAAO,IAAI,CAAC,YAAY,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,qSAAqS;IACrS,MAAM,CAAC,WAAW,CAAC,IAA0B;QACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,OAAO,gBAAgB,CAAC,oBAAoB,CAAC;QACjD,CAAC;QACD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,MAAM,CAAC;YACZ,KAAK,eAAe;gBAChB,OAAO,gBAAgB,CAAC,eAAe,CAAC;YAC5C,KAAK,KAAK,CAAC;YACX,KAAK,QAAQ,CAAC;YACd,kFAAkF;YAClF,oFAAoF;YACpF,mFAAmF;YACnF,qCAAqC;YACrC,KAAK,YAAY,CAAC;YAClB,qFAAqF;YACrF,uFAAuF;YACvF,uFAAuF;YACvF,4FAA4F;YAC5F,iCAAiC;YACjC,KAAK,QAAQ;gBACb,4EAA4E;gBAC5E,uFAAuF;gBACvF,wFAAwF;gBACxF,iFAAiF;gBAC7E,OAAO,gBAAgB,CAAC,oBAAoB,CAAC;QACrD,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,GAAkB;QACrB,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC,cAAc,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;IACnD,CAAC;IAED;;;;;;OAMG;IACH,gBAAgB,CAAC,GAAkB;QAC/B,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAClD,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;;AArHL,4CAsHC","sourcesContent":["import { AnyContextKey } from '../ContextKey';\nimport { AuthMode } from './auth-mode';\nimport { RouteMetadata } from './RouteMetadata';\n\n/**\n * DestinationTrust - the OUTBOUND half of the trust model: may a TRUSTED context key\n * ({@link ContextKey.trusted}) ride to the endpoint we are about to call?\n *\n * ## Why the client has to answer this at all\n *\n * The server already decided (see `PendingWireTrust`): an inbound `x-user-id` is admitted only on a\n * route that verified WHO called it — `oidcSameProject()` / `oidcSvcs(...)` / `sharedSecret(...)`. On a `jwt()` or `@WpAuthPublic`\n * route the same header must match what the authenticator independently derived, or the request is\n * REJECTED with a 401.\n *\n * That rule is correct, and it means a client that ships `x-user-id` to a `@WpAuthPublic` endpoint is\n * building a request the callee is obliged to reject. Before this class the outbound builders\n * forwarded EVERY transferred key with no idea what the destination was, so an internal service\n * calling another service's public or JWT endpoint 401'd itself. The fix belongs on the producing\n * side: don't send what cannot possibly be believed.\n *\n * ## Why it is a class with a private constructor and no boolean parameter\n *\n * `buildOutboundHeaders(sendTrusted = true)` would have been three characters of work and exactly the\n * \"widening that is an ABSENCE rather than a token\" `.claude/rules/no-backwards-compat.md` rejects — the\n * permissive answer would be\n * what you get by not typing anything. There is no way to build a DestinationTrust except from the\n * destination endpoint's own {@link AuthMode}, so the caller cannot assert a posture the route does\n * not actually have, and `grep -rn DestinationTrust.forAuthMode` lists every place the question is\n * asked. The two instances are PRIVATE for the same reason: exposing them would be a second spelling\n * that skips the derivation.\n *\n * Per CLAUDE.md: data-only structure, so a class rather than an interface or a bare boolean.\n */\nexport class DestinationTrust {\n    /**\n     * The destination authenticates its CALLER (oidcSameProject() / oidcSvcs(...) / sharedSecret(...)), so it is entitled to\n     * believe context WE vouch for — this is the service-to-service identity propagation that trusted\n     * keys keep an `httpHeader` for.\n     */\n    private static readonly VERIFIES_CALLER = new DestinationTrust(true, undefined);\n\n    /**\n     * The destination cannot tell us from a browser with curl (jwt() / @WpAuthPublic / vendorAuth(...) /\n     * apiKey(...) / @WpLocalOnly / an endpoint with no declared mode), so trusted keys are omitted.\n     * Untrusted keys still travel.\n     */\n    private static readonly CANNOT_VERIFY_CALLER = new DestinationTrust(false, undefined);\n\n    private constructor(\n        private readonly verifiesCaller: boolean,\n        /**\n         * Set ONLY for an `EXTERNAL_OUTBOUND` destination: the `@ExternalContextKeys` list, which is\n         * then the WHOLE of what may be sent. Undefined for every destination in this repo, whose wire\n         * is governed by {@link forAuthMode} exactly as before.\n         */\n        private readonly externalKeys: readonly AnyContextKey[] | undefined,\n    ) {}\n\n    /**\n     * The destination of ONE route. An `EXTERNAL_OUTBOUND` route (an outside system's API) gets a\n     * destination that sends ONLY its `@ExternalContextKeys` and believes NO response header: a vendor\n     * is somebody else's process, so our `x-request-id`, `x-webpieces-*` and app keys stay home unless\n     * the contract lists them, and nothing it answers may write into our context. Every other route is\n     * {@link forAuthMode}, unchanged — so the wire to our own servers is identical.\n     */\n    // webpieces-disable no-function-outside-class -- static factory beside forAuthMode, for the same reason\n    static forRoute(route: RouteMetadata): DestinationTrust {\n        if (route.externalOutbound) {\n            return new DestinationTrust(false, route.externalContextKeys);\n        }\n        return DestinationTrust.forAuthMode(route.authMeta?.methods[0]);\n    }\n\n    /**\n     * The keys an `EXTERNAL_OUTBOUND` destination sends — every one is REQUIRED, so a builder throws\n     * before any I/O when one has no value. Undefined for every other destination, whose builder\n     * iterates the registry's transferred keys and filters them with {@link allows}.\n     */\n    listedKeys(): readonly AnyContextKey[] | undefined {\n        return this.externalKeys;\n    }\n\n    /**\n     * The ONLY way to obtain one: state the destination endpoint's auth mode. `undefined` (an\n     * endpoint that declared no mode) is treated as un-verifying, i.e. the SAFE answer — an absent\n     * declaration must never be the widest one.\n     */\n    // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor, exactly as ContextKey.trusted/untrusted do: the destination's auth mode must be part of the CALL, and a DI-injected instance method would let a caller hold one without ever naming a route\n    static forAuthMode(mode: AuthMode | undefined): DestinationTrust {\n        if (mode === undefined) {\n            return DestinationTrust.CANNOT_VERIFY_CALLER;\n        }\n        switch (mode.kind) {\n            case 'oidc':\n            case 'shared-secret':\n                return DestinationTrust.VERIFIES_CALLER;\n            case 'jwt':\n            case 'public':\n            // vendorAuth(...) authenticates an OUTSIDE VENDOR, which is not the same thing as\n            // authenticating a peer in this repo. The vendor knows nothing of webpieces context\n            // headers and would never send one, so there is no identity to propagate in either\n            // direction. Trusted keys stay home.\n            case 'vendorAuth':\n            // apiKey(...) authenticates a CUSTOMER, not a peer service. The holder of the key is\n            // another company's codebase, so nothing it forwards may be believed, and no webpieces\n            // client can call it anyway (the framework extracts no api-key header — the app's hook\n            // owns which headers carry the credential; the contract's `credentials` list only DESCRIBES\n            // them). Trusted keys stay home.\n            case 'apikey':\n            // @WpLocalOnly authenticates NOBODY — it gates on the environment, not on a\n            // credential — so a browser with curl on the same laptop is indistinguishable from us.\n            // Same bucket as public/jwt. (This switch has NO `default` on purpose: adding a kind to\n            // AuthMode is a compile error here rather than a silent permissive fallthrough.)\n                return DestinationTrust.CANNOT_VERIFY_CALLER;\n        }\n    }\n\n    /**\n     * May this key cross the boundary between us and this destination? Untrusted keys always may —\n     * nobody was ever going to make a security decision on them. A trusted key may only when we and\n     * the destination authenticate each other.\n     *\n     * ONE method answers BOTH directions, deliberately, because it is one question:\n     *\n     * - OUTBOUND (`buildOutboundHeaders`): may we SEND a trusted key there? Only when the destination\n     *   will authenticate US, because that is the only case its `AuthFilter` will admit it.\n     * - RESPONSE (`acceptResponseHeaders`): may we BELIEVE a trusted key that came BACK? Only from a\n     *   destination this client authenticated to — an `oidcSameProject()` / `oidcSvcs(...)` / `sharedSecret(...)` peer is a\n     *   service in our own trust domain, while a `@WpAuthPublic` / `jwt()` / partner endpoint is\n     *   somebody else's process whose response headers are an assertion, not a proof.\n     *\n     * For every destination in this repo the two directions are one question, so the response side\n     * ({@link believesResponse}) delegates here; only an `EXTERNAL_OUTBOUND` destination answers them\n     * differently (it sends listed keys and believes none).\n     */\n    allows(key: AnyContextKey): boolean {\n        if (this.externalKeys !== undefined) return this.externalKeys.includes(key);\n        return this.verifiesCaller || !key.isTrusted();\n    }\n\n    /**\n     * May a key that came BACK on this destination's response be merged into our context? Exactly\n     * {@link allows} for a destination in this repo — and NOTHING from an `EXTERNAL_OUTBOUND` one,\n     * whose response headers are an outside system's, not a peer's. A separate method because for\n     * that destination the two directions genuinely differ: a key we LIST to send (`x-request-id`)\n     * is not thereby a key we let the vendor write back.\n     */\n    believesResponse(key: AnyContextKey): boolean {\n        if (this.externalKeys !== undefined) return false;\n        return this.allows(key);\n    }\n}\n"]}

package/src/http/EndpointCompileAssertions.js

@@ -2,13 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const decorators_1 = require("./decorators");
 (0, decorators_1.Endpoint)(decorators_1.POST, '/valid-rpc', decorators_1.WRITE, decorators_1.RPC);
-(0, decorators_1.Endpoint)(decorators_1.POST, '/valid-external', decorators_1.WRITE, decorators_1.EXTERNAL, { calledBy: 'twilio' });
-// @ts-expect-error external endpoints require options containing calledBy
-(0, decorators_1.Endpoint)(decorators_1.POST, '/missing-external-options', decorators_1.WRITE, decorators_1.EXTERNAL);
-// @ts-expect-error external endpoint options require calledBy
-(0, decorators_1.Endpoint)(decorators_1.POST, '/missing-external-caller', decorators_1.WRITE, decorators_1.EXTERNAL, { formPost: true });
+(0, decorators_1.Endpoint)(decorators_1.PUT, '/valid-put', decorators_1.WRITE_IDEMPOTENT, decorators_1.RPC);
+(0, decorators_1.Endpoint)(decorators_1.PATCH, '/valid-patch', decorators_1.WRITE, decorators_1.RPC);
+(0, decorators_1.Endpoint)(decorators_1.DELETE, '/valid-delete', decorators_1.WRITE_IDEMPOTENT, decorators_1.RPC);
+(0, decorators_1.Endpoint)(decorators_1.POST, '/valid-external', decorators_1.WRITE, decorators_1.EXTERNAL_INBOUND, { calledBy: 'twilio' });
+(0, decorators_1.Endpoint)(decorators_1.GET, '/valid-outbound', decorators_1.READ, decorators_1.EXTERNAL_OUTBOUND);
+// @ts-expect-error inbound external endpoints require options containing calledBy
+(0, decorators_1.Endpoint)(decorators_1.POST, '/missing-external-options', decorators_1.WRITE, decorators_1.EXTERNAL_INBOUND);
+// @ts-expect-error inbound external endpoint options require calledBy
+(0, decorators_1.Endpoint)(decorators_1.POST, '/missing-external-caller', decorators_1.WRITE, decorators_1.EXTERNAL_INBOUND, { formPost: true });
 // @ts-expect-error callerKind is a closed enum-backed union rather than free text
-(0, decorators_1.Endpoint)(decorators_1.POST, '/invalid-caller-kind', decorators_1.WRITE, decorators_1.EXTERNAL, {
+(0, decorators_1.Endpoint)(decorators_1.POST, '/invalid-caller-kind', decorators_1.WRITE, decorators_1.EXTERNAL_INBOUND, {
     calledBy: 'twilio',
     callerKind: 'vendor',
 });
@@ -18,4 +22,6 @@ const decorators_1 = require("./decorators");
 (0, decorators_1.Endpoint)('POST', '/raw-method', decorators_1.WRITE, decorators_1.RPC);
 // @ts-expect-error callers must import the enum-backed trigger-kind constant
 (0, decorators_1.Endpoint)(decorators_1.POST, '/raw-trigger', decorators_1.WRITE, 'rpc');
+// @ts-expect-error callers must import the enum-backed HTTP method constant, for the new verbs too
+(0, decorators_1.Endpoint)('PUT', '/raw-put', decorators_1.WRITE, decorators_1.RPC);
 //# sourceMappingURL=EndpointCompileAssertions.js.map

package/src/http/EndpointCompileAssertions.js.map

@@ -1 +1 @@
-{"version":3,"file":"EndpointCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/EndpointCompileAssertions.ts"],"names":[],"mappings":";;AAAA,6CAAoE;AAEpE,IAAA,qBAAQ,EAAC,iBAAI,EAAE,YAAY,EAAE,kBAAK,EAAE,gBAAG,CAAC,CAAC;AACzC,IAAA,qBAAQ,EAAC,iBAAI,EAAE,iBAAiB,EAAE,kBAAK,EAAE,qBAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;AAE3E,0EAA0E;AAC1E,IAAA,qBAAQ,EAAC,iBAAI,EAAE,2BAA2B,EAAE,kBAAK,EAAE,qBAAQ,CAAC,CAAC;AAE7D,8DAA8D;AAC9D,IAAA,qBAAQ,EAAC,iBAAI,EAAE,0BAA0B,EAAE,kBAAK,EAAE,qBAAQ,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AAEhF,kFAAkF;AAClF,IAAA,qBAAQ,EAAC,iBAAI,EAAE,sBAAsB,EAAE,kBAAK,EAAE,qBAAQ,EAAE;IACpD,QAAQ,EAAE,QAAQ;IAClB,UAAU,EAAE,QAAQ;CACvB,CAAC,CAAC;AAEH,0EAA0E;AAC1E,IAAA,qBAAQ,EAAC,iBAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAG,CAAC,CAAC;AAE/C,4EAA4E;AAC5E,IAAA,qBAAQ,EAAC,MAAM,EAAE,aAAa,EAAE,kBAAK,EAAE,gBAAG,CAAC,CAAC;AAE5C,6EAA6E;AAC7E,IAAA,qBAAQ,EAAC,iBAAI,EAAE,cAAc,EAAE,kBAAK,EAAE,KAAK,CAAC,CAAC","sourcesContent":["import { Endpoint, EXTERNAL, POST, RPC, WRITE } from './decorators';\n\nEndpoint(POST, '/valid-rpc', WRITE, RPC);\nEndpoint(POST, '/valid-external', WRITE, EXTERNAL, { calledBy: 'twilio' });\n\n// @ts-expect-error external endpoints require options containing calledBy\nEndpoint(POST, '/missing-external-options', WRITE, EXTERNAL);\n\n// @ts-expect-error external endpoint options require calledBy\nEndpoint(POST, '/missing-external-caller', WRITE, EXTERNAL, { formPost: true });\n\n// @ts-expect-error callerKind is a closed enum-backed union rather than free text\nEndpoint(POST, '/invalid-caller-kind', WRITE, EXTERNAL, {\n    calledBy: 'twilio',\n    callerKind: 'vendor',\n});\n\n// @ts-expect-error callers must import the enum-backed operation constant\nEndpoint(POST, '/raw-operation', 'write', RPC);\n\n// @ts-expect-error callers must import the enum-backed HTTP method constant\nEndpoint('POST', '/raw-method', WRITE, RPC);\n\n// @ts-expect-error callers must import the enum-backed trigger-kind constant\nEndpoint(POST, '/raw-trigger', WRITE, 'rpc');\n"]}
+{"version":3,"file":"EndpointCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/EndpointCompileAssertions.ts"],"names":[],"mappings":";;AAAA,6CAAgJ;AAEhJ,IAAA,qBAAQ,EAAC,iBAAI,EAAE,YAAY,EAAE,kBAAK,EAAE,gBAAG,CAAC,CAAC;AACzC,IAAA,qBAAQ,EAAC,gBAAG,EAAE,YAAY,EAAE,6BAAgB,EAAE,gBAAG,CAAC,CAAC;AACnD,IAAA,qBAAQ,EAAC,kBAAK,EAAE,cAAc,EAAE,kBAAK,EAAE,gBAAG,CAAC,CAAC;AAC5C,IAAA,qBAAQ,EAAC,mBAAM,EAAE,eAAe,EAAE,6BAAgB,EAAE,gBAAG,CAAC,CAAC;AACzD,IAAA,qBAAQ,EAAC,iBAAI,EAAE,iBAAiB,EAAE,kBAAK,EAAE,6BAAgB,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;AACnF,IAAA,qBAAQ,EAAC,gBAAG,EAAE,iBAAiB,EAAE,iBAAI,EAAE,8BAAiB,CAAC,CAAC;AAE1D,kFAAkF;AAClF,IAAA,qBAAQ,EAAC,iBAAI,EAAE,2BAA2B,EAAE,kBAAK,EAAE,6BAAgB,CAAC,CAAC;AAErE,sEAAsE;AACtE,IAAA,qBAAQ,EAAC,iBAAI,EAAE,0BAA0B,EAAE,kBAAK,EAAE,6BAAgB,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AAExF,kFAAkF;AAClF,IAAA,qBAAQ,EAAC,iBAAI,EAAE,sBAAsB,EAAE,kBAAK,EAAE,6BAAgB,EAAE;IAC5D,QAAQ,EAAE,QAAQ;IAClB,UAAU,EAAE,QAAQ;CACvB,CAAC,CAAC;AAEH,0EAA0E;AAC1E,IAAA,qBAAQ,EAAC,iBAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAG,CAAC,CAAC;AAE/C,4EAA4E;AAC5E,IAAA,qBAAQ,EAAC,MAAM,EAAE,aAAa,EAAE,kBAAK,EAAE,gBAAG,CAAC,CAAC;AAE5C,6EAA6E;AAC7E,IAAA,qBAAQ,EAAC,iBAAI,EAAE,cAAc,EAAE,kBAAK,EAAE,KAAK,CAAC,CAAC;AAE7C,mGAAmG;AACnG,IAAA,qBAAQ,EAAC,KAAK,EAAE,UAAU,EAAE,kBAAK,EAAE,gBAAG,CAAC,CAAC","sourcesContent":["import { DELETE, GET, READ, Endpoint, EXTERNAL_INBOUND, EXTERNAL_OUTBOUND, PATCH, POST, PUT, RPC, WRITE, WRITE_IDEMPOTENT } from './decorators';\n\nEndpoint(POST, '/valid-rpc', WRITE, RPC);\nEndpoint(PUT, '/valid-put', WRITE_IDEMPOTENT, RPC);\nEndpoint(PATCH, '/valid-patch', WRITE, RPC);\nEndpoint(DELETE, '/valid-delete', WRITE_IDEMPOTENT, RPC);\nEndpoint(POST, '/valid-external', WRITE, EXTERNAL_INBOUND, { calledBy: 'twilio' });\nEndpoint(GET, '/valid-outbound', READ, EXTERNAL_OUTBOUND);\n\n// @ts-expect-error inbound external endpoints require options containing calledBy\nEndpoint(POST, '/missing-external-options', WRITE, EXTERNAL_INBOUND);\n\n// @ts-expect-error inbound external endpoint options require calledBy\nEndpoint(POST, '/missing-external-caller', WRITE, EXTERNAL_INBOUND, { formPost: true });\n\n// @ts-expect-error callerKind is a closed enum-backed union rather than free text\nEndpoint(POST, '/invalid-caller-kind', WRITE, EXTERNAL_INBOUND, {\n    calledBy: 'twilio',\n    callerKind: 'vendor',\n});\n\n// @ts-expect-error callers must import the enum-backed operation constant\nEndpoint(POST, '/raw-operation', 'write', RPC);\n\n// @ts-expect-error callers must import the enum-backed HTTP method constant\nEndpoint('POST', '/raw-method', WRITE, RPC);\n\n// @ts-expect-error callers must import the enum-backed trigger-kind constant\nEndpoint(POST, '/raw-trigger', WRITE, 'rpc');\n\n// @ts-expect-error callers must import the enum-backed HTTP method constant, for the new verbs too\nEndpoint('PUT', '/raw-put', WRITE, RPC);\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;

package/src/http/HttpEndpointOptions.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WRITE = exports.WRITE_IDEMPOTENT = exports.READ = void 0;
+exports.NONE = exports.WRITE = exports.WRITE_IDEMPOTENT = exports.READ = void 0;
 /** Nominal backing keeps raw string literals out of endpoint declarations. */
 var EndpointOperationValue;
 (function (EndpointOperationValue) {
@@ -12,4 +12,11 @@ var EndpointOperationValue;
 exports.READ = EndpointOperationValue.READ;
 exports.WRITE_IDEMPOTENT = EndpointOperationValue.WRITE_IDEMPOTENT;
 exports.WRITE = EndpointOperationValue.WRITE;
+/** Nominal backing for {@link EndpointOptions.responseBody}. */
+var ResponseBodyValue;
+(function (ResponseBodyValue) {
+    ResponseBodyValue["NONE"] = "none";
+})(ResponseBodyValue || (ResponseBodyValue = {}));
+/** `@Endpoint(..., { responseBody: NONE })` — the success response carries 0 bytes. */
+exports.NONE = ResponseBodyValue.NONE;
 //# sourceMappingURL=HttpEndpointOptions.js.map