lambder 8.1.2 → 9.0.1

package/dist/client.d.ts

@@ -26,6 +26,8 @@ export type { LambderIdempotencyKeyScope } from "./shared/wire/LambderIdempotenc
 export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
 export type { LambderApiRefusalOptions, LambderRefusalMessage, LambderAppRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/wire/LambderApiRefusal.js";
 export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
+export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, } from "./shared/wire/LambderApiOptionEntries.js";
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 export type { LambderCrashDetail, LambderCrashCause } from "./shared/wire/LambderCrashDetail.js";
 export { compressPayloadGzip, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/wire/LambderRequestPayload.js";
@@ -36,6 +38,11 @@ export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtm
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
 export type { LambderHttpStatusCode } from "./shared/wire/LambderHttpStatus.js";
+export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
+export type { LambderBackoffTimerOptions } from "./shared/util/LambderBackoffTimer.js";
+export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
+export type { LambderSignedClaimsOptions } from "./shared/util/LambderSignedClaims.js";
+export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";
 export type { LambderUploadRunnerOptions, LambderUploadProgress, LambderUploadPhase, LambderUploadFailureReason } from "./client/LambderUploadRunner.js";
 export { checkUploadRule } from "./shared/contracts/LambderUploadBucket.js";

package/dist/client.js

@@ -23,6 +23,9 @@ export { createIdempotencyKey, createIdempotencyKeyScope } from "./shared/wire/L
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;
 // in the browser they are plain Errors).
 export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+// The server's declared options as plain data (the generated options module's
+// entry types) and the readers a client derives its own facts from.
+export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
 // A crash described for a caller allowed to see it (the envelope's `crash` field; pure, no Node built-ins).
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 // Request payload compression (browser-safe: gzip via CompressionStream, no Node built-ins).
@@ -33,6 +36,14 @@ export { resolveCompressionOption } from "./shared/wire/LambderCompressionOption
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
 // Typed translations (standalone, isomorphic)
 export { createLambderI18n } from "./shared/LambderI18n.js";
+// Waiting longer after each failure, once: for a reconnecting client or a
+// screen that has to come back by itself.
+export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
+// Signed claims tokens, for the isomorphic code that verifies them where a
+// server's secret is at hand (an edge Worker, a shared backend package);
+// never in a page, which holds no secret to verify with.
+export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
+export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 // Direct uploads: the runner that takes a file from the browser straight to
 // storage, and the vocabulary it shares with the server's bucket.
 export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";

package/dist/core/Lambder.d.ts

@@ -14,13 +14,14 @@ import type { LambderFileSource } from "../shared/contracts/LambderFileSource.js
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import { type LambderApiSignatureEntry } from "../api/LambderApiSignature.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
+import type { LambderApiOptionEntries } from "../shared/wire/LambderApiOptionEntries.js";
 import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
 import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderRateLimitOption } from "../api/LambderApiRateLimits.js";
 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 & {
@@ -91,6 +92,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private readonly apiDefinitions;
     /** The guards map given at creation, kept for apiSignatures(): a guard's schema is part of the signature of every endpoint declaring it. */
     private readonly guards;
+    /** The rate-limit policies given at creation, kept for apiOptionEntries(), which records each one less its key handler. */
+    private readonly rateLimitPolicies;
     private hookList;
     private createdHooks;
     private initPromise;
@@ -152,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;
     } & {
@@ -160,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;
     } & {
@@ -169,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
@@ -246,7 +269,25 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      * unless the generator writes it there.
      */
     apiSignatureEntries(): Promise<LambderApiSignatureEntry[]>;
-    getResponseBuilder(ctx?: LambderRenderContext): LambderResponseBuilder<any>;
+    /**
+     * Every registered API's mode and declared options as plain data, with
+     * the rate-limit policies and guards they name reduced to what is not
+     * code: what writeApiOptions (lambder/build) writes to a module a client,
+     * a mock or a test imports instead of the server. The contract carries
+     * the same options as types; this is the same fact as a value, for code
+     * that decides something at runtime with it.
+     *
+     * Nothing here is a secret or a handler by construction. A guard's
+     * parameter is written as it was declared, so it has to be plain data
+     * (a permission string, a list, a reason); one that is not fails by API
+     * and guard name. A policy's key handler is never written: its `per`
+     * says "custom" and no more. A guard's input schema is never written
+     * either; its declaration says only which of the three input modes it
+     * has. Every table is sorted by name, so the module diffs by endpoint
+     * and never moves when registrations are reordered.
+     */
+    apiOptionEntries(): LambderApiOptionEntries;
+    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). */
@@ -344,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

@@ -15,7 +15,9 @@ import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignature.js";
-import { apiNotFoundAnswer, refusalAnswer, sessionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
+import { assertPlainData } from "../shared/util/assertPlainData.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";
@@ -80,6 +82,8 @@ export default class Lambder {
     apiDefinitions = new Map();
     /** The guards map given at creation, kept for apiSignatures(): a guard's schema is part of the signature of every endpoint declaring it. */
     guards;
+    /** The rate-limit policies given at creation, kept for apiOptionEntries(), which records each one less its key handler. */
+    rateLimitPolicies;
     hookList = { "beforeRender": [], "afterRender": [], "fallback": [] };
     createdHooks = [];
     initPromise = null;
@@ -122,6 +126,7 @@ export default class Lambder {
         }
         const session = options.session;
         this.guards = options.guards;
+        this.rateLimitPolicies = options.rateLimits?.policies;
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
             minApiVersion: options.minApiVersion,
@@ -259,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;
     }
@@ -299,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) {
@@ -413,6 +422,71 @@ export default class Lambder {
         entries.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
         return entries;
     }
+    /**
+     * Every registered API's mode and declared options as plain data, with
+     * the rate-limit policies and guards they name reduced to what is not
+     * code: what writeApiOptions (lambder/build) writes to a module a client,
+     * a mock or a test imports instead of the server. The contract carries
+     * the same options as types; this is the same fact as a value, for code
+     * that decides something at runtime with it.
+     *
+     * Nothing here is a secret or a handler by construction. A guard's
+     * parameter is written as it was declared, so it has to be plain data
+     * (a permission string, a list, a reason); one that is not fails by API
+     * and guard name. A policy's key handler is never written: its `per`
+     * says "custom" and no more. A guard's input schema is never written
+     * either; its declaration says only which of the three input modes it
+     * has. Every table is sorted by name, so the module diffs by endpoint
+     * and never moves when registrations are reordered.
+     */
+    apiOptionEntries() {
+        const apis = {};
+        for (const name of [...this.apiDefinitions.keys()].sort()) {
+            const { mode, guards, rateLimit, idempotency } = this.apiDefinitions.get(name);
+            const entry = { mode };
+            if (guards !== undefined) {
+                assertPlainData(guards, `the guards option of API "${name}"`);
+                entry.guards = guards;
+            }
+            if (rateLimit !== undefined) {
+                assertPlainData(rateLimit, `the rateLimit option of API "${name}"`);
+                entry.rateLimit = rateLimit;
+            }
+            if (idempotency !== undefined)
+                entry.idempotency = idempotency;
+            apis[name] = entry;
+        }
+        const rateLimitPolicies = {};
+        for (const name of Object.keys(this.rateLimitPolicies ?? {}).sort()) {
+            const { per, budget, chargeAt, errorMessage, ...windows } = this.rateLimitPolicies[name];
+            const entry = {};
+            for (const [window, limit] of Object.entries(windows)) {
+                if (limit !== undefined)
+                    entry[window] = limit;
+            }
+            if (per !== undefined)
+                entry.per = per === "ip" || per === "session" ? per : "custom";
+            if (budget !== undefined)
+                entry.budget = budget;
+            if (chargeAt !== undefined)
+                entry.chargeAt = chargeAt;
+            if (errorMessage !== undefined) {
+                assertPlainData(errorMessage, `the errorMessage of rate-limit policy "${name}"`);
+                entry.errorMessage = errorMessage;
+            }
+            rateLimitPolicies[name] = entry;
+        }
+        const guards = {};
+        for (const name of Object.keys(this.guards ?? {}).sort()) {
+            const guard = this.guards[name];
+            guards[name] = {
+                input: guard.apiInput ? "apiInput" : guard.guardInput ? "guardInput" : "none",
+                session: guard.session === true,
+                runAt: guard.runAt ?? "beforeInputValidation",
+            };
+        }
+        return { apis, rateLimitPolicies, guards };
+    }
     getResponseBuilder(ctx) {
         return new LambderResponseBuilder({
             files: this.files,
@@ -631,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
@@ -814,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) {

package/dist/core/LambderContext.d.ts

@@ -2,6 +2,7 @@ import type { APIGatewayProxyEvent, APIGatewayProxyEventV2, APIGatewayProxyEvent
 import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
 import { type LambderApiRequest } from "../api/LambderApiRequest.js";
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
+import { type LambderResponseTools } from "../api/LambderApiCallContext.js";
 import type LambderSessionController from "../session/LambderSessionController.js";
 import type { LambderApiRateLimitPolicyConfig, LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult } from "../api/LambderApiRateLimits.js";
 export type LambderHttpEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2;
@@ -19,7 +20,9 @@ export declare const isV2HttpEvent: (event: unknown) => event is APIGatewayProxy
  * API core's call context (session, guardData, responseHeaders, logList),
  * which is the part the pipeline and the session controller work on; the
  * rest is the HTTP request as the Lambda event delivered it, plus the tools
- * the instance rendering it binds on (sessionController, rateLimit, isRateLimited).
+ * the instance rendering it binds on (sessionController, rateLimit, isRateLimited)
+ * and the response tools (setResponseHeader, addResponseHeader, setCookie,
+ * clearCookie) that write onto whatever answer the request ends with.
  *
  * TRateLimitPolicies is the app's policies map on a handler registered with
  * addApi, addSessionApi, addRoute or addSessionRoute, so a policy name is
@@ -102,9 +105,9 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     lambdaContext: Context;
     /** Which API Gateway payload format the event arrived in, and the response leaves in. */
     eventFormat: LambderHttpEventFormat;
-    /** Response headers written during the request (res.setHeader, res.addHeader, session cookies), applied onto the response at the end. */
+    /** Response headers written during the request (the response tools below, session cookies), applied onto the response at the end. */
     responseHeaders: LambderAnswerHeaders;
-    /** Entries for the API envelope's logList channel (res.logToApiResponse). */
+    /** Entries for the API envelope's logList channel: a handler pushes what it wants the caller's debug log to show. */
     logList: unknown[];
     /**
      * Sessions for this request: read the one it carries
@@ -125,12 +128,12 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     rateLimit: LambderContextRateLimit<TRateLimitPolicies>;
     /** The same count as rateLimit, answered instead of thrown: false, or the window that refused and its retryAfterSeconds. */
     isRateLimited: LambderContextRateLimitCheck<TRateLimitPolicies>;
-};
+} & LambderResponseTools;
 export type LambderSessionRenderContext<TApiPayload = any, SessionData = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}, TRateLimitPolicies = Record<string, LambderApiRateLimitPolicyConfig>> = Omit<LambderRenderContext<TApiPayload, TPathParams, TGuardData, SessionData, TRateLimitPolicies>, 'session'> & {
     session: LambderSessionRecord<SessionData>;
 };
-/** The members of a render context that belong to the instance rendering the request rather than to its event. */
-type LambderContextToolName = "sessionController" | "rateLimit" | "isRateLimited";
+/** The members of a render context that are bound onto it rather than read from its event. */
+type LambderContextToolName = "sessionController" | "rateLimit" | "isRateLimited" | keyof LambderResponseTools;
 /** What an instance binds onto each context it renders: see bindContextTools. */
 export type LambderContextTools = {
     sessionControllerFor: (ctx: LambderRenderContext) => LambderSessionController<any>;

package/dist/core/LambderContext.js

@@ -4,7 +4,7 @@ import { base64ToText } from "../shared/util/LambderBase64.js";
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
 import { DEFAULT_API_PATH } from "../shared/wire/LambderDefaultApiPath.js";
 import { LAMBDER_INVOKE_API_ID, LAMBDER_LOCAL_API_ID } from "../shared/wire/LambderInvokeApiId.js";
-import { bindCallTools } from "../api/LambderApiCallContext.js";
+import { bindCallTools, responseToolsOf } from "../api/LambderApiCallContext.js";
 import { decodeRequestPath } from "./LambderRequestPath.js";
 /** True for API Gateway HTTP API / Lambda Function URL (payload v2) events. */
 export const isV2HttpEvent = (event) => !!event && typeof event === "object"
@@ -23,6 +23,7 @@ export const bindContextTools = (ctx, tools) => {
         methods: {
             rateLimit: async (policy, key) => { await tools.chargeRateLimit(bound, policy, key, true); },
             isRateLimited: (policy, key) => tools.chargeRateLimit(bound, policy, key, false),
+            ...responseToolsOf(bound, bound.host),
         },
     });
     return bound;

package/dist/core/LambderResolver.d.ts

@@ -1,10 +1,9 @@
-import type { LambderApiNullAnswerConfig } from "../shared/wire/LambderApiContract.js";
-import LambderResponseBuilder, { type LambderResolverApiMethod, type LambderApiResponseConfig, type LambderResponseOptions } from "./LambderResponseBuilder.js";
+import LambderResponseBuilder from "./LambderResponseBuilder.js";
 import type { LambderResponse } from "./LambderResponse.js";
 type SyncDie<T extends (...args: any[]) => LambderResponse> = (...args: Parameters<T>) => never;
 type AsyncDie<T extends (...args: any[]) => Promise<LambderResponse>> = (...args: Parameters<T>) => Promise<never>;
 /** The `res.die.*` surface: every builder method, throwing what it built. Internal to the resolver, which is the only thing that has one. */
-interface DieResolverMethods<TOutput> {
+interface DieResolverMethods {
     raw: SyncDie<LambderResponseBuilder["raw"]>;
     json: SyncDie<LambderResponseBuilder["json"]>;
     text: SyncDie<LambderResponseBuilder["text"]>;
@@ -15,25 +14,20 @@ interface DieResolverMethods<TOutput> {
     redirect: SyncDie<LambderResponseBuilder["redirect"]>;
     versionExpired: SyncDie<LambderResponseBuilder["versionExpired"]>;
     fileBase64: SyncDie<LambderResponseBuilder["fileBase64"]>;
-    api: LambderResolverApiMethod<TOutput, never>;
-    apiBinary: LambderResolverApiMethod<TOutput, never>;
+    api: SyncDie<LambderResponseBuilder["api"]>;
     file: AsyncDie<LambderResponseBuilder["file"]>;
     templateFile: AsyncDie<LambderResponseBuilder["templateFile"]>;
 }
 /**
- * Response builder passed to route/api handlers and hooks.
+ * Response builder passed to route handlers and hooks.
  *
  * `res.die.*` builds the response and THROWS it, immediately halting the
  * request at any call depth (handlers, hooks, nested service functions).
  * Lambder's render pipeline catches thrown LambderResponse instances and uses
  * them as the response. Plain `throw res.html(...)` works the same way.
  */
-export default class LambderResolver<TOutput = any> extends LambderResponseBuilder<TOutput> {
-    die: DieResolverMethods<TOutput>;
+export default class LambderResolver extends LambderResponseBuilder {
+    die: DieResolverMethods;
     constructor(...args: ConstructorParameters<typeof LambderResponseBuilder>);
-    api(payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    api(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;
-    apiBinary(payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    apiBinary(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;
 }
 export {};

package/dist/core/LambderResolver.js

@@ -1,6 +1,6 @@
 import LambderResponseBuilder from "./LambderResponseBuilder.js";
 /**
- * Response builder passed to route/api handlers and hooks.
+ * Response builder passed to route handlers and hooks.
  *
  * `res.die.*` builds the response and THROWS it, immediately halting the
  * request at any call depth (handlers, hooks, nested service functions).
@@ -22,21 +22,9 @@ export default class LambderResolver extends LambderResponseBuilder {
             redirect: (...a) => { throw this.redirect(...a); },
             versionExpired: (...a) => { throw this.versionExpired(...a); },
             fileBase64: (...a) => { throw this.fileBase64(...a); },
-            // Overloaded on the payload (see LambderApiAnswer); the implementation takes both shapes.
-            api: ((payload, config, options) => {
-                throw this.api(payload, config, options);
-            }),
-            apiBinary: ((payload, config, options) => {
-                throw this.apiBinary(payload, config, options);
-            }),
+            api: (...a) => { throw this.api(...a); },
             file: async (...a) => { throw await this.file(...a); },
             templateFile: async (...a) => { throw await this.templateFile(...a); },
         };
     }
-    api(payload, config, options) {
-        return super.api(payload, config, options);
-    }
-    apiBinary(payload, config, options) {
-        return super.apiBinary(payload, config, options);
-    }
 }