lambder 4.0.1 → 4.2.1

package/dist/core/Lambder.js

@@ -10,19 +10,22 @@ import { isLambderApiError } from "../shared/LambderApiError.js";
 import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.js";
 /**
- * Main Lambder class for building type-safe serverless APIs
+ * Main Lambder class for building type-safe serverless APIs. Create
+ * instances with initLambder<SessionData>().create({...}) (see below): the
+ * whole configuration, including the typed policy layer, is given at
+ * construction, and only registration (routes, apis, hooks, use) chains.
  *
  * @typeParam TSessionData - Type of session data stored in DynamoDB
  * @typeParam _TContract - @internal Accumulates API contract during chaining (do not pass manually)
- * @typeParam _TRateLimitPolicies - @internal Accumulated by enableApiRateLimits (do not pass manually)
- * @typeParam _TGuards - @internal Guard name to required-payload map, accumulated by defineApiGuards (do not pass manually)
- * @typeParam _TIdempotencyEnabled - @internal Flipped by enableApiIdempotency (do not pass manually)
+ * @typeParam _TRateLimitPolicies - @internal Inferred from create()'s rateLimits.policies (do not pass manually)
+ * @typeParam _TGuards - @internal Guard metadata map inferred from create()'s guards (do not pass manually)
+ * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
  *
  * @example
  * ```typescript
  * interface SessionData { userId: string; role: string; }
  *
- * const lambder = new Lambder<SessionData>({ apiPath: '/api' })
+ * const lambder = initLambder<SessionData>().create({ apiPath: '/api' })
  *   .addApi('getUser', { input: z.object({...}), output: z.object({...}) }, handler)
  *   .addApi('createUser', { input: z.object({...}), output: z.object({...}) }, handler);
  * ```
@@ -73,26 +76,33 @@ export default class Lambder {
             etag: options.etag ?? DEFAULT_FINALIZE_OPTIONS.etag,
             maxResponseBytes: options.maxResponseBytes ?? DEFAULT_FINALIZE_OPTIONS.maxResponseBytes,
         };
-    }
-    enableCors(config) {
-        this.corsConfig = config === true ? {} : (config === false ? null : config);
-        return this;
-    }
-    enableDdbSession({ tableName, tableRegion, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, cookie, partitionKey, sortKey, dataRefresh, }) {
-        this.lambderSessionManager = new LambderSessionManager({
-            tableName, tableRegion,
-            partitionKey: partitionKey ?? "pk",
-            sortKey: sortKey ?? "sk",
-            sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds,
-            dataRefresh,
-        });
-        this.sessionCookieOptions = cookie ?? {};
-        return this;
-    }
-    setSessionCookieKey(sessionTokenCookieKey, sessionCsrfCookieKey) {
-        this.sessionTokenCookieKey = sessionTokenCookieKey;
-        this.sessionCsrfCookieKey = sessionCsrfCookieKey;
-        return this;
+        if (options.cors !== undefined && options.cors !== false) {
+            this.corsConfig = options.cors === true ? {} : options.cors;
+        }
+        if (options.session) {
+            const session = options.session;
+            this.lambderSessionManager = new LambderSessionManager({
+                tableName: session.tableName,
+                tableRegion: session.tableRegion,
+                partitionKey: session.partitionKey ?? "pk",
+                sortKey: session.sortKey ?? "sk",
+                sessionSalt: session.sessionSalt,
+                enableSlidingExpiration: session.enableSlidingExpiration,
+                slidingWriteIntervalSeconds: session.slidingWriteIntervalSeconds,
+                dataRefresh: session.dataRefresh,
+            });
+            this.sessionCookieOptions = session.cookie ?? {};
+            if (session.tokenCookieKey)
+                this.sessionTokenCookieKey = session.tokenCookieKey;
+            if (session.csrfCookieKey)
+                this.sessionCsrfCookieKey = session.csrfCookieKey;
+        }
+        if (options.rateLimits)
+            this.getOrCreatePolicyEngine().setRateLimits(options.rateLimits);
+        if (options.guards)
+            this.getOrCreatePolicyEngine().addGuards(options.guards);
+        if (options.idempotency)
+            this.getOrCreatePolicyEngine().setIdempotency(options.idempotency);
     }
     setRouteFallbackHandler(routeFallbackHandler) {
         this.routeFallbackHandler = routeFallbackHandler;
@@ -162,56 +172,24 @@ export default class Lambder {
         }
         return response;
     }
-    // ---------------------------------------------------------------------
-    // Declarative API policies (rate limits, guards, idempotency)
-    // ---------------------------------------------------------------------
-    /**
-     * Wire declarative per-API rate limiting: your LambderDdbRateLimiter
-     * instance plus named policies, each declaring its windows and what one
-     * counter tracks (`per`: "ip", "session", or a custom key function).
-     * APIs then reference policies by name via the `rateLimit` option; the
-     * returned type narrows so only declared names are accepted, and
-     * policies keyed per "session" are only referable from addSessionApi.
-     * Callable once; call it before the API registrations that use it.
-     */
-    enableApiRateLimits(config) {
-        this.getOrCreatePolicyEngine().setRateLimits(config);
-        return this;
-    }
-    /**
-     * Wire declarative idempotency: your LambderDdbIdempotency instance plus
-     * replay defaults. APIs opt in via `idempotency: true | { ttlSeconds }`;
-     * the option is a type error until this is called. Requests carrying a
-     * client `idempotencyKey` (sent by LambderCaller) claim an
-     * identity+api+key scope atomically: concurrent duplicates refuse with
-     * 409, replays of a completed request return the stored response, and a
-     * crashed original releases its claim. Callable once.
-     */
-    enableApiIdempotency(config) {
-        this.getOrCreatePolicyEngine().setIdempotency(config);
-        return this;
-    }
-    /**
-     * Define named guards that APIs reference (typed) via the `guards`
-     * option. Each guard is built with lambderGuard(): its input mode
-     * (apiInput slice of the API's own payload, a separate client-sent
-     * guardInput, or none), an optional `session: true` requirement, an
-     * optional parameter APIs pass in their declaration (`guards: { name:
-     * param }`), and an optional return value that lands typed on the
-     * handler's ctx.guardData[name]. Guards run before input validation, in
-     * the order the API declares them; a handler refuses by throwing
-     * (typically refuse()). Callable multiple times so domain modules can
-     * contribute their own; names must not collide.
-     */
-    defineApiGuards(guards) {
-        this.getOrCreatePolicyEngine().addGuards(guards);
-        return this;
-    }
     getOrCreatePolicyEngine() {
+        // Late-bound: the handler may be set after creation, so the engine
+        // asks at request time rather than capturing it here.
         if (!this.apiPolicyEngine)
-            this.apiPolicyEngine = new LambderApiPolicyEngine();
+            this.apiPolicyEngine = new LambderApiPolicyEngine((ctx, resolver, zodError) => this.inputValidationRefusal(ctx, resolver, zodError));
         return this.apiPolicyEngine;
     }
+    /**
+     * The response for a rejected input: the app's
+     * setApiInputValidationErrorHandler when set, otherwise the standard 422
+     * body. The API's own schema and every preflight slice (guard inputs,
+     * rate-limit keys) answer through here, so one failure has one shape.
+     */
+    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 });
+    }
     /** Registration-time checks shared by addApi/addSessionApi. */
     assertApiRegistration(name, mode, options) {
         if (this.registeredApiNames.has(name)) {
@@ -222,7 +200,7 @@ export default class Lambder {
         if (!usesPolicies)
             return;
         if (!this.apiPolicyEngine) {
-            throw new Error(`Lambder: API "${name}" declares rateLimit/guards/idempotency, but none of enableApiRateLimits()/defineApiGuards()/enableApiIdempotency() was called first.`);
+            throw new Error(`Lambder: API "${name}" declares rateLimit/guards/idempotency, but none of rateLimits/guards/idempotency was configured at creation.`);
         }
         this.apiPolicyEngine.assertRegistration(name, mode, options);
     }
@@ -268,12 +246,8 @@ export default class Lambder {
                 if (this.apiPolicyEngine)
                     await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);
-                if (!inputResult.success) {
-                    if (this.apiInputValidationErrorHandler) {
-                        return await this.apiInputValidationErrorHandler(ctx, resolver, inputResult.error);
-                    }
-                    return resolver.json({ error: "Input validation failed", zodError: inputResult.error }, { statusCode: 422 });
-                }
+                if (!inputResult.success)
+                    return await this.inputValidationRefusal(ctx, resolver, inputResult.error);
                 ctx.apiPayload = inputResult.data;
                 const run = async () => await handler(ctx, resolver);
                 if (this.apiPolicyEngine && schema.idempotency)
@@ -300,12 +274,8 @@ export default class Lambder {
                 if (this.apiPolicyEngine)
                     await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);
-                if (!inputResult.success) {
-                    if (this.apiInputValidationErrorHandler) {
-                        return await this.apiInputValidationErrorHandler(ctx, resolver, inputResult.error);
-                    }
-                    return resolver.json({ error: "Input validation failed", zodError: inputResult.error }, { statusCode: 422 });
-                }
+                if (!inputResult.success)
+                    return await this.inputValidationRefusal(ctx, resolver, inputResult.error);
                 ctx.apiPayload = inputResult.data;
                 const run = async () => await handler(ctx, resolver);
                 if (this.apiPolicyEngine && schema.idempotency)
@@ -345,7 +315,7 @@ export default class Lambder {
     }
     getSessionController(ctx) {
         if (!this.lambderSessionManager)
-            throw new Error("Session is not enabled. Use lambder.enableDdbSession(...) to enable.");
+            throw new Error("Session is not enabled. Configure the session option at creation.");
         return new LambderSessionController({
             lambderSessionManager: this.lambderSessionManager,
             sessionTokenCookieKey: this.sessionTokenCookieKey,
@@ -376,7 +346,10 @@ export default class Lambder {
             ...(err.errorMessage !== undefined ? { errorMessage: err.errorMessage } : {}),
             ...(err.notAuthorized ? { notAuthorized: true } : {}),
             ...(err.sessionExpired ? { sessionExpired: true } : {}),
-        }, err.statusCode !== undefined ? { statusCode: err.statusCode } : undefined);
+        }, {
+            ...(err.statusCode !== undefined ? { statusCode: err.statusCode } : {}),
+            ...(err.headers ? { headers: err.headers } : {}),
+        });
     }
     getHandler() {
         return ((event, context) => Lambder.isHttpEvent(event)
@@ -450,7 +423,7 @@ export default class Lambder {
         if (isAPI) {
             if (this.apiFallbackHandler)
                 return await this.apiFallbackHandler(ctx, resolver);
-            return resolver.api(null, { errorMessage: "API not found." });
+            return resolver.api(null, { errorMessage: { type: "warning", content: "API not found." } });
         }
         if (this.publicFilesHandler) {
             const fileResponse = await this.publicFilesHandler.handle(ctx);
@@ -582,6 +555,46 @@ export default class Lambder {
         }
     }
 }
+/**
+ * The canonical way to create an instance: fix the session data type first,
+ * then create with the full configuration in one declaration; the policy,
+ * guard, and idempotency types are INFERRED from the options, so the
+ * instance is born fully typed and `typeof lambderApp` is the annotation
+ * type for api modules. No enable/define chain exists, so there are no
+ * ordering rules and nothing can be half-configured.
+ *
+ * ```typescript
+ * // app.ts (imports no api modules, so modules can import the type back)
+ * export const lambderApp = initLambder<SessionData>().create({
+ *     apiPath: "/api",
+ *     session: { tableName: "app-session", tableRegion: "us-east-1", sessionSalt: "..." },
+ *     rateLimits: { limiter, policies },
+ *     guards,
+ *     idempotency: { store },
+ * });
+ * export type AppLambder = typeof lambderApp;
+ *
+ * // orders.ts
+ * export const orderApi = (lambder: AppLambder) => lambder.addSessionApi(...);
+ *
+ * // index.ts: registration only
+ * const lambder = lambderApp.addHook(...).use(orderApi)...;
+ * export const handler = lambder.getHandler();
+ * ```
+ *
+ * Why curried (`initLambder<S>().create(...)` rather than
+ * `new Lambder<S>(...)`): TypeScript type arguments are all-or-nothing per
+ * call, so explicitly passing the session data type to the constructor
+ * would silently WIDEN the inferred policy and guard types to their {}
+ * defaults. Fixing the session type in the first call lets the second call
+ * infer everything else from the options. `new Lambder(options)` remains
+ * for untyped or session-data-free instances.
+ */
+export const initLambder = () => ({
+    create(options) {
+        return new Lambder(options);
+    },
+});
 /** Rebuild the query string from the API Gateway event for redirects. */
 const buildQueryString = (ctx) => {
     if (isV2HttpEvent(ctx.event)) {

package/dist/core/LambderCors.d.ts

@@ -6,6 +6,12 @@ export type LambderCorsConfig = {
     credentials?: boolean;
     methods?: string[];
     allowHeaders?: string[];
+    /**
+     * Response headers a cross-origin browser caller may read. Default:
+     * ["Retry-After"], so rate-limit refusals stay readable (it is not on the
+     * CORS safelist, and a hidden header reads as null, not as an error).
+     */
+    exposeHeaders?: string[];
     maxAge?: number;
 };
 /** Mutate the response with the CORS headers the config allows for this request. */

package/dist/core/LambderCors.js

@@ -27,4 +27,9 @@ export const applyCorsHeaders = (config, ctx, response, isPreflight) => {
         if (config.maxAge !== undefined)
             response.setHeader("Access-Control-Max-Age", String(config.maxAge));
     }
+    else {
+        const exposeHeaders = config.exposeHeaders ?? ["Retry-After"];
+        if (exposeHeaders.length)
+            response.setHeader("Access-Control-Expose-Headers", exposeHeaders.join(", "));
+    }
 };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import Lambder from './core/Lambder.js';
 export default Lambder;
+export { initLambder } from './core/Lambder.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
 export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderIdempotencyKeyScope } from "./client/LambderCaller.js";
 export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
@@ -13,7 +14,7 @@ export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtm
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
 export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/LambderResponseBuilder.js";
-export type { LambderRouteMatcher, LambderCorsConfig, LambderConstructorOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, LambderApp, } from "./core/Lambder.js";
+export type { LambderRouteMatcher, LambderCorsConfig, LambderCreateOptions, LambderSessionOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, } from "./core/Lambder.js";
 export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
 export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
@@ -22,13 +23,13 @@ export { LambderSessionDataRefreshError, LambderSessionReadError } from "./sessi
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";
 export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./stores/LambderDdbCache.js";
 export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
-export type { LambderDdbRateLimiterOptions, LambderRateLimitPolicy, LambderRateLimitExceededMap, LambderRateLimitResult, } from "./stores/LambderDdbRateLimiter.js";
+export type { LambderDdbRateLimiterOptions, LambderRateLimitWindow, LambderRateLimitPolicy, LambderRateLimitExceeded, LambderRateLimitResult, } from "./stores/LambderDdbRateLimiter.js";
 export { LambderDdbIdempotency } from "./stores/LambderDdbIdempotency.js";
 export type { LambderDdbIdempotencyOptions, LambderIdempotencyBeginResult, LambderIdempotencyDoneRecord, } from "./stores/LambderDdbIdempotency.js";
 export { lambderGuard } from "./policies/LambderApiGuards.js";
 export type { LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderAllowedGuardNames, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardsOptionValue, LambderGuardDataOf, LambderGuardInputsOf, } from "./policies/LambderApiGuards.js";
 export { lambderRateLimitKey } from "./policies/LambderApiRateLimits.js";
-export type { LambderRateLimitKeyFn, LambderRateLimitPer, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, } from "./policies/LambderApiRateLimits.js";
+export type { LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderRateLimitOverride, LambderRateLimitOption, LambderRateLimitOptionValue, } from "./policies/LambderApiRateLimits.js";
 export type { LambderApiIdempotencyConfig } from "./policies/LambderApiIdempotency.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import Lambder from './core/Lambder.js';
 export default Lambder;
+export { initLambder } from './core/Lambder.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere)
 export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";

package/dist/policies/LambderApiGuards.d.ts

@@ -1,6 +1,7 @@
 import type { z } from "zod";
 import type { LambderRenderContext, LambderSessionRenderContext } from "../core/LambderContext.js";
 import type LambderResolver from "../core/LambderResolver.js";
+import type { LambderResponse } from "../core/LambderResponse.js";
 /**
  * A named guard, run before the API's own input validation. Three input
  * modes:
@@ -30,9 +31,10 @@ import type LambderResolver from "../core/LambderResolver.js";
  *   the API handler's context as `ctx.guardData[guardName]`, fully typed.
  *   Guards that return nothing never appear in guardData.
  *
- * A validation failure answers the standard 422 shape, and the handler
- * refuses by throwing (typically refuse()/LambderApiError). Build with
- * lambderGuard() so the handler's payload/ctx/param types line up.
+ * A validation failure answers like the API's own input validation (the
+ * app's setApiInputValidationErrorHandler when set, else the standard 422),
+ * and the handler refuses by throwing (typically refuse()/LambderApiError).
+ * Build with lambderGuard() so the handler's payload/ctx/param types line up.
  */
 export type LambderApiGuard<TInput extends z.ZodTypeAny = z.ZodTypeAny, TParam = any, TOutput = any> = {
     apiInput: TInput;
@@ -198,20 +200,29 @@ type GuardInputsEntries<TGuards, TOpt> = {
 export type LambderGuardInputsOf<TGuards, TOpt> = keyof GuardInputsEntries<TGuards, TOpt> extends never ? never : GuardInputsEntries<TGuards, TOpt>;
 /** The guards option's runtime shape: a name, ordered names, or a name-to-param map. */
 export type LambderGuardsOptionValue = string | readonly string[] | Readonly<Record<string, unknown>>;
+/**
+ * How a rejected input answers. Lambder binds this to its own decision
+ * (setApiInputValidationErrorHandler when set, else the standard 422 body),
+ * so the API's schema and every preflight slice refuse with one shape.
+ */
+export type LambderInputValidationRefusal = (ctx: LambderRenderContext, resolver: LambderResolver, zodError: z.ZodError) => Promise<LambderResponse>;
 /**
  * Validate a preflight input slice (an apiInput slice of the raw payload, or
  * a guardInput value from the raw guardInputs map). Runs before the API's
- * own validation; failures answer the same 422 shape as regular input
- * validation. Shared with the rate-limit engine's apiInput-keyed policies.
+ * own validation; a failure throws the response `onInvalid` decides, the
+ * same one regular input validation answers. Shared with the rate-limit
+ * engine's apiInput-keyed policies.
  */
-export declare const parsePreflightSlice: (input: z.ZodTypeAny, value: unknown, resolver: LambderResolver) => unknown;
+export declare const parsePreflightSlice: (input: z.ZodTypeAny, value: unknown, ctx: LambderRenderContext, resolver: LambderResolver, onInvalid: LambderInputValidationRefusal) => Promise<unknown>;
 /**
  * Runtime side of the guards subsystem: holds the defined guards, asserts
  * API registrations against them at startup, and executes an API's declared
  * guards during preflight. Composed into LambderApiPolicyEngine.
  */
 export declare class LambderApiGuardsEngine {
+    private readonly onInvalidInput;
     private guards;
+    constructor(onInvalidInput: LambderInputValidationRefusal);
     addGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
     /** Startup validation of one API registration's guards option. */
     assertRegistration(apiName: string, mode: "public" | "session", guardsOption?: LambderGuardsOptionValue): void;

package/dist/policies/LambderApiGuards.js

@@ -14,14 +14,14 @@ const toGuardEntries = (value) => {
 /**
  * Validate a preflight input slice (an apiInput slice of the raw payload, or
  * a guardInput value from the raw guardInputs map). Runs before the API's
- * own validation; failures answer the same 422 shape as regular input
- * validation. Shared with the rate-limit engine's apiInput-keyed policies.
+ * own validation; a failure throws the response `onInvalid` decides, the
+ * same one regular input validation answers. Shared with the rate-limit
+ * engine's apiInput-keyed policies.
  */
-export const parsePreflightSlice = (input, value, resolver) => {
+export const parsePreflightSlice = async (input, value, ctx, resolver, onInvalid) => {
     const parsed = input.safeParse(value);
-    if (!parsed.success) {
-        throw resolver.json({ error: "Input validation failed", zodError: parsed.error }, { statusCode: 422 });
-    }
+    if (!parsed.success)
+        throw await onInvalid(ctx, resolver, parsed.error);
     return parsed.data;
 };
 /**
@@ -30,7 +30,11 @@ export const parsePreflightSlice = (input, value, resolver) => {
  * guards during preflight. Composed into LambderApiPolicyEngine.
  */
 export class LambderApiGuardsEngine {
+    onInvalidInput;
     guards = {};
+    constructor(onInvalidInput) {
+        this.onInvalidInput = onInvalidInput;
+    }
     addGuards(guards) {
         for (const [name, guardDef] of Object.entries(guards)) {
             if (this.guards[name])
@@ -47,7 +51,7 @@ export class LambderApiGuardsEngine {
         for (const { name } of toGuardEntries(guardsOption)) {
             const guardDef = this.guards[name];
             if (!guardDef) {
-                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Define it via defineApiGuards() before registering the API.`);
+                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Declare it in the guards option at creation.`);
             }
             if (guardDef.session && mode !== "session") {
                 throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true), which requires addSessionApi.`);
@@ -63,10 +67,10 @@ export class LambderApiGuardsEngine {
             const post = ctx.post;
             let payload;
             if (guardDef.apiInput) {
-                payload = parsePreflightSlice(guardDef.apiInput, post?.payload, resolver);
+                payload = await parsePreflightSlice(guardDef.apiInput, post?.payload, ctx, resolver, this.onInvalidInput);
             }
             else if (guardDef.guardInput) {
-                payload = parsePreflightSlice(guardDef.guardInput, post?.guardInputs?.[name], resolver);
+                payload = await parsePreflightSlice(guardDef.guardInput, post?.guardInputs?.[name], ctx, resolver, this.onInvalidInput);
             }
             // A guard's return value becomes the handler's typed
             // ctx.guardData[name]; check-only guards return undefined.

package/dist/policies/LambderApiIdempotency.d.ts

@@ -19,7 +19,7 @@ export declare class LambderApiIdempotencyEngine {
     private defaultTtlSeconds;
     private failOpen;
     configure(config: LambderApiIdempotencyConfig): void;
-    /** True once enableApiIdempotency() ran; registration asserts check it. */
+    /** True once the idempotency option was configured; registration asserts check it. */
     get isConfigured(): boolean;
     /**
      * The request's idempotencyKey: null when absent, the key when valid, a

package/dist/policies/LambderApiIdempotency.js

@@ -20,12 +20,12 @@ export class LambderApiIdempotencyEngine {
     failOpen = true;
     configure(config) {
         if (this.store)
-            throw new Error("Lambder: enableApiIdempotency() was already called.");
+            throw new Error("Lambder: idempotency was already configured.");
         this.store = config.store;
         this.defaultTtlSeconds = config.defaultTtlSeconds ?? 24 * 3600;
         this.failOpen = config.failOpen ?? true;
     }
-    /** True once enableApiIdempotency() ran; registration asserts check it. */
+    /** True once the idempotency option was configured; registration asserts check it. */
     get isConfigured() { return this.store !== null; }
     /**
      * The request's idempotencyKey: null when absent, the key when valid, a
@@ -37,7 +37,11 @@ export class LambderApiIdempotencyEngine {
         if (rawKey === undefined || rawKey === null)
             return null;
         if (typeof rawKey !== "string" || rawKey.length < IDEMPOTENCY_MIN_KEY_LENGTH || rawKey.length > IDEMPOTENCY_MAX_KEY_LENGTH) {
-            throw new LambderApiError(`Invalid idempotency key: must be a string of ${IDEMPOTENCY_MIN_KEY_LENGTH}-${IDEMPOTENCY_MAX_KEY_LENGTH} characters.`, { statusCode: 400 });
+            const content = `Invalid idempotency key: must be a string of ${IDEMPOTENCY_MIN_KEY_LENGTH}-${IDEMPOTENCY_MAX_KEY_LENGTH} characters.`;
+            throw new LambderApiError(content, {
+                statusCode: 400,
+                errorMessage: { type: "error", content },
+            });
         }
         return rawKey;
     }
@@ -112,7 +116,7 @@ export class LambderApiIdempotencyEngine {
         if (begun.state === "pending") {
             throw new LambderApiError(`Duplicate request for "${apiName}": the original is still processing.`, {
                 statusCode: 409,
-                errorMessage: "This request is already being processed.",
+                errorMessage: { type: "warning", content: "This request is already being processed." },
             });
         }
         if (begun.state === "done") {

package/dist/policies/LambderApiPolicies.d.ts

@@ -1,12 +1,12 @@
 import type { LambderRenderContext } from "../core/LambderContext.js";
 import type LambderResolver from "../core/LambderResolver.js";
 import type { LambderResponse } from "../core/LambderResponse.js";
-import { type LambderApiGuard, type LambderGuardsOptionValue } from "./LambderApiGuards.js";
-import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
+import { type LambderApiGuard, type LambderGuardsOptionValue, type LambderInputValidationRefusal } from "./LambderApiGuards.js";
+import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderRateLimitOptionValue } from "./LambderApiRateLimits.js";
 import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
 /** The declarative options one API registration may carry. */
 type LambderApiPolicyOptions = {
-    rateLimit?: string | readonly string[];
+    rateLimit?: LambderRateLimitOptionValue;
     guards?: LambderGuardsOptionValue;
     idempotency?: unknown;
 };
@@ -16,13 +16,15 @@ type LambderApiPolicyOptions = {
  * ./LambderApiGuards.ts, idempotency in ./LambderApiIdempotency.ts), asserts
  * registrations against them at startup, and executes them around handlers
  * at request time. Internal to Lambder; apps interact through
- * enableApiRateLimits(), enableApiIdempotency(), defineApiGuards() and the
+ * the create() options (rateLimits, guards, idempotency) and the
  * per-API options.
  */
 export declare class LambderApiPolicyEngine {
     private rateLimits;
     private guards;
     private idempotency;
+    /** `onInvalidInput` is Lambder's input-validation refusal, so preflight slices answer exactly like the API's own schema. */
+    constructor(onInvalidInput: LambderInputValidationRefusal);
     setRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
     addGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
     setIdempotency(config: LambderApiIdempotencyConfig): void;

package/dist/policies/LambderApiPolicies.js

@@ -7,13 +7,18 @@ import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
  * ./LambderApiGuards.ts, idempotency in ./LambderApiIdempotency.ts), asserts
  * registrations against them at startup, and executes them around handlers
  * at request time. Internal to Lambder; apps interact through
- * enableApiRateLimits(), enableApiIdempotency(), defineApiGuards() and the
+ * the create() options (rateLimits, guards, idempotency) and the
  * per-API options.
  */
 export class LambderApiPolicyEngine {
-    rateLimits = new LambderApiRateLimitsEngine();
-    guards = new LambderApiGuardsEngine();
+    rateLimits;
+    guards;
     idempotency = new LambderApiIdempotencyEngine();
+    /** `onInvalidInput` is Lambder's input-validation refusal, so preflight slices answer exactly like the API's own schema. */
+    constructor(onInvalidInput) {
+        this.rateLimits = new LambderApiRateLimitsEngine(onInvalidInput);
+        this.guards = new LambderApiGuardsEngine(onInvalidInput);
+    }
     setRateLimits(config) {
         this.rateLimits.configure(config);
     }
@@ -28,7 +33,7 @@ export class LambderApiPolicyEngine {
         this.rateLimits.assertRegistration(apiName, mode, options.rateLimit);
         this.guards.assertRegistration(apiName, mode, options.guards);
         if (options.idempotency !== undefined && !this.idempotency.isConfigured) {
-            throw new Error(`Lambder: API "${apiName}" declares idempotency but enableApiIdempotency() was not called first.`);
+            throw new Error(`Lambder: API "${apiName}" declares idempotency but no idempotency store was configured at creation.`);
         }
     }
     /** Rate limits then guards, in declared order. Refusals throw (LambderApiError or a guard's own throw). */