lambder 8.3.1 → 9.0.1

package/CHANGELOG.md

@@ -9,6 +9,78 @@ 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.
 
+## [9.0.1] - 2026-09-27
+
+A major that gives an API handler one shape. It takes its context and returns
+its output; it says no with `refuse()`; it writes headers, cookies and log
+entries through the context. The response builder stays with routes, hooks,
+fallbacks and error handlers, which build HTTP responses. An API is typed data
+in and typed data out, and a handler that has no response builder cannot
+answer any other way, so the two ways a handler used to refuse (throwing, or
+answering null beside a reason) are one, and the untyped side channels are
+gone. A server handler and its mock twin now read alike.
+
+### Changed (breaking)
+
+- **An API handler returns its output.** `addApi` and `addSessionApi` take
+  `async (ctx) => output` instead of `async (ctx, res) => res.api(output)`.
+  The return is checked against the output schema's input form and parsed
+  through the schema before it is sent, as `res.api()`'s payload was:
+  undeclared fields are stripped, defaults filled, transforms run once, and
+  an output the schema rejects is answered as a crash
+  (`LambderApiOutputValidationError`). A literal in a returned object keeps
+  its type (`{ status: "open" }` is checked as `"open"`, not `string`), which
+  is why the handler's return is its own `const` type parameter; arrays in a
+  returned literal are read as readonly, which is all an answer needs.
+  - To move: drop the second parameter and return what was passed to
+    `res.api()`. An answer that was `res.api(null, { errorMessage })`,
+    `{ notAuthorized }` or `{ sessionExpired }` becomes `refuse(content, {
+    notAuthorized, sessionExpired, code, type })`. A handler that answered
+    null where the output does not allow null no longer compiles; it refuses
+    instead, or the output becomes nullable.
+- **A refusal is never stored for replay.** Only an answer (a returned
+  output) is stored under an idempotency key; a refusal is thrown, the claim
+  is released, and a retry runs the handler again, which decides afresh. A
+  corrected request after a refusal goes through under the same key instead
+  of being refused as a reused key.
+- **Response headers and cookies are written through the context.**
+  `ctx.setResponseHeader(key, value)`, `ctx.addResponseHeader(key, value)`,
+  `ctx.setCookie(name, value, options?)` and `ctx.clearCookie(name,
+  options?)` (the type `LambderResponseTools`) are on every context: routes,
+  API handlers, hooks, and mock handlers alike. `res.setHeader`,
+  `res.addHeader`, `res.setCookie` and `res.clearCookie` are removed. The
+  writers say "Response" because `ctx.header(name)` reads a request header.
+- **The log channel is `ctx.logList`.** `res.logToApiResponse(entry)` is
+  removed; push the entry onto `ctx.logList`, which the mock's context has
+  always had.
+- **Answer compression is declared per API.** `addApi` and `addSessionApi`
+  take `compress?: boolean | "auto"` beside the other options: "auto" (the
+  default) compresses for an accepting caller when the body is large enough,
+  false never (an answer carrying base64 bytes), true always. It covers
+  refusals and replayed answers too, and is a transport setting of the
+  server, not part of the contract. `res.apiBinary()` and the per-answer
+  response options of an API handler (status code, compression, cache
+  headers) are removed; a header goes through `ctx.setResponseHeader`.
+- **`res.api()` writes an envelope by hand, for code outside an API
+  handler.** A hook, the input validation handler or a global error handler
+  answering an API call still uses it; the payload goes out as given. The
+  typed overloads and `LambderResolver`'s output type parameter are removed,
+  with the types `LambderResolverApiMethod` and `LambderApiNullAnswerConfig`.
+  A binary or file answer is a route's job.
+
+### Removed
+
+- **The `message` envelope channel.** The untyped `message` field of the
+  envelope and of `LambderApiResponseConfig`, `LambderCaller`'s
+  `messageHandler` option and per-call override, and the mock's
+  `ctx.envelope`. What a success says belongs in the output schema, where it
+  is typed and parsed.
+
+### Added
+
+- `LambderResponseTools`, the type of the four response writers every
+  context carries, exported from `lambder`.
+
 ## [8.3.1] - 2026-09-27
 
 Six additions, each a thing an app otherwise writes for itself once per kind

package/README.md

@@ -17,15 +17,17 @@ const lambder = initLambder<SessionData>().create({
 }).addApi("getCompany", {
     input: z.object({ slug: z.string() }),
     output: z.object({ id: z.string(), name: z.string() }),
-}, async ({ apiPayload }, res) => res.api(await loadCompany(apiPayload.slug)));
+}, async ({ apiPayload }) => await loadCompany(apiPayload.slug));
 
 export type ApiContractType = typeof lambder.ApiContract;
 export const handler = lambder.getHandler();
 ```
 
-Registration chains onto the creation call: every `addApi` returns an instance
-carrying the contract so far, so the whole backend is one declaration and
-`lambder.ApiContract` is the accumulated type.
+A handler returns its output, which is parsed through the output schema before
+it is sent, and says no by throwing `refuse()`. Registration chains onto the
+creation call: every `addApi` returns an instance carrying the contract so
+far, so the whole backend is one declaration and `lambder.ApiContract` is the
+accumulated type.
 
 The frontend imports that contract type and gets autocomplete, typed payloads
 and typed results with no hand-written client:
@@ -153,7 +155,7 @@ guide that matches what you are building. The full index lives in
 | [Configuration](./docs/configuration.md) | Every `initLambder().create({...})` option, in one reference |
 | [Routing and actions](./docs/routing.md) | Routes, matchers, hooks, fallbacks, crash reporting, and non-HTTP invocations |
 | [APIs and refusals](./docs/apis.md) | `addApi`/`addSessionApi`, the inferred contract, `refuse()` and `LambderApiRefusal`, the signature file |
-| [Responses](./docs/responses.md) | The render context, resolver methods, cookies, compression, ETag and the size cap |
+| [Responses](./docs/responses.md) | The render context and its response tools (headers, cookies, log entries), the response builder routes and hooks use, compression, ETag and the size cap |
 | [Sessions](./docs/sessions.md) | Sessions over a store, cookie scope, secrets at rest, `dataRefresh`, the controller API |
 | [API policies](./docs/api-policies.md) | Declarative rate limits, guards and idempotency, and mandatory authorization declarations |
 | [Calling another lambda](./docs/invoke.md) | `LambderInvokeCaller`: invoking a Lambder app in another function, its contract, failures and compression |
@@ -185,25 +187,14 @@ framework:
 ## Versioning and changes
 
 Released versions and what each one changed are in
-[CHANGELOG.md](./CHANGELOG.md). The current major is v8, which came out of a
-review of 7.3.1: session writes that cannot undo a logout, API calls that must
-be JSON, output schemas applied at runtime, rate limits that count IPv6 callers
-by their /64 and custom keys after the guards, idempotency keys bound to the
-request they were first sent with, and the same behavior on every gateway and
-in the mock. Every break and what to do about it is in the 8.0.2 entry. The
-compiler finds most of them. Fourteen it cannot are named there: hand-built
-calls without a JSON Content-Type, hand-built answers without `apiVersion`,
-handlers whose payload does not match their output schema, code that decoded
-`ctx.path` itself, string routes that match case-sensitively, compression
-behind a REST API, two more IAM actions (`UpdateItem` on the session table,
-`GetItem` on the rate-limit table), custom-key limits charged after the
-guards, idempotency keys bound to the request they were first sent with,
-`errorMessage` always being an object, `credentials: true` needing named
-origins, template slots and `html` interpolations refused or checked in
-more attribute positions, `refreshSessionData()` throwing where it answered
-null, and `z.ZodType<T>` annotations leaving a field unchecked. Every live
-session is signed out once by the
-upgrade. An app still on v6 goes through the 7.0.0 entry first.
+[CHANGELOG.md](./CHANGELOG.md). The current major is v9, which gives an API
+handler one shape: it takes its context and returns its output, says no with
+`refuse()`, and writes headers, cookies and log entries through the context,
+while the response builder stays with routes, hooks and error handlers. Every
+break and what to do about it is in the 9.0.1 entry, and the compiler finds
+most of them. An app still on v7 goes through the 8.0.2 entry first, which
+names the breaks of v8 the compiler cannot find, and one on v6 through the
+7.0.0 entry before that.
 
 ## Contributing
 

package/dist/api/LambderApiCallContext.d.ts

@@ -1,5 +1,6 @@
 import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
+import { type LambderCookieOptions, type LambderClearCookieOptions } from "../shared/wire/LambderCookie.js";
 /**
  * The context the API core needs from whoever runs it. The server's render
  * context and the mock runtime's handler context both extend it; the
@@ -12,7 +13,7 @@ import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
  * - `responseHeaders` collects headers written during the call, applied
  *   onto the answer by the pipeline.
  * - `logList` collects entries for the envelope's logList channel
- *   (`res.logToApiResponse` on the server).
+ *   (`ctx.logList.push(entry)` from a handler).
  */
 export type LambderApiCallContext<TSessionData = any> = {
     session: LambderSessionRecord<TSessionData> | null;
@@ -22,6 +23,35 @@ export type LambderApiCallContext<TSessionData = any> = {
 };
 /** A fresh call context: no session, no guard data, nothing pending. */
 export declare const createApiCallContext: <TSessionData = any>() => LambderApiCallContext<TSessionData>;
+/**
+ * What a handler writes onto its answer beside the body: headers and cookies,
+ * collected on `responseHeaders` and applied to whatever answer the request
+ * ends with. On every context a handler receives, the server's and the
+ * mock's alike, since an API handler returns its output and has no response
+ * builder to write them on.
+ */
+export type LambderResponseTools = {
+    /** Replaces a response header. */
+    setResponseHeader(key: string, value: string | string[]): void;
+    /** Appends a response header value (repeatable for one key). */
+    addResponseHeader(key: string, value: string): void;
+    /**
+     * Adds a Set-Cookie header. A function-form `domain` is resolved against
+     * the request host. Defaults: Path=/, SameSite=Lax, Secure, not HttpOnly,
+     * browser-session lifetime.
+     */
+    setCookie(name: string, value: string, options?: LambderCookieOptions): void;
+    /**
+     * Adds a Set-Cookie header that deletes the cookie. Pass the `domain` and
+     * `path` it was set with: a cookie's identity is (name, domain, path), and
+     * a deletion under another scope deletes nothing.
+     */
+    clearCookie(name: string, options?: LambderClearCookieOptions): void;
+};
+/** The response tools of one context, writing into its own responseHeaders; `host` resolves a function-form cookie domain. */
+export declare const responseToolsOf: (ctx: {
+    responseHeaders: LambderAnswerHeaders;
+}, host: string) => LambderResponseTools;
 /**
  * Binds an adapter's tools onto one call context: `getters` run when read
  * (`ctx.sessionController` is built over the object it was read from),

package/dist/api/LambderApiCallContext.js

@@ -1,4 +1,5 @@
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
+import { serializeCookie, serializeClearCookie } from "../shared/wire/LambderCookie.js";
 /** A fresh call context: no session, no guard data, nothing pending. */
 export const createApiCallContext = () => ({
     session: null,
@@ -10,6 +11,13 @@ export const createApiCallContext = () => ({
     responseHeaders: new LambderAnswerHeaders(),
     logList: [],
 });
+/** The response tools of one context, writing into its own responseHeaders; `host` resolves a function-form cookie domain. */
+export const responseToolsOf = (ctx, host) => ({
+    setResponseHeader: (key, value) => { ctx.responseHeaders.set(key, value); },
+    addResponseHeader: (key, value) => { ctx.responseHeaders.add(key, value); },
+    setCookie: (name, value, options) => { ctx.responseHeaders.add("Set-Cookie", serializeCookie(name, value, options, host)); },
+    clearCookie: (name, options) => { ctx.responseHeaders.add("Set-Cookie", serializeClearCookie(name, options, host)); },
+});
 /**
  * Binds an adapter's tools onto one call context: `getters` run when read
  * (`ctx.sessionController` is built over the object it was read from),

package/dist/api/LambderApiDefinition.d.ts

@@ -8,8 +8,8 @@ import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRate
  * because the mock has none; when input is present, validation runs and the
  * handler sees the parsed payload. Output is part of the endpoint's
  * signature (apiSignatureOf), which is what a client's build is checked
- * against; the server's resolver also parses every payload a handler
- * answers through it before it is sent.
+ * against; the server also parses every output a handler returns through it
+ * before it is sent.
  */
 export type LambderApiDefinition = {
     name: string;

package/dist/api/LambderApiEnvelope.d.ts

@@ -13,7 +13,7 @@ export type LambderApiEnvelopeConfig = LambderApiResponseConfig & {
  * plain success is `{ apiVersion, payload }` and nothing else; an empty
  * logList is omitted.
  */
-export declare const buildApiEnvelope: <T>(apiVersion: string | null | undefined, payload: T | null, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, crash, }?: LambderApiEnvelopeConfig) => LambderApiEnvelopeBody<T>;
+export declare const buildApiEnvelope: <T>(apiVersion: string | null | undefined, payload: T | null, { versionExpired, sessionExpired, notAuthorized, errorMessage, logList, crash, }?: LambderApiEnvelopeConfig) => LambderApiEnvelopeBody<T>;
 /** An envelope as an answer: JSON body, JSON content type, the status and headers given (200 and none by default). */
 export declare const envelopeAnswer: (envelope: LambderApiEnvelopeBody<unknown>, options?: {
     statusCode?: number;

package/dist/api/LambderApiEnvelope.js

@@ -4,8 +4,8 @@ import { setAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
  * The one place the API envelope is written, and the one mapping from each
  * kind of protocol outcome onto an answer: a success, a thrown refusal, a
  * rejected input, an unknown name, a missing session, a stale client, a
- * malformed compressed payload, and the last-resort crash. The server's
- * res.api(), the mock runtime and the pipeline all build through these
+ * malformed compressed payload, and the last-resort crash. The server's API
+ * path and res.api(), the mock runtime and the pipeline all build through these
  * functions, so server and mock cannot drift on a single byte of the wire
  * format. Pure: no Node built-ins, no response classes.
  */
@@ -15,7 +15,7 @@ export const API_ANSWER_CONTENT_TYPE = "application/json; charset=utf-8";
  * plain success is `{ apiVersion, payload }` and nothing else; an empty
  * logList is omitted.
  */
-export const buildApiEnvelope = (apiVersion, payload, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, crash, } = {}) => ({
+export const buildApiEnvelope = (apiVersion, payload, { versionExpired, sessionExpired, notAuthorized, errorMessage, logList, crash, } = {}) => ({
     apiVersion: apiVersion ?? null,
     payload,
     ...(versionExpired ? { versionExpired } : {}),
@@ -26,7 +26,6 @@ export const buildApiEnvelope = (apiVersion, payload, { versionExpired, sessionE
     // flags above are booleans, where false and absent mean the same. An
     // errorMessage goes out as a message object whatever form it was written
     // in, so every reader meets one shape.
-    ...(message !== undefined ? { message } : {}),
     ...(errorMessage !== undefined ? { errorMessage: refusalMessageOf(errorMessage) } : {}),
     ...(crash !== undefined ? { crash } : {}),
     ...(logList?.length ? { logList } : {}),

package/dist/api/LambderApiIdempotency.js

@@ -386,13 +386,11 @@ export class LambderApiIdempotencyEngine {
             }
             // A crash or a thrown refusal (LambderApiRefusal, refuse())
             // releases the claim so a retry retries. The rule is deliberate:
-            // ANSWERS are stored and replayed, returned refusal envelopes
-            // included; EXCEPTIONS are not, so a thrown refusal re-executes
-            // on retry and the handler decides afresh. (On the server,
-            // res.die.api() is an answer: the adapter catches it before it
-            // reaches here.) The handler's own error is what gets rethrown,
-            // since a cleanup error in its place would hide why the call
-            // failed.
+            // ANSWERS (the output a handler returned) are stored and
+            // replayed; EXCEPTIONS are not, so a thrown refusal re-executes
+            // on retry and the handler decides afresh. The handler's own
+            // error is what gets rethrown, since a cleanup error in its place
+            // would hide why the call failed.
             try {
                 await store.abandon(scopeKey, ownerToken);
             }

package/dist/client/LambderCaller.d.ts

@@ -29,7 +29,6 @@ type FetchEndEventHandler = (params: {
 }) => void | Promise<void>;
 type ErrorHandler = (err: Error) => void | Promise<void>;
 type ValidationErrorHandler = (zodError: LambderValidationError) => (void | false) | Promise<(void | false)>;
-type MessageHandler = (message: LambderAppRefusalMessage | string) => void | Promise<void>;
 /** Handed the refusal as its message object, a plain-string errorMessage having been read as one (refusalMessageOf). */
 type ErrorMessageHandler = (message: LambderAppRefusalMessage) => 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. */
@@ -41,7 +40,6 @@ export type LambderLogListHandler = (apiName: string, logList: unknown[]) => voi
 export type LambderCallOptions = LambderSharedCallOptions & {
     versionExpiredHandler?: NotifyHandler;
     sessionExpiredHandler?: NotifyHandler;
-    messageHandler?: MessageHandler;
     errorMessageHandler?: ErrorMessageHandler;
     apiInputValidationErrorHandler?: ValidationErrorHandler;
     notAuthorizedHandler?: NotifyHandler;
@@ -73,7 +71,6 @@ type LambderCallerBaseOptions = {
     timeoutMs?: number;
     versionExpiredHandler?: NotifyHandler;
     sessionExpiredHandler?: NotifyHandler;
-    messageHandler?: MessageHandler;
     errorMessageHandler?: ErrorMessageHandler;
     notAuthorizedHandler?: NotifyHandler;
     errorHandler?: ErrorHandler;
@@ -119,7 +116,6 @@ export default class LambderCaller<TContract extends LambderApiContractShape = a
     get isLoading(): boolean;
     private versionExpiredHandler?;
     private sessionExpiredHandler?;
-    private messageHandler?;
     private errorMessageHandler?;
     private notAuthorizedHandler?;
     private errorHandler?;

package/dist/client/LambderCaller.js

@@ -33,7 +33,6 @@ export default class LambderCaller {
     get isLoading() { return this.fetchTrackerList.length > 0; }
     versionExpiredHandler;
     sessionExpiredHandler;
-    messageHandler;
     errorMessageHandler;
     notAuthorizedHandler;
     errorHandler;
@@ -50,7 +49,7 @@ export default class LambderCaller {
     constructor(options) {
         // The conditional provider option is resolved per instantiation;
         // inside the class it is read through the plain shape.
-        const { apiPath, apiVersion, apiSignatures, isCorsEnabled, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, logListHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, requestCompression, guardInputsProvider, transport, } = options;
+        const { apiPath, apiVersion, apiSignatures, isCorsEnabled, timeoutMs, versionExpiredHandler, sessionExpiredHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, logListHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, requestCompression, guardInputsProvider, transport, } = options;
         this.apiPath = apiPath;
         this.apiVersion = apiVersion;
         this.apiSignatures = apiSignatures;
@@ -61,7 +60,6 @@ export default class LambderCaller {
         this.transport = transport ?? lambderFetchTransport({ cors: isCorsEnabled });
         this.versionExpiredHandler = versionExpiredHandler;
         this.sessionExpiredHandler = sessionExpiredHandler;
-        this.messageHandler = messageHandler;
         this.errorMessageHandler = errorMessageHandler;
         this.notAuthorizedHandler = notAuthorizedHandler;
         this.errorHandler = errorHandler;
@@ -100,7 +98,6 @@ export default class LambderCaller {
         // Per-call overrides win over the constructor handlers.
         const versionExpiredHandler = options?.versionExpiredHandler ?? this.versionExpiredHandler;
         const sessionExpiredHandler = options?.sessionExpiredHandler ?? this.sessionExpiredHandler;
-        const messageHandler = options?.messageHandler ?? this.messageHandler;
         const errorMessageHandler = options?.errorMessageHandler ?? this.errorMessageHandler;
         const notAuthorizedHandler = options?.notAuthorizedHandler ?? this.notAuthorizedHandler;
         const errorHandler = options?.errorHandler ?? this.errorHandler;
@@ -328,11 +325,6 @@ export default class LambderCaller {
                 }
                 return outcome;
             }
-            // Presence, not truthiness: the envelope keeps a message an app
-            // spelled out as the empty string, so the handler runs for it.
-            if (data.message !== undefined && messageHandler) {
-                await messageHandler(data.message);
-            }
             if (!outcome.ok && outcome.reason === 'errorMessage') {
                 if (errorMessageHandler && outcome.errorMessage !== undefined) {
                     await errorMessageHandler(outcome.errorMessage);

package/dist/core/Lambder.d.ts

@@ -21,7 +21,7 @@ import type { LambderApiRateLimitPolicyConfig, LambderRateLimitOption } from "..
 import type { LambderApiIdempotencyConfig } from "../api/LambderApiIdempotency.js";
 import type { LambderContractEntry, LambderJsonOutputOf, LambderMergeContract } from "../shared/wire/LambderApiContract.js";
 import { type LambderHttpEvent, type LambderRenderContext, type LambderSessionRenderContext } from "./LambderContext.js";
-import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
+import type { LambderReadonlyDeep, MaybePromise } from "../shared/util/LambderTypeUtilities.js";
 import { type LambderRouteHandler, type LambderInputValidationHandler, type LambderFallbackHandler, type LambderGlobalErrorHandler, type LambderAfterRenderHook, type LambderBeforeRenderHook, type LambderFallbackHook, type LambderActionTools, type LambderCreateOptions, type LambderGivenOption, type LambderHandler, type LambderNestedOptionChecks, type LambderNoExtraKeys, type LambderRequirableGuardsField, type LambderSessionEnabledInstance, type LambderSessionRouteHandler } from "./LambderCreateOptions.js";
 /** Everything `lambder/testing` may put under a built instance: the pipeline's stores, and the source its files are read from. */
 export type LambderInstanceBackends = LambderPipelineBackends & {
@@ -155,7 +155,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     addRoute(condition: RegExp | LambderRouteConditionFn | LambderRouteMatcher, actionFn: LambderRouteHandler): this;
     addSessionRoute<TPath extends LambderRoutePath>(condition: TPath, actionFn: ((ctx: LambderSessionRenderContext<any, TSessionData, LambderPathParamsOf<TPath>, {}, _TRateLimitPolicies>, resolver: LambderResolver) => MaybePromise<LambderResponse>) & LambderSessionEnabledInstance<_TSessionsEnabled>): this;
     addSessionRoute(condition: RegExp | LambderRouteConditionFn | LambderRouteMatcher, actionFn: LambderSessionRouteHandler<TSessionData> & LambderSessionEnabledInstance<_TSessionsEnabled>): this;
-    addApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.input<TInput>, false> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.input<TInput>, false> = never, const TIdempotencyOpt extends LambderApiIdempotencyOption = never>(name: TName, schema: {
+    addApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TAnswer extends LambderReadonlyDeep<z.input<TOutput>>, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.input<TInput>, false> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.input<TInput>, false> = never, const TIdempotencyOpt extends LambderApiIdempotencyOption = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
@@ -163,8 +163,18 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         rateLimit?: TRateOpt;
         /** Replay-protect this API per client idempotencyKey. Requires the idempotency option at creation. */
         idempotency?: _TIdempotencyEnabled extends true ? TIdempotencyOpt : never;
-    } & LambderRequirableGuardsField<_TPublicGuardsRequired, TGuardsOpt>, handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>, TSessionData, _TRateLimitPolicies>, resolver: LambderResolver<z.input<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, LambderMergeContract<_TContract, TName, LambderContractEntry<z.input<TInput>, LambderJsonOutputOf<z.output<TOutput>>, "public", LambderGuardInputsOf<_TGuards, TGuardsOpt>, TGuardsOpt, TRateOpt, TIdempotencyOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired, _TSessionsEnabled>;
-    addSessionApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.input<TInput>, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.input<TInput>, true> = never, const TIdempotencyOpt extends LambderApiIdempotencyOption = never>(name: TName, schema: {
+        /**
+         * Whether this API's answers are compressed for a caller that accepts it: "auto" (the default) when the
+         * body is large enough to gain, false never, true always. false suits an answer of base64 bytes: once
+         * compressed it leaves the function base64-encoded again, so it is no smaller under Lambda's response
+         * cap or to a lambda caller, and a browser gets it only about a quarter smaller for the time spent at
+         * both ends. A transport setting of this server's, not part of the API's contract.
+         */
+        compress?: boolean | "auto";
+    } & LambderRequirableGuardsField<_TPublicGuardsRequired, TGuardsOpt>, 
+    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with refuse(). */
+    handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>, TSessionData, _TRateLimitPolicies>) => MaybePromise<TAnswer>): Lambder<TSessionData, LambderMergeContract<_TContract, TName, LambderContractEntry<z.input<TInput>, LambderJsonOutputOf<z.output<TOutput>>, "public", LambderGuardInputsOf<_TGuards, TGuardsOpt>, TGuardsOpt, TRateOpt, TIdempotencyOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired, _TSessionsEnabled>;
+    addSessionApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TAnswer extends LambderReadonlyDeep<z.input<TOutput>>, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.input<TInput>, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.input<TInput>, true> = never, const TIdempotencyOpt extends LambderApiIdempotencyOption = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
@@ -172,7 +182,17 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         rateLimit?: TRateOpt;
         /** Replay-protect this API per client idempotencyKey. Requires the idempotency option at creation. */
         idempotency?: _TIdempotencyEnabled extends true ? TIdempotencyOpt : never;
-    } & LambderRequirableGuardsField<_TSessionGuardsRequired, TGuardsOpt> & LambderSessionEnabledInstance<_TSessionsEnabled>, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>, _TRateLimitPolicies>, resolver: LambderResolver<z.input<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, LambderMergeContract<_TContract, TName, LambderContractEntry<z.input<TInput>, LambderJsonOutputOf<z.output<TOutput>>, "session", LambderGuardInputsOf<_TGuards, TGuardsOpt>, TGuardsOpt, TRateOpt, TIdempotencyOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired, _TSessionsEnabled>;
+        /**
+         * Whether this API's answers are compressed for a caller that accepts it: "auto" (the default) when the
+         * body is large enough to gain, false never, true always. false suits an answer of base64 bytes: once
+         * compressed it leaves the function base64-encoded again, so it is no smaller under Lambda's response
+         * cap or to a lambda caller, and a browser gets it only about a quarter smaller for the time spent at
+         * both ends. A transport setting of this server's, not part of the API's contract.
+         */
+        compress?: boolean | "auto";
+    } & LambderRequirableGuardsField<_TSessionGuardsRequired, TGuardsOpt> & LambderSessionEnabledInstance<_TSessionsEnabled>, 
+    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with refuse(). */
+    handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>, _TRateLimitPolicies>) => MaybePromise<TAnswer>): Lambder<TSessionData, LambderMergeContract<_TContract, TName, LambderContractEntry<z.input<TInput>, LambderJsonOutputOf<z.output<TOutput>>, "session", LambderGuardInputsOf<_TGuards, TGuardsOpt>, TGuardsOpt, TRateOpt, TIdempotencyOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired, _TSessionsEnabled>;
     /**
      * What registering an API is, for addApi and addSessionApi alike: the
      * checks that can refuse it, then its definition recorded (what
@@ -267,7 +287,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      * and never moves when registrations are reordered.
      */
     apiOptionEntries(): LambderApiOptionEntries;
-    getResponseBuilder(ctx?: LambderRenderContext): LambderResponseBuilder<any>;
+    getResponseBuilder(ctx?: LambderRenderContext): LambderResponseBuilder;
     private getResolver;
     getHandler(): LambderHandler;
     /** True when the Lambda event is an API Gateway HTTP event (REST API v1 or HTTP API / Function URL v2). */
@@ -365,12 +385,30 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private inputValidationRefusal;
     /**
      * One API call through the core: the pipeline runs the protocol steps and
-     * calls back for the handler, whose LambderResponse (returned, or thrown
-     * via res.die.*) becomes the answer the pipeline stores and hands back.
-     * The context is the pipeline's context, so a session it fetched is on
-     * ctx.session and the validated payload is on ctx.apiPayload when the
-     * handler runs. The handler's resolver knows the API's output schema, so
-     * every success payload is parsed through it before it is sent.
+     * calls back for the handler, whose returned output becomes the answer
+     * the pipeline stores and hands back. The context is the pipeline's
+     * context, so a session it fetched is on ctx.session and the validated
+     * payload is on ctx.apiPayload when the handler runs.
+     *
+     * The output goes out as the API's schema declares it. The type system
+     * accepts a value that carries more than the schema (a row read straight
+     * from a table is assignable to a narrower object type), and without the
+     * parse the extra fields, a password hash included, would reach the
+     * client. zod strips what the schema does not declare, fills its defaults
+     * and applies its transforms, so the wire and the idempotency store only
+     * see the declared shape. The handler returns the schema's input form, so
+     * a transform runs exactly once.
+     *
+     * An output the schema rejects is the handler breaking its contract,
+     * answered as a crash rather than sent (LambderApiOutputValidationError,
+     * which an idempotency key records as its answer, since the handler has
+     * already run). The parse is synchronous, so an output schema cannot be
+     * async: zod throws from a synchronous parse that meets an async
+     * refinement or transform, and a transform may throw of its own accord.
+     * Either throw becomes the same error, carrying what was thrown as its
+     * cause. Left to escape as it is, it would read as the handler crashing
+     * before its answer: the idempotency engine would release the key's claim
+     * and every retry would run the operation again.
      */
     private runApi;
     /** A thrown LambderApiRefusal (from a hook, say) as the structured API envelope: the core's one mapping. */

package/dist/core/Lambder.js

@@ -16,7 +16,8 @@ import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/Lambde
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignature.js";
 import { assertPlainData } from "../shared/util/assertPlainData.js";
-import { apiNotFoundAnswer, refusalAnswer, sessionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
+import { apiNotFoundAnswer, buildApiEnvelope, envelopeAnswer, refusalAnswer, sessionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
+import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
 import { bindContextTools, createContext, isV2HttpEvent, } from "./LambderContext.js";
 import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD } from "../shared/wire/LambderRequestPayload.js";
 import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
@@ -263,12 +264,16 @@ export default class Lambder {
         return this;
     }
     // Typed API with Zod
-    addApi(name, schema, handler) {
+    addApi(name, schema, 
+    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with refuse(). */
+    handler) {
         this.registerApi(name, "public", schema, handler);
         return this;
     }
     // Typed Session API with Zod
-    addSessionApi(name, schema, handler) {
+    addSessionApi(name, schema, 
+    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with refuse(). */
+    handler) {
         this.registerApi(name, "session", schema, handler);
         return this;
     }
@@ -303,7 +308,7 @@ export default class Lambder {
         this.apiDefinitions.set(name, definition);
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
-            actionFn: (ctx) => this.runApi(ctx, definition, handler),
+            actionFn: (ctx) => this.runApi(ctx, definition, schema.output, schema.compress ?? "auto", handler),
         });
     }
     addHook(hookEvent, hookFn, priority = 0) {
@@ -700,8 +705,8 @@ export default class Lambder {
             catch (err) {
                 response = (await this.answerThrown(err, ctx, resolver)).copy();
             }
-            // Only what the hooks themselves wrote (res.setHeader inside a
-            // hook) is left to apply, which leaves their overrides standing.
+            // Only what the hooks themselves wrote (ctx.setResponseHeader
+            // inside a hook) is left to apply, which leaves their overrides standing.
             // A hook that answered with a different response takes the whole
             // set instead: headers belong to the call, not to the response
             // that first carried them, so the call's session cookie must
@@ -883,48 +888,52 @@ export default class Lambder {
     }
     /**
      * One API call through the core: the pipeline runs the protocol steps and
-     * calls back for the handler, whose LambderResponse (returned, or thrown
-     * via res.die.*) becomes the answer the pipeline stores and hands back.
-     * The context is the pipeline's context, so a session it fetched is on
-     * ctx.session and the validated payload is on ctx.apiPayload when the
-     * handler runs. The handler's resolver knows the API's output schema, so
-     * every success payload is parsed through it before it is sent.
+     * calls back for the handler, whose returned output becomes the answer
+     * the pipeline stores and hands back. The context is the pipeline's
+     * context, so a session it fetched is on ctx.session and the validated
+     * payload is on ctx.apiPayload when the handler runs.
+     *
+     * The output goes out as the API's schema declares it. The type system
+     * accepts a value that carries more than the schema (a row read straight
+     * from a table is assignable to a narrower object type), and without the
+     * parse the extra fields, a password hash included, would reach the
+     * client. zod strips what the schema does not declare, fills its defaults
+     * and applies its transforms, so the wire and the idempotency store only
+     * see the declared shape. The handler returns the schema's input form, so
+     * a transform runs exactly once.
+     *
+     * An output the schema rejects is the handler breaking its contract,
+     * answered as a crash rather than sent (LambderApiOutputValidationError,
+     * which an idempotency key records as its answer, since the handler has
+     * already run). The parse is synchronous, so an output schema cannot be
+     * async: zod throws from a synchronous parse that meets an async
+     * refinement or transform, and a transform may throw of its own accord.
+     * Either throw becomes the same error, carrying what was thrown as its
+     * cause. Left to escape as it is, it would read as the handler crashing
+     * before its answer: the idempotency engine would release the key's claim
+     * and every retry would run the operation again.
      */
-    async runApi(ctx, definition, handler) {
+    async runApi(ctx, definition, output, compress, handler) {
         const request = ctx.api;
         if (!request)
             throw new Error(`Lambder: API "${definition.name}" was matched by a request that is not an API call.`);
-        const resolver = new LambderResolver({ files: this.files, apiVersion: this.apiVersion, ctx, apiOutput: definition.output });
-        // What the handler produced, in both forms: the answer went to the
-        // pipeline, and the response is kept so it can carry on unchanged.
-        const handled = { output: null };
         const { answer } = await this.pipeline.run(request, ctx, definition, async () => {
             ctx.apiPayload = request.payload;
-            let response;
+            const returned = await handler(ctx);
+            let parsed;
             try {
-                response = await handler(ctx, resolver);
+                parsed = output.safeParse(returned);
             }
-            catch (err) {
-                // A thrown LambderResponse IS the response (res.die.*): an
-                // answer like a returned one, stored and replayed alike.
-                if (err instanceof LambderResponse)
-                    response = err;
-                else
-                    throw err;
+            catch (thrown) {
+                throw new LambderApiOutputValidationError(definition.name, { thrown });
             }
-            handled.output = { response, answer: answerFromResponse(response) };
-            return handled.output.answer;
+            if (!parsed.success)
+                throw new LambderApiOutputValidationError(definition.name, { zodError: parsed.error });
+            return envelopeAnswer(buildApiEnvelope(this.apiVersion, parsed.data, { logList: ctx.logList }));
         });
-        // When the pipeline answered with the handler's own answer, its
-        // response carries on rather than a rebuild. An answer holds a Buffer
-        // body base64-encoded (the plain shape the idempotency store
-        // persists), and a response rebuilt from it would hand finalization a
-        // base64 string it must pass through uncompressed. Identity decides,
-        // since the pipeline may have answered with a stored replay or a
-        // refusal instead.
-        if (handled.output?.answer === answer)
-            return handled.output.response;
-        return responseFromAnswer(answer);
+        // The API's compress option, on whatever answer the call ended with:
+        // a replayed one comes back from its store without the hint.
+        return responseFromAnswer({ ...answer, compress });
     }
     /** A thrown LambderApiRefusal (from a hook, say) as the structured API envelope: the core's one mapping. */
     apiErrorResponse(err, ctx) {