lambder 8.3.1 → 9.0.2

package/dist/core/Lambder.js

@@ -14,9 +14,10 @@ import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 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 { apiNameKeyOf } from "../shared/wire/LambderApiSignatureMap.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) {

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/LambderCreateOptions.d.ts

@@ -1,5 +1,5 @@
 import type { z } from "zod";
-import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
+import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
 import type { Context } from "aws-lambda";
 import type LambderResolver from "./LambderResolver.js";
 import type LambderResponseBuilder from "./LambderResponseBuilder.js";

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);
-    }
 }

package/dist/core/LambderResponseBuilder.d.ts

@@ -1,12 +1,10 @@
-import type { z } from "zod";
 import type { LambderRenderContext } from "./LambderContext.js";
-import { type LambderCookieOptions, type LambderClearCookieOptions } from "../shared/wire/LambderCookie.js";
 import type { LambderFiles } from "./LambderFiles.js";
 import { LambderResponse, type LambderHeadersInput } from "./LambderResponse.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import { LambderSafeHtml } from "../shared/LambderHtml.js";
 import type { LambderTemplateData } from "./LambderTemplatingEngine.js";
-import type { LambderApiResponseConfig, LambderApiNullAnswerConfig } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
 export type { LambderApiEnvelopeBody, LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
 export type LambderResponseOptions = {
     statusCode?: LambderHttpStatusCode;
@@ -18,19 +16,6 @@ export type LambderResponseOptions = {
     /** "auto" (default): ETag on GET/HEAD 200 when globally enabled. true: force. false: never. */
     etag?: boolean | "auto";
 };
-/**
- * The two shapes of an API answer: the output the contract declares, or
- * `null` beside a config that says why (a refusal flag, an `errorMessage`, a
- * `message`). A bare `res.api(null)` compiles only when the output type
- * itself allows null, so a success payload is always the declared output,
- * which lets a typed caller (LambderInvokeCaller.api) promise it. Untyped
- * resolvers (`TOutput = any`) accept anything. This is the resolver's method
- * type; the core's answer type is LambderApiAnswer.
- */
-export type LambderResolverApiMethod<TOutput, TResult> = {
-    (payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): TResult;
-    (payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): TResult;
-};
 export type LambderRawResponseInit = {
     statusCode: LambderHttpStatusCode;
     headers?: LambderHeadersInput;
@@ -40,39 +25,23 @@ export type LambderRawResponseInit = {
     compress?: boolean | "auto";
     etag?: boolean | "auto";
 };
-export default class LambderResponseBuilder<TResponse = any> {
+/**
+ * Builds the responses of routes, hooks and error handlers. An API handler
+ * never holds one: it returns its output or refuses, and writes headers and
+ * cookies through its context (LambderResponseTools).
+ */
+export default class LambderResponseBuilder {
     protected files: LambderFiles | null;
     protected apiVersion: string | null;
     protected ctx?: LambderRenderContext;
-    /** The output schema of the API this builder answers, which every success payload is parsed through; null outside an API handler. */
-    protected apiOutput: z.ZodType | null;
-    constructor({ files, apiVersion, ctx, apiOutput }: {
+    constructor({ files, apiVersion, ctx }: {
         files?: LambderFiles | null;
         apiVersion?: string | null;
         ctx?: LambderRenderContext;
-        apiOutput?: z.ZodType;
     });
     private buildResponse;
     /** The instance's file reader, which res.file and res.templateFile need. */
     private requireFiles;
-    /** Appends a response header; applied onto the response once the handler has one, in call order. */
-    addHeader(key: string, value: string): void;
-    /** Replaces a response header; applied onto the response once the handler has one, in call order. */
-    setHeader(key: string, value: string | string[]): void;
-    /**
-     * Adds a Set-Cookie header. A function-form `domain` is resolved against
-     * the request hostname. 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 same
-     * `domain` and `path` the cookie was set with: a cookie's identity is
-     * (name, domain, path), and a deletion under a different scope targets a
-     * different cookie and deletes nothing.
-     */
-    clearCookie(name: string, options?: LambderClearCookieOptions): void;
-    logToApiResponse(input: unknown): void;
     raw(init: LambderRawResponseInit): LambderResponse;
     json(data: Record<string, any>, options?: LambderResponseOptions): LambderResponse;
     text(data: string, options?: LambderResponseOptions): LambderResponse;
@@ -109,37 +78,13 @@ export default class LambderResponseBuilder<TResponse = any> {
     templateFile(filePath: string, data?: LambderTemplateData, options?: LambderResponseOptions & {
         htmlVirtualSlots?: boolean;
     }): Promise<LambderResponse>;
-    api(payload: TResponse, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    api(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;
     /**
-     * A payload as the API's output 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 this
-     * 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. A refusal's payload beside an errorMessage or a
-     * flag is parsed the same way; only null passes as it is. Only an API
-     * handler's own resolver holds the schema: a hook, a validation handler
-     * or an error handler answers in shapes of its own, a cached answer in
-     * its wire form, and is sent as given.
-     *
-     * The payload is the schema's input form (what a handler writes before
-     * the transforms), so a transform runs exactly once. A payload the schema
-     * rejects is a 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 LambderApiOutputValidationError, 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.
+     * An API envelope written by hand: what a hook, an input validation
+     * handler or a global error handler answers an API call with (a refusal
+     * flag, an errorMessage, a crash). The payload goes out as given; an API
+     * handler's own output is parsed through its schema by the instance
+     * instead. The logList channel is what the request accumulated unless the
+     * config names its own.
      */
-    private declaredPayload;
-    /** Same as api() but forces compression of the response body. */
-    apiBinary(payload: TResponse, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    apiBinary(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;
+    api(payload: unknown, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
 }

package/dist/core/LambderResponseBuilder.js

@@ -1,18 +1,18 @@
-import { serializeCookie, serializeClearCookie } from "../shared/wire/LambderCookie.js";
 import { LambderResponse } from "./LambderResponse.js";
 import { buildApiEnvelope } from "../api/LambderApiEnvelope.js";
-import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
+/**
+ * Builds the responses of routes, hooks and error handlers. An API handler
+ * never holds one: it returns its output or refuses, and writes headers and
+ * cookies through its context (LambderResponseTools).
+ */
 export default class LambderResponseBuilder {
     files;
     apiVersion;
     ctx;
-    /** The output schema of the API this builder answers, which every success payload is parsed through; null outside an API handler. */
-    apiOutput;
-    constructor({ files, apiVersion, ctx, apiOutput }) {
+    constructor({ files, apiVersion, ctx }) {
         this.files = files ?? null;
         this.apiVersion = apiVersion ?? null;
         this.ctx = ctx;
-        this.apiOutput = apiOutput ?? null;
     }
     ;
     buildResponse(statusCode, contentType, body, options, defaults) {
@@ -37,49 +37,6 @@ export default class LambderResponseBuilder {
             throw new Error(`Lambder: ${method} requires the files option at creation (e.g. files: new LambderLocalFileSource({ root }))`);
         return this.files;
     }
-    /** Appends a response header; applied onto the response once the handler has one, in call order. */
-    addHeader(key, value) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.addHeader needs the request context, and this response builder was created without one.");
-        this.ctx.responseHeaders.add(key, value);
-    }
-    ;
-    /** Replaces a response header; applied onto the response once the handler has one, in call order. */
-    setHeader(key, value) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.setHeader needs the request context, and this response builder was created without one.");
-        this.ctx.responseHeaders.set(key, value);
-    }
-    ;
-    /**
-     * Adds a Set-Cookie header. A function-form `domain` is resolved against
-     * the request hostname. Defaults: Path=/, SameSite=Lax, Secure, not
-     * HttpOnly, browser-session lifetime.
-     */
-    setCookie(name, value, options) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.setCookie needs the request context, and this response builder was created without one.");
-        this.addHeader("Set-Cookie", serializeCookie(name, value, options, this.ctx.host));
-    }
-    ;
-    /**
-     * Adds a Set-Cookie header that deletes the cookie. Pass the same
-     * `domain` and `path` the cookie was set with: a cookie's identity is
-     * (name, domain, path), and a deletion under a different scope targets a
-     * different cookie and deletes nothing.
-     */
-    clearCookie(name, options) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.clearCookie needs the request context, and this response builder was created without one.");
-        this.addHeader("Set-Cookie", serializeClearCookie(name, options, this.ctx.host));
-    }
-    ;
-    logToApiResponse(input) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.logToApiResponse needs the request context, and this response builder was created without one.");
-        this.ctx.logList.push(input);
-    }
-    ;
     raw(init) {
         return new LambderResponse({
             statusCode: init.statusCode,
@@ -177,58 +134,17 @@ export default class LambderResponseBuilder {
         return this.buildResponse(200, "text/html; charset=utf-8", template.render(data), options);
     }
     ;
-    api(payload, config = {}, options) {
-        // The envelope is the core's (one writer for both the server and the
-        // mock runtime); the logList channel is what this request accumulated
-        // unless the config names its own.
-        const envelope = buildApiEnvelope(this.apiVersion, this.declaredPayload(payload), { ...config, logList: config.logList || this.ctx?.logList });
-        return this.json(envelope, options);
-    }
-    ;
     /**
-     * A payload as the API's output 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 this
-     * 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. A refusal's payload beside an errorMessage or a
-     * flag is parsed the same way; only null passes as it is. Only an API
-     * handler's own resolver holds the schema: a hook, a validation handler
-     * or an error handler answers in shapes of its own, a cached answer in
-     * its wire form, and is sent as given.
-     *
-     * The payload is the schema's input form (what a handler writes before
-     * the transforms), so a transform runs exactly once. A payload the schema
-     * rejects is a 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 LambderApiOutputValidationError, 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.
+     * An API envelope written by hand: what a hook, an input validation
+     * handler or a global error handler answers an API call with (a refusal
+     * flag, an errorMessage, a crash). The payload goes out as given; an API
+     * handler's own output is parsed through its schema by the instance
+     * instead. The logList channel is what the request accumulated unless the
+     * config names its own.
      */
-    declaredPayload(payload) {
-        if (!this.apiOutput || payload === null)
-            return payload;
-        const apiName = this.ctx?.apiName ?? "?";
-        let parsed;
-        try {
-            parsed = this.apiOutput.safeParse(payload);
-        }
-        catch (thrown) {
-            throw new LambderApiOutputValidationError(apiName, { thrown });
-        }
-        if (parsed.success)
-            return parsed.data;
-        throw new LambderApiOutputValidationError(apiName, { zodError: parsed.error });
-    }
-    apiBinary(payload, config = {}, options) {
-        return this.api(payload, config, { ...options, compress: true });
+    api(payload, config = {}, options) {
+        const envelope = buildApiEnvelope(this.apiVersion, payload, { ...config, logList: config.logList || this.ctx?.logList });
+        return this.json(envelope, options);
     }
     ;
 }

package/dist/index.d.ts

@@ -30,12 +30,12 @@ export { toHttpAnswer } from "./api/LambderApiAnswer.js";
 export type { LambderApiAnswer } from "./api/LambderApiAnswer.js";
 export { LambderAnswerHeaders, getAnswerHeader, setAnswerHeader, addAnswerHeader } from "./shared/wire/LambderAnswerHeaders.js";
 export { createApiCallContext } from "./api/LambderApiCallContext.js";
-export type { LambderApiCallContext, LambderApiCallTrace } from "./api/LambderApiCallContext.js";
+export type { LambderApiCallContext, LambderApiCallTrace, LambderResponseTools } from "./api/LambderApiCallContext.js";
 export type { LambderApiDefinition } from "./api/LambderApiDefinition.js";
 export { apiSignatureOf } from "./api/LambderApiSignature.js";
 export type { LambderApiSignatureEntry } from "./api/LambderApiSignature.js";
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
-export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignatureMap.js";
+export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignatureMap.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
@@ -68,7 +68,7 @@ export type { LambderHttpStatusCode } from "./shared/wire/LambderHttpStatus.js";
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
-export type { LambderResponseOptions, LambderRawResponseInit, LambderResolverApiMethod, } from "./core/LambderResponseBuilder.js";
+export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/LambderResponseBuilder.js";
 export type { LambderRouteMatcher, LambderRouteConditionFn, LambderRouteCondition, LambderPathParamsOf, LambderRoutePath } from "./core/LambderRouting.js";
 export type { LambderCorsConfig } from "./core/LambderCors.js";
 export type { LambderCreateOptions, LambderSessionOptions, LambderActionTools, LambderHandler, } from "./core/LambderCreateOptions.js";
@@ -133,7 +133,7 @@ export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
 export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, } from "./shared/wire/LambderApiOptionEntries.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderHttpEventFormat } from "./core/LambderContext.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";

package/dist/index.js

@@ -24,7 +24,7 @@ export { LambderAnswerHeaders, getAnswerHeader, setAnswerHeader, addAnswerHeader
 export { createApiCallContext } from "./api/LambderApiCallContext.js";
 // Per-endpoint signatures: what a client build ships with, digested from the server's own registrations.
 export { apiSignatureOf } from "./api/LambderApiSignature.js";
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignatureMap.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
@@ -99,5 +99,5 @@ export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
 export { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, 
 // The Brotli twin of the browser's compressPayloadGzip, and its defaults.
 DEFAULT_INVOKE_REQUEST_COMPRESSION_SETTINGS, compressPayloadBrotli, } from "./shared/wire/LambderRequestPayload.js";
-// Cookies (res.setCookie / res.clearCookie build on these; exported for code holding a LambderResponse)
+// Cookies (ctx.setCookie / ctx.clearCookie build on these; exported for code holding a LambderResponse)
 export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./shared/wire/LambderCookie.js";

package/dist/invoke/LambderInvokeCaller.d.ts

@@ -22,7 +22,7 @@
  */
 import type { APIGatewayProxyEventV2, Context } from "aws-lambda";
 import { type LambderInvokeFailure, type LambderInvokeOutcome } from "./LambderInvokeOutcome.js";
-import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
+import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
 import type { LambdaClient, LambdaClientConfig } from "@aws-sdk/client-lambda";
 import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
 import { type LambderCallArgs, type LambderContractOutputOf, type LambderGuardInputsProviderOption, type LambderSharedCallOptions } from "../shared/wire/LambderCallOptions.js";