lambder 5.1.2 → 6.0.1

package/README.md

@@ -53,6 +53,9 @@ const company = await caller.api("getCompany", { slug: "acme" });
   cookies, and a guard against Lambda's response size cap.
 - **Hooks and actions.** Lifecycle hooks, plus `addAction()` for the non-HTTP
   invocations (EventBridge, SQS, custom events) the same function receives.
+- **Lambda to lambda calls.** `LambderInvokeCaller` invokes a Lambder app in
+  another function directly, with no API Gateway in between, typed from the
+  callee's own contract and carrying its refusals, crash detail and logs back.
 - **Frontend hosting.** Serve a build from a folder, S3, R2 or any HTTP
   origin, with an app shell rendered through a build-pipeline-safe template
   engine.
@@ -74,8 +77,9 @@ import needs:
 | --- | --- |
 | `lambder/client` (browser, shared isomorphic code) | `zod` |
 | `lambder` on AWS Lambda (`nodejs18.x` and later) | `zod`. The runtime already provides the AWS SDK v3, so mark the SDK packages as dev dependencies and keep them out of the deployment package |
-| `lambder` anywhere else (a long-running server, a container, local tests) | `zod`, `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb` |
+| `lambder` anywhere else (a long-running server, a container, local tests) | `zod`, plus `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` when sessions or the DynamoDB stores are used; both are loaded on the first table access, so an app that uses neither needs neither |
 | `LambderS3FileSource` | `@aws-sdk/client-s3`, loaded on first read |
+| `LambderInvokeCaller` | `@aws-sdk/client-lambda`, loaded on the first call |
 | `lambder/testing` | `msw` |
 
 The SDK and its `@smithy` tree are roughly 21MB installed, which is why they are
@@ -101,8 +105,8 @@ tree-shaking.
 
 Source layout mirrors this: `src/core/` (request pipeline), `src/policies/`
 (declarative rate limits, guards, idempotency), `src/session/`, `src/stores/`
-(DynamoDB primitives), `src/client/`, and `src/shared/` (isomorphic modules
-both entries re-export).
+(DynamoDB primitives), `src/client/`, `src/invoke/` (the lambda-to-lambda
+caller), and `src/shared/` (isomorphic modules both entries re-export).
 
 ## Documentation
 
@@ -119,6 +123,7 @@ guide that matches what you are building. The full index lives in
 | [Responses](./docs/responses.md) | The render context, resolver methods, cookies, compression, ETag and the size cap |
 | [Sessions](./docs/sessions.md) | DynamoDB sessions, 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 |
 | [Frontend client](./docs/client.md) | `LambderCaller`: typed calls, failure outcomes, timeouts, guard inputs, request compression |
 | [Frontend hosting](./docs/frontend-hosting.md) | File sources, `servePublicFiles`, `serveIndexHtml`, `res.templateFile` |
 | [Templating](./docs/templating.md) | `html`/`xml` tagged templates and `LambderTemplatingEngine` |

package/dist/client/LambderCaller.d.ts

@@ -1,57 +1,9 @@
 import { type LambderRequestCompressionOption } from '../shared/LambderRequestPayload.js';
-import type { LambderApiResponse } from '../shared/LambderApiContract.js';
 import type { ApiContractShape } from '../shared/LambderApiContract.js';
-import type { z } from "zod";
-type IsAny<T> = 0 extends (1 & T) ? true : false;
-type GuardInputsOf<TEntry> = TEntry extends {
-    guardInputs: infer G;
-} ? G : never;
-/** Input type of guard G on one contract entry; never when that API does not declare it. */
-type GuardInputOf<TEntry, G extends string> = GuardInputsOf<TEntry> extends infer I ? (G extends keyof I ? I[G] : never) : never;
-/**
- * What guardInputsProvider returns: for every provided guard name, the value
- * the contract's APIs expect for it (a union across APIs when they differ).
- * Naming a guard no API declares in guardInput mode resolves to never, so a
- * typo fails the provider's return type instead of going missing at runtime.
- */
-export type LambderProvidedGuardInputs<TContract, TProvided extends string> = IsAny<TContract> extends true ? Record<TProvided, unknown> : {
-    [G in TProvided]: {
-        [K in keyof TContract]: GuardInputOf<TContract[K], G>;
-    }[keyof TContract];
-};
-/**
- * Supplies guardInputs for every call from one place (the organization the
- * UI is on, a device token), keyed by guard name; per-call guardInputs
- * merge on top. Name the guards it covers in the caller's second type
- * parameter, `new LambderCaller<Contract, "orgPermission">`, and calls to
- * APIs whose guardInput guards are all covered no longer require the
- * options argument. May be async; a throw fails the call as an unknown
- * error before anything is sent.
- */
-export type LambderGuardInputsProvider<TContract, TProvided extends string> = (apiName: keyof TContract & string) => LambderProvidedGuardInputs<TContract, TProvided> | Promise<LambderProvidedGuardInputs<TContract, TProvided>>;
-/** Optional until the caller names provided guards: naming them without a provider would send nothing. */
-type GuardInputsProviderOption<TContract, TProvided extends string> = [
-    TProvided
-] extends [never] ? {
-    guardInputsProvider?: LambderGuardInputsProvider<TContract, TProvided>;
-} : {
-    guardInputsProvider: LambderGuardInputsProvider<TContract, TProvided>;
-};
-/** An API's guardInput guards the provider does not cover: those the call must still pass. */
-type RemainingGuardInputs<TEntry, TProvided extends string> = Omit<GuardInputsOf<TEntry>, TProvided>;
-/**
- * The options argument: optional normally, REQUIRED (with guardInputs) when
- * the API's contract declares guardInput-mode guards the provider does not
- * cover, so forgetting to send a guard's value is a compile error at the
- * call site. Provided guards may still be overridden per call.
- */
-type CallOptionsArg<TContract, TApiName, TProvided extends string> = IsAny<TContract> extends true ? [options?: LambderCallOptions] : TApiName extends keyof TContract ? [GuardInputsOf<TContract[TApiName]>] extends [never] ? [options?: LambderCallOptions] : [keyof RemainingGuardInputs<TContract[TApiName], TProvided>] extends [never] ? [options?: LambderCallOptions & {
-    guardInputs?: Partial<GuardInputsOf<TContract[TApiName]>>;
-}] : [
-    options: LambderCallOptions & {
-        guardInputs: RemainingGuardInputs<TContract[TApiName], TProvided> & Partial<GuardInputsOf<TContract[TApiName]>>;
-    }
-] : [options?: LambderCallOptions];
+import { type LambderApiOutcome, type LambderValidationError } from '../shared/LambderApiOutcome.js';
+import { type LambderCallOptionsArg, type LambderGuardInputsProviderOption } from '../shared/LambderCallOptions.js';
+export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError } from '../shared/LambderApiOutcome.js';
+export type { LambderProvidedGuardInputs, LambderGuardInputsProvider } from '../shared/LambderCallOptions.js';
 type VoidFunction = () => void | Promise<void>;
 type FetchTracker = {
     apiName: string;
@@ -73,7 +25,7 @@ type FetchEndEventHandler = (params: {
     activeFetchList: FetchTracker[];
 }) => void | Promise<void>;
 type ErrorHandler = (err: Error) => void | Promise<void>;
-type ValidationErrorHandler = (zodError: z.ZodError) => (void | false) | Promise<(void | false)>;
+type ValidationErrorHandler = (zodError: LambderValidationError) => (void | false) | Promise<(void | false)>;
 type MessageHandler = (message: any) => void | Promise<void>;
 /** One logical operation's rotating idempotency key: see LambderCaller.createIdempotencyKeyScope(). */
 export type LambderIdempotencyKeyScope = {
@@ -82,32 +34,6 @@ export type LambderIdempotencyKeyScope = {
     /** Call after a confirmed success: the next operation is a new intent. Returns the new key. */
     rotate(): string;
 };
-export type LambderApiFailureReason = 'network' | 'timeout' | 'server' | 'validation' | 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'errorMessage' | 'unknown';
-/**
- * Discriminated result of an API call: `ok: true` carries the payload, every
- * failure carries a machine-readable reason, so "the server returned null"
- * and "the request failed" are never conflated.
- */
-export type LambderApiOutcome<T> = {
-    ok: true;
-    payload: T | null | undefined;
-    response: LambderApiResponse<T>;
-} | {
-    ok: false;
-    reason: LambderApiFailureReason;
-    /** HTTP status, when a response was received. */
-    status?: number;
-    /** Envelope errorMessage, when the server provided one. */
-    errorMessage?: any;
-    /** Seconds to wait before retrying, from the response's Retry-After header (rate-limit refusals send it). */
-    retryAfterSeconds?: number;
-    /** Underlying Error for network/timeout/server/unknown failures. */
-    error?: Error;
-    /** Zod issue detail for 'validation'. */
-    zodError?: z.ZodError;
-    /** The parsed envelope, when one was received (protocol-level failures). */
-    response?: LambderApiResponse<T>;
-};
 /** Per-call options: request extras plus overrides for every constructor handler. */
 export type LambderCallOptions = {
     headers?: Record<string, any>;
@@ -179,7 +105,7 @@ type LambderCallerBaseOptions = {
     requestCompression?: LambderRequestCompressionOption;
 };
 /** Constructor options: the base options plus guardInputsProvider, mandatory once TProvided names guards. */
-export type LambderCallerOptions<TContract, TProvided extends string = never> = LambderCallerBaseOptions & GuardInputsProviderOption<TContract, TProvided>;
+export type LambderCallerOptions<TContract, TProvided extends string = never> = LambderCallerBaseOptions & LambderGuardInputsProviderOption<TContract, TProvided>;
 /**
  * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
  * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
@@ -238,8 +164,7 @@ export default class LambderCaller<TContract extends ApiContractShape = any, TPr
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
      * instead of collapsing every failure to null. Never throws.
      */
-    apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName, TProvidedGuards>): Promise<LambderApiOutcome<TOutput>>;
+    apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: LambderCallOptionsArg<TContract, TApiName, TProvidedGuards, LambderCallOptions>): Promise<LambderApiOutcome<TOutput>>;
     /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
-    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName, TProvidedGuards>): Promise<TOutput | null | undefined>;
+    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: LambderCallOptionsArg<TContract, TApiName, TProvidedGuards, LambderCallOptions>): Promise<TOutput | null | undefined>;
 }
-export {};

package/dist/client/LambderCaller.js

@@ -1,6 +1,8 @@
 import Cookies from 'js-cookie';
-import { compressPayloadJson, isRequestCompressionAvailable, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from '../shared/LambderRequestPayload.js';
+import { compressPayloadGzip, isRequestCompressionAvailable, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from '../shared/LambderRequestPayload.js';
 import { resolveCompressionOption } from '../shared/LambderCompressionOption.js';
+import { resolveApiOutcome } from '../shared/LambderApiOutcome.js';
+import { mergeGuardInputs, } from '../shared/LambderCallOptions.js';
 /**
  * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
  * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
@@ -180,9 +182,7 @@ export default class LambderCaller {
             const providedGuardInputs = this.guardInputsProvider
                 ? await this.guardInputsProvider(apiName)
                 : undefined;
-            const guardInputs = providedGuardInputs !== undefined || options?.guardInputs !== undefined
-                ? { ...providedGuardInputs, ...options?.guardInputs }
-                : undefined;
+            const guardInputs = mergeGuardInputs(providedGuardInputs, options?.guardInputs);
             // Compressed when enabled and the payload's JSON reaches the
             // threshold; `compressRequest` overrides both ways, and a runtime
             // without CompressionStream always sends the payload plainly.
@@ -192,7 +192,7 @@ export default class LambderCaller {
                 : options?.compressRequest === false ? null
                     : this.requestCompression?.minBytes ?? null;
             const compressedPayload = compressionMinBytes !== null && payload !== undefined && isRequestCompressionAvailable()
-                ? await compressPayloadJson(JSON.stringify(payload), compressionMinBytes)
+                ? await compressPayloadGzip(JSON.stringify(payload), compressionMinBytes)
                 : null;
             let res;
             try {
@@ -218,79 +218,47 @@ export default class LambderCaller {
                 await reportError(wrappedError);
                 return { ok: false, reason: timedOut ? 'timeout' : 'network', error: wrappedError };
             }
-            if (res.status >= 500) {
-                // Lambder's own 500 fallback is a JSON envelope, but custom
-                // error handlers may answer text/HTML: parse defensively.
-                let errorMessage;
-                try {
-                    const bodyText = await res.text();
-                    try {
-                        errorMessage = JSON.parse(bodyText)?.errorMessage;
-                    }
-                    catch { /* not an envelope */ }
-                }
-                catch { /* body unavailable */ }
-                const wrappedError = new Error("Request failed: " + res.status + " - " + res.statusText);
-                await fetchEnded(wrappedError);
-                await reportError(wrappedError);
-                return { ok: false, reason: 'server', status: res.status, errorMessage, error: wrappedError };
+            // The reading of the answer is shared with LambderInvokeCaller;
+            // only what to do about each outcome is this caller's.
+            const outcome = await resolveApiOutcome({
+                status: res.status,
+                statusText: res.statusText,
+                header: (name) => res.headers?.get?.(name) ?? null,
+                json: () => res.json(),
+                text: () => res.text(),
+            });
+            if (!outcome.ok && outcome.reason === 'server') {
+                await fetchEnded(outcome.error);
+                await reportError(outcome.error);
+                return outcome;
             }
-            if (res.status === 422) {
-                // A 422 without Lambder's validation body (e.g. a proxy's
-                // error page) is a server failure, not a validation result.
-                let zodError;
-                try {
-                    zodError = (await res.json())?.zodError;
-                }
-                catch { /* not JSON */ }
-                if (zodError === undefined) {
-                    const wrappedError = new Error("Request failed: 422 without a validation body");
-                    await fetchEnded(wrappedError);
-                    await reportError(wrappedError);
-                    return { ok: false, reason: 'server', status: res.status, error: wrappedError };
-                }
+            if (!outcome.ok && outcome.reason === 'validation') {
                 await fetchEnded(null);
                 if (apiInputValidationErrorHandler) {
-                    await apiInputValidationErrorHandler(zodError);
+                    await apiInputValidationErrorHandler(outcome.zodError);
                 }
                 else {
-                    await reportError(new Error("API Input Validation Error", { cause: zodError }));
+                    await reportError(new Error("API Input Validation Error", { cause: outcome.zodError }));
                 }
-                return { ok: false, reason: 'validation', status: res.status, zodError };
-            }
-            // Retry-After (delta-seconds) rides every refusal that knows its
-            // reset time, e.g. a rate limit; absent or unreadable is undefined.
-            const retryAfterValue = Number(res.headers.get("retry-after") ?? NaN);
-            const retryAfter = Number.isFinite(retryAfterValue) && retryAfterValue >= 0 ? { retryAfterSeconds: retryAfterValue } : {};
-            let data;
-            try {
-                data = await res.json();
-                if (data === null || typeof data !== "object")
-                    throw new Error("Response is not an object");
-            }
-            catch (err) {
-                // A non-envelope body (e.g. an HTML error page) is a server failure.
-                const wrappedError = new Error("Request failed: response is not a valid API envelope (status " + res.status + ")", { cause: err });
-                await fetchEnded(wrappedError);
-                await reportError(wrappedError);
-                return { ok: false, reason: 'server', status: res.status, error: wrappedError };
+                return outcome;
             }
+            const data = outcome.response;
             await fetchEnded(data);
             if (data.logList?.length) {
                 for (const record of data.logList) {
                     console.log("[lambder]", record);
                 }
             }
-            if (data.versionExpired) {
+            if (!outcome.ok && outcome.reason === 'versionExpired') {
                 if (versionExpiredHandler) {
                     await versionExpiredHandler();
                 }
                 else {
                     await reportError(new Error("Version Expired; Please refresh;"));
                 }
-                return { ok: false, reason: 'versionExpired', status: res.status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+                return outcome;
             }
-            if (data.sessionExpired) {
+            if (!outcome.ok && outcome.reason === 'sessionExpired') {
                 this.clearSessionCookies();
                 if (sessionExpiredHandler) {
                     await sessionExpiredHandler();
@@ -298,27 +266,27 @@ export default class LambderCaller {
                 else {
                     await reportError(new Error("Session Expired; Please log in again;"));
                 }
-                return { ok: false, reason: 'sessionExpired', status: res.status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+                return outcome;
             }
-            if (data.notAuthorized) {
+            if (!outcome.ok && outcome.reason === 'notAuthorized') {
                 if (notAuthorizedHandler) {
                     await notAuthorizedHandler();
                 }
                 else {
                     await reportError(new Error("Not Authorized;"));
                 }
-                return { ok: false, reason: 'notAuthorized', status: res.status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+                return outcome;
             }
             if (data.message && messageHandler) {
                 await messageHandler(data.message);
             }
-            if (data.errorMessage) {
+            if (!outcome.ok && outcome.reason === 'errorMessage') {
                 if (errorMessageHandler) {
                     await errorMessageHandler(data.errorMessage);
                 }
-                return { ok: false, reason: 'errorMessage', status: res.status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+                return outcome;
             }
-            return { ok: true, payload: data.payload, response: data };
+            return outcome;
         }
         catch (err) {
             // Escape hatch for anything above (typically an app handler throwing):

package/dist/client/LambderMSW.js

@@ -1,4 +1,4 @@
-import { COMPRESSED_PAYLOAD_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, decompressPayloadJson } from '../shared/LambderRequestPayload.js';
+import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, decompressPayloadGzip } from '../shared/LambderRequestPayload.js';
 export default class LambderMSW {
     apiPath;
     apiVersion;
@@ -46,15 +46,15 @@ export default class LambderMSW {
             // A caller with requestCompression on sends the payload gzipped;
             // mock handlers still receive the payload itself, and the wire
             // fields are consumed the way the server consumes them.
-            if (typeof body[COMPRESSED_PAYLOAD_FIELD] === 'string') {
+            if (typeof body[COMPRESSED_PAYLOAD_GZ_FIELD] === 'string') {
                 try {
-                    body.payload = await decompressPayloadJson(body[COMPRESSED_PAYLOAD_FIELD]);
+                    body.payload = await decompressPayloadGzip(body[COMPRESSED_PAYLOAD_GZ_FIELD]);
                 }
                 catch {
                     console.warn("LambderMSW: Failed to decompress the request payload");
                     return;
                 }
-                delete body[COMPRESSED_PAYLOAD_FIELD];
+                delete body[COMPRESSED_PAYLOAD_GZ_FIELD];
                 delete body[COMPRESSED_PAYLOAD_BYTES_FIELD];
             }
             try {

package/dist/client.d.ts

@@ -7,12 +7,14 @@
  * the root entry (`"lambder"`) is the server surface.
  */
 export { default as LambderCaller } from "./client/LambderCaller.js";
-export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope, } from "./client/LambderCaller.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope, } from "./client/LambderCaller.js";
 export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
 export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/LambderApiError.js";
 export type { ApiContractShape, LambderApiResponse, LambderApiResponseConfig } from "./shared/LambderApiContract.js";
-export { compressPayloadJson, decompressPayloadJson, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/LambderRequestPayload.js";
-export type { LambderCompressedPayload, LambderRequestCompressionOption, LambderRequestCompressionSettings, } from "./shared/LambderRequestPayload.js";
+export { describeCrash, errorFromCrashDetail } from "./shared/LambderCrashDetail.js";
+export type { LambderCrashDetail, LambderCrashCause } from "./shared/LambderCrashDetail.js";
+export { compressPayloadGzip, decompressPayloadGzip, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/LambderRequestPayload.js";
+export type { LambderCompressedGzipPayload, LambderCompressedBrotliPayload, LambderRequestCompressionOption, LambderRequestCompressionSettings, } from "./shared/LambderRequestPayload.js";
 export { resolveCompressionOption } from "./shared/LambderCompressionOption.js";
 export type { LambderCompressionOption, LambderCompressionSettingsBase } from "./shared/LambderCompressionOption.js";
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";

package/dist/client.js

@@ -11,8 +11,10 @@ export { default as LambderCaller } from "./client/LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;
 // in the browser they are plain Errors).
 export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.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/LambderCrashDetail.js";
 // Request payload compression (browser-safe: gzip via CompressionStream, no Node built-ins).
-export { compressPayloadJson, decompressPayloadJson, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/LambderRequestPayload.js";
+export { compressPayloadGzip, decompressPayloadGzip, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/LambderRequestPayload.js";
 // The compression option vocabulary every Lambder surface shares (pure: no zlib).
 export { resolveCompressionOption } from "./shared/LambderCompressionOption.js";
 // Type-safe templating (tagged templates with auto-escaping)

package/dist/core/Lambder.d.ts

@@ -297,7 +297,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     addSessionRoute<TPath extends Path>(condition: TPath, actionFn: (ctx: LambderSessionRenderContext<any, TSessionData, PathParamsOf<TPath>>, resolver: LambderResolver) => MaybePromise<LambderResponse>): this;
     addSessionRoute(condition: RegExp | ConditionFunction | LambderRouteMatcher, actionFn: SessionActionFunction<TSessionData>): this;
     use<_TNewContract extends Record<string, any>>(plugin: (lambder: Lambder<TSessionData, _TContract, any, any, any, any, any>) => Lambder<TSessionData, _TNewContract, any, any, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired>;
-    addApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, false> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, false> = never>(name: TName, schema: {
+    addApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, false> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, false> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
@@ -308,7 +308,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
             ttlSeconds?: number;
         }) : never;
     } & LambderRequirableGuardsField<_TPublicGuardsRequired, TGuardsOpt>, handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>, TGuardsOpt>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired>;
-    addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, true> = never>(name: TName, schema: {
+    addSessionApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, true> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {

package/dist/core/Lambder.js

@@ -11,7 +11,7 @@ import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
 import { createContext, isV2HttpEvent, restoreCompressedApiPayload } from "./LambderContext.js";
-import { DEFAULT_MAX_REQUEST_PAYLOAD_BYTES } from "../shared/LambderRequestPayload.js";
+import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/LambderRequestPayload.js";
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
  * instances with initLambder<SessionData>().create({...}) (see below): the
@@ -85,7 +85,7 @@ export default class Lambder {
             etag: options.etag ?? DEFAULT_FINALIZE_OPTIONS.etag,
             maxResponseBytes: options.maxResponseBytes ?? DEFAULT_FINALIZE_OPTIONS.maxResponseBytes,
         };
-        this.maxRequestPayloadBytes = options.maxRequestPayloadBytes ?? DEFAULT_MAX_REQUEST_PAYLOAD_BYTES;
+        this.maxRequestPayloadBytes = options.maxRequestPayloadBytes ?? DEFAULT_MAX_RESTORED_PAYLOAD_BYTES;
         if (!Number.isSafeInteger(this.maxRequestPayloadBytes) || this.maxRequestPayloadBytes <= 0) {
             throw new Error("maxRequestPayloadBytes must be a positive integer");
         }
@@ -211,7 +211,14 @@ export default class Lambder {
     async inputValidationRefusal(ctx, resolver, zodError) {
         if (this.apiInputValidationErrorHandler)
             return await this.apiInputValidationErrorHandler(ctx, resolver, zodError);
-        return resolver.json({ error: "Input validation failed", zodError }, { statusCode: 422 });
+        // Spelled out rather than serialized as-is: zod 4 keeps `issues` as a
+        // non-enumerable property, so JSON.stringify(zodError) would carry the
+        // issues only inside the message string, and a client's validation
+        // handler would receive a ZodError with nothing to branch on.
+        return resolver.json({
+            error: "Input validation failed",
+            zodError: { name: zodError.name, message: zodError.message, issues: zodError.issues },
+        }, { statusCode: 422 });
     }
     /** Registration-time checks shared by addApi/addSessionApi. */
     assertApiRegistration(name, mode, options) {

package/dist/core/LambderContext.d.ts

@@ -66,11 +66,12 @@ export type LambderRestorePayloadResult = {
     message: string;
 };
 /**
- * Restores a request payload the caller sent gzipped (`payloadGz` +
- * `payloadBytes`) onto ctx.post.payload and ctx.apiPayload, so every later
- * stage (rate-limit key slices, guards, input validation, the handler) reads
- * an ordinary payload and needs no awareness of the wire format. A request
- * that sent a plain payload passes through untouched.
+ * Restores a request payload the caller sent compressed (`payloadGz` or
+ * `payloadBr`, beside `payloadBytes`) onto ctx.post.payload and
+ * ctx.apiPayload, so every later stage (rate-limit key slices, guards, input
+ * validation, the handler) reads an ordinary payload and needs no awareness
+ * of the wire format. The field names the encoding; a request carrying both
+ * is refused. A request that sent a plain payload passes through untouched.
  *
  * Every failure answers with a message instead of throwing: a malformed body
  * is a client error, not a crash. The declared byte length both bounds the

package/dist/core/LambderContext.js

@@ -1,6 +1,6 @@
 import cookieParser from "cookie";
-import { COMPRESSED_PAYLOAD_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, } from "../shared/LambderRequestPayload.js";
-import { restoreBoundedText, LambderCompressionError, LAMBDER_RESTORE_FAILURES, } from "../shared/LambderCompressionCodec.js";
+import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, } from "../shared/LambderRequestPayload.js";
+import { restoreText, LambderCompressionError, LAMBDER_RESTORE_FAILURES, } from "../shared/LambderCompressionCodec.js";
 /** True for API Gateway HTTP API / Lambda Function URL (payload v2) events. */
 export const isV2HttpEvent = (event) => !!event && typeof event === "object"
     && event.version === "2.0"
@@ -101,11 +101,12 @@ export const createContext = (event, lambdaContext, apiPath) => {
     };
 };
 /**
- * Restores a request payload the caller sent gzipped (`payloadGz` +
- * `payloadBytes`) onto ctx.post.payload and ctx.apiPayload, so every later
- * stage (rate-limit key slices, guards, input validation, the handler) reads
- * an ordinary payload and needs no awareness of the wire format. A request
- * that sent a plain payload passes through untouched.
+ * Restores a request payload the caller sent compressed (`payloadGz` or
+ * `payloadBr`, beside `payloadBytes`) onto ctx.post.payload and
+ * ctx.apiPayload, so every later stage (rate-limit key slices, guards, input
+ * validation, the handler) reads an ordinary payload and needs no awareness
+ * of the wire format. The field names the encoding; a request carrying both
+ * is refused. A request that sent a plain payload passes through untouched.
  *
  * Every failure answers with a message instead of throwing: a malformed body
  * is a client error, not a crash. The declared byte length both bounds the
@@ -114,11 +115,18 @@ export const createContext = (event, lambdaContext, apiPath) => {
  */
 export const restoreCompressedApiPayload = async (ctx, maxPayloadBytes) => {
     const post = ctx.post;
-    const compressed = post[COMPRESSED_PAYLOAD_FIELD];
-    if (compressed === undefined)
+    const hasGzip = post[COMPRESSED_PAYLOAD_GZ_FIELD] !== undefined;
+    const hasBrotli = post[COMPRESSED_PAYLOAD_BR_FIELD] !== undefined;
+    if (!hasGzip && !hasBrotli)
         return { ok: true };
+    if (hasGzip && hasBrotli) {
+        return { ok: false, message: `Request carries both ${COMPRESSED_PAYLOAD_GZ_FIELD} and ${COMPRESSED_PAYLOAD_BR_FIELD}; send one.` };
+    }
+    const field = hasGzip ? COMPRESSED_PAYLOAD_GZ_FIELD : COMPRESSED_PAYLOAD_BR_FIELD;
+    const encoding = hasGzip ? "gzip" : "br";
+    const compressed = post[field];
     if (typeof compressed !== "string") {
-        return { ok: false, message: `Request ${COMPRESSED_PAYLOAD_FIELD} must be a base64 string.` };
+        return { ok: false, message: `Request ${field} must be a base64 string.` };
     }
     const declaredBytes = post[COMPRESSED_PAYLOAD_BYTES_FIELD];
     if (typeof declaredBytes !== "number" || !Number.isSafeInteger(declaredBytes) || declaredBytes <= 0) {
@@ -131,7 +139,7 @@ export const restoreCompressedApiPayload = async (ctx, maxPayloadBytes) => {
     // ones a stored record gets; only the wording of the refusal is ours.
     let json;
     try {
-        json = await restoreBoundedText(Buffer.from(compressed, "base64"), declaredBytes, "gzip");
+        json = await restoreText(Buffer.from(compressed, "base64"), encoding, { declaredBytes });
     }
     catch (err) {
         const reason = err instanceof LambderCompressionError ? err.reason : null;
@@ -146,7 +154,7 @@ export const restoreCompressedApiPayload = async (ctx, maxPayloadBytes) => {
     catch {
         return { ok: false, message: "Compressed request payload is not valid JSON." };
     }
-    delete post[COMPRESSED_PAYLOAD_FIELD];
+    delete post[field];
     delete post[COMPRESSED_PAYLOAD_BYTES_FIELD];
     post.payload = payload;
     ctx.apiPayload = payload;

package/dist/core/LambderResolver.d.ts

@@ -1,4 +1,4 @@
-import LambderResponseBuilder, { type LambderApiResponseConfig, type LambderResponseOptions } from "./LambderResponseBuilder.js";
+import LambderResponseBuilder, { type LambderApiAnswer, type LambderApiResponseConfig, type LambderResponseOptions } 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>;
@@ -13,8 +13,8 @@ export interface DieResolverMethods<TOutput> {
     redirect: SyncDie<LambderResponseBuilder["redirect"]>;
     versionExpired: SyncDie<LambderResponseBuilder["versionExpired"]>;
     fileBase64: SyncDie<LambderResponseBuilder["fileBase64"]>;
-    api: (payload: TOutput | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions) => never;
-    apiBinary: (payload: TOutput | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions) => never;
+    api: LambderApiAnswer<TOutput, never>;
+    apiBinary: LambderApiAnswer<TOutput, never>;
     file: AsyncDie<LambderResponseBuilder["file"]>;
     templateFile: AsyncDie<LambderResponseBuilder["templateFile"]>;
 }
@@ -29,7 +29,9 @@ export interface DieResolverMethods<TOutput> {
 export default class LambderResolver<TOutput = any> extends LambderResponseBuilder<TOutput> {
     die: DieResolverMethods<TOutput>;
     constructor(...args: ConstructorParameters<typeof LambderResponseBuilder>);
-    api(payload: TOutput | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    apiBinary(payload: TOutput | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    api(payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    api(payload: null, config: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    apiBinary(payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    apiBinary(payload: null, config: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
 }
 export {};

package/dist/core/LambderResolver.js

@@ -22,13 +22,17 @@ export default class LambderResolver extends LambderResponseBuilder {
             redirect: (...a) => { throw this.redirect(...a); },
             versionExpired: (...a) => { throw this.versionExpired(...a); },
             fileBase64: (...a) => { throw this.fileBase64(...a); },
-            api: (...a) => { throw this.api(...a); },
-            apiBinary: (...a) => { throw this.apiBinary(...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);
+            }),
             file: async (...a) => { throw await this.file(...a); },
             templateFile: async (...a) => { throw await this.templateFile(...a); },
         };
     }
-    // Override api method with proper output typing
     api(payload, config, options) {
         return super.api(payload, config, options);
     }

package/dist/core/LambderResponseBuilder.d.ts

@@ -16,6 +16,18 @@ 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 is what lets a typed caller (LambderInvokeCaller.api) promise it.
+ * Untyped resolvers (`TOutput = any`) accept anything, as before.
+ */
+export type LambderApiAnswer<TOutput, TResult> = {
+    (payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): TResult;
+    (payload: null, config: LambderApiResponseConfig, options?: LambderResponseOptions): TResult;
+};
 export type LambderRawResponseInit = {
     statusCode: HttpStatusCode;
     headers?: LambderHeadersInput;
@@ -76,7 +88,9 @@ export default class LambderResponseBuilder<TResponse = any> {
     templateFile(filePath: string, data?: LambderTemplateData, options?: LambderResponseOptions & {
         htmlVirtualSlots?: boolean;
     }): Promise<LambderResponse>;
-    api(payload: TResponse | null, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, }?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    /** Same as api() but forces gzip compression of the response body. */
-    apiBinary(payload: TResponse | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    api(payload: TResponse, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    api(payload: null, config: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    /** Same as api() but forces compression of the response body. */
+    apiBinary(payload: TResponse, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    apiBinary(payload: null, config: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
 }