lambder 13.0.1 → 14.1.1

package/CHANGELOG.md

@@ -9,6 +9,88 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [14.1.1] - 2026-09-30
+
+A minor: a refusal code can declare the `sessionExpired` flag, and
+`checkApiRefusals` holds every refusal a handler can reach to the codes its
+endpoint may send, which is what an app that requires codes needs to know
+before a call finds out.
+
+### Added
+
+- **A code declared `sessionExpired: true`** leaves with the envelope's
+  `sessionExpired` flag, as one declared `notAuthorized: true` leaves with
+  that one: for a session the pipeline found good that the handler then
+  finds gone (its login deleted, say). With `requireCodes`, a refusal that
+  meant "your session is over" had no way to carry both a code and the
+  flag. The declaration owns the flag, so a raise site that sets it on a
+  declared code is still a crash; a code may set one flag at most, since a
+  caller routes a refusal one way; and the flag counts in an endpoint's
+  signature only where a code sets it, so every existing digest stays as it
+  was. The mock sends it the same way.
+- **`checkApiRefusals`** (`lambder/build`): reads a project through the
+  TypeScript compiler and, for every handler Lambder hands a typed `refuse`
+  (an endpoint's, a guard's, a mock entry's), follows it into every function
+  it can reach (a call, a method of what it constructs, a function handed
+  along, a module loaded with `import()`, a handler the app wraps or holds
+  in an object) and holds each code raised there to the codes its
+  `ctx.refuse` takes. It names a code a handler may not send, a declared
+  code nothing reaches, a refusal with no code where codes are required, a
+  refusal whose code is any string, and a handler whose function it cannot
+  find; a project in which it finds no handler to check fails rather than
+  passes. Before it, a shared helper's code for an endpoint that did not
+  declare it compiled, and crashed only when a call reached it.
+
+### Changed
+
+- **A refusal that leaves an API call with the `sessionExpired` flag ends
+  the session the call held**, whether a declared code or the raise site set
+  the flag, and whether a handler, a guard or a hook threw it. The caller
+  stops sending a session it is told is over, and before this nothing
+  deleted it on the server until it expired. The record is deleted and the
+  cookies are left alone, as when the session read finds no session, since a
+  cookie deletion would also delete a session another response has just
+  set.
+
+## [14.0.1] - 2026-09-30
+
+A major: `writeApiGuardParams` writes one export per API in place of one
+table, so a browser carries only the guard parameters its screens import,
+and none of the API names behind them.
+
+### Changed (breaking)
+
+- **`writeApiGuardParams` writes one export per API** that declares the
+  guard, in place of the `guardParams` table: `orders.list` exports
+  `ordersListGuardParam`, holding the parameter as declared (`true` for the
+  guard named without one) and typed
+  `LambderApiGuardParam<"orders.list", "store", literal>`. A bundler keeps
+  only the exports a client imports, and none of them carries its API's name,
+  which sits in the export's type and doc comment alone, so a page no longer
+  ships the name of every API behind the guard and what each asks. The
+  module imports the tag type from `lambder/client`, as a type. Two APIs
+  whose names would export under one identifier fail the write, and so does
+  a `null` parameter, which the tag cannot carry; a guard no API declares
+  writes an empty module. A file still in the table form reads as one to
+  regenerate, on a check and on a write.
+  - To move: regenerate the file, and import the exports a screen gates on
+    in place of reading `guardParams[name]`. A function that takes any of a
+    guard's parameters reads their union off the module with a type-only
+    import (`(typeof params)[keyof typeof params]`, over
+    `import type * as params`). Code that needs every API's name, a test
+    walking them all, reads it from the `writeApiOptions` file.
+
+### Added
+
+- **`LambderApiGuardParam`** (`lambder/client`, `lambder`): the type of each
+  export `writeApiGuardParams` writes, a guard's parameter tagged in types
+  alone with the API's name and the guard's, so a function typed to a
+  guard's parameters refuses a hand-written literal.
+- **`apiGuardParamExportName`** (`lambder/client`, `lambder`): the identifier
+  `writeApiGuardParams` exports an API's parameter under, for code that reads
+  a generated module by API name, such as a test comparing it with the
+  server.
+
 ## [13.0.1] - 2026-09-30
 
 A major: session data is checked against a schema on every read, and

package/README.md

@@ -140,7 +140,7 @@ The package ships five entry points; pick by where the code runs:
 | `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiRefusal`/`refuse`, the API contract and envelope types, `LambderUploadRunner`, `LambderBackoffTimer`, `LambderSignedClaims`, `html`/`xml` tagged templates, `createLambderI18n` |
 | `lambder/mock` | Browser and Node, in development and tests | `LambderMockApp`, the mock runtime: your typed contract served from mock handlers over the real API pipeline and memory stores |
 | `lambder/testing` | Node, in tests | `lambderTestApp`: your real instance under test in this process, memory stores put under it in place, simulated browsers with typed callers in front of it, and the outcome assertions; the store conformance suites, to hold a store you write to the rules Lambder's own meet |
-| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiOptions`: every API's declared options, policies and guard declarations as plain data, for the code that decides with them; `writeApiGuardParams`: one guard's parameters and nothing else, what a browser gating on that guard carries; `writeApiContract`: the contract as plain types a client compiles instead of the server; `generateApiFiles`: every one of them, for every app a script names, in one call |
+| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiOptions`: every API's declared options, policies and guard declarations as plain data, for the code that decides with them; `writeApiGuardParams`: one guard's parameters, one export per API and nothing else, so a browser gating on that guard carries only the ones it imports; `writeApiContract`: the contract as plain types a client compiles instead of the server; `generateApiFiles`: every one of them, for every app a script names, in one call |
 
 Frontends and shared isomorphic packages should import from `lambder/client`
 only; the entry's module graph contains no AWS SDK, Node built-ins, or server

package/dist/api/LambderApiPipeline.d.ts

@@ -5,6 +5,8 @@ import type { LambderApiCallContext } from "./LambderApiCallContext.js";
 import type { LambderApiCallTrace } from "./LambderApiCallContext.js";
 import type { LambderApiDefinition } from "./LambderApiDefinition.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
+import { type LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import { type LambderEndpointRefusals } from "./LambderApiRefusals.js";
 import { type LambderApiGuard } from "./LambderApiGuards.js";
 import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderRateLimitChargeResult, type LambderRateLimitChargeSubject } from "./LambderApiRateLimits.js";
 import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
@@ -107,8 +109,12 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
  * validation error through onInvalidInput, any other refusal as the refusal
  * envelope once checked against the endpoint's declared codes
  * (checkedRefusal), and a session ended while the handler held it
- * (LambderSessionNotFoundError) as sessionExpired. Anything else propagates, because only the adapter knows what a
- * crash means (a global error handler, a mock event).
+ * (LambderSessionNotFoundError) as sessionExpired. A refusal that leaves
+ * with the sessionExpired flag ends the session the call held
+ * (answerRefusal), so the server keeps no session its caller has been told
+ * is over. Anything else
+ * propagates, because only the adapter knows what a crash means (a global
+ * error handler, a mock event).
  *
  * `run` never sees a name it has no definition for; resolving a name to a
  * definition is the one thing the adapters legitimately do differently (an
@@ -161,6 +167,20 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      * versionExpired by the time anything asks for an unknown name.
      */
     answerUnknownApi(ctx?: TCtx): LambderApiAnswer;
+    /**
+     * A thrown refusal as the answer to a call of `apiName`: checked against
+     * the codes the endpoint declares (checkedRefusal, which throws for one it
+     * may not send), then rendered. run() answers a step's, a guard's or a
+     * handler's refusal with it, and the server a hook's.
+     *
+     * A refusal telling the caller its session is over (a declared code's
+     * flag, or a raise site's own) ends the session the call held: the caller
+     * stops sending it, and nothing else would delete it before it expires.
+     * The record is deleted and the cookies left alone, which is what the
+     * pipeline's own sessionExpired leaves behind (endWithNoSession in the
+     * session controller says why the cookies stay).
+     */
+    answerRefusal(apiName: string, refusals: LambderEndpointRefusals | undefined, thrown: LambderApiRefusal, ctx: TCtx): Promise<LambderApiAnswer>;
     /**
      * The steps that come before anything may read the request: the version
      * floor, the signature gate, then the compressed-payload restore that

package/dist/api/LambderApiPipeline.js

@@ -37,8 +37,12 @@ const usesIdempotency = (definition) => definition.idempotency !== undefined &&
  * validation error through onInvalidInput, any other refusal as the refusal
  * envelope once checked against the endpoint's declared codes
  * (checkedRefusal), and a session ended while the handler held it
- * (LambderSessionNotFoundError) as sessionExpired. Anything else propagates, because only the adapter knows what a
- * crash means (a global error handler, a mock event).
+ * (LambderSessionNotFoundError) as sessionExpired. A refusal that leaves
+ * with the sessionExpired flag ends the session the call held
+ * (answerRefusal), so the server keeps no session its caller has been told
+ * is over. Anything else
+ * propagates, because only the adapter knows what a crash means (a global
+ * error handler, a mock event).
  *
  * `run` never sees a name it has no definition for; resolving a name to a
  * definition is the one thing the adapters legitimately do differently (an
@@ -185,6 +189,27 @@ export class LambderApiPipeline {
         ctx?.responseHeaders.applyInto(answer.headers);
         return answer;
     }
+    /**
+     * A thrown refusal as the answer to a call of `apiName`: checked against
+     * the codes the endpoint declares (checkedRefusal, which throws for one it
+     * may not send), then rendered. run() answers a step's, a guard's or a
+     * handler's refusal with it, and the server a hook's.
+     *
+     * A refusal telling the caller its session is over (a declared code's
+     * flag, or a raise site's own) ends the session the call held: the caller
+     * stops sending it, and nothing else would delete it before it expires.
+     * The record is deleted and the cookies left alone, which is what the
+     * pipeline's own sessionExpired leaves behind (endWithNoSession in the
+     * session controller says why the cookies stay).
+     */
+    async answerRefusal(apiName, refusals, thrown, ctx) {
+        const checked = checkedRefusal(apiName, refusals, thrown);
+        if (checked.sessionExpired && ctx.session && this.sessions) {
+            await this.sessions.manager.deleteSession(ctx.session);
+            ctx.session = null;
+        }
+        return refusalAnswer(checked, this.apiVersion, ctx.logList);
+    }
     /**
      * The steps that come before anything may read the request: the version
      * floor, the signature gate, then the compressed-payload restore that
@@ -250,7 +275,7 @@ export class LambderApiPipeline {
                 // idempotency engine has already released the claim, as it
                 // does for every thrown refusal: a retry runs the handler
                 // again and decides afresh.
-                answer = refusalAnswer(checkedRefusal(definition.name, definition.refusals, err), this.apiVersion, ctx.logList);
+                answer = await this.answerRefusal(definition.name, definition.refusals, err, ctx);
             }
             else if (err instanceof LambderSessionNotFoundError) {
                 // No usable session: it ended while the handler held it (a

package/dist/api/LambderApiRefusals.d.ts

@@ -8,7 +8,7 @@ import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderN
  * 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,
+ * status and the flags are declared once here rather than at each raise site,
  * so a code always reaches a caller the same way.
  */
 export type LambderRefusalDeclaration = {
@@ -18,6 +18,14 @@ export type LambderRefusalDeclaration = {
     status?: LambderRefusalStatusCode;
     /** Whether every refusal with this code sets the envelope's notAuthorized flag, which a caller routes to its notAuthorizedHandler. */
     notAuthorized?: true;
+    /**
+     * Whether every refusal with this code sets the envelope's sessionExpired
+     * flag, which a caller answers by clearing its session and routing to its
+     * sessionExpiredHandler: for a session the handler found no longer good
+     * (its login deleted, say), which the pipeline's own check could not know.
+     * The server ends the session the call held as the refusal leaves.
+     */
+    sessionExpired?: true;
 };
 /**
  * One code as its endpoint may send it: the status and flag its declaration
@@ -30,6 +38,8 @@ export type LambderApiAllowedRefusal = {
     status?: LambderRefusalStatusCode;
     /** Present when every refusal with the code sets the envelope's notAuthorized flag. */
     notAuthorized?: true;
+    /** Present when every refusal with the code sets the envelope's sessionExpired flag. */
+    sessionExpired?: true;
 } & ({
     data: false;
 } | {
@@ -61,7 +71,7 @@ type LambderRefusalDataRefusal = {
 };
 /**
  * The vocabulary as declareRefusals() checks it, code by code: no `lambder/`
- * prefix, no key beside data, status and notAuthorized (a `dat:` would leave
+ * prefix, no key beside data, status and the two flags (a `dat:` would leave
  * a code that carries data declared as one that does not), and data that is
  * an object or an array.
  */
@@ -154,8 +164,8 @@ export declare class LambderApiRefusalValidationError extends Error {
  * - 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
+ * - A declared code leaves with its declaration's status and flags, 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.
@@ -187,8 +197,8 @@ export declare const toRefusalCodes: (value: string | readonly string[] | undefi
  * 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
+ * reader files as a refusal, and whose `notAuthorized` and `sessionExpired`,
+ * when present, are 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;

package/dist/api/LambderApiRefusals.js

@@ -18,6 +18,7 @@ export const allowedRefusalOf = (declaration) => {
     const leaves = {
         ...(declaration.status !== undefined ? { status: declaration.status } : {}),
         ...(declaration.notAuthorized ? { notAuthorized: true } : {}),
+        ...(declaration.sessionExpired ? { sessionExpired: true } : {}),
     };
     return declaration.data === undefined ? { ...leaves, data: false } : { ...leaves, data: true, schema: declaration.data };
 };
@@ -63,7 +64,7 @@ export class LambderApiRefusalValidationError extends Error {
         }
         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.";
+                + "A declared code's status and its notAuthorized and sessionExpired flags 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
@@ -95,8 +96,8 @@ export class LambderApiRefusalValidationError extends Error {
  * - 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
+ * - A declared code leaves with its declaration's status and flags, 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.
@@ -145,11 +146,12 @@ export const checkedRefusal = (apiName, endpoint, thrown) => {
             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
+    // The declaration's status and flags, 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,
+        sessionExpired: declaration.sessionExpired,
         statusCode: declaration.status,
         headers: thrown.headers,
         cause: thrown.cause,
@@ -195,8 +197,8 @@ export const toRefusalCodes = (value) => value === undefined ? [] : typeof 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
+ * reader files as a refusal, and whose `notAuthorized` and `sessionExpired`,
+ * when present, are true. A Map, so a code named for something Object.prototype carries
  * ("toString") is still an ordinary code.
  */
 export const readRefusalVocabulary = (refusals) => {
@@ -215,9 +217,9 @@ export const readRefusalVocabulary = (refusals) => {
         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");
+        const extra = Object.keys(declaration).filter((key) => key !== "data" && key !== "status" && key !== "notAuthorized" && key !== "sessionExpired");
         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.`);
+            throw new Error(`Lambder: the refusal "${code}" has ${extra.map((key) => `"${key}"`).join(", ")} beside data, status, notAuthorized and sessionExpired, 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.
@@ -228,8 +230,13 @@ export const readRefusalVocabulary = (refusals) => {
         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.`);
+        for (const flag of ["notAuthorized", "sessionExpired"]) {
+            if (declaration[flag] !== undefined && declaration[flag] !== true) {
+                throw new Error(`Lambder: the refusal "${code}" declares ${flag} as ${String(declaration[flag])}; write true, or leave it off.`);
+            }
+        }
+        if (declaration.notAuthorized && declaration.sessionExpired) {
+            throw new Error(`Lambder: the refusal "${code}" declares both notAuthorized and sessionExpired. A caller routes a refusal one way: a session that is gone is not also a session that is not allowed.`);
         }
     }
     return new Map(entries);

package/dist/api/LambderApiSignature.d.ts

@@ -18,17 +18,17 @@ export type LambderApiSignatureEntry = {
  * schema that guard validates (the guardInput the client sends separately,
  * 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.
+ * and its flags. 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.
+ * leave the digest. Its status and flags count too: a caller reads the one
+ * and routes on the others.
  *
  * 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

@@ -56,17 +56,17 @@ const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasO
  * schema that guard validates (the guardInput the client sends separately,
  * 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.
+ * and its flags. 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.
+ * leave the digest. Its status and flags count too: a caller reads the one
+ * and routes on the others.
  *
  * Schemas are hashed as built, descriptions and titles included, so a client
  * built against a different one reloads once. The exception is an output
@@ -89,6 +89,8 @@ export const apiSignatureOf = async (definition, guards) => {
             data: jsonSchemaOf(declaration.data ? declaration.schema : undefined, "output"),
             status: declaration.status ?? 200,
             notAuthorized: declaration.notAuthorized === true,
+            // Written only when set, so a vocabulary with no such code digests as it did before the flag existed.
+            ...(declaration.sessionExpired ? { sessionExpired: true } : {}),
         }]);
     refusalShapes.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
     const description = {

package/dist/build/checkApiRefusals.d.ts

@@ -0,0 +1,54 @@
+export type LambderApiRefusalCheckOptions = {
+    /** The tsconfig.json the project compiles under, whose options and path aliases resolve its imports. Relative to the working directory. */
+    tsconfig: string;
+    /** The files the program starts from, relative to the working directory; everything they import is read too. Default: the tsconfig's own files. */
+    files?: string[];
+    /** Whether a refusal with no code is a finding, as it is a crash in an app whose vocabulary requires codes (declareRefusals's requireCodes). Default: true. */
+    requireCodes?: boolean;
+};
+/** What one handler's check found. */
+export type LambderRefusalCheckFinding = {
+    /** The handler, as its registration names it: an endpoint's `group.action`, a mock entry's name, a guard's name. */
+    handler: string;
+    /** Where the handler is registered, as `file:line` relative to the working directory. */
+    at: string;
+    /**
+     * - `undeclared`: a code the handler can reach that it may not send.
+     * - `unused`: a code the handler's own `refusals` option names that nothing it reaches raises.
+     * - `uncoded`: a refusal with no code it can reach, where codes are required.
+     * - `unreadable`: a refusal it can reach whose code is not a string literal type.
+     * - `untraced`: a handler handed a typed refuse whose function cannot be
+     *   found (a parameter, a dependency's value), so nothing it reaches was
+     *   checked.
+     */
+    problem: "undeclared" | "unused" | "uncoded" | "unreadable" | "untraced";
+    /** The code, for `undeclared` and `unused`. */
+    code?: string;
+    /** Where the refusal is raised, as `file:line`, for `undeclared`, `uncoded` and `unreadable`. */
+    raisedAt?: string;
+};
+export type LambderApiRefusalCheckResult = {
+    /** False when the project could not be read, no handler in it could be checked, or any handler has a finding. */
+    ok: boolean;
+    /** How many handlers were checked. */
+    handlers: number;
+    findings: LambderRefusalCheckFinding[];
+    /** What happened, as lines to print: a summary, then one line per finding. */
+    lines: string[];
+};
+/**
+ * Checks every handler of a project against the codes it may send, and
+ * answers what it found.
+ *
+ * ```ts
+ * import { checkApiRefusals } from "lambder/build";
+ *
+ * const result = await checkApiRefusals({ tsconfig: "server/tsconfig.json" });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * Run it where the app runs its other build checks, or from a test: it
+ * compiles the project, so it takes as long as a type check does.
+ */
+export declare const checkApiRefusals: (options: LambderApiRefusalCheckOptions) => Promise<LambderApiRefusalCheckResult>;