lambder 9.0.3 → 10.0.1

package/dist/shared/wire/LambderApiRefusal.d.ts

@@ -1,13 +1,13 @@
 import type { LambderHttpStatusCode } from "./LambderHttpStatus.js";
 export type LambderApiRefusalOptions = {
     /**
-     * User-facing failure detail placed on the API envelope's `errorMessage`
+     * User-facing failure detail placed on the API envelope's `refusal`
      * field: a refusal message (`{ type: "warning", content: "..." }`, with
      * an app's own `code`) or a plain string, which becomes an "error"
      * message with that content. Defaults to the error message, so a bare
      * `throw new LambderApiRefusal("...")` is still visible to the client.
      */
-    errorMessage?: LambderAppRefusalMessage | string;
+    refusal?: LambderUncheckedRefusalMessage | string;
     /** Sets the envelope's `notAuthorized` flag (routed to the caller's notAuthorizedHandler). */
     notAuthorized?: boolean;
     /** Sets the envelope's `sessionExpired` flag (the caller clears session cookies and calls sessionExpiredHandler). */
@@ -27,7 +27,7 @@ export type LambderApiRefusalOptions = {
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
  * crashed". Throw it from anywhere in an API call's call stack (handlers,
  * hooks, guards or nested helpers) and the render pipeline maps it onto the
- * structured API envelope (its errorMessage, notAuthorized and
+ * structured API envelope (its refusal, notAuthorized and
  * sessionExpired) instead of routing it through setGlobalErrorHandler, so refusals never reach crash
  * logging and clients receive a parseable response.
  *
@@ -45,8 +45,8 @@ export declare class LambderApiRefusal extends Error {
      * across them while this marker does not. The pipeline checks the brand.
      */
     readonly isLambderApiRefusal = true;
-    /** What the envelope's errorMessage carries: always a message object, a plain string given to the options made into one. */
-    readonly errorMessage: LambderAppRefusalMessage;
+    /** What the envelope's refusal carries: always a message object, a plain string given to the options made into one. */
+    readonly refusal: LambderUncheckedRefusalMessage;
     readonly notAuthorized?: boolean;
     readonly sessionExpired?: boolean;
     readonly statusCode?: LambderHttpStatusCode;
@@ -55,44 +55,70 @@ export declare class LambderApiRefusal extends Error {
 }
 /** Brand-based type guard (see LambderApiRefusal.isLambderApiRefusal). */
 export declare const isLambderApiRefusal: (err: unknown) => err is LambderApiRefusal;
-/**
- * The standard shape refusals carry on the envelope's errorMessage field.
- * `code` is the refusal's machine-readable identity: clients branch and
- * translate on it and never string-match `content`, which stays the
- * human-readable fallback for codes a client does not know yet. The
- * framework's own refusals carry a LambderRefusalCode; apps put their own
- * typed vocabulary in `code`. The caller's errorMessageHandler receives the
- * object as-is, typed as LambderAppRefusalMessage; a server that wrote a
- * plain string reaches it as `{ type: "error", content }` (refusalMessageOf).
- */
-export type LambderRefusalMessage<TAppCode extends string = never> = {
+/** What every refusal message carries, whatever its code. */
+type LambderRefusalMessageFields = {
+    /** Rendering intent for the client: how loud to be about it. */
     type: "warning" | "error" | "info";
+    /** Optional heading shown above the content. */
+    title?: string;
     /**
-     * Machine-readable identity of the refusal: a LambderRefusalCode, plus
-     * whatever vocabulary the reader names in TAppCode.
-     *
-     * Parameterized rather than widened with `string & {}`: a union with
-     * `string` in it does not narrow, so a `switch(message.code)` could not
-     * end in a `default: never` exhaustiveness check, which is what the codes
-     * exist for. A client that reads its own vocabulary declares it
-     * (`LambderRefusalMessage<"app/not-verified" | ...>`) and gets a checked
-     * switch; a value an app WRITES takes LambderAppRefusalMessage, where any
-     * code is welcome.
+     * The human-readable text: what a client shows when it has nothing better.
+     * A client that translates reads the code and the data instead, and falls
+     * back to this for a code it does not know.
      */
-    code?: LambderRefusalCode | TAppCode;
-    title?: string;
     content: string;
 };
 /**
- * The refusal shape an app authors: any code, with the framework's own still
- * autocompleting. Every option that takes a message from an app is typed as
- * this (a rate-limit policy's errorMessage, the mock's failure injection);
- * LambderRefusalMessage itself defaults to the framework's codes alone, so a
- * reader's switch over it is exhaustive.
+ * A refusal no app declared: one the framework wrote itself (a
+ * LambderRefusalCode), or an app's `refuse("...")` without a code. It never
+ * carries data.
  */
-export type LambderAppRefusalMessage = LambderRefusalMessage<string & {}>;
+export type LambderPlainRefusalMessage = LambderRefusalMessageFields & {
+    code?: LambderRefusalCode;
+    data?: undefined;
+};
 /**
- * An errorMessage as the one shape a reader handles: a plain string becomes
+ * One declared code's message: the code, and its data when the code declares
+ * data. TDeclaration is the code's value in a contract entry's `refusals`:
+ * `{ data: D }` or `{}`.
+ */
+type LambderDeclaredRefusalMessage<TCode extends string, TDeclaration> = LambderRefusalMessageFields & {
+    code: TCode;
+} & (TDeclaration extends {
+    data: infer TData;
+} ? {
+    data: TData;
+} : {
+    data?: undefined;
+});
+/**
+ * The refusal message a reader receives, discriminated by `code`.
+ *
+ * TRefusals maps each code the endpoint declares to its contract value
+ * (`{ data: D }` or `{}`; see LambderContractRefusalsOf). Every declared code
+ * is one arm, carrying its own data type, and the framework's codes and the
+ * uncoded refusal are one more arm with no data. A `switch (message.code)`
+ * therefore narrows `data` in each case, and a `default: never` holds: the
+ * server refuses to send a code the endpoint did not declare (see
+ * LambderApiRefusalValidationError), so no other code can arrive.
+ *
+ * Left without an argument it is the framework's own vocabulary alone.
+ */
+export type LambderRefusalMessage<TRefusals = {}> = 0 extends 1 & TRefusals ? LambderUncheckedRefusalMessage : LambderPlainRefusalMessage | {
+    [TCode in keyof TRefusals & string]: LambderDeclaredRefusalMessage<TCode, TRefusals[TCode]>;
+}[keyof TRefusals & string];
+/**
+ * The refusal shape an app writes, and the widest a reader can be handed:
+ * any code (the framework's still autocomplete) and any data. What
+ * LambderApiRefusal carries and refusalMessageOf reads; a reader that knows
+ * the endpoint reads the narrower LambderRefusalMessage instead.
+ */
+export type LambderUncheckedRefusalMessage = LambderRefusalMessageFields & {
+    code?: LambderRefusalCode | (string & {});
+    data?: unknown;
+};
+/**
+ * An refusal as the one shape a reader handles: a plain string becomes
  * an "error" message with that content, and a value that is not a message
  * at all becomes one describing it. The envelope writer applies it, so a
  * Lambder server only ever sends the object. A reader applies it too,
@@ -100,7 +126,7 @@ export type LambderAppRefusalMessage = LambderRefusalMessage<string & {}>;
  * mock answer (an MSW handler, a test double) or a proxy that wrote its own
  * body can put anything there.
  */
-export declare const refusalMessageOf: (message: unknown) => LambderAppRefusalMessage;
+export declare const refusalMessageOf: (message: unknown) => LambderUncheckedRefusalMessage;
 /**
  * Codes the framework stamps on the refusals it authors itself, under the
  * reserved `lambder/` prefix so app codes never collide. Compare against
@@ -108,7 +134,7 @@ export declare const refusalMessageOf: (message: unknown) => LambderAppRefusalMe
  * than retyping the strings.
  */
 export declare const LAMBDER_REFUSAL_CODES: {
-    /** A rate-limit policy refused (429). A policy's own errorMessage inherits this unless it sets a code. */
+    /** A rate-limit policy refused (429). A policy's own message carries it. */
     readonly rateLimited: "lambder/rate-limited";
     /** The original of an idempotent request is still processing (409). */
     readonly duplicateInFlight: "lambder/duplicate-in-flight";
@@ -130,18 +156,31 @@ export declare const LAMBDER_REFUSAL_CODES: {
     readonly uploadTooLarge: "lambder/upload-too-large";
 };
 export type LambderRefusalCode = (typeof LAMBDER_REFUSAL_CODES)[keyof typeof LAMBDER_REFUSAL_CODES];
+/** Whether a code is one the framework stamps on its own refusals. */
+export declare const isLambderRefusalCode: (code: unknown) => code is LambderRefusalCode;
 export type LambderRefuseOptions = {
-    /** Rendering intent for the client's errorMessageHandler. Default: "warning". */
+    /** Rendering intent for the client's refusalHandler. Default: "warning". */
     type?: LambderRefusalMessage["type"];
-    /** Machine-readable identity of the refusal, for clients to branch and translate on. */
+    /**
+     * Machine-readable identity of the refusal, for clients to branch and
+     * translate on: a code the endpoint declares in its `refusals` option (or
+     * through one of its guards). A code it does not declare is a crash, not
+     * a refusal; see LambderApiRefusalValidationError.
+     */
     code?: string;
+    /**
+     * The code's data, when the code declares data: parsed through the
+     * declared schema before it is sent, as an output is. A refusal without
+     * a declared code carries none.
+     */
+    data?: unknown;
     /** Optional heading shown above the content. */
     title?: string;
-    /** Sets the envelope's notAuthorized flag (routed to the caller's notAuthorizedHandler). */
+    /** Sets the envelope's notAuthorized flag (routed to the caller's notAuthorizedHandler). A declared code's flag is its declaration's, and a refusal with such a code that sets it here is a crash. */
     notAuthorized?: boolean;
-    /** Sets the envelope's sessionExpired flag. */
+    /** Sets the envelope's sessionExpired flag. Not for a refusal with a declared code, whose flags are its declaration's. */
     sessionExpired?: boolean;
-    /** HTTP status of the refusal. Default 200; avoid 5xx (caller treats as crash) and 422 (reserved for validation). */
+    /** HTTP status of the refusal. Default 200; avoid 5xx (caller treats as crash) and 422 (reserved for validation). A declared code's status is its declaration's, and a refusal with such a code that sets one here is a crash. */
     statusCode?: LambderHttpStatusCode;
     /** Extra response headers on the refusal (e.g. Retry-After). */
     headers?: Record<string, string>;
@@ -159,5 +198,51 @@ export type LambderRefuseOptions = {
  * The const carries the annotation so TypeScript applies never-return
  * control-flow narrowing at call sites (`if (!row) refuse(...)` implies
  * `row` is defined afterwards).
+ *
+ * Its `code` and `data` are checked when the refusal is rendered, against the
+ * endpoint it answers. Inside an API handler, `ctx.refuse` takes the same
+ * arguments typed to that endpoint's declared codes (LambderDeclaredRefuse).
  */
 export declare const refuse: (content: string, options?: LambderRefuseOptions) => never;
+/** refuse()'s options other than the refusal's identity. */
+type LambderRefuseFlagOptions = Omit<LambderRefuseOptions, "code" | "data">;
+/** What a raise site of a declared code still chooses: the code's declaration owns its status and its flags. */
+type LambderDeclaredCodeOptions = Omit<LambderRefuseFlagOptions, "statusCode" | "notAuthorized" | "sessionExpired">;
+/**
+ * refuse()'s options where the endpoint's declarations are known: `code` is
+ * one of TRefusals' codes, `data` is required when that code declares data
+ * and absent otherwise, and the status and flags are the code's
+ * declaration's, so they cannot be set here. TRefusals maps each code to
+ * `{ data: D }` or `{}`, D being what the handler hands over (the schema's
+ * input form on the server, the wire form in the mock). A discriminated
+ * union rather than a generic over the code, so a code widened to a union
+ * cannot loosen `data`. With TCodeRequired (declareRefusals's requireCodes)
+ * the uncoded arm is gone: every refusal names a code.
+ */
+export type LambderDeclaredRefuseOptions<TRefusals, TCodeRequired extends boolean = false> = (TCodeRequired extends true ? never : LambderRefuseFlagOptions & {
+    code?: undefined;
+    data?: undefined;
+}) | {
+    [TCode in keyof TRefusals & string]: LambderDeclaredCodeOptions & {
+        code: TCode;
+    } & (TRefusals[TCode] extends {
+        data: infer TData;
+    } ? {
+        data: TData;
+    } : {
+        data?: undefined;
+    });
+}[keyof TRefusals & string];
+/**
+ * The refuse an API handler's context carries, typed to the endpoint's
+ * declared codes (a guard's to the guard's, the init's to the whole
+ * vocabulary). It throws what refuse() throws. Where the app requires codes,
+ * the options are not optional: a refusal is a code.
+ *
+ * TypeScript narrows after a never-returning call only when every name in it
+ * carries an explicit annotation, which a handler's contextually typed `ctx`
+ * does not. Where the code after it relies on the refusal, write
+ * `return ctx.refuse(...)`; the free refuse() narrows on its own.
+ */
+export type LambderDeclaredRefuse<TRefusals, TCodeRequired extends boolean = false> = TCodeRequired extends true ? (content: string, options: LambderDeclaredRefuseOptions<TRefusals, true>) => never : (content: string, options?: LambderDeclaredRefuseOptions<TRefusals, false>) => never;
+export {};

package/dist/shared/wire/LambderApiRefusal.js

@@ -2,7 +2,7 @@
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
  * crashed". Throw it from anywhere in an API call's call stack (handlers,
  * hooks, guards or nested helpers) and the render pipeline maps it onto the
- * structured API envelope (its errorMessage, notAuthorized and
+ * structured API envelope (its refusal, notAuthorized and
  * sessionExpired) instead of routing it through setGlobalErrorHandler, so refusals never reach crash
  * logging and clients receive a parseable response.
  *
@@ -20,8 +20,8 @@ export class LambderApiRefusal extends Error {
      * across them while this marker does not. The pipeline checks the brand.
      */
     isLambderApiRefusal = true;
-    /** What the envelope's errorMessage carries: always a message object, a plain string given to the options made into one. */
-    errorMessage;
+    /** What the envelope's refusal carries: always a message object, a plain string given to the options made into one. */
+    refusal;
     notAuthorized;
     sessionExpired;
     statusCode;
@@ -29,7 +29,7 @@ export class LambderApiRefusal extends Error {
     constructor(message, options = {}) {
         super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
         this.name = "LambderApiRefusal";
-        this.errorMessage = refusalMessageOf(options.errorMessage ?? message);
+        this.refusal = refusalMessageOf(options.refusal ?? message);
         this.notAuthorized = options.notAuthorized;
         this.sessionExpired = options.sessionExpired;
         this.statusCode = options.statusCode;
@@ -40,7 +40,7 @@ export class LambderApiRefusal extends Error {
 export const isLambderApiRefusal = (err) => err instanceof Error && err.isLambderApiRefusal === true;
 const REFUSAL_MESSAGE_TYPES = ["warning", "error", "info"];
 /**
- * An errorMessage as the one shape a reader handles: a plain string becomes
+ * An refusal as the one shape a reader handles: a plain string becomes
  * an "error" message with that content, and a value that is not a message
  * at all becomes one describing it. The envelope writer applies it, so a
  * Lambder server only ever sends the object. A reader applies it too,
@@ -71,7 +71,7 @@ export const refusalMessageOf = (message) => {
  * than retyping the strings.
  */
 export const LAMBDER_REFUSAL_CODES = {
-    /** A rate-limit policy refused (429). A policy's own errorMessage inherits this unless it sets a code. */
+    /** A rate-limit policy refused (429). A policy's own message carries it. */
     rateLimited: "lambder/rate-limited",
     /** The original of an idempotent request is still processing (409). */
     duplicateInFlight: "lambder/duplicate-in-flight",
@@ -92,6 +92,9 @@ export const LAMBDER_REFUSAL_CODES = {
     /** An upload bucket would not sign a ticket for a file larger than the rule accepts. */
     uploadTooLarge: "lambder/upload-too-large",
 };
+const FRAMEWORK_REFUSAL_CODES = new Set(Object.values(LAMBDER_REFUSAL_CODES));
+/** Whether a code is one the framework stamps on its own refusals. */
+export const isLambderRefusalCode = (code) => typeof code === "string" && FRAMEWORK_REFUSAL_CODES.has(code);
 /**
  * Refuse the current API call: a routine business "no" (not found, invalid
  * input, not allowed) with a user-facing message. Throws a LambderApiRefusal
@@ -103,14 +106,19 @@ export const LAMBDER_REFUSAL_CODES = {
  * The const carries the annotation so TypeScript applies never-return
  * control-flow narrowing at call sites (`if (!row) refuse(...)` implies
  * `row` is defined afterwards).
+ *
+ * Its `code` and `data` are checked when the refusal is rendered, against the
+ * endpoint it answers. Inside an API handler, `ctx.refuse` takes the same
+ * arguments typed to that endpoint's declared codes (LambderDeclaredRefuse).
  */
 export const refuse = (content, options = {}) => {
     throw new LambderApiRefusal(content, {
-        errorMessage: {
+        refusal: {
             type: options.type ?? "warning",
             ...(options.code !== undefined ? { code: options.code } : {}),
             ...(options.title !== undefined ? { title: options.title } : {}),
             content,
+            ...(options.data !== undefined ? { data: options.data } : {}),
         },
         notAuthorized: options.notAuthorized,
         sessionExpired: options.sessionExpired,

package/dist/shared/wire/LambderCrashDetail.d.ts

@@ -6,7 +6,7 @@
  * one, a developer holding a debug cookie) can get the error's name, message,
  * stack, cause chain and where it happened, to store in its own error log
  * and find the right CloudWatch stream. The envelope carries it in `crash`
- * beside errorMessage; LambderInvokeCaller rebuilds an Error from it as the
+ * beside refusal; LambderInvokeCaller rebuilds an Error from it as the
  * `cause` of the error it throws, so a reporter that walks causes sees the
  * callee's stack unaided.
  *

package/dist/shared/wire/LambderCrashDetail.js

@@ -6,7 +6,7 @@
  * one, a developer holding a debug cookie) can get the error's name, message,
  * stack, cause chain and where it happened, to store in its own error log
  * and find the right CloudWatch stream. The envelope carries it in `crash`
- * beside errorMessage; LambderInvokeCaller rebuilds an Error from it as the
+ * beside refusal; LambderInvokeCaller rebuilds an Error from it as the
  * `cause` of the error it throws, so a reporter that walks causes sees the
  * callee's stack unaided.
  *

package/dist/shared/wire/LambderHttpStatus.d.ts

@@ -9,3 +9,9 @@
  * to typecheck a status union.
  */
 export type LambderHttpStatusCode = 100 | 101 | 200 | 201 | 202 | 203 | 204 | 206 | 300 | 301 | 302 | 303 | 304 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 408 | 409 | 410 | 412 | 413 | 415 | 416 | 418 | 422 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504;
+/**
+ * The status a refusal with a declared code may leave with: not a 5xx, which a
+ * reader files as a server failure, not 422, which is input validation's, and
+ * not a 1xx.
+ */
+export type LambderRefusalStatusCode = Exclude<LambderHttpStatusCode, 100 | 101 | 422 | 500 | 501 | 502 | 503 | 504>;

package/dist/shared/wire/LambderIdempotencyKeyScope.d.ts

@@ -7,7 +7,8 @@ export type LambderIdempotentAttemptOutcome = {
     ok: boolean;
     reason?: string;
     status?: number;
-    errorMessage?: {
+    /** The refusal's message, when the answer carried one: only its code is read. */
+    refusal?: {
         code?: string;
     };
 };
@@ -43,7 +44,7 @@ export declare const createIdempotencyKey: () => string;
  * - A success settles it, and so does a key refused as reused for another
  *   request, since that key can never carry this one.
  * - A refusal of this request (a rejected input, not authorized, an
- *   errorMessage) settles it, unless another attempt under the same key is
+ *   refusal) settles it, unless another attempt under the same key is
  *   still in flight or went unanswered. That attempt may run or have run the
  *   operation, and guards, validation and rate limits refuse before the
  *   replay record is claimed, so the refusal of a retry or a double-tap says

package/dist/shared/wire/LambderIdempotencyKeyScope.js

@@ -5,7 +5,7 @@ export const IDEMPOTENT_ATTEMPT_NOT_SENT = { ok: false, reason: "notSent" };
  * Refusals that answer this request itself, so the same request would get
  * the same answer again and what the person sends next is a new operation.
  */
-const REFUSAL_REASONS = new Set(["validation", "notAuthorized", "errorMessage"]);
+const REFUSAL_REASONS = new Set(["validation", "notAuthorized", "refusal"]);
 /** Answers that never reached the operation: the same request may pass later. */
 const UNTRIED_REASONS = new Set(["sessionExpired", "versionExpired", "payloadTooLarge", "notSent"]);
 /**
@@ -45,7 +45,7 @@ let beginAttemptOf;
  * - A success settles it, and so does a key refused as reused for another
  *   request, since that key can never carry this one.
  * - A refusal of this request (a rejected input, not authorized, an
- *   errorMessage) settles it, unless another attempt under the same key is
+ *   refusal) settles it, unless another attempt under the same key is
  *   still in flight or went unanswered. That attempt may run or have run the
  *   operation, and guards, validation and rate limits refuse before the
  *   replay record is claimed, so the refusal of a retry or a double-tap says
@@ -98,13 +98,13 @@ export class LambderIdempotencyKeyScope {
                 if (key !== this.#key)
                     return;
                 this.#inFlight -= 1;
-                const code = outcome.errorMessage?.code;
+                const code = outcome.refusal?.code;
                 if (outcome.ok || code === LAMBDER_REFUSAL_CODES.idempotencyKeyReused) {
                     this.rotate();
                     return;
                 }
-                // A rate limit refuses before the claim, whatever code a policy's
-                // own message carries, so its status is what names it.
+                // A rate limit refuses before the claim, and its status names it
+                // as surely as its code.
                 if (UNTRIED_REASONS.has(outcome.reason ?? "") || outcome.status === 429 || code === LAMBDER_REFUSAL_CODES.rateLimited)
                     return;
                 if (REFUSAL_REASONS.has(outcome.reason ?? "") && code !== LAMBDER_REFUSAL_CODES.duplicateInFlight) {

package/dist/shared/wire/LambderObjectPayload.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether a value is what an API answers with or a refusal carries as data:
+ * an array, or an object that goes through JSON as an object. A Date or a
+ * class with a toJSON of its own is written as whatever toJSON returns (a
+ * string, for a Date), so it does not count.
+ *
+ * The rule is what makes `caller.api()` truthy exactly on success: an
+ * answer is never null, false, 0 or "", so a falsy result can only mean the
+ * call failed. The server checks a handler's parsed output with it, and a
+ * reader checks what it received, so a body no Lambder handler wrote (a
+ * hand-built one, a proxy's) cannot pass for a success.
+ */
+export declare const isObjectPayload: (value: unknown) => value is object;
+/** What a value that is not an object payload is, for an error message: its kind, never the value itself. */
+export declare const describePayloadKind: (value: unknown) => string;

package/dist/shared/wire/LambderObjectPayload.js

@@ -0,0 +1,24 @@
+/**
+ * Whether a value is what an API answers with or a refusal carries as data:
+ * an array, or an object that goes through JSON as an object. A Date or a
+ * class with a toJSON of its own is written as whatever toJSON returns (a
+ * string, for a Date), so it does not count.
+ *
+ * The rule is what makes `caller.api()` truthy exactly on success: an
+ * answer is never null, false, 0 or "", so a falsy result can only mean the
+ * call failed. The server checks a handler's parsed output with it, and a
+ * reader checks what it received, so a body no Lambder handler wrote (a
+ * hand-built one, a proxy's) cannot pass for a success.
+ */
+export const isObjectPayload = (value) => Array.isArray(value)
+    || (value !== null && typeof value === "object" && typeof value.toJSON !== "function");
+/** What a value that is not an object payload is, for an error message: its kind, never the value itself. */
+export const describePayloadKind = (value) => {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "nothing";
+    if (typeof value === "object")
+        return "an object that JSON writes as something else (a Date, or a class with a toJSON of its own)";
+    return `a ${typeof value}`;
+};

package/dist/shared/wire/LambderOutcomeAssertions.d.ts

@@ -1,5 +1,5 @@
 /**
- * Two assertions over a call's outcome, for tests.
+ * Three assertions over a call's outcome, for tests.
  *
  * An outcome is a discriminated union, so a test that expects a refusal must
  * narrow before it can read what the refusal carries: check `ok`, branch on
@@ -10,7 +10,7 @@
  *
  * These narrow through an `asserts` signature, so the lines after one read
  * the arm it proved, and they throw a plain Error naming what the outcome
- * was. No test runner is imported: the same two functions serve vitest, jest
+ * was. No test runner is imported: the same functions serve vitest, jest
  * and node:test, from `lambder/testing` over a real server and from
  * `lambder/mock` over a mock one. Pure and dependency-free, like the outcome
  * vocabulary they read.
@@ -44,10 +44,34 @@ type LambderFailureWithReason<TOutcome, TReason> = TOutcome extends {
 } ? [TReason & TArmReason] extends [never] ? never : TOutcome & {
     reason: TReason & TArmReason;
 } : never;
+/** The refusal message a failure of this outcome union carries: the endpoint's, with its declared codes. */
+type LambderRefusalMessageOf<TOutcome> = TOutcome extends {
+    ok: false;
+    refusal?: infer TMessage;
+} ? TMessage : never;
+/** Every code a failure of this outcome union can be refused with: the endpoint's declared codes and the framework's. */
+type LambderRefusalCodeOf<TOutcome> = LambderRefusalMessageOf<TOutcome> extends infer TMessage ? TMessage extends {
+    code?: infer TCode;
+} ? Exclude<TCode, undefined> & string : never : never;
+/**
+ * The arm of a refusal message that carries code C: the declared code's own
+ * arm, with its data. A framework code has no arm of its own (it shares the
+ * uncoded one), and neither does any code of a message typed as any code, so
+ * those are the message with the code pinned.
+ */
+type LambderRefusalWithCode<TMessage, TCode> = [
+    Extract<TMessage, {
+        code: TCode;
+    }>
+] extends [never] ? TMessage & {
+    code: TCode;
+} : Extract<TMessage, {
+    code: TCode;
+}>;
 /** What else a failure is expected to carry, beside its reason. */
-export type LambderExpectedFailure = {
-    /** The refusal's machine-readable code (`errorMessage.code`), e.g. a LAMBDER_REFUSAL_CODES value or the app's own. */
-    code?: string;
+export type LambderExpectedFailure<TCode extends string = string> = {
+    /** The refusal's machine-readable code (`refusal.code`): one the endpoint declares, or a LAMBDER_REFUSAL_CODES value. */
+    code?: TCode;
     /** The HTTP status the answer came with. */
     status?: number;
 };
@@ -72,8 +96,29 @@ export declare function assertApiSuccess<TOutcome extends LambderOutcomeShape>(o
  *
  * ```typescript
  * assertApiFailure(await member.apiOutcome("org.delete", { id }), "notAuthorized");
- * assertApiFailure(await guest.apiOutcome("signup", form), "errorMessage", { code: LAMBDER_REFUSAL_CODES.rateLimited, status: 429 });
+ * assertApiFailure(await guest.apiOutcome("signup", form), "refusal", { code: LAMBDER_REFUSAL_CODES.rateLimited, status: 429 });
+ * ```
+ */
+export declare function assertApiFailure<TOutcome extends LambderOutcomeShape, TReason extends LambderFailureReasonOf<TOutcome> = LambderFailureReasonOf<TOutcome>>(outcome: TOutcome, reason?: TReason, expected?: LambderExpectedFailure<LambderRefusalCodeOf<TOutcome>>): asserts outcome is LambderFailureWithReason<TOutcome, TReason>;
+/**
+ * Asserts that a call was refused with the given code, whichever reason it
+ * arrived under (a refusal flagged notAuthorized carries its code too), and
+ * narrows the outcome's refusal to that code's message, so its `data`
+ * reads with the type the code declares.
+ *
+ * ```typescript
+ * const outcome = await visitor.apiOutcome("order.pay", { orderId });
+ * assertApiRefusal(outcome, "wallet-short");
+ * expect(outcome.refusal.data.available).toBe(1250);
  * ```
+ *
+ * The code is checked against the outcome's own codes, so one the endpoint
+ * does not declare is a compile error rather than an assertion that can
+ * never pass.
  */
-export declare function assertApiFailure<TOutcome extends LambderOutcomeShape, TReason extends LambderFailureReasonOf<TOutcome> = LambderFailureReasonOf<TOutcome>>(outcome: TOutcome, reason?: TReason, expected?: LambderExpectedFailure): asserts outcome is LambderFailureWithReason<TOutcome, TReason>;
+export declare function assertApiRefusal<TOutcome extends LambderOutcomeShape, const TCode extends LambderRefusalCodeOf<TOutcome>>(outcome: TOutcome, code: TCode): asserts outcome is Extract<TOutcome, {
+    ok: false;
+}> & {
+    refusal: LambderRefusalWithCode<LambderRefusalMessageOf<TOutcome>, TCode>;
+};
 export {};

package/dist/shared/wire/LambderOutcomeAssertions.js

@@ -1,5 +1,5 @@
 /**
- * Two assertions over a call's outcome, for tests.
+ * Three assertions over a call's outcome, for tests.
  *
  * An outcome is a discriminated union, so a test that expects a refusal must
  * narrow before it can read what the refusal carries: check `ok`, branch on
@@ -10,7 +10,7 @@
  *
  * These narrow through an `asserts` signature, so the lines after one read
  * the arm it proved, and they throw a plain Error naming what the outcome
- * was. No test runner is imported: the same two functions serve vitest, jest
+ * was. No test runner is imported: the same functions serve vitest, jest
  * and node:test, from `lambder/testing` over a real server and from
  * `lambder/mock` over a mock one. Pure and dependency-free, like the outcome
  * vocabulary they read.
@@ -49,8 +49,8 @@ const describeOutcome = (outcome) => {
     const details = [];
     if (failure.status !== undefined)
         details.push(`status ${failure.status}`);
-    if (failure.errorMessage !== undefined)
-        details.push(`errorMessage ${describeValue(failure.errorMessage)}`);
+    if (failure.refusal !== undefined)
+        details.push(`refusal ${describeValue(failure.refusal)}`);
     if (failure.zodError !== undefined)
         details.push(`zodError ${describeValue(failure.zodError.message)}`);
     // The error's own message, and its cause when it has one: an in-process
@@ -84,7 +84,7 @@ export function assertApiSuccess(outcome) {
  *
  * ```typescript
  * assertApiFailure(await member.apiOutcome("org.delete", { id }), "notAuthorized");
- * assertApiFailure(await guest.apiOutcome("signup", form), "errorMessage", { code: LAMBDER_REFUSAL_CODES.rateLimited, status: 429 });
+ * assertApiFailure(await guest.apiOutcome("signup", form), "refusal", { code: LAMBDER_REFUSAL_CODES.rateLimited, status: 429 });
  * ```
  */
 export function assertApiFailure(outcome, reason, expected = {}) {
@@ -101,12 +101,38 @@ export function assertApiFailure(outcome, reason, expected = {}) {
     if (reason !== undefined && outcome.reason !== reason)
         return refuse();
     if (expected.code !== undefined) {
-        // Only the structured errorMessage carries a code; a plain string has none to match.
-        const errorMessage = outcome.errorMessage;
-        const code = errorMessage && typeof errorMessage === "object" ? errorMessage.code : undefined;
+        // Only the structured refusal carries a code; a plain string has none to match.
+        const refusal = outcome.refusal;
+        const code = refusal && typeof refusal === "object" ? refusal.code : undefined;
         if (code !== expected.code)
             return refuse();
     }
     if (expected.status !== undefined && outcome.status !== expected.status)
         return refuse();
 }
+/**
+ * Asserts that a call was refused with the given code, whichever reason it
+ * arrived under (a refusal flagged notAuthorized carries its code too), and
+ * narrows the outcome's refusal to that code's message, so its `data`
+ * reads with the type the code declares.
+ *
+ * ```typescript
+ * const outcome = await visitor.apiOutcome("order.pay", { orderId });
+ * assertApiRefusal(outcome, "wallet-short");
+ * expect(outcome.refusal.data.available).toBe(1250);
+ * ```
+ *
+ * The code is checked against the outcome's own codes, so one the endpoint
+ * does not declare is a compile error rather than an assertion that can
+ * never pass.
+ */
+// `const`: the constraint depends on TOutcome, and without it the code
+// argument widens to that whole constraint instead of staying the literal
+// passed, which would narrow to every declared code at once.
+export function assertApiRefusal(outcome, code) {
+    const refusal = outcome.ok ? undefined : outcome.refusal;
+    const received = refusal && typeof refusal === "object" ? refusal.code : undefined;
+    if (received !== code) {
+        throw new Error(`Expected the call to be refused with code "${code}", but it was ${describeOutcome(outcome)}.`, { cause: errorOf(outcome) });
+    }
+}

package/dist/testing/LambderTestApp.d.ts

@@ -51,7 +51,7 @@ export type LambderTestAppOptions = {
  * (`lambderTestApp<SessionData, ApiContractType>(lambder)`), so the tests type
  * their calls against plain members rather than the chained intersection.
  */
-export type LambderTestedInstance<TSessionData, TContract> = Lambder<TSessionData, any, any, any, any, any, any, any> & {
+export type LambderTestedInstance<TSessionData, TContract> = Lambder<TSessionData, any, any, any, any, any, any, any, any, any> & {
     readonly ApiContract: TContract;
 };
 /**

package/dist/testing.d.ts

@@ -17,7 +17,7 @@
 export { lambderTestApp } from "./testing/LambderTestApp.js";
 export type { LambderTestApp, LambderTestAppOptions, LambderTestedInstance } from "./testing/LambderTestApp.js";
 export type { LambderTestVisitor, LambderTestVisitorOptions, LambderTestRequestInit } from "./testing/LambderTestVisitor.js";
-export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+export { assertApiSuccess, assertApiFailure, assertApiRefusal } from "./shared/wire/LambderOutcomeAssertions.js";
 export type { LambderExpectedFailure } from "./shared/wire/LambderOutcomeAssertions.js";
 export { lambderSessionStoreConformance } from "./testing/lambderSessionStoreConformance.js";
 export type { LambderSessionStoreConformanceOptions } from "./testing/lambderSessionStoreConformance.js";

package/dist/testing.js

@@ -15,7 +15,7 @@
  * writes itself.
  */
 export { lambderTestApp } from "./testing/LambderTestApp.js";
-export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+export { assertApiSuccess, assertApiFailure, assertApiRefusal } from "./shared/wire/LambderOutcomeAssertions.js";
 // The rules each store interface promises, as cases an app registers with its
 // own runner's `it` and `expect` to hold a store it writes over its own
 // database to the same rules Lambder's memory and DynamoDB stores meet.