lambder 9.0.2 → 10.0.1

package/dist/mock/LambderMockApp.js

@@ -3,15 +3,18 @@ import { readApiEnvelope, cookieValuesByName, lowercaseHeaderNames } from "../ap
 import { bindCallTools, createApiCallContext, responseToolsOf } from "../api/LambderApiCallContext.js";
 import { toHttpAnswer } from "../api/LambderApiAnswer.js";
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
-import { buildApiEnvelope, envelopeAnswer, crashAnswer, } from "../api/LambderApiEnvelope.js";
-import { LambderApiRefusal, LAMBDER_REFUSAL_CODES } from "../shared/wire/LambderApiRefusal.js";
+import { envelopeAnswer, crashAnswer, plainRefusalEnvelope, refusalEnvelope, successEnvelope, } from "../api/LambderApiEnvelope.js";
+import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
+import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
+import { LambderApiRefusal, LAMBDER_REFUSAL_CODES, refuse as refuseApiCall } from "../shared/wire/LambderApiRefusal.js";
+import { allowedRefusalOf, readRefusalVocabulary, toRefusalCodes, } from "../api/LambderApiRefusals.js";
 import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
 import { buildTransportEnvelope } from "../shared/transport/LambderApiTransport.js";
 import { lambderCookieJarTransport } from "../shared/transport/lambderCookieJarTransport.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import { serializeClearCookie } from "../shared/wire/LambderCookie.js";
 import { LOOPBACK_CLIENT_IP, normalizeClientIp } from "../shared/util/LambderClientIp.js";
-import { lambderGuardBuilder } from "../api/LambderApiGuards.js";
+import { lambderGuardBuilder, toGuardEntries } from "../api/LambderApiGuards.js";
 import { lambderRateLimitKeyBuilder } from "../api/LambderApiRateLimits.js";
 import { LambderMockFailureInjector, LambderMockTransportError } from "./LambderMockFailureInjector.js";
 import { LambderMockCallRecorder } from "./LambderMockCallRecorder.js";
@@ -49,6 +52,8 @@ const defaultCookieHost = () => globalThis.location?.host || "localhost";
  * which fixes the contract and session types first so everything else is
  * inferred from the options. `TDerived` is true for a mock created with the
  * generated `apiOptions` table, whose entries are their handlers alone.
+ * `TVocabulary` and `TCodesRequired` are the refusal vocabulary the init
+ * declared (declareRefusals), which types every handler's ctx.refuse.
  */
 export class LambderMockApp {
     apiVersion;
@@ -88,11 +93,25 @@ export class LambderMockApp {
     registry = new LambderMockEntryRegistry();
     /** The server's declared options per API, when create() was given the generated table; the entries' declarations come from here. */
     apiOptions;
+    /** The server's guard declarations, when create() was given the generated table: the refusal codes a declared guard adds to an entry. */
+    guardDeclarations;
+    /** The server's refusal vocabulary, when create() was given the generated table: whether each code an entry may refuse with carries data. */
+    refusalVocabulary;
+    /** Whether every refusal an entry answers with has to name a code, as the server's declareRefusals() requireCodes. */
+    requireRefusalCodes;
     /** The jars the runtime owns and what it planted in document.cookie (see LambderMockBrowserCookies). */
     browserCookies = new LambderMockBrowserCookies();
-    constructor(options) {
+    constructor(options, 
+    /** The vocabulary the init declared, or null: what initLambderMock().declareRefusals() passes on. */
+    declared = null) {
         this.apiVersion = options.apiVersion ?? null;
         this.apiOptions = options.apiOptions ?? null;
+        this.guardDeclarations = options.guardDeclarations ?? null;
+        this.refusalVocabulary = declared?.vocabulary ?? null;
+        this.requireRefusalCodes = declared?.requireCodes ?? false;
+        if (this.requireRefusalCodes && !this.apiOptions) {
+            throw new Error("LambderMockApp: requireCodes needs the apiOptions table, which holds the codes each entry may refuse with.");
+        }
         this.failures = new LambderMockFailureInjector({ apiVersion: this.apiVersion, latency: options.latency ?? 0 });
         this.recorder = new LambderMockCallRecorder({ callLogSize: options.callLogSize ?? DEFAULT_CALL_LOG_SIZE });
         // The loopback address when nothing names a client, as for a request
@@ -124,15 +143,14 @@ export class LambderMockApp {
             maxRequestPayloadBytes: options.maxRequestPayloadBytes,
             // The server app's own answer to a bad input, where it has one:
             // without it the mock would answer 422 where the server answers,
-            // say, 200 with an errorMessage, and a form's error handling would
+            // say, 200 with a refusal, and a form's error handling would
             // be tested against an answer production never gives.
             onInvalidInput: options.onInvalidInput
                 ? async (zodError, ctx) => {
                     const answer = await options.onInvalidInput(zodError, ctx);
                     if (!answer)
                         return null;
-                    const config = answer.config ?? {};
-                    return envelopeAnswer(buildApiEnvelope(this.apiVersion, answer.payload ?? null, { ...config, logList: config.logList ?? ctx.logList }), { statusCode: answer.statusCode ?? 200 });
+                    return envelopeAnswer(plainRefusalEnvelope(this.apiVersion, answer.config, "the mock's onInvalidInput", ctx.logList), { statusCode: answer.statusCode ?? 200 });
                 }
                 : undefined,
             sessions: sessionOptions
@@ -219,6 +237,39 @@ export class LambderMockApp {
         }
         return declared;
     }
+    /**
+     * The codes an entry may refuse with, read off the generated tables (its
+     * own from apiOptions, its guards' from guardDeclarations), each resolved
+     * through the vocabulary the init declared, exactly as the server
+     * resolves its own: schema, status and flag. An entry that declares
+     * guards needs the guardDeclarations table, and one with any code needs
+     * the vocabulary; a code the tables name that the vocabulary lacks means
+     * the two describe different servers.
+     */
+    declaredRefusalsOf(name, declared) {
+        const codes = new Set(toRefusalCodes(declared.refusals));
+        const guards = toGuardEntries(declared.guards);
+        if (guards.length && !this.guardDeclarations) {
+            throw new Error(`LambderMockApp: "${name}" declares guards in the apiOptions table, and create() was not given the guardDeclarations table, which holds the refusal codes they add. Pass both from the generated options module.`);
+        }
+        for (const { name: guard } of guards) {
+            const declaration = this.guardDeclarations && Object.prototype.hasOwnProperty.call(this.guardDeclarations, guard) ? this.guardDeclarations[guard] : undefined;
+            for (const code of declaration?.refusals ?? [])
+                codes.add(code);
+        }
+        if (codes.size && !this.refusalVocabulary) {
+            throw new Error(`LambderMockApp: "${name}" can refuse with declared codes by the apiOptions table, and the mock init declared no refusal vocabulary. Declare the server's vocabulary, the same object, with initLambderMock().declareRefusals().`);
+        }
+        const allowed = new Map();
+        for (const code of codes) {
+            const declaration = this.refusalVocabulary.get(code);
+            if (!declaration) {
+                throw new Error(`LambderMockApp: "${name}" can refuse with "${code}" by the apiOptions and guardDeclarations tables, which the vocabulary declared on the mock init does not hold. The tables and the vocabulary describe one server: regenerate the tables, or declare the server's vocabulary.`);
+            }
+            allowed.set(code, allowedRefusalOf(declaration));
+        }
+        return allowed;
+    }
     /** The mode the apiOptions table gives a name, or null without a table or for a name it does not hold. */
     declaredModeOf(name) {
         if (!this.apiOptions || !Object.prototype.hasOwnProperty.call(this.apiOptions, name))
@@ -243,6 +294,7 @@ export class LambderMockApp {
             guards: declarations.guards,
             rateLimit: declarations.rateLimit,
             idempotency: declarations.idempotency,
+            refusals: declared ? { codes: this.declaredRefusalsOf(name, declared), codeRequired: this.requireRefusalCodes } : undefined,
             // No cast: the entry's schema is a z.ZodType, the same type the
             // definition holds. A structural { safeParse } here would let a
             // validator that is not a zod schema reach the 422 body as
@@ -411,7 +463,7 @@ export class LambderMockApp {
     // -----------------------------------------------------------------------
     // Control surface
     // -----------------------------------------------------------------------
-    /** The next call to the endpoint fails this way; several calls queue in order. */
+    /** The next call to the endpoint fails this way; several calls queue in order. An injected refusal names one of the endpoint's declared codes, its data as a handler raises it (see LambderMockRefusalsOf), and is checked and sent as a real one is. */
     failNext(apiName, failure) {
         this.failures.failNext(apiName, failure);
     }
@@ -590,6 +642,9 @@ export class LambderMockApp {
             methods: {
                 rateLimit: async (policy, key) => { await chargeRateLimit(policy, key, true); },
                 isRateLimited: (policy, key) => chargeRateLimit(policy, key, false),
+                // refuse() itself, typed on a handler's context to the
+                // endpoint's declared codes; checked where it is rendered.
+                refuse: refuseApiCall,
                 ...responseToolsOf(ctx, request.host),
             },
         });
@@ -665,7 +720,7 @@ export class LambderMockApp {
             // normally.
             const failure = this.failures.take(request.apiName);
             if (failure) {
-                answer = await this.failures.answerFor(failure, request);
+                answer = await this.failures.answerFor(failure, request, entry?.definition.refusals);
                 outcome = "injected";
             }
             else if (prepared) {
@@ -682,9 +737,12 @@ export class LambderMockApp {
                         // The payload the handler sees is the restored one.
                         callCtx.payload = request.payload;
                         const payload = await handler(callCtx);
-                        return envelopeAnswer(buildApiEnvelope(this.apiVersion, payload === undefined ? null : payload, {
-                            logList: callCtx.logList,
-                        }));
+                        // The server's rule, where the server applies it: an
+                        // answer is an object or an array, and a handler that
+                        // returns anything else has broken its contract.
+                        if (!isObjectPayload(payload))
+                            throw new LambderApiOutputValidationError(request.apiName, { notObject: describePayloadKind(payload) });
+                        return envelopeAnswer(successEnvelope(this.apiVersion, payload, callCtx.logList));
                     }
                     // A notMocked entry refuses where a handler would run, not
                     // ahead of the pipeline, so the steps that precede
@@ -693,7 +751,7 @@ export class LambderMockApp {
                     // compressed payload reaches the events.
                     : async () => {
                         throw new LambderApiRefusal(`Not mocked: ${entry.notMockedReason}`, {
-                            errorMessage: { type: "warning", code: LAMBDER_REFUSAL_CODES.notMocked, content: `"${request.apiName}" is not mocked: ${entry.notMockedReason}` },
+                            refusal: { type: "warning", code: LAMBDER_REFUSAL_CODES.notMocked, content: `"${request.apiName}" is not mocked: ${entry.notMockedReason}` },
                         });
                     }, trace);
                 answer = result.answer;
@@ -713,7 +771,7 @@ export class LambderMockApp {
             // for what could have been on the screen. Apps that want the
             // production shape turn it off.
             answer = this.revealHandlerErrors
-                ? envelopeAnswer(buildApiEnvelope(this.apiVersion, null, { errorMessage: error.message }), { statusCode: 500 })
+                ? envelopeAnswer(refusalEnvelope(this.apiVersion, { refusal: error.message }), { statusCode: 500 })
                 : crashAnswer(this.apiVersion);
             outcome = "crash";
         }
@@ -849,7 +907,8 @@ export class LambderMockApp {
  * });
  * ```
  */
-export const initLambderMock = () => ({
+/** The mock init bound to one vocabulary (or none): the builders, refuse and create() that share it. */
+const lambderMockInitOf = (declared) => ({
     /** Builds a mock guard: the server guard's shape, the handler seeing the mock's contexts. */
     guard: lambderGuardBuilder(),
     /**
@@ -859,6 +918,13 @@ export const initLambderMock = () => ({
      * while reading fields the mock context does not have.
      */
     rateLimitKey: lambderRateLimitKeyBuilder(),
+    /**
+     * refuse() typed to the vocabulary the mock declared, for a mock guard or
+     * a helper of the mock with no endpoint in hand: `code` is one of its
+     * codes and `data` the schema's input form, parsed as the server parses
+     * it. The free refuse() where the mock declared none.
+     */
+    refuse: refuseApiCall,
     /**
      * The mock app, with the guard map and the rate-limit policies inferred
      * from the options.
@@ -871,6 +937,32 @@ export const initLambderMock = () => ({
      * LambderMockSurplusKeys puts the error back on the key.
      */
     create(options) {
-        return new LambderMockApp(options);
+        return new LambderMockApp(options, declared);
+    },
+});
+/**
+ * The mock's entry point: fixes the contract and session types, and hands
+ * out the builders and create() that share them. `declareRefusals()` binds
+ * the server's refusal vocabulary too, the same object the server's init
+ * declares, so a mock handler's ctx.refuse takes a code's data in the
+ * schema's input form and the mock parses it exactly as the server does.
+ */
+export const initLambderMock = () => ({
+    ...lambderMockInitOf(null),
+    /**
+     * Declares the server's refusal vocabulary on the mock: the same object,
+     * and the same `requireCodes`, the server's init declares, imported from
+     * shared code (codes, zod schemas, statuses and flags hold nothing
+     * secret). Given, every refusal an entry answers with is checked and sent
+     * as the server would send it: the code among the codes the tables give
+     * the entry, its data parsed through the code's schema from the input
+     * form, and the declaration's status and flag. An entry whose tables name
+     * a code needs it.
+     */
+    declareRefusals(refusals, options = {}) {
+        const vocabulary = readRefusalVocabulary(refusals);
+        if (!vocabulary)
+            throw new Error("LambderMockApp: declareRefusals() takes the vocabulary, an object of codes.");
+        return lambderMockInitOf({ refusals, vocabulary, requireCodes: (options.requireCodes ?? false) });
     },
 });

package/dist/mock/LambderMockCallRecorder.js

@@ -42,7 +42,10 @@ const envelopeOf = (answer) => {
     }
 };
 /** How an answer reads, in the runtime's vocabulary. */
-const classifyAnswer = (answer, envelope) => {
+const classifyAnswer = (answer, body) => {
+    // Read field by field: the body is whatever the answer carried, and a
+    // success envelope has none of a refusal's fields.
+    const envelope = body;
     if (answer.statusCode >= 500)
         return "crash";
     if (answer.statusCode === 422)
@@ -55,14 +58,14 @@ const classifyAnswer = (answer, envelope) => {
         return "sessionExpired";
     if (envelope.notAuthorized)
         return "notAuthorized";
-    const code = envelope.errorMessage?.code;
+    const code = envelope.refusal?.code;
     if (code === LAMBDER_REFUSAL_CODES.rateLimited)
         return "rateLimited";
     if (code === LAMBDER_REFUSAL_CODES.notMocked)
         return "notMocked";
     if (code === LAMBDER_REFUSAL_CODES.apiNotFound)
         return "unknownApi";
-    if (envelope.errorMessage)
+    if (envelope.refusal)
         return "refusal";
     return "ok";
 };

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -1,6 +1,6 @@
 import type { z } from "zod";
 import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
-import type { LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiRefusalConfig } from "../shared/wire/LambderApiContract.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
 import type { LambderContractGuardNames, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractMode, LambderContractRateLimitNames, LambderContractRateLimitOf } from "../shared/wire/LambderApiContract.js";
@@ -282,12 +282,11 @@ export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicie
 };
 /**
  * What the server's input validation handler answers, as a mock states it:
- * the handler's `res.api(payload, config)` as data, with the status it went
- * out with (200 unless named).
+ * the handler's `res.apiRefusal(config)` as data, with the status it went
+ * out with (200 unless named). Like res.apiRefusal it is always a refusal.
  */
 export type LambderMockInvalidInputAnswer = {
-    payload?: unknown;
-    config?: LambderApiResponseConfig;
+    config: LambderApiRefusalConfig;
     statusCode?: LambderHttpStatusCode;
 };
 /** How the mock transport carries cookies: a fresh memory jar (default), a jar of yours, the memory jar mirrored into document.cookie, or none. */

package/dist/mock/LambderMockFailureInjector.d.ts

@@ -1,3 +1,4 @@
+import { type LambderEndpointRefusals } from "../api/LambderApiRefusals.js";
 import type { LambderApiAnswer } from "../api/LambderApiAnswer.js";
 import type { LambderApiRequest } from "../api/LambderApiRequest.js";
 import type { LambderMockFailure, LambderMockFailureReason, LambderMockLatency } from "./LambderMockTypes.js";
@@ -50,8 +51,14 @@ export declare class LambderMockFailureInjector {
     wait(ms: number, signal: AbortSignal | undefined): Promise<void>;
     /** Waits for the caller's own abort, which is what a timeout is; a call with no signal waits for ever. */
     waitForAbort(signal: AbortSignal | undefined): Promise<never>;
-    /** The answer an injected failure produces, or a throw for the ones that never reach the caller as answers. */
-    answerFor(failure: LambderMockFailure, request: LambderApiRequest): Promise<LambderApiAnswer>;
+    /**
+     * The answer an injected failure produces, or a throw for the ones that
+     * never reach the caller as answers. An injected refusal is checked
+     * against the endpoint's declared codes (`endpoint`), as the pipeline
+     * checks a real one, so a test cannot inject what the server could never
+     * send.
+     */
+    answerFor(failure: LambderMockFailure, request: LambderApiRequest, endpoint: LambderEndpointRefusals | undefined): Promise<LambderApiAnswer>;
     /** Clears every injected failure and puts the configured latency back. */
     reset(): void;
 }

package/dist/mock/LambderMockFailureInjector.js

@@ -1,6 +1,7 @@
 import { LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { crashAnswer, refusalAnswer, sessionExpiredAnswer, versionExpiredAnswer } from "../api/LambderApiEnvelope.js";
 import { rateLimitRefusal } from "../api/LambderApiRateLimits.js";
+import { checkedRefusal } from "../api/LambderApiRefusals.js";
 /** An injected refusal's message, from a string, a full message, or the reason's own wording. */
 const toRefusalMessage = (message, fallback) => typeof message === "string" ? { type: "warning", content: message }
     : message ?? { type: "warning", content: fallback };
@@ -106,19 +107,32 @@ export class LambderMockFailureInjector {
             signal.addEventListener("abort", () => reject(new LambderMockTransportError("timeout")), { once: true });
         });
     }
-    /** The answer an injected failure produces, or a throw for the ones that never reach the caller as answers. */
-    async answerFor(failure, request) {
+    /**
+     * The answer an injected failure produces, or a throw for the ones that
+     * never reach the caller as answers. An injected refusal is checked
+     * against the endpoint's declared codes (`endpoint`), as the pipeline
+     * checks a real one, so a test cannot inject what the server could never
+     * send.
+     */
+    async answerFor(failure, request, endpoint) {
         switch (failure.reason) {
             case "network": throw new LambderMockTransportError("network");
             case "timeout": return await this.waitForAbort(request.signal);
             case "server": return crashAnswer(this.apiVersion);
             case "refusal": {
                 const message = toRefusalMessage(failure.message, "Injected refusal.");
-                return refusalAnswer(new LambderApiRefusal(message.content, { errorMessage: message, statusCode: failure.statusCode }), this.apiVersion);
+                return refusalAnswer(checkedRefusal(request.apiName, endpoint, new LambderApiRefusal(message.content, { refusal: message, statusCode: failure.statusCode })), this.apiVersion);
             }
             case "notAuthorized": {
                 const message = toRefusalMessage(failure.message, "Injected authorization refusal.");
-                return refusalAnswer(new LambderApiRefusal(message.content, { errorMessage: message, notAuthorized: true }), this.apiVersion);
+                // A declared code's flag is its declaration's: the refusal is
+                // built without one and the declaration has to supply it.
+                const declared = message.code !== undefined && endpoint?.codes.has(message.code) === true;
+                const checked = checkedRefusal(request.apiName, endpoint, new LambderApiRefusal(message.content, { refusal: message, ...(declared ? {} : { notAuthorized: true }) }));
+                if (!checked.notAuthorized) {
+                    throw new Error(`LambderMockApp: the injected notAuthorized failure names the code "${String(message.code)}", which is not declared notAuthorized. Inject it as a refusal, or declare the flag on the code.`);
+                }
+                return refusalAnswer(checked, this.apiVersion);
             }
             case "sessionExpired": return sessionExpiredAnswer(this.apiVersion);
             case "versionExpired": return versionExpiredAnswer(this.apiVersion);

package/dist/mock/LambderMockTypes.d.ts

@@ -14,7 +14,10 @@ import type { LambderApiRequest } from "../api/LambderApiRequest.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import type { LambderApiDefinition } from "../api/LambderApiDefinition.js";
 import type { LambderApiEnvelopeBody } from "../shared/wire/LambderApiContract.js";
-import type { LambderAppRefusalMessage } from "../shared/wire/LambderApiRefusal.js";
+import type { LambderUncheckedRefusalMessage, LambderDeclaredRefuse } from "../shared/wire/LambderApiRefusal.js";
+import type { LambderRateLimitMessage } from "../shared/wire/LambderApiOptionValues.js";
+import type { LambderContractRefusalsOf } from "../shared/wire/LambderApiContract.js";
+import type { LambderHandlerRefusalsOf } from "../api/LambderApiRefusals.js";
 import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
 import type LambderSessionController from "../session/LambderSessionController.js";
 export type LambderMockInputOf<C, K extends keyof C> = C[K] extends {
@@ -67,7 +70,16 @@ export type LambderMockSessionCallContext<S = any> = Omit<LambderMockCallContext
     session: LambderSessionRecord<S>;
 };
 /** What a mock handler for endpoint K receives. */
-export type LambderMockContext<C, K extends keyof C, S, G> = Omit<LambderMockCallContext<S>, "apiName" | "session" | "guardData"> & {
+/**
+ * The codes endpoint K may refuse with, as a mock handler raises them. Where
+ * the mock init declared the vocabulary (declareRefusals), each code's data is
+ * its schema's input form and the mock parses it as the server does; where it
+ * declared none, the contract's wire form, sent as given.
+ */
+export type LambderMockRefusalsOf<C, K extends keyof C, TVocabulary> = [
+    TVocabulary
+] extends [never] ? LambderContractRefusalsOf<C, K> : LambderHandlerRefusalsOf<TVocabulary, keyof LambderContractRefusalsOf<C, K> & string>;
+export type LambderMockContext<C, K extends keyof C, S, G, TVocabulary = never, TCodesRequired extends boolean = false> = Omit<LambderMockCallContext<S>, "apiName" | "session" | "guardData"> & {
     apiName: K;
     /** The payload as posted; never optional, the way a validated payload reaches a server handler. */
     payload: LambderMockInputOf<C, K>;
@@ -79,6 +91,14 @@ export type LambderMockContext<C, K extends keyof C, S, G> = Omit<LambderMockCal
     guardInputs: [LambderContractGuardInputsOf<C, K>] extends [never] ? undefined : LambderContractGuardInputsOf<C, K>;
     /** The key the caller sent, when it sent a string; anything else is not a key and reaches a handler as undefined, having already been refused wherever it mattered. */
     idempotencyKey: string | undefined;
+    /**
+     * Refuses the call, as a server handler's ctx.refuse does: `code` is one
+     * of the endpoint's declared codes, and `data` is the code's data as a
+     * handler hands it over (see LambderMockRefusalsOf). Where the mock
+     * declared the vocabulary with requireCodes, a code is required. Write
+     * `return ctx.refuse(...)` where the code after it relies on it.
+     */
+    refuse: LambderDeclaredRefuse<LambderMockRefusalsOf<C, K, TVocabulary>, TCodesRequired>;
 };
 /**
  * The guard map a mock app must declare: one guard per name any endpoint of
@@ -99,7 +119,7 @@ export type LambderMockGuards<C, S = any> = {
         session?: false;
     };
 };
-export type LambderMockHandler<C, K extends keyof C, S, G> = (ctx: LambderMockContext<C, K, S, G>) => LambderMockOutputOf<C, K> | Promise<LambderMockOutputOf<C, K>>;
+export type LambderMockHandler<C, K extends keyof C, S, G, TVocabulary = never, TCodesRequired extends boolean = false> = (ctx: LambderMockContext<C, K, S, G, TVocabulary, TCodesRequired>) => LambderMockOutputOf<C, K> | Promise<LambderMockOutputOf<C, K>>;
 /**
  * The guards field of an entry: required whenever the contract declares any
  * guard for the endpoint, and type-equal to the server's own declaration.
@@ -196,7 +216,7 @@ type LambderMockDerivedFields = {
  * pinned to the contract, or, with `TDerived` (a mock created with the
  * generated `apiOptions` table), the handler alone.
  */
-export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType, TDerived extends boolean = false> = (TDerived extends true ? LambderMockDerivedFields : LambderMockGuardsField<C, K> & LambderMockRateLimitField<C, K> & LambderMockIdempotencyField<C, K>) & {
+export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType, TDerived extends boolean = false, TVocabulary = never, TCodesRequired extends boolean = false> = (TDerived extends true ? LambderMockDerivedFields : LambderMockGuardsField<C, K> & LambderMockRateLimitField<C, K> & LambderMockIdempotencyField<C, K>) & {
     /**
      * A schema to validate the posted payload against, so the mock answers
      * 422 exactly as the server would. Optional, and the mock's own: the
@@ -207,7 +227,7 @@ export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema ext
      * LambderMockInputPin).
      */
     input?: TInputSchema & LambderMockInputPin<C, K, TInputSchema>;
-    handler: LambderMockHandler<C, K, S, G>;
+    handler: LambderMockHandler<C, K, S, G, TVocabulary, TCodesRequired>;
 };
 /**
  * What publicApi/sessionApi accept. On a mock created with the generated
@@ -219,7 +239,7 @@ export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema ext
  * guardless endpoint could drop its rate limit and idempotency through the
  * bare form.
  */
-export type LambderMockEntryInput<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType, TDerived extends boolean = false> = TDerived extends true ? LambderMockHandler<C, K, S, G> | LambderMockEntryOptions<C, K, S, G, TInputSchema, true> : [LambderContractGuardsOf<C, K> | LambderContractRateLimitOf<C, K> | LambderContractIdempotencyOf<C, K>] extends [never] ? LambderMockHandler<C, K, S, G> | LambderMockEntryOptions<C, K, S, G, TInputSchema> : LambderMockEntryOptions<C, K, S, G, TInputSchema>;
+export type LambderMockEntryInput<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType, TDerived extends boolean = false, TVocabulary = never, TCodesRequired extends boolean = false> = TDerived extends true ? LambderMockHandler<C, K, S, G, TVocabulary, TCodesRequired> | LambderMockEntryOptions<C, K, S, G, TInputSchema, true, TVocabulary, TCodesRequired> : [LambderContractGuardsOf<C, K> | LambderContractRateLimitOf<C, K> | LambderContractIdempotencyOf<C, K>] extends [never] ? LambderMockHandler<C, K, S, G, TVocabulary, TCodesRequired> | LambderMockEntryOptions<C, K, S, G, TInputSchema, false, TVocabulary, TCodesRequired> : LambderMockEntryOptions<C, K, S, G, TInputSchema, false, TVocabulary, TCodesRequired>;
 /** One registry entry: the endpoint's definition as the pipeline runs it, and its handler (null when registered as not mocked). */
 export type LambderMockEntry<C, K extends keyof C & string> = {
     readonly name: K;
@@ -317,9 +337,12 @@ export type LambderMockLatency = number | {
  * uses for the real thing, so an injected 429 carries the Retry-After a
  * real one does. `network` rejects the transport; `timeout` waits for the
  * caller's own abort (a call with no timeout configured waits for its
- * external signal, or for ever, which is what a timeout is).
+ * external signal, or for ever, which is what a timeout is). TMessage is the
+ * endpoint's refusal message, so an injected refusal names one of its
+ * declared codes with that code's data, and is checked against the
+ * declaration as a real one is.
  */
-export type LambderMockFailure = {
+export type LambderMockFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = {
     reason: "network";
 } | {
     reason: "timeout";
@@ -327,11 +350,11 @@ export type LambderMockFailure = {
     reason: "server";
 } | {
     reason: "refusal";
-    message?: LambderAppRefusalMessage | string;
+    message?: TMessage | string;
     statusCode?: LambderHttpStatusCode;
 } | {
     reason: "notAuthorized";
-    message?: LambderAppRefusalMessage | string;
+    message?: TMessage | string;
 } | {
     reason: "sessionExpired";
 } | {
@@ -339,7 +362,7 @@ export type LambderMockFailure = {
 } | {
     reason: "rateLimited";
     retryAfterSeconds?: number;
-    message?: LambderAppRefusalMessage;
+    message?: LambderRateLimitMessage;
 };
 /** Every sibling in the package spells this `reason`: an outcome's, a transport failure's, an invoke failure's. */
 export type LambderMockFailureReason = LambderMockFailure["reason"];

package/dist/mock.d.ts

@@ -9,7 +9,7 @@
 export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
 export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
 export type { LambderMockAppOptions, LambderMockSessionsOptions, LambderMockIdempotencyOptions, LambderMockInvalidInputAnswer, LambderMockTransport, LambderMockTransportOptions } from "./mock/LambderMockCreateOptions.js";
-export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockPublicNames, LambderMockSessionNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
+export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockRefusalsOf, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockPublicNames, LambderMockSessionNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
 export { lambderMockPoliciesFrom } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderCustomKeyedPolicyNames, LambderMockPolicyKeys } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderMockGuardShapeOf } from "./mock/LambderMockCreateOptions.js";
@@ -31,8 +31,9 @@ export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotency
 export { LambderWebCrypto, LambderPlainSessionCrypto } from "./session/LambderSessionCrypto.js";
 export type { LambderSessionCrypto } from "./session/LambderSessionCrypto.js";
 export { LambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
-export type { LambderRefusalMessage } from "./shared/wire/LambderApiRefusal.js";
-export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+export type { LambderRefusalMessage, LambderDeclaredRefuse, LambderDeclaredRefuseOptions } from "./shared/wire/LambderApiRefusal.js";
+export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
+export { assertApiSuccess, assertApiFailure, assertApiRefusal } from "./shared/wire/LambderOutcomeAssertions.js";
 export type { LambderExpectedFailure } from "./shared/wire/LambderOutcomeAssertions.js";
 export type { LambderApiRequest } from "./api/LambderApiRequest.js";
 export type { LambderApiAnswer } from "./api/LambderApiAnswer.js";

package/dist/mock.js

@@ -31,6 +31,7 @@ export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
 export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
 export { LambderWebCrypto, LambderPlainSessionCrypto } from "./session/LambderSessionCrypto.js";
 export { LambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
-// The outcome assertions a test over the mock app narrows with; the same two
-// `lambder/testing` exports for a test over the real server.
-export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
+// The outcome assertions a test over the mock app narrows with; the same
+// ones `lambder/testing` exports for a test over the real server.
+export { assertApiSuccess, assertApiFailure, assertApiRefusal } from "./shared/wire/LambderOutcomeAssertions.js";

package/dist/shared/contracts/LambderUploadBucket.d.ts

@@ -13,14 +13,29 @@ export type LambderUploadFileFacts = {
     /** SHA-256 of the file's bytes as base64, the form storage checks an upload against: 43 characters and one pad. */
     sha256Base64: string;
 };
-/** Everything the browser needs to post one file to storage, and until when. */
+/**
+ * Everything the browser needs to send one file to storage, and until when,
+ * in one of the two forms a store signs. `POST` is a form (S3's presigned
+ * POST), `PUT` the file as the body of a signed URL (a presigned PUT, which
+ * Cloudflare R2 and other stores without POST policies take).
+ */
 export type LambderUploadTicket = {
+    method: "POST";
     uploadUrl: string;
     /** Sent as form fields ahead of the file, which storage wants last. */
     formFields: Record<string, string>;
     /** Epoch milliseconds after which storage refuses the ticket. */
     expiresAt: number;
+} | {
+    method: "PUT";
+    uploadUrl: string;
+    /** Sent exactly as given, each one signed into the URL; the browser adds the length itself. */
+    headers: Record<string, string>;
+    /** Epoch milliseconds after which storage refuses the ticket. */
+    expiresAt: number;
 };
+/** How a bucket's tickets send a file: the `method` of the tickets it signs. */
+export type LambderUploadMethod = LambderUploadTicket["method"];
 /** What a bucket holds under a key, compared with what the browser said it would upload. */
 export type LambderUploadVerdict = {
     verified: true;
@@ -38,7 +53,7 @@ export type LambderUploadContentDisposition = {
 };
 /**
  * What storage keeps beside an object's bytes. A ticket pins every one of
- * these in its signed policy, so the browser posts them unchanged.
+ * these in its signature, so the browser sends them unchanged.
  */
 export type LambderUploadObjectOptions = {
     /**
@@ -91,7 +106,7 @@ export interface LambderUploadBucket {
      * Signs a ticket for exactly the file the browser described, or refuses
      * (a LambderApiRefusal, code `lambder/upload-empty`,
      * `lambder/upload-type-rejected` or `lambder/upload-too-large`) when the
-     * rule does not accept it. Storage then enforces every fact: the post
+     * rule does not accept it. Storage then enforces every fact: the upload
      * fails unless the body has that byte size, that content type and that
      * SHA-256, so what verifies later is what was described here. `object`
      * is what the stored object carries besides, pinned the same way, and

package/dist/shared/contracts/LambderUploadBucket.js

@@ -4,7 +4,7 @@
  *
  * An API payload tops out near a few megabytes once a file is base64, and a
  * Lambda's request body at six, so anything larger (a scanned lease, a
- * signed PDF, a video) is posted by the browser to the bucket itself, with a
+ * signed PDF, a video) is sent by the browser to the bucket itself, with a
  * ticket the server signed beforehand. The ticket pins everything about the
  * upload: the key, the exact byte size, the content type and the SHA-256 of
  * the bytes, all enforced by the storage, so the browser can only ever store
@@ -12,7 +12,7 @@
  *
  * The conversation is the same three steps whatever the app stores: the
  * browser describes the file (LambderUploadFileFacts), the app's endpoint
- * answers with a ticket (LambderUploadTicket), and after the post the app's
+ * answers with a ticket (LambderUploadTicket), and after the upload the app's
  * confirm endpoint asks the bucket what arrived before its record counts as
  * uploaded. The server half is a LambderUploadBucket, the browser half is
  * LambderUploadRunner.

package/dist/shared/util/LambderTypeUtilities.d.ts

@@ -48,3 +48,14 @@ export type LambderReadonlyDeep<T, TDepth extends unknown[] = []> = TDepth["leng
 export type LambderNonEmptyOptionMap<TMap> = {
     [K in keyof TMap]-?: Required<Pick<TMap, K>> & Omit<TMap, K>;
 }[keyof TMap];
+/**
+ * Rejects a key the options type does not have, which `const TOptions` would
+ * otherwise wave through: inferring a generic from an object literal switches
+ * excess-property checking off for the whole literal, so
+ * `requireSessionApiGuard` (no trailing "s") or `maxResponseByte` would
+ * compile, be dropped in silence, and leave the app on the default. That is
+ * worst for the two require*ApiGuards flags, which exist to make a missing
+ * authorization declaration a compile error. Mapping every surplus key to
+ * `never` puts the error back on the key itself.
+ */
+export type LambderNoExtraKeys<TOptions, TShape> = TOptions & Record<Exclude<keyof TOptions, keyof TShape>, never>;