lambder 9.0.2 → 10.0.1

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

@@ -4,7 +4,7 @@
  * Contracts are built via method chaining and inferred using typeof lambder.ApiContract
  */
 import type { LambderCrashDetail } from "./LambderCrashDetail.js";
-import type { LambderAppRefusalMessage } from "./LambderApiRefusal.js";
+import type { LambderUncheckedRefusalMessage, LambderPlainRefusalMessage, LambderRefusalMessage } from "./LambderApiRefusal.js";
 import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "./LambderApiOptionValues.js";
 /** Whether an endpoint runs without a session or requires one (addApi versus addSessionApi). */
 export type LambderApiMode = "public" | "session";
@@ -30,26 +30,27 @@ export type LambderApiContractShape = Record<string, {
     rateLimit?: LambderRateLimitOptionValue;
     /** Present when the API declares idempotency: the `idempotency` option exactly as written. */
     idempotency?: LambderApiIdempotencyOption;
+    /** Present when the API can refuse with a declared code: each code mapped to `{ data }` or `{}`. See LambderContractRefusalsOf. */
+    refusals?: Record<string, {
+        data?: unknown;
+    }>;
 }>;
 /**
- * Envelope flags and channels beside (or instead of) the payload: what a
- * refusal, the pipeline's own answers, a hook or an error handler set. An API
- * handler sets none of them itself: it returns its output or refuses.
+ * What a refusal envelope may carry besides its null payload: the flags a
+ * caller routes on, the refusal's message, the call's logList, and a crash
+ * described for a caller allowed to see it. The one shape the envelope
+ * writer takes for every answer that is not a handler's output.
  */
-export type LambderApiResponseConfig = {
+export type LambderRefusalEnvelopeFields = {
     versionExpired?: boolean;
     sessionExpired?: boolean;
     notAuthorized?: boolean;
     /**
-     * A refusal message, or a plain string when writing (a refusal thrown
-     * with refuse(), or an error handler's `res.api(null, { errorMessage })`): the envelope goes out with
-     * the message object either way. Read off the wire it can still be a
-     * string, or no message at all, wherever a Lambder server did not write
-     * the body (a hand-built mock answer, a proxy); refusalMessageOf reads
-     * whatever arrives as a message.
+     * The refusal's message, or a plain string: the envelope goes out with
+     * the message object either way (refusalMessageOf).
      */
-    errorMessage?: LambderAppRefusalMessage | string;
-    logList?: any[];
+    refusal?: LambderUncheckedRefusalMessage | string;
+    logList?: unknown[];
     /**
      * A crash described in full (name, message, stack, cause chain, where it
      * happened), for a caller that is allowed to see it: a global error
@@ -60,16 +61,54 @@ export type LambderApiResponseConfig = {
     crash?: LambderCrashDetail;
 };
 /**
- * The API wire envelope both sides speak: the server writes it around a
- * handler's output or a refusal, LambderCaller parses it. `apiVersion` is always there (null when the server set none):
- * it is how a reader tells a Lambder envelope from another JSON answer, such
- * as API Gateway's own `{ "message": ... }` errors, so an answer without it
- * reads as a server failure.
+ * What `res.apiRefusal` writes: an answer to an API call from outside its
+ * handler (a hook, a fallback, the input validation handler, the global
+ * error handler). It is always a refusal, never a success: it carries an
+ * refusal or one of the three flags, which is what a reader tells it
+ * from a handler's output by, so a caller's success is only ever the
+ * handler's parsed output.
+ *
+ * Its message carries a framework code or none, and never data: it answers
+ * outside any one endpoint's declared refusals, which are what a reader's
+ * types allow.
  */
-export type LambderApiEnvelopeBody<T> = LambderApiResponseConfig & {
+export type LambderApiRefusalConfig = Omit<LambderRefusalEnvelopeFields, "refusal"> & {
+    refusal?: LambderPlainRefusalMessage | string;
+} & ({
+    refusal: LambderPlainRefusalMessage | string;
+} | {
+    versionExpired: true;
+} | {
+    sessionExpired: true;
+} | {
+    notAuthorized: true;
+});
+/** What every API envelope carries. `apiVersion` is always there (null when the server set none): it is how a reader tells a Lambder envelope from another JSON answer, such as API Gateway's own `{ "message": ... }` errors. */
+type LambderApiEnvelopeFields = {
     apiVersion: string | null;
-    payload?: T | null;
+    logList?: unknown[];
+};
+/** A handler's answer on the wire: its output, parsed through the API's output schema, and nothing else. */
+export type LambderApiSuccessEnvelope<T> = LambderApiEnvelopeFields & {
+    payload: T;
 };
+/**
+ * Every other answer on the wire: a null payload beside the refusal's
+ * message and flags. The flags are present only when set. `refusal` is
+ * as it came off the wire, which a reader normalizes (refusalMessageOf),
+ * since a body no Lambder server wrote (a hand-built mock answer, a proxy)
+ * can put anything there.
+ */
+export type LambderApiRefusalEnvelope = LambderApiEnvelopeFields & {
+    payload: null;
+    versionExpired?: true;
+    sessionExpired?: true;
+    notAuthorized?: true;
+    refusal?: LambderUncheckedRefusalMessage | string;
+    crash?: LambderCrashDetail;
+};
+/** The API wire envelope both sides speak: the server writes it, LambderCaller and LambderInvokeCaller read it. */
+export type LambderApiEnvelopeBody<T> = LambderApiSuccessEnvelope<T> | LambderApiRefusalEnvelope;
 /** A value that is already JSON, recursive structures such as z.json() included. */
 type LambderJsonValue = string | number | boolean | null | LambderJsonValue[] | {
     [key: string]: LambderJsonValue;
@@ -109,15 +148,6 @@ export type LambderJsonOf<T> = unknown extends T ? T : T extends LambderJsonValu
 } : T extends ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> ? {} : T extends object ? (Partial<Pick<T, LambderJsonOmissibleKeys<T>>> & Omit<T, LambderJsonOmissibleKeys<T>>) extends infer TKeyed ? {
     [K in keyof TKeyed as K extends string | number ? (string extends K ? K : number extends K ? K : [LambderJsonOf<TKeyed[K]>] extends [never] ? never : K) : never]: LambderJsonOf<TKeyed[K]>;
 } : never : never;
-/**
- * What an API's output reaches the client as: LambderJsonOf of the schema's
- * output, except at the top, where an envelope carries no payload at all
- * rather than a JSON `undefined`. A void or undefined output keeps its type,
- * so a handler and a mock handler answer nothing, and an output that may be
- * undefined keeps that member, which LambderJsonOf drops as it would a
- * member of an object.
- */
-export type LambderJsonOutputOf<T> = [T] extends [void] ? T : (undefined extends T ? undefined : never) | LambderJsonOf<T>;
 /**
  * One contract entry as addApi/addSessionApi record it: the payload types,
  * the mode, and every declarative option exactly as written. Options that
@@ -129,12 +159,19 @@ export type LambderJsonOutputOf<T> = [T] extends [void] ? T : (undefined extends
  * what it receives (the output schema's z.output as JSON, see
  * LambderJsonOf). The handler's own types are the other side of each, and
  * are not recorded here.
+ *
+ * `Refusals` is the one member not recorded as written: it is every code the
+ * endpoint can refuse with, its own `refusals` option and those of the guards
+ * it declares together, each mapped to `{ data }` (the data as JSON) or `{}`.
+ * A reader needs the whole set, and the guards' part is not in the entry.
  */
-export type LambderContractEntry<In, Out, Mode extends LambderApiMode, GuardInputs = never, Guards = never, RateLimit = never, Idempotency = never> = {
+export type LambderContractEntry<In, Out, Mode extends LambderApiMode, GuardInputs = never, Guards = never, RateLimit = never, Idempotency = never, Refusals = never> = {
     input: In;
     output: Out;
     mode: Mode;
-} & ([GuardInputs] extends [never] ? {} : {
+} & ([Refusals] extends [never] ? {} : {
+    refusals: Refusals;
+}) & ([GuardInputs] extends [never] ? {} : {
     guardInputs: GuardInputs;
 }) & ([Guards] extends [never] ? {} : {
     guards: Guards;
@@ -220,4 +257,32 @@ export type LambderContractRateLimitNames<C, M extends LambderApiMode = LambderA
 export type LambderContractIdempotencyOf<C, K extends keyof C> = C[K] extends {
     idempotency: infer I;
 } ? I : never;
+/**
+ * The codes endpoint K can refuse with, each mapped to `{ data }` or `{}`;
+ * `{}` when it declares none.
+ */
+export type LambderContractRefusalsOf<C, K extends keyof C> = C[K] extends {
+    refusals: infer R;
+} ? R : {};
+/**
+ * The refusal message a call to endpoint K can come back with: one arm per
+ * code it declares, plus the framework's and the uncoded refusal. An untyped
+ * contract (one with an index signature) is read as any code.
+ */
+export type LambderContractRefusalMessage<C, K extends keyof C> = 0 extends 1 & C ? LambderUncheckedRefusalMessage : string extends keyof C ? LambderUncheckedRefusalMessage : LambderRefusalMessage<LambderContractRefusalsOf<C, K>>;
+type LambderContractRefusalMaps<C> = {
+    [K in keyof C]: LambderContractRefusalsOf<C, K>;
+}[keyof C];
+type LambderContractRefusalCodes<C> = LambderContractRefusalMaps<C> extends infer TMap ? TMap extends unknown ? keyof TMap & string : never : never;
+/**
+ * Every code any endpoint of the contract declares, mapped to its `{ data }`
+ * or `{}`. Built code by code, not by joining the endpoints' own maps, so a
+ * code many endpoints declare is one arm rather than one per endpoint (the
+ * vocabulary gives a code one data shape wherever it is used).
+ */
+export type LambderContractRefusals<C> = {
+    [TCode in LambderContractRefusalCodes<C>]: Extract<LambderContractRefusalMaps<C>, Record<TCode, unknown>>[TCode];
+};
+/** The refusal message any call of the contract can come back with: what a handler for every endpoint at once (a caller's refusalHandler) is handed. */
+export type LambderContractAnyRefusalMessage<C> = 0 extends 1 & C ? LambderUncheckedRefusalMessage : string extends keyof C ? LambderUncheckedRefusalMessage : LambderRefusalMessage<LambderContractRefusals<C>>;
 export {};

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

@@ -16,8 +16,7 @@
  * declared here too and re-exported by the engines that read them.
  */
 import type { LambderApiMode, LambderGuardNamesIn } from "./LambderApiContract.js";
-import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "./LambderApiOptionValues.js";
-import type { LambderAppRefusalMessage } from "./LambderApiRefusal.js";
+import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitMessage, LambderRateLimitOptionValue, LambderRefusalsOptionValue } from "./LambderApiOptionValues.js";
 import type { LambderRateLimitPolicy } from "../contracts/LambderRateLimiter.js";
 /**
  * When a guard runs, relative to the API's input validation.
@@ -64,17 +63,19 @@ export type LambderRateLimitBudget = "perApi" | "perPolicy";
  */
 export type LambderRateLimitChargeAt = "beforeGuards" | "afterGuards";
 /**
- * One API as the generated module records it: its mode and its three
- * declarative options exactly as written at registration. A guard's
- * parameter is written as the JSON it is (a permission string, a list of
- * them, a reason), which is what makes the module plain data: a parameter
- * that is code or a class instance fails the write and names the API.
+ * One API as the generated module records it: its mode and its declarative
+ * options exactly as written at registration. A guard's parameter is written
+ * as the JSON it is (a permission string, a list of them, a reason), which is
+ * what makes the module plain data: a parameter that is code or a class
+ * instance fails the write and names the API. `refusals` is the API's own
+ * option; the codes its guards add are on their declarations.
  */
 export type LambderApiOptionEntry = {
     mode: LambderApiMode;
     guards?: LambderGuardsOptionValue;
     rateLimit?: LambderRateLimitOptionValue;
     idempotency?: LambderApiIdempotencyOption;
+    refusals?: LambderRefusalsOptionValue;
 };
 /**
  * One rate-limit policy as the generated module records it: its windows,
@@ -87,21 +88,27 @@ export type LambderRateLimitPolicyEntry = LambderRateLimitPolicy & {
     per?: "ip" | "session" | "custom";
     budget?: LambderRateLimitBudget;
     chargeAt?: LambderRateLimitChargeAt;
-    errorMessage?: LambderAppRefusalMessage;
+    refusal?: LambderRateLimitMessage;
 };
 /**
  * One guard as the generated module records it: how it is fed (a slice of
  * the API's own payload, a value the client sends separately, or nothing),
- * whether it needs a session, and when it runs. The schema behind an input
- * mode is never written; the mode alone is what a mock guard standing in for
- * it has to match.
+ * whether it needs a session, when it runs, and the refusal codes it
+ * declares, which join those of every API declaring it. The schema behind an
+ * input mode is never written; the mode alone is what a mock guard standing
+ * in for it has to match.
  */
 export type LambderGuardDeclarationEntry = {
     input: "apiInput" | "guardInput" | "none";
     session: boolean;
     runAt: LambderGuardRunAt;
+    refusals?: readonly string[];
 };
-/** Everything `lambder.apiOptionEntries()` reports, and the three tables the generated module exports. */
+/**
+ * Everything `lambder.apiOptionEntries()` reports, and the three tables the
+ * generated module exports. The refusal vocabulary is not among them: it is
+ * shared code, which the mock declares as the server does.
+ */
 export type LambderApiOptionEntries = {
     apis: Record<string, LambderApiOptionEntry>;
     rateLimitPolicies: Record<string, LambderRateLimitPolicyEntry>;

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

@@ -1,29 +1,38 @@
 /**
- * The runtime shapes of the three per-API policy options (guards, rate limit,
- * idempotency), declared below both the contract that records them and the
- * engines that enforce them so neither has to import the other.
+ * The runtime shapes of the per-API declarative options (guards, rate limit,
+ * idempotency, refusals), declared below both the contract that records them
+ * and the engines that enforce them so neither has to import the other.
  *
  * A contract type carries these options exactly as an API wrote them, and the
  * engines in `api/` read the same shapes back. Declaring them here is what
  * keeps `shared/` at the bottom of the stack: without it the contract would
  * name an `api/` type and `shared/` would depend on a layer above it.
  */
-import type { LambderAppRefusalMessage } from "./LambderApiRefusal.js";
+import type { LambderUncheckedRefusalMessage } from "./LambderApiRefusal.js";
 import type { LambderRateLimitPolicy } from "../contracts/LambderRateLimiter.js";
 /** The guards option's runtime shape: a name, ordered names, or a name-to-param map. */
 export type LambderGuardsOptionValue = string | readonly string[] | Readonly<Record<string, unknown>>;
+/**
+ * The message a rate-limit refusal carries, as a policy or an API writes it:
+ * its type, title and content. Its code is always `lambder/rate-limited` and
+ * it carries no data, so a rate limit is never a code an endpoint has to
+ * declare.
+ */
+export type LambderRateLimitMessage = Omit<LambderUncheckedRefusalMessage, "code" | "data">;
 /**
  * What an API may override on a policy it references, in the map form of the
  * rateLimit option. Windows merge over the policy's own (a tighter burst keeps
  * the policy's daily cap) and are only overridable on "perApi" budgets: a
- * shared counter has one set of numbers. errorMessage is per-API text, so it
+ * shared counter has one set of numbers. refusal is per-API text, so it
  * is overridable on either budget.
  */
 export type LambderRateLimitOverride = LambderRateLimitPolicy & {
-    errorMessage?: LambderAppRefusalMessage;
+    refusal?: LambderRateLimitMessage;
 };
 /** The rateLimit option's runtime shape: a name, ordered names, or a name-to-override map (LambderRateLimitOption narrows the names and overrides per policy). */
 export type LambderRateLimitOptionValue = string | readonly string[] | Readonly<Record<string, true | LambderRateLimitOverride | undefined>>;
+/** The refusals option's runtime shape: one code of the app's vocabulary, or a non-empty list of them. */
+export type LambderRefusalsOptionValue = string | readonly string[];
 /** The per-endpoint idempotency declaration: on, or on with its own replay TTL. */
 export type LambderApiIdempotencyOption = boolean | {
     /** Seconds this API's stored answer replays for; overrides defaultTtlSeconds. */

package/dist/shared/wire/LambderApiOptionValues.js

@@ -1,7 +1,7 @@
 /**
- * The runtime shapes of the three per-API policy options (guards, rate limit,
- * idempotency), declared below both the contract that records them and the
- * engines that enforce them so neither has to import the other.
+ * The runtime shapes of the per-API declarative options (guards, rate limit,
+ * idempotency, refusals), declared below both the contract that records them
+ * and the engines that enforce them so neither has to import the other.
  *
  * A contract type carries these options exactly as an API wrote them, and the
  * engines in `api/` read the same shapes back. Declaring them here is what

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

@@ -10,8 +10,8 @@
  * Pure and dependency-free, so the browser entry can include it.
  */
 import type { z } from "zod";
-import type { LambderApiEnvelopeBody } from "./LambderApiContract.js";
-import { type LambderAppRefusalMessage } from "./LambderApiRefusal.js";
+import type { LambderApiRefusalEnvelope, LambderApiSuccessEnvelope } from "./LambderApiContract.js";
+import { type LambderUncheckedRefusalMessage } from "./LambderApiRefusal.js";
 /**
  * The 422 body's `zodError` as it survives JSON: a ZodError's name and
  * message, and its issues spelled out. Not a ZodError instance (it has no
@@ -22,22 +22,33 @@ export type LambderValidationError = {
     message: string;
     issues: z.core.$ZodIssue[];
 };
-export type LambderApiFailureReason = 'network' | 'timeout' | 'server' | 'validation' | 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'errorMessage' | 'unknown';
-/** A call that produced an answer the server means as a result. */
+export type LambderApiFailureReason = 'network' | 'timeout' | 'server' | 'validation' | 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'refusal' | 'unknown';
+/**
+ * The endpoint's handler answered: `payload` is its output, parsed through
+ * the API's output schema on the server, exactly the contract's type. Only a
+ * handler's answer reads as a success: everything else the server writes
+ * into an API call is a refusal (see LambderApiRefusalConfig), and a reader
+ * refuses a success whose payload is not an object (see isObjectPayload).
+ */
 export type LambderApiSuccessOutcome<T> = {
     ok: true;
-    payload: T | null | undefined;
-    response: LambderApiEnvelopeBody<T>;
+    payload: T;
+    response: LambderApiSuccessEnvelope<T>;
     /** The answer's logList, when it carried one. See LambderApiFailureFields.logList: the field is on every arm so a caller surfaces logs once. */
     logList?: unknown[];
 };
-/** What every failure carries, whatever went wrong. */
-type LambderApiFailureFields = {
+/**
+ * What every failure carries, whatever went wrong. TMessage is the refusal
+ * message the endpoint can answer with (LambderContractRefusalMessage), on
+ * every arm: a refusal flagged notAuthorized arrives as that reason and still
+ * carries its message.
+ */
+type LambderApiFailureFields<TMessage extends LambderUncheckedRefusalMessage> = {
     ok: false;
     /** HTTP status, when a response was received. */
     status?: number;
-    /** Envelope errorMessage, when the server provided one: always the message object, a plain string having been read as one (refusalMessageOf). */
-    errorMessage?: LambderAppRefusalMessage;
+    /** The envelope's refusal, when the server provided one: always the message object, a plain string having been read as one (refusalMessageOf). */
+    refusal?: TMessage;
     /** Seconds to wait before retrying, from the response's Retry-After header (rate-limit refusals send it, and so may a 503). */
     retryAfterSeconds?: number;
     /**
@@ -57,36 +68,37 @@ type LambderApiFailureFields = {
  * A 5xx also carries `response` when the server answered with Lambder's own
  * envelope, which is how a crash detail and a logList arrive with it.
  */
-export type LambderApiCallFailure<T> = LambderApiFailureFields & {
+export type LambderApiCallFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderApiFailureFields<TMessage> & {
     reason: 'network' | 'timeout' | 'server' | 'unknown';
     error: Error;
-    response?: LambderApiEnvelopeBody<T>;
+    response?: LambderApiRefusalEnvelope;
 };
 /** HTTP 422: the server rejected the input against the API's schema. Always carries the issues. */
-export type LambderApiValidationFailure = LambderApiFailureFields & {
+export type LambderApiValidationFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderApiFailureFields<TMessage> & {
     reason: 'validation';
     zodError: LambderValidationError;
 };
-/** The server answered, and the envelope itself says the call is refused. Always carries that envelope, and an `errorMessage` refusal always carries its message. */
-export type LambderApiEnvelopeFailure<T> = LambderApiFailureFields & {
-    response: LambderApiEnvelopeBody<T>;
+/** The server answered, and the envelope itself says the call is refused. Always carries that envelope, and a `refusal` failure always carries the refusal. */
+export type LambderApiEnvelopeFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderApiFailureFields<TMessage> & {
+    response: LambderApiRefusalEnvelope;
 } & ({
     reason: 'versionExpired' | 'sessionExpired' | 'notAuthorized';
 } | {
-    reason: 'errorMessage';
-    errorMessage: LambderAppRefusalMessage;
+    reason: 'refusal';
+    refusal: TMessage;
 });
 /**
- * Discriminated result of an API call: `ok: true` carries the payload, every
- * failure carries a machine-readable reason, so "the server returned null"
- * and "the request failed" are never conflated.
+ * Discriminated result of an API call: `ok: true` carries the handler's
+ * output, every failure carries a machine-readable reason, so "the server
+ * answered" and "the request failed" are never conflated.
  *
  * The failure side is discriminated by `reason`, so narrowing to a reason
  * narrows to what it carries: `zodError` after `reason === 'validation'`,
  * `response` after an envelope reason, `error` after the rest, with no
- * non-null assertion needed.
+ * non-null assertion needed. TMessage is the endpoint's refusal message
+ * (LambderContractRefusalMessage), which `refusal.code` narrows.
  */
-export type LambderApiOutcome<T> = LambderApiSuccessOutcome<T> | LambderApiCallFailure<T> | LambderApiValidationFailure | LambderApiEnvelopeFailure<T>;
+export type LambderApiOutcome<T, TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderApiSuccessOutcome<T> | LambderApiCallFailure<TMessage> | LambderApiValidationFailure<TMessage> | LambderApiEnvelopeFailure<TMessage>;
 /**
  * What reading one HTTP answer can produce: LambderApiOutcome minus the
  * three reasons no answer carries (`network` and `timeout` are the caller's
@@ -94,9 +106,9 @@ export type LambderApiOutcome<T> = LambderApiSuccessOutcome<T> | LambderApiCallF
  * has handled `server` and `validation` holds a success or an envelope
  * refusal, both of which carry the envelope.
  */
-export type LambderApiAnswerOutcome<T> = LambderApiSuccessOutcome<T> | (LambderApiCallFailure<T> & {
+export type LambderApiAnswerOutcome<T, TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderApiSuccessOutcome<T> | (LambderApiCallFailure<TMessage> & {
     reason: 'server';
-}) | LambderApiValidationFailure | LambderApiEnvelopeFailure<T>;
+}) | LambderApiValidationFailure<TMessage> | LambderApiEnvelopeFailure<TMessage>;
 /**
  * What the mapping needs from an HTTP answer, whichever transport produced it.
  *
@@ -130,11 +142,21 @@ export type LambderApiHttpAnswer = {
 /**
  * Reads one HTTP answer into an outcome. A 5xx is a server failure that keeps
  * the envelope when the server sent one (Lambder's own 500 body carries
- * errorMessage, and a global error handler may add crash and logList); a
+ * refusal, and a global error handler may add crash and logList); a
  * 422 is a validation failure only with Lambder's validation body; anything
  * else must be a JSON envelope, whose flags are honoured in a fixed order.
  * A failure read off any answer but a 422 carries the answer's Retry-After
  * as retryAfterSeconds.
+ *
+ * A success is a 2xx envelope with no flag and no refusal whose payload
+ * is an object or an array: what only a handler's parsed output is. Anything
+ * else that says nothing is wrong (a null or primitive payload a hand-built
+ * body, a proxy or an old stored answer carries) is a server failure, so a
+ * success's payload is always the contract's output and never falsy.
+ *
+ * TMessage is the endpoint's refusal message type: the reader cannot check
+ * a code against declarations it does not have, and relies on the server,
+ * which never sends a code the endpoint did not declare.
  */
-export declare const resolveApiOutcome: <T>(answer: LambderApiHttpAnswer) => Promise<LambderApiAnswerOutcome<T>>;
+export declare const resolveApiOutcome: <T, TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage>(answer: LambderApiHttpAnswer) => Promise<LambderApiAnswerOutcome<T, TMessage>>;
 export {};

package/dist/shared/wire/LambderApiOutcome.js

@@ -10,6 +10,7 @@
  * Pure and dependency-free, so the browser entry can include it.
  */
 import { refusalMessageOf } from "./LambderApiRefusal.js";
+import { isObjectPayload } from "./LambderObjectPayload.js";
 /**
  * Whether a parsed body is Lambder's envelope, which always carries
  * apiVersion (null when the server set none). An object without it is
@@ -21,15 +22,25 @@ const isApiEnvelope = (value) => value !== null && typeof value === "object" &&
 /**
  * Reads one HTTP answer into an outcome. A 5xx is a server failure that keeps
  * the envelope when the server sent one (Lambder's own 500 body carries
- * errorMessage, and a global error handler may add crash and logList); a
+ * refusal, and a global error handler may add crash and logList); a
  * 422 is a validation failure only with Lambder's validation body; anything
  * else must be a JSON envelope, whose flags are honoured in a fixed order.
  * A failure read off any answer but a 422 carries the answer's Retry-After
  * as retryAfterSeconds.
+ *
+ * A success is a 2xx envelope with no flag and no refusal whose payload
+ * is an object or an array: what only a handler's parsed output is. Anything
+ * else that says nothing is wrong (a null or primitive payload a hand-built
+ * body, a proxy or an old stored answer carries) is a server failure, so a
+ * success's payload is always the contract's output and never falsy.
+ *
+ * TMessage is the endpoint's refusal message type: the reader cannot check
+ * a code against declarations it does not have, and relies on the server,
+ * which never sends a code the endpoint did not declare.
  */
 export const resolveApiOutcome = async (answer) => {
     const status = answer.status;
-    const errorMessageOf = (envelope) => envelope?.errorMessage !== undefined ? { errorMessage: refusalMessageOf(envelope.errorMessage) } : {};
+    const refusalOf = (envelope) => envelope?.refusal !== undefined ? { refusal: refusalMessageOf(envelope.refusal) } : {};
     // Retry-After (delta-seconds) rides every refusal that knows its reset
     // time, e.g. a rate limit, and a 503 that says when to come back; absent
     // or unreadable is undefined.
@@ -53,7 +64,7 @@ export const resolveApiOutcome = async (answer) => {
         catch { /* body unavailable */ }
         return {
             ok: false, reason: 'server', status,
-            ...errorMessageOf(envelope),
+            ...refusalOf(envelope),
             logList: envelope?.logList,
             ...(envelope ? { response: envelope } : {}),
             error: new Error("Request failed: " + status + " - " + (answer.statusText ?? "")),
@@ -91,21 +102,27 @@ export const resolveApiOutcome = async (answer) => {
         const gatewayMessage = typeof data.message === "string" ? `: ${data.message}` : "";
         return { ok: false, reason: 'server', status, error: new Error(`Request failed: ${status} - the answer is not a Lambder envelope${gatewayMessage}`), ...retryAfter };
     }
+    const asRefusal = data;
     if (data.versionExpired)
-        return { ok: false, reason: 'versionExpired', status, ...errorMessageOf(data), response: data, logList: data.logList, ...retryAfter };
+        return { ok: false, reason: 'versionExpired', status, ...refusalOf(data), response: asRefusal, logList: data.logList, ...retryAfter };
     if (data.sessionExpired)
-        return { ok: false, reason: 'sessionExpired', status, ...errorMessageOf(data), response: data, logList: data.logList, ...retryAfter };
+        return { ok: false, reason: 'sessionExpired', status, ...refusalOf(data), response: asRefusal, logList: data.logList, ...retryAfter };
     if (data.notAuthorized)
-        return { ok: false, reason: 'notAuthorized', status, ...errorMessageOf(data), response: data, logList: data.logList, ...retryAfter };
-    // Presence, not truthiness: the writer keeps an errorMessage an app set
+        return { ok: false, reason: 'notAuthorized', status, ...refusalOf(data), response: asRefusal, logList: data.logList, ...retryAfter };
+    // Presence, not truthiness: the writer keeps a refusal an app set
     // to the empty string, and a refusal that says nothing is still a
     // refusal, not a success.
-    if (data.errorMessage !== undefined)
-        return { ok: false, reason: 'errorMessage', status, errorMessage: refusalMessageOf(data.errorMessage), response: data, logList: data.logList, ...retryAfter };
+    if (data.refusal !== undefined)
+        return { ok: false, reason: 'refusal', status, refusal: refusalMessageOf(data.refusal), response: asRefusal, logList: data.logList, ...retryAfter };
     // An envelope that says nothing is wrong is still not a success when the
-    // status says otherwise.
+    // status says otherwise, nor when its payload is not what a handler
+    // answers. Neither is a refusal either, so neither carries the body as
+    // one: the error says what it was.
     if (status < 200 || status >= 300) {
-        return { ok: false, reason: 'server', status, response: data, logList: data.logList, error: new Error(`Request failed: ${status} - ${answer.statusText ?? ""}`), ...retryAfter };
+        return { ok: false, reason: 'server', status, logList: data.logList, error: new Error(`Request failed: ${status} - ${answer.statusText ?? ""}`), ...retryAfter };
+    }
+    if (!isObjectPayload(data.payload)) {
+        return { ok: false, reason: 'server', status, logList: data.logList, error: new Error("Request failed: the answer's payload is not an object or an array, so no handler of this API wrote it") };
     }
     return { ok: true, payload: data.payload, response: data, logList: data.logList };
 };