lambder 9.0.3 → 10.0.1

package/dist/api/LambderApiRefusals.d.ts

@@ -0,0 +1,204 @@
+import type { z } from "zod";
+import type { LambderJsonOf } from "../shared/wire/LambderApiContract.js";
+import type { LambderRefusalStatusCode } from "../shared/wire/LambderHttpStatus.js";
+import type { LambderNoExtraKeys } from "../shared/util/LambderTypeUtilities.js";
+import { LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+/**
+ * One code of an app's refusal vocabulary: the schema of the data it carries,
+ * when it carries data, and how every refusal with the code leaves the
+ * server. A code's data is an object or an array, as an API's output is. The
+ * status and the flag are declared once here rather than at each raise site,
+ * so a code always reaches a caller the same way.
+ */
+export type LambderRefusalDeclaration = {
+    /** The schema of the code's data, when it carries data. */
+    data?: z.ZodType;
+    /** The HTTP status every refusal with this code leaves with. Default 200: the envelope is the channel. */
+    status?: LambderRefusalStatusCode;
+    /** Whether every refusal with this code sets the envelope's notAuthorized flag, which a caller routes to its notAuthorizedHandler. */
+    notAuthorized?: true;
+};
+/**
+ * One code as its endpoint may send it: the status and flag its declaration
+ * gives it, and whether it carries data, with the data's schema when it does.
+ * The server and the mock both resolve it from the vocabulary
+ * (allowedRefusalOf), so a refusal's data is parsed the same way on both.
+ */
+export type LambderApiAllowedRefusal = {
+    /** The status every refusal with the code leaves with; 200 when absent. */
+    status?: LambderRefusalStatusCode;
+    /** Present when every refusal with the code sets the envelope's notAuthorized flag. */
+    notAuthorized?: true;
+} & ({
+    data: false;
+} | {
+    data: true;
+    schema: z.ZodType;
+});
+/** The codes one endpoint may refuse with: its own `refusals` option and those of the guards it declares. */
+export type LambderApiAllowedRefusals = ReadonlyMap<string, LambderApiAllowedRefusal>;
+/** The app's refusal vocabulary, as `initLambder().declareRefusals()` and the mock's take it: every code once, with its declaration. */
+export type LambderRefusalVocabulary = Record<string, LambderRefusalDeclaration>;
+/**
+ * What declareRefusals() hands the rest of an init, the server's and the
+ * mock's alike: the vocabulary as declared, checked and keyed, and whether
+ * every refusal an API answers with has to name a code.
+ */
+export type LambderDeclaredVocabulary<TRefusals extends LambderRefusalVocabulary, TCodesRequired extends boolean> = {
+    refusals: TRefusals;
+    vocabulary: ReadonlyMap<string, LambderRefusalDeclaration>;
+    requireCodes: TCodesRequired;
+};
+/** A refusal's data is an object or an array, as an API's output is: the same rule, where the code is declared. */
+type LambderRefusalDataCheck<TDeclaration> = TDeclaration extends {
+    data: infer TSchema extends z.ZodType;
+} ? 0 extends 1 & z.output<TSchema> ? unknown : undefined extends z.output<TSchema> ? LambderRefusalDataRefusal : [LambderJsonOf<z.output<TSchema>>] extends [never] ? LambderRefusalDataRefusal : [LambderJsonOf<z.output<TSchema>>] extends [object] ? unknown : LambderRefusalDataRefusal : unknown;
+type LambderRefusalDataRefusal = {
+    data: {
+        readonly "lambder: a refusal's data is an object or an array, as an API's output is.": never;
+    };
+};
+/**
+ * The vocabulary as declareRefusals() checks it, code by code: no `lambder/`
+ * prefix, no key beside data, status and notAuthorized (a `dat:` would leave
+ * a code that carries data declared as one that does not), and data that is
+ * an object or an array.
+ */
+export type LambderRefusalVocabularyChecks<TVocabulary> = {
+    [TCode in keyof TVocabulary]: TCode extends `lambder/${string}` ? {
+        readonly "lambder: a refusal code may not start with lambder/, the prefix of the framework's own codes": never;
+    } : LambderNoExtraKeys<TVocabulary[TCode], LambderRefusalDeclaration> & LambderRefusalDataCheck<TVocabulary[TCode]>;
+};
+/** One code's declaration as checkedRefusal reads it: how a refusal with the code leaves, and its schema. */
+export declare const allowedRefusalOf: (declaration: LambderRefusalDeclaration) => LambderApiAllowedRefusal;
+/**
+ * What one endpoint's refusals are checked against: the codes it may refuse
+ * with, and whether every refusal it answers with has to name one
+ * (declareRefusals's `requireCodes`). Undefined on a definition whose codes
+ * are not known (a mock without the generated tables), which checks nothing.
+ */
+export type LambderEndpointRefusals = {
+    codes: LambderApiAllowedRefusals;
+    codeRequired: boolean;
+};
+/** How a refusal broke its endpoint's declaration. */
+type LambderRefusalViolation = {
+    uncoded: true;
+} | {
+    undeclared: string;
+} | {
+    dataWithoutDeclaredCode: string | undefined;
+} | {
+    missingData: string;
+} | {
+    ownStatusOrFlag: true;
+} | {
+    zodError: z.ZodError;
+} | {
+    thrown: unknown;
+} | {
+    notObject: string;
+};
+/**
+ * A refusal an endpoint is not allowed to send, so it was not sent and the
+ * call is answered as a crash: no code where the app requires one, a code
+ * the endpoint does not declare (neither
+ * in its own `refusals` option nor through a guard), data on a refusal whose
+ * code declares none, no data on one whose code carries data, data its code's
+ * schema rejects or that is not an object or an array, or a declared code
+ * raised with a status or flag of its own, which its declaration owns.
+ *
+ * What makes a client's refusal type exact: a reader narrows `code` to the
+ * endpoint's declared codes and the framework's own, and relies on this to
+ * never see another. The refusal side's counterpart of
+ * LambderApiOutputValidationError. The refusal as thrown is the cause, so
+ * the stack points at the line that raised it.
+ */
+export declare class LambderApiRefusalValidationError extends Error {
+    readonly apiName: string;
+    /** The code the refusal carried, if any. */
+    readonly code: string | undefined;
+    /** The schema's issues when the code's schema rejected the data; null otherwise. */
+    readonly zodError: z.ZodError | null;
+    constructor(apiName: string, thrown: LambderApiRefusal, violation: LambderRefusalViolation);
+}
+/**
+ * The refusal as endpoint `apiName` may send it, or a thrown
+ * LambderApiRefusalValidationError when it may not. Where a thrown refusal
+ * becomes an answer for a known endpoint (the pipeline, a hook refusing an
+ * API call on the server, an injected failure in the mock), it passes through
+ * here first.
+ *
+ * - An uncoded refusal, or one carrying a framework code, goes out as it is,
+ *   provided it carries no data. Where the app requires codes, an uncoded
+ *   refusal is refused too; a framework code still passes.
+ * - A declared code leaves with its declaration's status and notAuthorized
+ *   flag, and with data exactly when the code carries data, parsed through
+ *   the code's schema as an output is: undeclared fields stripped, defaults
+ *   filled, transforms run. The parse is synchronous, so a data schema cannot
+ *   be async.
+ * - Anything else is refused, a declared code raised with a status or flag of
+ *   its own included.
+ *
+ * `endpoint` undefined means the endpoint's codes are not known here (a mock
+ * given no generated options), and nothing is checked.
+ */
+export declare const checkedRefusal: (apiName: string, endpoint: LambderEndpointRefusals | undefined, thrown: LambderApiRefusal) => LambderApiRefusal;
+/**
+ * Throws when `where` (an API, a guard) names a refusal code the vocabulary
+ * does not hold, or names one when there is no vocabulary at all.
+ */
+export declare const assertRefusalCodesDeclared: (where: string, codes: readonly string[], vocabulary: ReadonlyMap<string, LambderRefusalDeclaration> | null) => void;
+/**
+ * One endpoint's allowed codes, resolved from the vocabulary: the codes its
+ * own `refusals` option names and those of its declared guards, each as
+ * checkedRefusal reads it, schema included. Throws on a name the vocabulary
+ * does not hold, and on a declaration when there is no vocabulary at all.
+ */
+export declare const resolveAllowedRefusals: (apiName: string, vocabulary: ReadonlyMap<string, LambderRefusalDeclaration> | null, ownCodes: readonly string[], guardCodes: readonly {
+    guard: string;
+    codes: readonly string[];
+}[]) => LambderApiAllowedRefusals;
+/** The refusals option in its list form: one name becomes a list of one. */
+export declare const toRefusalCodes: (value: string | readonly string[] | undefined) => readonly string[];
+/**
+ * The vocabulary, checked: every code a non-empty string outside the
+ * framework's `lambder/` prefix, every declaration an object whose `data`,
+ * when present, is a zod schema, whose `status`, when present, is one a
+ * reader files as a refusal, and whose `notAuthorized`, when present, is
+ * true. A Map, so a code named for something Object.prototype carries
+ * ("toString") is still an ordinary code.
+ */
+export declare const readRefusalVocabulary: (refusals: Record<string, LambderRefusalDeclaration> | undefined) => Map<string, LambderRefusalDeclaration> | null;
+/** The per-API refusals option: one code of the vocabulary, or a non-empty list of them. Empty is not a declaration, so it is not a form. */
+export type LambderRefusalsOption<TVocabulary> = (keyof TVocabulary & string) | readonly [keyof TVocabulary & string, ...(keyof TVocabulary & string)[]];
+/** The codes a refusals option names, whichever of its two forms is used: toRefusalCodes at the type level. */
+export type LambderRefusalNamesIn<TOpt> = TOpt extends string ? TOpt : TOpt extends readonly (infer TCode extends string)[] ? TCode : never;
+/**
+ * The codes as an API handler raises them (ctx.refuse): each mapped to
+ * `{ data }` in the schema's input form, the one its transforms take, or to
+ * `{}` for a code with no data.
+ */
+export type LambderHandlerRefusalsOf<TVocabulary, TCodes extends string> = {
+    [TCode in TCodes]: TCode extends keyof TVocabulary ? TVocabulary[TCode] extends {
+        data: infer TSchema extends z.ZodType;
+    } ? {
+        data: z.input<TSchema>;
+    } : {} : never;
+};
+/**
+ * The codes as a contract records them, for the client to narrow on: each
+ * mapped to `{ data }` as JSON (the schema's output after its transforms, as
+ * it arrives) or to `{}`. never when there are none, so the entry leaves the
+ * member out.
+ */
+export type LambderWireRefusalsOf<TVocabulary, TCodes extends string> = [
+    TCodes
+] extends [never] ? never : {
+    [TCode in TCodes]: TCode extends keyof TVocabulary ? TVocabulary[TCode] extends {
+        data: infer TSchema extends z.ZodType;
+    } ? {
+        data: LambderJsonOf<z.output<TSchema>>;
+    } : {} : never;
+};
+export {};

package/dist/api/LambderApiRefusals.js

@@ -0,0 +1,223 @@
+import { LambderApiRefusal, isLambderRefusalCode } from "../shared/wire/LambderApiRefusal.js";
+import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
+/** One code's declaration as checkedRefusal reads it: how a refusal with the code leaves, and its schema. */
+export const allowedRefusalOf = (declaration) => {
+    const leaves = {
+        ...(declaration.status !== undefined ? { status: declaration.status } : {}),
+        ...(declaration.notAuthorized ? { notAuthorized: true } : {}),
+    };
+    return declaration.data === undefined ? { ...leaves, data: false } : { ...leaves, data: true, schema: declaration.data };
+};
+/**
+ * A refusal an endpoint is not allowed to send, so it was not sent and the
+ * call is answered as a crash: no code where the app requires one, a code
+ * the endpoint does not declare (neither
+ * in its own `refusals` option nor through a guard), data on a refusal whose
+ * code declares none, no data on one whose code carries data, data its code's
+ * schema rejects or that is not an object or an array, or a declared code
+ * raised with a status or flag of its own, which its declaration owns.
+ *
+ * What makes a client's refusal type exact: a reader narrows `code` to the
+ * endpoint's declared codes and the framework's own, and relies on this to
+ * never see another. The refusal side's counterpart of
+ * LambderApiOutputValidationError. The refusal as thrown is the cause, so
+ * the stack points at the line that raised it.
+ */
+export class LambderApiRefusalValidationError extends Error {
+    apiName;
+    /** The code the refusal carried, if any. */
+    code;
+    /** The schema's issues when the code's schema rejected the data; null otherwise. */
+    zodError;
+    constructor(apiName, thrown, violation) {
+        const code = thrown.refusal.code;
+        let message;
+        if ("uncoded" in violation) {
+            message = `Lambder: API "${apiName}" refused without a code, and this app requires every refusal an API answers with to name a declared code (declareRefusals with requireCodes), so the refusal was not sent. `
+                + "Name one of the API's declared codes, or a framework code.";
+        }
+        else if ("undeclared" in violation) {
+            message = `Lambder: API "${apiName}" refused with the code "${violation.undeclared}", which it does not declare, so the refusal was not sent. `
+                + "Name the code in the API's refusals option (or in a guard it declares), from the refusals vocabulary given at creation.";
+        }
+        else if ("dataWithoutDeclaredCode" in violation) {
+            message = violation.dataWithoutDeclaredCode === undefined
+                ? `Lambder: API "${apiName}" refused with data but no code, so the refusal was not sent. Only a declared code carries data.`
+                : `Lambder: API "${apiName}" refused with the code "${violation.dataWithoutDeclaredCode}" and data it does not declare, so the refusal was not sent.`;
+        }
+        else if ("missingData" in violation) {
+            message = `Lambder: API "${apiName}" refused with the code "${violation.missingData}", which carries data, and no data, so the refusal was not sent.`;
+        }
+        else if ("ownStatusOrFlag" in violation) {
+            message = `Lambder: API "${apiName}" refused with the declared code "${String(code)}" and a status or flag of its own, so the refusal was not sent. `
+                + "A declared code's status and notAuthorized flag are its declaration's: set them in the refusals vocabulary, and leave them off the refuse() call.";
+        }
+        else if ("zodError" in violation) {
+            // Paths and messages only, never the values: they may be the
+            // user's data.
+            const issues = violation.zodError.issues.slice(0, 3).map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+            message = `Lambder: API "${apiName}" refused with the code "${String(code)}" and data its schema does not accept, so the refusal was not sent. ${issues}`;
+        }
+        else if ("thrown" in violation) {
+            message = `Lambder: API "${apiName}" refused with the code "${String(code)}" and data its schema threw on while parsing it (a transform that threw, `
+                + "or an async step: a refusal's data is parsed synchronously), so the refusal was not sent.";
+        }
+        else {
+            message = `Lambder: API "${apiName}" refused with the code "${String(code)}" and data that is ${violation.notObject}, and a refusal's data is an object or an array, so the refusal was not sent.`;
+        }
+        super(message, { cause: thrown });
+        this.name = "LambderApiRefusalValidationError";
+        this.apiName = apiName;
+        this.code = code;
+        this.zodError = "zodError" in violation ? violation.zodError : null;
+    }
+}
+/**
+ * The refusal as endpoint `apiName` may send it, or a thrown
+ * LambderApiRefusalValidationError when it may not. Where a thrown refusal
+ * becomes an answer for a known endpoint (the pipeline, a hook refusing an
+ * API call on the server, an injected failure in the mock), it passes through
+ * here first.
+ *
+ * - An uncoded refusal, or one carrying a framework code, goes out as it is,
+ *   provided it carries no data. Where the app requires codes, an uncoded
+ *   refusal is refused too; a framework code still passes.
+ * - A declared code leaves with its declaration's status and notAuthorized
+ *   flag, and with data exactly when the code carries data, parsed through
+ *   the code's schema as an output is: undeclared fields stripped, defaults
+ *   filled, transforms run. The parse is synchronous, so a data schema cannot
+ *   be async.
+ * - Anything else is refused, a declared code raised with a status or flag of
+ *   its own included.
+ *
+ * `endpoint` undefined means the endpoint's codes are not known here (a mock
+ * given no generated options), and nothing is checked.
+ */
+export const checkedRefusal = (apiName, endpoint, thrown) => {
+    if (endpoint === undefined)
+        return thrown;
+    const { code, data } = thrown.refusal;
+    if (code === undefined || isLambderRefusalCode(code)) {
+        if (code === undefined && endpoint.codeRequired)
+            throw new LambderApiRefusalValidationError(apiName, thrown, { uncoded: true });
+        if (data !== undefined)
+            throw new LambderApiRefusalValidationError(apiName, thrown, { dataWithoutDeclaredCode: code });
+        return thrown;
+    }
+    const declaration = endpoint.codes.get(code);
+    if (declaration === undefined)
+        throw new LambderApiRefusalValidationError(apiName, thrown, { undeclared: code });
+    if (thrown.statusCode !== undefined || thrown.notAuthorized || thrown.sessionExpired) {
+        throw new LambderApiRefusalValidationError(apiName, thrown, { ownStatusOrFlag: true });
+    }
+    let sent;
+    if (!declaration.data) {
+        if (data !== undefined)
+            throw new LambderApiRefusalValidationError(apiName, thrown, { dataWithoutDeclaredCode: code });
+    }
+    else if (data === undefined) {
+        throw new LambderApiRefusalValidationError(apiName, thrown, { missingData: code });
+    }
+    else {
+        let parsed;
+        try {
+            parsed = declaration.schema.safeParse(data);
+        }
+        catch (cause) {
+            throw new LambderApiRefusalValidationError(apiName, thrown, { thrown: cause });
+        }
+        if (!parsed.success)
+            throw new LambderApiRefusalValidationError(apiName, thrown, { zodError: parsed.error });
+        if (!isObjectPayload(parsed.data))
+            throw new LambderApiRefusalValidationError(apiName, thrown, { notObject: describePayloadKind(parsed.data) });
+        sent = parsed.data;
+    }
+    // The declaration's status and flag, and the data as parsed: how every
+    // refusal with this code leaves, wherever it was raised.
+    return new LambderApiRefusal(thrown.message, {
+        refusal: { ...thrown.refusal, ...(sent !== undefined ? { data: sent } : {}) },
+        notAuthorized: declaration.notAuthorized,
+        statusCode: declaration.status,
+        headers: thrown.headers,
+        cause: thrown.cause,
+    });
+};
+/**
+ * Throws when `where` (an API, a guard) names a refusal code the vocabulary
+ * does not hold, or names one when there is no vocabulary at all.
+ */
+export const assertRefusalCodesDeclared = (where, codes, vocabulary) => {
+    for (const code of codes) {
+        if (!vocabulary) {
+            throw new Error(`Lambder: ${where} declares the refusal "${code}", but no refusals vocabulary was declared. Declare the app's codes with initLambder().declareRefusals().`);
+        }
+        if (!vocabulary.has(code)) {
+            throw new Error(`Lambder: ${where} declares the refusal "${code}", which the refusals vocabulary does not hold.`);
+        }
+    }
+};
+/**
+ * One endpoint's allowed codes, resolved from the vocabulary: the codes its
+ * own `refusals` option names and those of its declared guards, each as
+ * checkedRefusal reads it, schema included. Throws on a name the vocabulary
+ * does not hold, and on a declaration when there is no vocabulary at all.
+ */
+export const resolveAllowedRefusals = (apiName, vocabulary, ownCodes, guardCodes) => {
+    const allowed = new Map();
+    const take = (code, where) => {
+        assertRefusalCodesDeclared(where, [code], vocabulary);
+        allowed.set(code, allowedRefusalOf(vocabulary.get(code)));
+    };
+    for (const code of ownCodes)
+        take(code, `API "${apiName}"`);
+    for (const { guard, codes } of guardCodes) {
+        for (const code of codes)
+            take(code, `guard "${guard}" (declared by API "${apiName}")`);
+    }
+    return allowed;
+};
+/** The refusals option in its list form: one name becomes a list of one. */
+export const toRefusalCodes = (value) => value === undefined ? [] : typeof value === "string" ? [value] : value;
+/**
+ * The vocabulary, checked: every code a non-empty string outside the
+ * framework's `lambder/` prefix, every declaration an object whose `data`,
+ * when present, is a zod schema, whose `status`, when present, is one a
+ * reader files as a refusal, and whose `notAuthorized`, when present, is
+ * true. A Map, so a code named for something Object.prototype carries
+ * ("toString") is still an ordinary code.
+ */
+export const readRefusalVocabulary = (refusals) => {
+    if (refusals === undefined)
+        return null;
+    const entries = Object.entries(refusals);
+    if (entries.length === 0) {
+        throw new Error("Lambder: the refusals vocabulary was declared with no codes in it, which declares nothing. Name the codes APIs will refuse with, or leave declareRefusals() out.");
+    }
+    for (const [code, declaration] of entries) {
+        if (code === "")
+            throw new Error("Lambder: the refusals vocabulary declares an empty code.");
+        if (code.startsWith("lambder/")) {
+            throw new Error(`Lambder: the refusals vocabulary declares "${code}", under the "lambder/" prefix the framework's own codes use. Name it outside that prefix.`);
+        }
+        if (declaration === null || typeof declaration !== "object") {
+            throw new Error(`Lambder: the refusal "${code}" is not declared as an object: write {} for a code with no data, or { data: schema }.`);
+        }
+        const extra = Object.keys(declaration).filter((key) => key !== "data" && key !== "status" && key !== "notAuthorized");
+        if (extra.length) {
+            throw new Error(`Lambder: the refusal "${code}" has ${extra.map((key) => `"${key}"`).join(", ")} beside data, status and notAuthorized, which a refusal declaration does not take.`);
+        }
+        // Read for what it is used as rather than by class, so a schema from
+        // a second copy of zod in the bundle still counts.
+        if (declaration.data !== undefined && typeof declaration.data?.safeParse !== "function") {
+            throw new Error(`Lambder: the refusal "${code}" declares data that is not a zod schema.`);
+        }
+        const status = declaration.status;
+        if (status !== undefined && (typeof status !== "number" || !Number.isInteger(status) || status < 200 || status >= 500 || status === 422)) {
+            throw new Error(`Lambder: the refusal "${code}" declares the status ${String(status)}. A declared refusal leaves with a status from 200 to 499 other than 422: a reader files a 5xx as a server failure and a 422 as an input validation failure.`);
+        }
+        if (declaration.notAuthorized !== undefined && declaration.notAuthorized !== true) {
+            throw new Error(`Lambder: the refusal "${code}" declares notAuthorized as ${String(declaration.notAuthorized)}; write true, or leave it off.`);
+        }
+    }
+    return new Map(entries);
+};

package/dist/api/LambderApiSignature.d.ts

@@ -16,10 +16,19 @@ export type LambderApiSignatureEntry = {
  * The digest of an endpoint's client-facing shape: its name and mode, its
  * input and output schemas as JSON Schema, every guard it declares with the
  * schema that guard validates (the guardInput the client sends separately,
- * or the apiInput slice of the payload), and whether it demands an
- * idempotency key. Anything else (rate limits, a guard's parameter, the
- * handler) changes nothing for a client and is left out, so changing it never
- * forces a reload.
+ * or the apiInput slice of the payload), whether it demands an idempotency
+ * key, and every refusal code it may send with its data's schema, its status
+ * and its notAuthorized flag. Anything
+ * else (rate limits, a guard's parameter, the handler) changes nothing for a
+ * client and is left out, so changing it never forces a reload.
+ *
+ * The refusal codes count in full: a client's refusal type lists exactly the
+ * codes the endpoint declares, so one built before a code was added would be
+ * handed a code its types say cannot arrive. Adding a code, or changing a
+ * code's data, reloads that endpoint's clients. A code's data is received,
+ * so it is digested in the output position, where an extensibleEnum's values
+ * leave the digest. Its status and flag count too: a caller reads the one
+ * and routes on the other.
  *
  * Schemas are hashed as built, descriptions and titles included, so a client
  * built against a different one reloads once. The exception is an output

package/dist/api/LambderApiSignature.js

@@ -54,10 +54,19 @@ const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasO
  * The digest of an endpoint's client-facing shape: its name and mode, its
  * input and output schemas as JSON Schema, every guard it declares with the
  * schema that guard validates (the guardInput the client sends separately,
- * or the apiInput slice of the payload), and whether it demands an
- * idempotency key. Anything else (rate limits, a guard's parameter, the
- * handler) changes nothing for a client and is left out, so changing it never
- * forces a reload.
+ * or the apiInput slice of the payload), whether it demands an idempotency
+ * key, and every refusal code it may send with its data's schema, its status
+ * and its notAuthorized flag. Anything
+ * else (rate limits, a guard's parameter, the handler) changes nothing for a
+ * client and is left out, so changing it never forces a reload.
+ *
+ * The refusal codes count in full: a client's refusal type lists exactly the
+ * codes the endpoint declares, so one built before a code was added would be
+ * handed a code its types say cannot arrive. Adding a code, or changing a
+ * code's data, reloads that endpoint's clients. A code's data is received,
+ * so it is digested in the output position, where an extensibleEnum's values
+ * leave the digest. Its status and flag count too: a caller reads the one
+ * and routes on the other.
  *
  * Schemas are hashed as built, descriptions and titles included, so a client
  * built against a different one reloads once. The exception is an output
@@ -75,6 +84,13 @@ export const apiSignatureOf = async (definition, guards) => {
             }];
     });
     guardShapes.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const refusalShapes = [...(definition.refusals?.codes ?? new Map()).entries()]
+        .map(([code, declaration]) => [code, {
+            data: jsonSchemaOf(declaration.data ? declaration.schema : undefined, "output"),
+            status: declaration.status ?? 200,
+            notAuthorized: declaration.notAuthorized === true,
+        }]);
+    refusalShapes.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
     const description = {
         name: definition.name,
         mode: definition.mode,
@@ -82,6 +98,7 @@ export const apiSignatureOf = async (definition, guards) => {
         output: jsonSchemaOf(definition.output, "output"),
         guards: guardShapes,
         idempotency: definition.idempotency !== undefined && definition.idempotency !== false,
+        refusals: refusalShapes,
     };
     const hex = await sha256HexOf(canonicalJson(description));
     return hex.slice(0, API_SIGNATURE_HEX_LENGTH);

package/dist/build/writeApiOptions.js

@@ -3,9 +3,11 @@ import { resolve } from "path";
 import { headerLinesOf, loadApiOptionEntries, nameChangesOf, readGeneratedTable, settleGeneratedFile, tableStatementLines, } from "./generatedTables.js";
 /*
  * The declared options of an app's APIs as a generated module of plain data:
- * every API's mode and its guards, rateLimit and idempotency options as
- * written, every rate-limit policy less its key handler, and every guard's
- * input mode, session flag and place in the call. The contract already
+ * every API's mode and its guards, rateLimit, idempotency and refusals
+ * options as written, every rate-limit policy less its key handler, and
+ * every guard's input mode, session flag, place in the call and refusal
+ * codes. The refusal vocabulary itself is not written: it is shared code,
+ * which the mock declares as the server does. The contract already
  * carries the options as types; this is the same fact as a value, for the
  * code that decides something at runtime with it: a mock restating the
  * server's declarations, a test walking the public surface. Neither imports
@@ -29,9 +31,9 @@ const DEFAULT_HEADER = [
 ].join("\n");
 /** The three tables the module exports, in the order they are written. */
 const TABLES = [
-    { name: "apiOptions", key: "apis", type: "LambderApiOptionEntry", doc: "Every API the server registers: its mode and its guards, rateLimit and idempotency options as written." },
+    { name: "apiOptions", key: "apis", type: "LambderApiOptionEntry", doc: "Every API the server registers: its mode and its guards, rateLimit, idempotency and refusals options as written." },
     { name: "rateLimitPolicies", key: "rateLimitPolicies", type: "LambderRateLimitPolicyEntry", doc: "Every rate-limit policy the server declares, its key reduced to what it counts: an address, a session, or a key the app derives (\"custom\")." },
-    { name: "guardDeclarations", key: "guards", type: "LambderGuardDeclarationEntry", doc: "Every guard the server declares: how it is fed, whether it needs a session, and when it runs." },
+    { name: "guardDeclarations", key: "guards", type: "LambderGuardDeclarationEntry", doc: "Every guard the server declares: how it is fed, whether it needs a session, when it runs, and the refusal codes it adds to the APIs declaring it." },
 ];
 /** The tables a generated file holds, read back as data, or null for a file that does not hold all three as written (never written, or rewritten by hand). */
 export const readOptionTables = (contents) => {

package/dist/client/LambderCaller.d.ts

@@ -1,6 +1,6 @@
-import type { LambderAppRefusalMessage } from '../shared/wire/LambderApiRefusal.js';
+import type { LambderUncheckedRefusalMessage } from '../shared/wire/LambderApiRefusal.js';
 import { type LambderRequestCompressionOption } from '../shared/wire/LambderRequestPayload.js';
-import type { LambderApiContractShape } from '../shared/wire/LambderApiContract.js';
+import type { LambderApiContractShape, LambderContractAnyRefusalMessage, LambderContractRefusalMessage } from '../shared/wire/LambderApiContract.js';
 import { type LambderApiOutcome, type LambderValidationError } from '../shared/wire/LambderApiOutcome.js';
 import { type LambderCallArgs, type LambderContractOutputOf, type LambderGuardInputsProviderOption, type LambderSharedCallOptions } from '../shared/wire/LambderCallOptions.js';
 import { type LambderApiTransport } from '../shared/transport/LambderApiTransport.js';
@@ -29,18 +29,25 @@ type FetchEndEventHandler = (params: {
 }) => void | Promise<void>;
 type ErrorHandler = (err: Error) => void | Promise<void>;
 type ValidationErrorHandler = (zodError: LambderValidationError) => (void | false) | Promise<(void | false)>;
-/** Handed the refusal as its message object, a plain-string errorMessage having been read as one (refusalMessageOf). */
-type ErrorMessageHandler = (message: LambderAppRefusalMessage) => void | Promise<void>;
+/**
+ * Handed the refusal as its message object, a plain-string refusal
+ * having been read as one (refusalMessageOf). TMessage is what the calls it
+ * hears can refuse with: one endpoint's declared codes on a per-call
+ * override, every endpoint's on the constructor's.
+ */
+type RefusalHandler<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = (message: TMessage) => void | Promise<void>;
 /** The logListHandler option: an answer's logList, success or failure, when it has entries. The invoke caller's onLogList, for a browser. */
 export type LambderLogListHandler = (apiName: string, logList: unknown[]) => void | Promise<void>;
 /**
  * Per-call options: the request extras both callers share (see
  * LambderSharedCallOptions) plus an override for every constructor handler.
+ * TMessage is the endpoint's refusal message, which the per-call
+ * refusalHandler is handed.
  */
-export type LambderCallOptions = LambderSharedCallOptions & {
+export type LambderCallOptions<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderSharedCallOptions & {
     versionExpiredHandler?: NotifyHandler;
     sessionExpiredHandler?: NotifyHandler;
-    errorMessageHandler?: ErrorMessageHandler;
+    refusalHandler?: RefusalHandler<TMessage>;
     apiInputValidationErrorHandler?: ValidationErrorHandler;
     notAuthorizedHandler?: NotifyHandler;
     errorHandler?: ErrorHandler;
@@ -48,7 +55,7 @@ export type LambderCallOptions = LambderSharedCallOptions & {
     fetchStartedHandler?: FetchStartEventHandler;
     fetchEndedHandler?: FetchEndEventHandler;
 };
-type LambderCallerBaseOptions = {
+type LambderCallerBaseOptions<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = {
     apiPath: string;
     /** Sent with every call as `version`, informational: the server stamps its own on every answer. */
     apiVersion?: string;
@@ -71,7 +78,8 @@ type LambderCallerBaseOptions = {
     timeoutMs?: number;
     versionExpiredHandler?: NotifyHandler;
     sessionExpiredHandler?: NotifyHandler;
-    errorMessageHandler?: ErrorMessageHandler;
+    /** Handed every refusal a call of this caller comes back with, typed with every code the contract declares. */
+    refusalHandler?: RefusalHandler<TMessage>;
     notAuthorizedHandler?: NotifyHandler;
     errorHandler?: ErrorHandler;
     /** Receives each answer's logList, with the API name. Default: console.log with a `[lambder]` prefix, one line per entry. */
@@ -100,7 +108,7 @@ type LambderCallerBaseOptions = {
     transport?: LambderApiTransport;
 };
 /** Constructor options: the base options plus guardInputsProvider, mandatory once TProvided names guards. */
-export type LambderCallerOptions<TContract, TProvided extends string = never> = LambderCallerBaseOptions & LambderGuardInputsProviderOption<TContract, TProvided>;
+export type LambderCallerOptions<TContract, TProvided extends string = never> = LambderCallerBaseOptions<LambderContractAnyRefusalMessage<TContract>> & LambderGuardInputsProviderOption<TContract, TProvided>;
 /**
  * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
  * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
@@ -116,7 +124,7 @@ export default class LambderCaller<TContract extends LambderApiContractShape = a
     get isLoading(): boolean;
     private versionExpiredHandler?;
     private sessionExpiredHandler?;
-    private errorMessageHandler?;
+    private refusalHandler?;
     private notAuthorizedHandler?;
     private errorHandler?;
     private apiInputValidationErrorHandler?;
@@ -138,18 +146,21 @@ export default class LambderCaller<TContract extends LambderApiContractShape = a
     private dispatch;
     /**
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
-     * instead of collapsing every failure to undefined. Never throws.
+     * instead of collapsing every failure to undefined. Never throws. A
+     * success's payload is the endpoint's output, and a refusal's
+     * refusal narrows on the codes the endpoint declares.
      *
      * The output is computed from the contract in the return type rather than
      * taken as a type parameter, so a call site cannot replace it by
      * annotating what it assigns to.
      */
-    apiOutcome<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderCallOptions>): Promise<LambderApiOutcome<LambderContractOutputOf<TContract, TApiName>>>;
+    apiOutcome<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderCallOptions<LambderContractRefusalMessage<TContract, TApiName>>>): Promise<LambderApiOutcome<LambderContractOutputOf<TContract, TApiName>, LambderContractRefusalMessage<TContract, TApiName>>>;
     /**
-     * The payload on success, `undefined` on every failure except a
-     * structured refusal, which hands back whatever payload the envelope
-     * carried (usually null). Neither is distinguishable from a legitimately
-     * null or undefined payload: use apiOutcome() when that matters.
+     * The endpoint's output on success, `undefined` on every failure. An
+     * output is always an object or an array, so the result is truthy exactly
+     * when the call succeeded; the handlers configured on the caller have
+     * already been told why it did not. Use apiOutcome() to branch on the
+     * reason at the call site.
      */
-    api<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderCallOptions>): Promise<LambderContractOutputOf<TContract, TApiName> | null | undefined>;
+    api<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderCallOptions<LambderContractRefusalMessage<TContract, TApiName>>>): Promise<LambderContractOutputOf<TContract, TApiName> | undefined>;
 }