lambder 7.2.4 → 7.3.1

package/dist/invoke/LambderLambdaEvent.js

@@ -31,18 +31,7 @@ const randomRequestId = () => {
         return webCrypto.randomUUID();
     return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
 };
-/**
- * The payload-format-2.0 event API Gateway would deliver for this request.
- * `invoke: true` adds the invoke marker headers a server-to-server call
- * carries; a browser-shaped request (the handler transport) leaves them off.
- *
- * The client address is `clientIp` and reaches the callee as
- * requestContext.http.sourceIp only. Writing it as x-forwarded-for as well
- * would put the same fact on a channel a callee may be configured to trust
- * (trustedClientIpHeaders), and the header is the one the caller's own
- * `headers` could otherwise have set.
- */
-export const synthesizeLambdaHttpEvent = (request, options) => {
+export function synthesizeLambdaHttpEvent(request, options) {
     // The caller's own headers go on first, so the ones this function owns
     // cannot be displaced by them. Forwarding an incoming browser request's
     // headers into `headers` is an ordinary gateway-lambda pattern, and with
@@ -72,7 +61,45 @@ export const synthesizeLambdaHttpEvent = (request, options) => {
     if (request.body !== undefined && !headers["content-type"]) {
         headers["content-type"] = isBinary ? "application/octet-stream" : "application/json";
     }
+    const body = request.body === undefined ? undefined : isBinary ? bytesToBase64(request.body) : request.body;
     const now = Date.now();
+    if (options.eventFormat === "v1") {
+        // A REST API has no cookies array: cookies ride in the Cookie header,
+        // and every header is delivered twice, once as its last value and
+        // once as the list of all of them.
+        if (request.cookies?.length)
+            headers.cookie = request.cookies.join("; ");
+        const query = request.query && Object.keys(request.query).length ? request.query : null;
+        return {
+            resource: "/{proxy+}",
+            path: request.path,
+            httpMethod: request.method,
+            headers,
+            multiValueHeaders: Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, [value]])),
+            queryStringParameters: query,
+            multiValueQueryStringParameters: query ? Object.fromEntries(Object.entries(query).map(([name, value]) => [name, [value]])) : null,
+            pathParameters: null,
+            stageVariables: null,
+            // The fields a handler might read, filled plausibly; the rest of
+            // a REST API's request context (authorizer, the API key, the
+            // Cognito identity) describes a deployment this event has none of.
+            requestContext: {
+                accountId: "",
+                apiId: "lambder-local",
+                domainName: request.host,
+                httpMethod: request.method,
+                identity: { sourceIp: request.clientIp ?? "", userAgent: "lambder-local" },
+                path: request.path,
+                protocol: "HTTP/1.1",
+                requestId: randomRequestId(),
+                requestTimeEpoch: now,
+                resourcePath: "/{proxy+}",
+                stage: "local",
+            },
+            body: body ?? null,
+            isBase64Encoded: isBinary,
+        };
+    }
     return {
         version: "2.0",
         routeKey: "$default",
@@ -98,12 +125,10 @@ export const synthesizeLambdaHttpEvent = (request, options) => {
             time: new Date(now).toISOString(),
             timeEpoch: now,
         },
-        ...(request.body !== undefined
-            ? { body: isBinary ? bytesToBase64(request.body) : request.body }
-            : {}),
+        ...(body !== undefined ? { body } : {}),
         isBase64Encoded: isBinary,
     };
-};
+}
 /**
  * The body envelope LambderCaller sends, minus the fields only a browser has
  * a value for, as JSON. A plain payload arrives already serialized (the

package/dist/invoke/lambderHandlerTransport.d.ts

@@ -1,6 +1,7 @@
 import type { Context } from "aws-lambda";
 import type { LambderApiTransport } from "../shared/transport/LambderApiTransport.js";
 import type { LambderHandler } from "../core/LambderCreateOptions.js";
+import type { LambderHttpEventFormat } from "../core/LambderContext.js";
 export type LambderHandlerTransportOptions = {
     /** The Host the handler sees (ctx.host), and the siteHost the envelope carries when the caller has none. Default: the apiPath's own host when it is absolute, otherwise "localhost". */
     host?: string;
@@ -10,6 +11,8 @@ export type LambderHandlerTransportOptions = {
     maxResponseBytes?: number;
     /** Fields of the Lambda context the handler receives. */
     context?: Partial<Context>;
+    /** The gateway shape the handler is called with: "v2" (an HTTP API, a Function URL) or "v1" (a REST API). Default: "v2". A handler answers both alike; name the one your deployment delivers when the difference is what you are testing. */
+    eventFormat?: LambderHttpEventFormat;
 };
 /**
  * A transport that calls a Lambder handler in this process, the way a

package/dist/invoke/lambderHandlerTransport.js

@@ -50,7 +50,7 @@ export const lambderHandlerTransport = (handler, options = {}) => {
             clientIp: request.clientIp ?? clientIp,
             cookies: request.cookies,
             body: JSON.stringify(buildTransportEnvelope({ ...request, siteHost: request.siteHost || host })),
-        }, { invoke: false });
+        }, { invoke: false, eventFormat: options.eventFormat });
         let result;
         try {
             result = await stopWaitingWhenAborted(handler(event, localLambdaContext("lambder-local", options.context)), request.signal);

package/dist/mock.d.ts

@@ -26,6 +26,8 @@ export { LambderWebCrypto, LambderPlainSessionCrypto } from "./session/LambderSe
 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 { LambderExpectedFailure } from "./shared/wire/LambderOutcomeAssertions.js";
 export type { LambderApiRequest } from "./api/LambderApiRequest.js";
 export type { LambderApiAnswer } from "./api/LambderApiAnswer.js";
 export type { LambderSessionRecord } from "./shared/contracts/LambderSessionStore.js";

package/dist/mock.js

@@ -25,3 +25,6 @@ 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";

package/dist/session/LambderSessionManager.d.ts

@@ -1,5 +1,6 @@
 import type { LambderSessionCrypto } from "./LambderSessionCrypto.js";
 import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 /**
  * A freshly created (or regenerated) session: the persisted record plus the
  * RAW cookie secrets, which exist only here and in the cookies the caller
@@ -92,13 +93,23 @@ export declare const isMintedSessionToken: (token: string) => boolean;
  * stored too.
  */
 export default class LambderSessionManager<SessionData = any> {
-    private readonly store;
+    /** Replaceable through the backend swap alone; see LAMBDER_BACKEND_SWAP. */
+    private store;
     private readonly sessionSalt;
     private readonly enableSlidingExpiration;
     private readonly slidingWriteIntervalSeconds;
     private readonly dataRefresh;
     private readonly crypto;
     constructor({ store, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, crypto, }: LambderSessionManagerOptions<SessionData>);
+    /** A store this manager's crypto may sit in front of. Asked of every store it is given, the one at creation and a swapped one alike. */
+    private assertCryptoFitsStore;
+    /**
+     * Puts the manager over another store, for `lambder/testing`. The model
+     * (salt, tokens, expiry, dataRefresh) stays this manager's own, so a test
+     * runs the app's sessions as configured over a store that dies with the
+     * process. Sessions held by the store it leaves are simply out of reach.
+     */
+    [LAMBDER_BACKEND_SWAP](store: LambderSessionStore<SessionData>): void;
     /**
      * The salted partition hash of a sessionKey: sha256 of the key followed
      * by the salt, with NO separator between them.

package/dist/session/LambderSessionManager.js

@@ -1,6 +1,7 @@
 import { LambderWebCrypto } from "./LambderSessionCrypto.js";
 import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 /**
  * Wraps errors thrown by the dataRefresh callback so they stay
  * distinguishable from "no session": fetchSessionIfExists() swallows missing
@@ -79,6 +80,7 @@ export const isMintedSessionToken = (token) => {
  * stored too.
  */
 export default class LambderSessionManager {
+    /** Replaceable through the backend swap alone; see LAMBDER_BACKEND_SWAP. */
     store;
     sessionSalt;
     enableSlidingExpiration;
@@ -96,14 +98,28 @@ export default class LambderSessionManager {
             assertPositiveInteger(dataRefresh.ttlSeconds, "session.dataRefresh.ttlSeconds");
         this.dataRefresh = dataRefresh ?? null;
         this.crypto = crypto ?? new LambderWebCrypto();
+        this.assertCryptoFitsStore(store);
+        if (typeof sessionSalt !== "string" || sessionSalt.length === 0) {
+            throw new Error("Lambder: session sessionSalt is empty. It salts the hash that partitions the store, so it has to be a real, stable secret.");
+        }
+    }
+    /** A store this manager's crypto may sit in front of. Asked of every store it is given, the one at creation and a swapped one alike. */
+    assertCryptoFitsStore(store) {
         if (!this.crypto.isCryptographic && !store.isMemoryOnly) {
             throw new Error("Lambder: this session crypto does not hash and does not draw cryptographically random bytes, " +
                 "so it may only sit in front of a store that dies with the process. Over a persistent store every " +
                 "record would be a usable credential and the sessionSalt would be readable from it.");
         }
-        if (typeof sessionSalt !== "string" || sessionSalt.length === 0) {
-            throw new Error("Lambder: session sessionSalt is empty. It salts the hash that partitions the store, so it has to be a real, stable secret.");
-        }
+    }
+    /**
+     * Puts the manager over another store, for `lambder/testing`. The model
+     * (salt, tokens, expiry, dataRefresh) stays this manager's own, so a test
+     * runs the app's sessions as configured over a store that dies with the
+     * process. Sessions held by the store it leaves are simply out of reach.
+     */
+    [LAMBDER_BACKEND_SWAP](store) {
+        this.assertCryptoFitsStore(store);
+        this.store = store;
     }
     /**
      * The salted partition hash of a sessionKey: sha256 of the key followed

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

@@ -0,0 +1,29 @@
+/**
+ * The keys of the two doors `lambder/testing` opens on a built instance.
+ *
+ * Symbols rather than named methods, and exported by no entry point: the
+ * package's exports map is what a consumer can import, so only
+ * `lambder/testing` can name a key, and nothing on the typed surface of an
+ * instance offers either door to a serving app.
+ */
+/**
+ * Puts other stores under the instance.
+ *
+ * An app is one module-level instance whose handlers and guards close over it
+ * (`app.getSessionController(ctx)`), so a test cannot be handed a copy over
+ * other stores: the copy's closures would still reach the original and the
+ * production table under it. The stores are therefore replaced in place, and
+ * every class that holds one answers to this key with a method that takes the
+ * replacement.
+ */
+export declare const LAMBDER_BACKEND_SWAP: unique symbol;
+/**
+ * Watches what the instance throws while answering a request.
+ *
+ * A crash is answered by the app's global error handler, or by the framework's
+ * own 500, and either way the answer deliberately says nothing about what was
+ * thrown: that is right for a client and useless to a test, whose author needs
+ * the error and its stack. The watcher is handed the error and changes nothing
+ * about the answer, so what an app does with a crash stays testable.
+ */
+export declare const LAMBDER_CRASH_WATCH: unique symbol;

package/dist/shared/util/LambderTestingDoors.js

@@ -0,0 +1,29 @@
+/**
+ * The keys of the two doors `lambder/testing` opens on a built instance.
+ *
+ * Symbols rather than named methods, and exported by no entry point: the
+ * package's exports map is what a consumer can import, so only
+ * `lambder/testing` can name a key, and nothing on the typed surface of an
+ * instance offers either door to a serving app.
+ */
+/**
+ * Puts other stores under the instance.
+ *
+ * An app is one module-level instance whose handlers and guards close over it
+ * (`app.getSessionController(ctx)`), so a test cannot be handed a copy over
+ * other stores: the copy's closures would still reach the original and the
+ * production table under it. The stores are therefore replaced in place, and
+ * every class that holds one answers to this key with a method that takes the
+ * replacement.
+ */
+export const LAMBDER_BACKEND_SWAP = Symbol("lambder.backendSwap");
+/**
+ * Watches what the instance throws while answering a request.
+ *
+ * A crash is answered by the app's global error handler, or by the framework's
+ * own 500, and either way the answer deliberately says nothing about what was
+ * thrown: that is right for a client and useless to a test, whose author needs
+ * the error and its stack. The watcher is handed the error and changes nothing
+ * about the answer, so what an app does with a crash stays testable.
+ */
+export const LAMBDER_CRASH_WATCH = Symbol("lambder.crashWatch");

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

@@ -85,6 +85,56 @@ export type LambderContractEntry<In, Out, Mode extends LambderApiMode, GuardInpu
 export type LambderMergeContract<Old, Name extends string, Entry> = Old & {
     [K in Name]: Entry;
 };
+/**
+ * The contract as one object type, for the `export interface` a consuming
+ * app declares its contract through:
+ *
+ * ```ts
+ * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
+ * ```
+ *
+ * Chaining leaves the contract an intersection one member deep per endpoint
+ * (LambderMergeContract above), and every `C[K]` written against a type
+ * parameter then resolves the property across all of them. That lookup is
+ * the atom the reading helpers below are built from, so its cost is paid
+ * again by each of them, per endpoint, in every app that registers a mock,
+ * declares a needs map, or otherwise reads the contract generically: in a
+ * 182-endpoint app one indexed access measured ~3,000 type instantiations
+ * and one mock registration ~18,000.
+ *
+ * Extending an interface is what collapses it. An interface's members are
+ * declared, so they are resolved once for the whole declaration rather than
+ * per lookup, and the same access measured ~6 instantiations after the
+ * change: a 182-endpoint app's frontend type check went from 27.8M
+ * instantiations to 7.0M and from 20.2s to 10.6s of check time. The alias
+ * form (`type C = LambderFlattenContract<...>`) does NOT do this: a mapped
+ * type stays deferred and each lookup pays the full cost again, so the
+ * `interface ... extends` spelling is the point.
+ *
+ * Diagnostics are the same ones, and they read better: a message naming the
+ * contract prints the interface by name, where the intersection is printed
+ * as a truncated spill of entries.
+ *
+ * Every endpoint name must be a string literal for an interface to extend
+ * the result, which registration through addApi/addSessionApi guarantees.
+ *
+ * Two things quietly undo it, both of which look like tidying:
+ *
+ * - `@typescript-eslint/no-empty-object-type` reports the empty body as
+ *   "equivalent to its supertype" and its fix is a type alias, which is the
+ *   one spelling that does not collapse anything. Disable the rule on the
+ *   line rather than taking the fix.
+ * - Extending anything but a mapped type loses the inferable index signature.
+ *   An interface has none of its own, so a hand-written `interface C { ... }`
+ *   is not assignable to LambderApiContractShape and is rejected by
+ *   initLambderMock<C>, LambderCaller<C> and LambderInvokeCaller<C>;
+ *   extending this mapped type is what keeps it. api-contract.test.ts pins
+ *   that, along with the flattened contract being the same type member for
+ *   member.
+ */
+export type LambderFlattenContract<C> = {
+    [K in keyof C]: C[K];
+};
 /** Guard names referenced by a guards option, whichever of its three forms is used. */
 export type LambderGuardNamesIn<TOpt> = TOpt extends string ? TOpt : TOpt extends readonly (infer N extends string)[] ? N : TOpt extends object ? keyof TOpt & string : never;
 /** The endpoint's mode; a contract written without one admits either. */

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

@@ -0,0 +1,80 @@
+/**
+ * Two assertions over a call's outcome, for tests.
+ *
+ * An outcome is a discriminated union, so a test that expects a refusal has
+ * to narrow before it can read what the refusal carries, and the narrowing is
+ * the same three lines every time: check `ok`, branch on it, check `reason`.
+ * Written by hand, the failing case prints "expected false to be true" and
+ * says nothing about what actually came back, which is the one thing worth
+ * knowing when a call that should have been refused went through, or crashed
+ * instead.
+ *
+ * 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
+ * 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.
+ *
+ * Typed structurally over `ok` and `reason` rather than over
+ * LambderApiOutcome, so a LambderInvokeOutcome, whose failure side names
+ * other reasons, is narrowed by the same functions and a misspelled reason is
+ * a compile error against whichever union was passed.
+ */
+/** What both callers' outcomes have in common: the discriminant, and a reason on the failure side. */
+type LambderOutcomeShape = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Every reason the failure side of an outcome union can carry. */
+type LambderFailureReasonOf<TOutcome> = TOutcome extends {
+    ok: false;
+    reason: infer TReason;
+} ? TReason : never;
+/**
+ * The failure arms that can carry one of the given reasons, each narrowed to
+ * it. Per arm rather than through Extract: one arm may carry several reasons
+ * (`network`, `timeout`, `server` and `unknown` share theirs), and Extract
+ * would drop that arm for any single one of them.
+ */
+type LambderFailureWithReason<TOutcome, TReason> = TOutcome extends {
+    ok: false;
+    reason: infer TArmReason;
+} ? [TReason & TArmReason] extends [never] ? never : TOutcome & {
+    reason: TReason & TArmReason;
+} : never;
+/** 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;
+    /** The HTTP status the answer came with. */
+    status?: number;
+};
+/**
+ * Asserts that a call succeeded, and narrows the outcome to its success arm,
+ * so `outcome.payload` reads directly on the next line.
+ *
+ * ```typescript
+ * const outcome = await visitor.apiOutcome("order.create", { sku });
+ * assertApiSuccess(outcome);
+ * expect(outcome.payload?.orderId).toBeDefined();
+ * ```
+ */
+export declare function assertApiSuccess<TOutcome extends LambderOutcomeShape>(outcome: TOutcome): asserts outcome is Extract<TOutcome, {
+    ok: true;
+}>;
+/**
+ * Asserts that a call failed, with the given reason when one is named, and
+ * narrows the outcome to the arms that reason can be, so what it carries
+ * (`zodError` after "validation", `response` after an envelope reason,
+ * `error` after the rest) reads directly on the next line.
+ *
+ * ```typescript
+ * assertApiFailure(await member.apiOutcome("org.delete", { id }), "notAuthorized");
+ * assertApiFailure(await guest.apiOutcome("signup", form), "errorMessage", { 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): asserts outcome is LambderFailureWithReason<TOutcome, TReason>;
+export {};

package/dist/shared/wire/LambderOutcomeAssertions.js

@@ -0,0 +1,113 @@
+/**
+ * Two assertions over a call's outcome, for tests.
+ *
+ * An outcome is a discriminated union, so a test that expects a refusal has
+ * to narrow before it can read what the refusal carries, and the narrowing is
+ * the same three lines every time: check `ok`, branch on it, check `reason`.
+ * Written by hand, the failing case prints "expected false to be true" and
+ * says nothing about what actually came back, which is the one thing worth
+ * knowing when a call that should have been refused went through, or crashed
+ * instead.
+ *
+ * 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
+ * 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.
+ *
+ * Typed structurally over `ok` and `reason` rather than over
+ * LambderApiOutcome, so a LambderInvokeOutcome, whose failure side names
+ * other reasons, is narrowed by the same functions and a misspelled reason is
+ * a compile error against whichever union was passed.
+ */
+const MAX_DESCRIBED_VALUE_LENGTH = 300;
+/** A value as it can be printed in an assertion message: JSON, cut short, never throwing over a cyclic one. */
+const describeValue = (value) => {
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return text.length > MAX_DESCRIBED_VALUE_LENGTH ? `${text.slice(0, MAX_DESCRIBED_VALUE_LENGTH)}...` : text;
+};
+/**
+ * The error a failure carries, which becomes the cause of the assertion's
+ * own: a test runner prints the chain, so an app that crashed under
+ * `lambder/testing` shows the handler's stack under the failed assertion.
+ */
+const errorOf = (outcome) => {
+    const error = outcome.error;
+    return error instanceof Error ? error : undefined;
+};
+/** One line saying what an outcome was, for the message of an assertion it failed. */
+const describeOutcome = (outcome) => {
+    if (outcome.ok)
+        return `a success carrying ${describeValue(outcome.payload)}`;
+    const failure = outcome;
+    const details = [];
+    if (failure.status !== undefined)
+        details.push(`status ${failure.status}`);
+    if (failure.errorMessage !== undefined)
+        details.push(`errorMessage ${describeValue(failure.errorMessage)}`);
+    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
+    // transport reports a handler that threw as a failure whose cause is
+    // what actually threw, and that is the line a test author needs.
+    if (failure.error instanceof Error) {
+        const cause = failure.error.cause instanceof Error ? ` (cause: ${failure.error.cause.message})` : "";
+        details.push(`error "${failure.error.message}"${cause}`);
+    }
+    return `a failure with reason "${failure.reason}"${details.length ? `, ${details.join(", ")}` : ""}`;
+};
+/**
+ * Asserts that a call succeeded, and narrows the outcome to its success arm,
+ * so `outcome.payload` reads directly on the next line.
+ *
+ * ```typescript
+ * const outcome = await visitor.apiOutcome("order.create", { sku });
+ * assertApiSuccess(outcome);
+ * expect(outcome.payload?.orderId).toBeDefined();
+ * ```
+ */
+export function assertApiSuccess(outcome) {
+    if (!outcome.ok)
+        throw new Error(`Expected the call to succeed, but it was ${describeOutcome(outcome)}.`, { cause: errorOf(outcome) });
+}
+/**
+ * Asserts that a call failed, with the given reason when one is named, and
+ * narrows the outcome to the arms that reason can be, so what it carries
+ * (`zodError` after "validation", `response` after an envelope reason,
+ * `error` after the rest) reads directly on the next line.
+ *
+ * ```typescript
+ * assertApiFailure(await member.apiOutcome("org.delete", { id }), "notAuthorized");
+ * assertApiFailure(await guest.apiOutcome("signup", form), "errorMessage", { code: LAMBDER_REFUSAL_CODES.rateLimited, status: 429 });
+ * ```
+ */
+export function assertApiFailure(outcome, reason, expected = {}) {
+    const wanted = [
+        reason !== undefined ? `reason "${String(reason)}"` : null,
+        expected.code !== undefined ? `code "${expected.code}"` : null,
+        expected.status !== undefined ? `status ${expected.status}` : null,
+    ].filter((part) => part !== null).join(", ");
+    const refuse = () => {
+        throw new Error(`Expected the call to fail${wanted ? ` with ${wanted}` : ""}, but it was ${describeOutcome(outcome)}.`, { cause: errorOf(outcome) });
+    };
+    if (outcome.ok)
+        return refuse();
+    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;
+        if (code !== expected.code)
+            return refuse();
+    }
+    if (expected.status !== undefined && outcome.status !== expected.status)
+        return refuse();
+}