lambder 3.5.2 → 3.7.1

package/Readme.md

@@ -2,7 +2,7 @@
 
 Lambder is a highly opinionated dynamic serverless framework designed to facilitate the management and implementation of routes and APIs within AWS Lambda functions, specifically tailored for TypeScript projects. It provides a streamlined approach to handling HTTP requests, managing sessions, and defining API routes, making serverless application development more intuitive and structured.
 
-**New in v3:** Public file serving with `servePublicFiles()` + `serveIndexHtml()`, unified `addAction()` for non-HTTP triggers, automatic gzip + ETag, thrown responses with a real `die`, the comment-based `LambderTemplatingEngine`, type-safe `html`/`xml` tagged templates, API Gateway HTTP API (payload v2) / Lambda Function URL support, the `LambderDdbCache` DynamoDB cache (3.1), typed translations with `createLambderI18n` (3.2), and in 3.5: typed API refusals with `LambderApiError`, caller outcomes/timeouts with `apiOutcome()`, plus declarative per-API rate limits, guards, and idempotency.
+**New in v3:** Public file serving with `servePublicFiles()` + `serveIndexHtml()`, unified `addAction()` for non-HTTP triggers, automatic gzip + ETag, thrown responses with a real `die`, the comment-based `LambderTemplatingEngine`, type-safe `html`/`xml` tagged templates, API Gateway HTTP API (payload v2) / Lambda Function URL support, the `LambderDdbCache` DynamoDB cache (3.1), typed translations with `createLambderI18n` (3.2), and in 3.5: typed API refusals with `LambderApiError`, caller outcomes/timeouts with `apiOutcome()`, plus declarative per-API rate limits, guards, and idempotency; 3.7 makes guards and custom rate-limit keys payload-sliced ({ input, handler }): the slice is validated pre-run, typed in the handler, and force-merged into the contract input.
 
 ## Features
 
@@ -428,9 +428,20 @@ Responses are finalized once at the end of the request: automatic gzip (when the
 
 **Die Methods**: `res.die.*` - Builds the response and throws it, immediately halting the request at any call depth (handlers, hooks, nested helper functions). Plain `throw res.html(...)` works the same way.
 
-### Typed API Refusals (LambderApiError)
+### Typed API Refusals (refuse / LambderApiError)
 
-A refusal ("you are not allowed", "quota exceeded") is not a crash. `res.die.*` covers refusals where you hold the resolver, but shared helpers (permission checks, validators) usually don't. Throw `LambderApiError` from anywhere in an API call's stack and the pipeline maps it onto the structured envelope instead of the global error handler, so refusals never pollute crash logging and clients get a parseable response:
+A refusal ("you are not allowed", "quota exceeded") is not a crash. `res.die.*` covers refusals where you hold the resolver, but shared helpers (permission checks, validators) usually don't. The one-liner for the common case is `refuse()`: callable from anywhere in an API call's stack, it throws a typed refusal carrying the standard `LambderRefusalMessage` shape (`{ type, title?, content }`) that the pipeline maps onto the envelope's `errorMessage`, so refusals never pollute crash logging and clients get a parseable response:
+
+```typescript
+import { refuse } from "lambder";
+
+if (!row) refuse("Record not found.");                                  // { type: "warning", content }
+if (!isAdmin) refuse("Admins only.", { notAuthorized: true });          // + envelope flag
+refuse("Too many attempts.", { type: "error", statusCode: 429 });       // custom rendering intent + status
+// TypeScript applies never-return narrowing: after `if (!row) refuse(...)`, row is defined.
+```
+
+For full control of the errorMessage payload (apps with their own message vocabulary), throw `LambderApiError` directly; `refuse()` is sugar over it:
 
 ```typescript
 import { LambderApiError } from "lambder";
@@ -455,7 +466,7 @@ Related: when an API call crashes with no `setGlobalErrorHandler` (or the handle
 Declare named building blocks once; reference them from API definitions with full type inference (unknown names are compile errors, and everything is re-asserted at registration time for plain-JS safety). Each piece is independent and optional.
 
 ```typescript
-import Lambder, { LambderDdbRateLimiter, LambderDdbIdempotency, LambderApiError } from "lambder";
+import Lambder, { LambderDdbRateLimiter, LambderDdbIdempotency, lambderGuard, lambderRateLimitKey, refuse } from "lambder";
 
 const lambder = new Lambder<SessionData>({ apiPath: "/api" })
     // 1. Rate limiting: your limiter instance + named policies. Each policy
@@ -465,8 +476,17 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
         policies: {
             authPerIp:    { perMin: 5, perHour: 30, per: "ip" },
             writePerUser: { perMin: 30, per: "session" },   // only referable from addSessionApi (also enforced at compile time)
-            codePerEmail: { perMin: 3, per: (ctx) => String(ctx.post?.payload?.email ?? "").toLowerCase(),
-                            errorMessage: { type: "warning", content: "Too many attempts for this address." } },
+            codePerEmail: {
+                perMin: 3,
+                // The key declares the payload slice it needs: validated before
+                // it runs, handed to the handler typed, and merged into the
+                // contract input of every API referencing this policy.
+                per: lambderRateLimitKey({
+                    input: z.object({ email: z.string() }),
+                    handler: (_ctx, { email }) => email.trim().toLowerCase(),
+                }),
+                errorMessage: { type: "warning", content: "Too many attempts for this address." },
+            },
         },
     })
     // 2. Idempotency: a store instance + replay defaults. May share the rate
@@ -476,18 +496,25 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
         defaultTtlSeconds: 24 * 3600,
         failOpen: true,   // DynamoDB down => execute without dedupe instead of failing
     })
-    // 3. Named guards: run before input validation, refuse by throwing.
-    //    Callable multiple times; domain modules can contribute their own.
+    // 3. Named guards: { input?, handler } definitions run before input
+    //    validation and refuse by throwing. A guard's `input` slice is
+    //    validated against the raw payload, handed to the handler typed, and
+    //    merged into the contract input of every API declaring the guard, so
+    //    forgetting to send captchaToken is a compile error at the call site.
     .defineApiGuards({
-        captcha: async (ctx) => {
-            if (!await verifyCaptcha(ctx.post?.payload?.captchaToken, ctx.ip)) {
-                throw new LambderApiError("Captcha failed", { errorMessage: "Verification failed, please retry." });
-            }
-        },
+        captcha: lambderGuard({
+            input: z.object({ captchaToken: z.string() }),
+            handler: async (ctx, { captchaToken }) => {
+                if (!await verifyCaptcha(captchaToken, ctx.ip)) refuse("Verification failed, please retry.");
+            },
+        }),
     });
 
 lambder.addApi("public.resetPassword", {
-    input: z.object({ email: z.string().email(), captchaToken: z.string() }),
+    // captchaToken is NOT declared here: the guard contributes it to the
+    // contract, the guard validates and consumes it, and the handler never
+    // sees it.
+    input: z.object({ email: z.string().email() }),
     output: z.object({ ok: z.boolean() }),
     rateLimit: ["authPerIp", "codePerEmail"],   // stacked: checked in order, first exceeded refuses (429 envelope)
     guards: "captcha",

package/dist/Lambder.d.ts

@@ -8,7 +8,7 @@ import { type LambderCorsConfig } from "./LambderCors.js";
 import { type LambderSessionDataRefreshConfig } from "./LambderSessionManager.js";
 import LambderSessionController, { type LambderSessionCookieOptions } from "./LambderSessionController.js";
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
-import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderApiIdempotencyConfig, type LambderApiGuardFunction, type LambderApiRegistrationOptions, type LambderPublicRateLimitNames } from "./LambderApiPolicies.js";
+import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderApiIdempotencyConfig, type LambderApiGuard, type LambderGuardPayloadMap, type LambderGuardsRequirement, type LambderPoliciesRequirement, type LambderMergedInput, type LambderPublicRateLimitNames } from "./LambderApiPolicies.js";
 import type { MergeContract } from "./LambderApiContract.js";
 import { type LambderHttpEvent, type LambderRenderContext, type LambderSessionRenderContext } from "./LambderContext.js";
 export type { PathParamsOf, RouteCondition, ConditionFunction, LambderRouteMatcher } from "./LambderRouting.js";
@@ -81,7 +81,7 @@ export type LambderConstructorOptions = {
  * @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 _TGuardName - @internal Accumulated by defineApiGuards (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)
  *
  * @example
@@ -93,7 +93,7 @@ export type LambderConstructorOptions = {
  *   .addApi('createUser', { input: z.object({...}), output: z.object({...}) }, handler);
  * ```
  */
-export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuardName extends string = never, _TIdempotencyEnabled extends boolean = false> {
+export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false> {
     apiPath: string;
     apiVersion: null | string;
     publicPath: string;
@@ -188,7 +188,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      * policies keyed per "session" are only referable from addSessionApi.
      * Callable once; call it before the API registrations that use it.
      */
-    enableApiRateLimits<const TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>>(config: LambderApiRateLimitsConfig<TPolicies>): Lambder<TSessionData, _TContract, TPolicies, _TGuardName, _TIdempotencyEnabled>;
+    enableApiRateLimits<const TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>>(config: LambderApiRateLimitsConfig<TPolicies>): Lambder<TSessionData, _TContract, TPolicies, _TGuards, _TIdempotencyEnabled>;
     /**
      * Wire declarative idempotency: your LambderDdbIdempotency instance plus
      * replay defaults. APIs opt in via `idempotency: true | { ttlSeconds }`;
@@ -198,15 +198,19 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      * 409, replays of a completed request return the stored response, and a
      * crashed original releases its claim. Callable once.
      */
-    enableApiIdempotency(config: LambderApiIdempotencyConfig): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuardName, true>;
+    enableApiIdempotency(config: LambderApiIdempotencyConfig): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards, true>;
     /**
      * Define named guards that APIs reference (typed) via the `guards`
-     * option. Guards run before input validation, in the order the API
-     * declares them; a guard refuses by throwing (typically LambderApiError).
+     * option. Each guard is a { input?, handler } definition (build with
+     * lambderGuard()): the input slice is validated against the raw payload
+     * before the handler runs, the handler receives it typed, and the
+     * requirement merges into the contract input of every API declaring the
+     * guard. 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<TGuards extends Record<string, LambderApiGuardFunction>>(guards: TGuards): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuardName | Extract<keyof TGuards, string>, _TIdempotencyEnabled>;
+    defineApiGuards<TGuards extends Record<string, LambderApiGuard<any>>>(guards: TGuards): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards & LambderGuardPayloadMap<TGuards>, _TIdempotencyEnabled>;
     private getOrCreatePolicyEngine;
     /** Registration-time checks shared by addApi/addSessionApi. */
     private assertApiRegistration;
@@ -214,15 +218,33 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     addRoute(condition: RegExp | ConditionFunction | LambderRouteMatcher, actionFn: ActionFunction): this;
     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>) => Lambder<TSessionData, _TNewContract, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuardName, _TIdempotencyEnabled>;
-    addApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny>(name: TName, schema: {
+    use<_TNewContract extends Record<string, any>>(plugin: (lambder: Lambder<TSessionData, _TContract, any, any, any>) => Lambder<TSessionData, _TNewContract, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
+    addApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderPublicRateLimitNames<_TRateLimitPolicies> | readonly LambderPublicRateLimitNames<_TRateLimitPolicies>[] = never, const TGuardsOpt extends Extract<keyof _TGuards, string> | readonly Extract<keyof _TGuards, string>[] = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
-    } & LambderApiRegistrationOptions<LambderPublicRateLimitNames<_TRateLimitPolicies>, _TGuardName, _TIdempotencyEnabled>, handler: (ctx: LambderRenderContext<z.infer<TInput>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>>, _TRateLimitPolicies, _TGuardName, _TIdempotencyEnabled>;
-    addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny>(name: TName, schema: {
+    } & {
+        /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
+        rateLimit?: TRateOpt;
+        /** Named guards, run in declared order before input validation; their input requirements merge into this API's contract input. */
+        guards?: TGuardsOpt;
+        /** Replay-protect this API per client idempotencyKey. Requires enableApiIdempotency() first. */
+        idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
+            ttlSeconds?: number;
+        }) : never;
+    }, handler: (ctx: LambderRenderContext<z.infer<TInput>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, LambderMergedInput<z.infer<TInput>, LambderPoliciesRequirement<_TRateLimitPolicies, TRateOpt>, LambderGuardsRequirement<_TGuards, TGuardsOpt>>, z.infer<TOutput>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
+    addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends Extract<keyof _TRateLimitPolicies, string> | readonly Extract<keyof _TRateLimitPolicies, string>[] = never, const TGuardsOpt extends Extract<keyof _TGuards, string> | readonly Extract<keyof _TGuards, string>[] = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
-    } & LambderApiRegistrationOptions<Extract<keyof _TRateLimitPolicies, string>, _TGuardName, _TIdempotencyEnabled>, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>>, _TRateLimitPolicies, _TGuardName, _TIdempotencyEnabled>;
+    } & {
+        /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
+        rateLimit?: TRateOpt;
+        /** Named guards, run in declared order before input validation; their input requirements merge into this API's contract input. */
+        guards?: TGuardsOpt;
+        /** Replay-protect this API per client idempotencyKey. Requires enableApiIdempotency() first. */
+        idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
+            ttlSeconds?: number;
+        }) : never;
+    }, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, LambderMergedInput<z.infer<TInput>, LambderPoliciesRequirement<_TRateLimitPolicies, TRateOpt>, LambderGuardsRequirement<_TGuards, TGuardsOpt>>, z.infer<TOutput>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
     /**
      * Fetch the session or short-circuit the request: API calls get the
      * protocol's { sessionExpired: true } response (handled by LambderCaller),

package/dist/Lambder.js

@@ -15,7 +15,7 @@ import { createContext, isV2HttpEvent } from "./LambderContext.js";
  * @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 _TGuardName - @internal Accumulated by defineApiGuards (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)
  *
  * @example
@@ -193,8 +193,12 @@ export default class Lambder {
     }
     /**
      * Define named guards that APIs reference (typed) via the `guards`
-     * option. Guards run before input validation, in the order the API
-     * declares them; a guard refuses by throwing (typically LambderApiError).
+     * option. Each guard is a { input?, handler } definition (build with
+     * lambderGuard()): the input slice is validated against the raw payload
+     * before the handler runs, the handler receives it typed, and the
+     * requirement merges into the contract input of every API declaring the
+     * guard. 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.
      */

package/dist/LambderApiError.d.ts

@@ -52,3 +52,40 @@ export declare class LambderApiError extends Error {
 }
 /** Brand-based type guard (see LambderApiError.isLambderApiError). */
 export declare const isLambderApiError: (err: unknown) => err is LambderApiError;
+/**
+ * The standard shape refusals carry on the envelope's errorMessage field.
+ * The caller's errorMessageHandler receives it as-is; apps with their own
+ * errorMessage vocabulary can keep using LambderApiError directly instead.
+ */
+export type LambderRefusalMessage = {
+    type: "warning" | "error" | "info";
+    title?: string;
+    content: string;
+};
+export type LambderRefuseOptions = {
+    /** Rendering intent for the client's errorMessageHandler. Default: "warning". */
+    type?: LambderRefusalMessage["type"];
+    /** Optional heading shown above the content. */
+    title?: string;
+    /** Sets the envelope's notAuthorized flag (routed to the caller's notAuthorizedHandler). */
+    notAuthorized?: boolean;
+    /** Sets the envelope's sessionExpired flag. */
+    sessionExpired?: boolean;
+    /** HTTP status of the refusal. Default 200; avoid 5xx (caller treats as crash) and 422 (reserved for validation). */
+    statusCode?: HttpStatusCode;
+    /** Underlying cause, preserved on the Error cause property. */
+    cause?: unknown;
+};
+/**
+ * Refuse the current API call: a routine business "no" (not found, invalid
+ * input, not allowed) with a user-facing message. Throws a LambderApiError
+ * carrying the standard LambderRefusalMessage shape, so the pipeline maps it
+ * onto the structured envelope instead of a 500, and crash logging never
+ * sees it. Callable from anywhere in the call stack — handlers, hooks,
+ * guards, shared helpers with no resolver access.
+ *
+ * The const carries the annotation so TypeScript applies never-return
+ * control-flow narrowing at call sites (`if (!row) refuse(...)` implies
+ * `row` is defined afterwards).
+ */
+export declare const refuse: (content: string, options?: LambderRefuseOptions) => never;

package/dist/LambderApiError.js

@@ -36,3 +36,28 @@ export class LambderApiError extends Error {
 }
 /** Brand-based type guard (see LambderApiError.isLambderApiError). */
 export const isLambderApiError = (err) => err instanceof Error && err.isLambderApiError === true;
+/**
+ * Refuse the current API call: a routine business "no" (not found, invalid
+ * input, not allowed) with a user-facing message. Throws a LambderApiError
+ * carrying the standard LambderRefusalMessage shape, so the pipeline maps it
+ * onto the structured envelope instead of a 500, and crash logging never
+ * sees it. Callable from anywhere in the call stack — handlers, hooks,
+ * guards, shared helpers with no resolver access.
+ *
+ * The const carries the annotation so TypeScript applies never-return
+ * control-flow narrowing at call sites (`if (!row) refuse(...)` implies
+ * `row` is defined afterwards).
+ */
+export const refuse = (content, options = {}) => {
+    throw new LambderApiError(content, {
+        errorMessage: {
+            type: options.type ?? "warning",
+            ...(options.title !== undefined ? { title: options.title } : {}),
+            content,
+        },
+        notAuthorized: options.notAuthorized,
+        sessionExpired: options.sessionExpired,
+        statusCode: options.statusCode,
+        cause: options.cause,
+    });
+};

package/dist/LambderApiPolicies.d.ts

@@ -1,14 +1,44 @@
+import type { z } from "zod";
 import type { LambderRenderContext } from "./LambderContext.js";
 import type LambderResolver from "./LambderResolver.js";
 import type { LambderRateLimitPolicy, LambderDdbRateLimiter } from "./LambderDdbRateLimiter.js";
 import type { LambderDdbIdempotency } from "./LambderDdbIdempotency.js";
 import { LambderResponse } from "./LambderResponse.js";
 /**
- * What one rate-limit counter tracks: the client IP, the session identity, or
- * a custom key derived from the request (e.g. a normalized email). Custom
- * functions run before input validation, so they read the raw payload.
+ * A custom rate-limit key: `input` names the payload fields the key needs.
+ * The slice is validated against the raw payload before `handler` runs (a
+ * failure answers the standard 422 validation shape), and the requirement is
+ * merged into the contract input of every API that references the policy, so
+ * clients are forced by the compiler to send those fields. Build with
+ * lambderRateLimitKey() so the handler's payload type follows `input`.
  */
-export type LambderRateLimitPer = "ip" | "session" | ((ctx: LambderRenderContext) => string | Promise<string>);
+export type LambderRateLimitKeyFn<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
+    input: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
+} | {
+    input?: undefined;
+    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
+};
+/**
+ * Builder that ties the handler's payload type to the `input` schema inside
+ * one literal. Returns the exact union member (not the union), so requirement
+ * extraction can see the `input` type.
+ */
+export declare function lambderRateLimitKey<TInput extends z.ZodTypeAny>(key: {
+    input: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
+}): {
+    input: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
+};
+export declare function lambderRateLimitKey(key: {
+    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
+}): {
+    input?: undefined;
+    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
+};
+/** What one rate-limit counter tracks: the client IP, the session identity, or a custom payload-derived key. */
+export type LambderRateLimitPer = "ip" | "session" | LambderRateLimitKeyFn<any>;
 /** A named rate-limit policy: fixed windows plus the key one counter tracks. */
 export type LambderApiRateLimitPolicyConfig = LambderRateLimitPolicy & {
     per: LambderRateLimitPer;
@@ -30,28 +60,72 @@ export type LambderApiIdempotencyConfig = {
     failOpen?: boolean;
 };
 /**
- * A named guard, run before input validation. Refuse by throwing (typically a
- * LambderApiError, or res.die.*); return normally to let the request through.
- * ctx.apiPayload is unvalidated at this point.
+ * A named guard, run before the API's own input validation. `input` names the
+ * payload fields the guard requires: the slice is validated against the raw
+ * payload before `handler` runs (a failure answers the standard 422
+ * validation shape), the handler receives it typed, and the requirement is
+ * merged into the contract input of every API that declares the guard, so
+ * clients are forced by the compiler to send those fields. The handler
+ * refuses by throwing (typically refuse()/LambderApiError). Build with
+ * lambderGuard() so the handler's payload type follows `input`.
  */
-export type LambderApiGuardFunction = (ctx: LambderRenderContext, res: LambderResolver) => void | Promise<void>;
+export type LambderApiGuard<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
+    input: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
+} | {
+    input?: undefined;
+    handler: (ctx: LambderRenderContext, payload: undefined, res: LambderResolver) => void | Promise<void>;
+};
+/**
+ * Builder that ties the handler's payload type to the `input` schema inside
+ * one literal. Returns the exact union member (not the union), so requirement
+ * extraction can see the `input` type.
+ */
+export declare function lambderGuard<TInput extends z.ZodTypeAny>(guard: {
+    input: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
+}): {
+    input: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
+};
+export declare function lambderGuard(guard: {
+    handler: (ctx: LambderRenderContext, payload: undefined, res: LambderResolver) => void | Promise<void>;
+}): {
+    input?: undefined;
+    handler: (ctx: LambderRenderContext, payload: undefined, res: LambderResolver) => void | Promise<void>;
+};
 /** Names of policies usable on public APIs: everything not keyed per "session". */
 export type LambderPublicRateLimitNames<TPolicies> = {
     [K in keyof TPolicies]: TPolicies[K] extends {
         per: "session";
     } ? never : K;
 }[keyof TPolicies] & string;
-/** Declarative per-API options carried in the addApi/addSessionApi schema object. */
-export type LambderApiRegistrationOptions<TRateLimitName extends string, TGuardName extends string, TIdempotencyEnabled extends boolean> = {
-    /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
-    rateLimit?: TRateLimitName | readonly TRateLimitName[];
-    /** Named guards, run in declared order before input validation; refuse by throwing. */
-    guards?: TGuardName | readonly TGuardName[];
-    /** Replay-protect this API per client idempotencyKey. Requires enableApiIdempotency() first. */
-    idempotency?: TIdempotencyEnabled extends true ? (boolean | {
-        ttlSeconds?: number;
-    }) : never;
+/** Payload fields a guard requires; {} when it declares no input. */
+export type LambderGuardPayload<G> = G extends {
+    input: infer S extends z.ZodTypeAny;
+} ? z.output<S> : {};
+/** Guard name to required-payload map, accumulated on the Lambder instance by defineApiGuards. */
+export type LambderGuardPayloadMap<TGuards> = {
+    [K in keyof TGuards]: LambderGuardPayload<TGuards[K]>;
 };
+/** Payload fields a policy's custom key requires; {} for "ip"/"session" or keys with no input. */
+export type LambderPolicyPayload<P> = P extends {
+    per: {
+        input: infer S extends z.ZodTypeAny;
+    };
+} ? z.output<S> : {};
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type NamesIn<TOpt> = TOpt extends readonly (infer N extends string)[] ? N : TOpt extends string ? TOpt : never;
+/** Intersection of the payload requirements of the referenced guards; never when none are declared. */
+export type LambderGuardsRequirement<TGuardPayloads, TOpt> = [
+    NamesIn<TOpt>
+] extends [never] ? never : UnionToIntersection<TGuardPayloads[Extract<NamesIn<TOpt>, keyof TGuardPayloads>]>;
+/** Intersection of the payload requirements of the referenced rate-limit policies; never when none are declared. */
+export type LambderPoliciesRequirement<TPolicies, TOpt> = [
+    NamesIn<TOpt>
+] extends [never] ? never : UnionToIntersection<LambderPolicyPayload<TPolicies[Extract<NamesIn<TOpt>, keyof TPolicies>]>>;
+/** Contract-input merge: the API's own input plus everything its rate limits and guards force clients to send. */
+export type LambderMergedInput<TIn, TReqA, TReqB> = ([TReqA] extends [never] ? TIn : TIn & TReqA) extends infer TMid ? ([TReqB] extends [never] ? TMid : TMid & TReqB) : never;
 /**
  * Runtime side of the declarative API options: holds what the enable/define
  * calls declared, asserts registrations against it at startup, and executes
@@ -67,7 +141,7 @@ export declare class LambderApiPolicyEngine {
     private idempotencyDefaultTtlSeconds;
     private idempotencyFailOpen;
     setRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
-    addGuards(guards: Record<string, LambderApiGuardFunction>): void;
+    addGuards(guards: Record<string, LambderApiGuard<any>>): void;
     setIdempotency(config: LambderApiIdempotencyConfig): void;
     /** Startup validation of one API registration's declarative options. */
     assertRegistration(apiName: string, mode: "public" | "session", options: {
@@ -80,6 +154,13 @@ export declare class LambderApiPolicyEngine {
         rateLimit?: string | readonly string[];
         guards?: string | readonly string[];
     }): Promise<void>;
+    /**
+     * Validate a preflight input slice against the raw payload. Runs before
+     * the API's own validation, so guard/key requirements hold even when the
+     * API schema does not declare (and would strip) those fields. Failures
+     * answer the same 422 shape as regular input validation.
+     */
+    private parseSlice;
     private resolveRateLimitKey;
     /**
      * Idempotency wrapper around validation-passed handler execution. Without
@@ -93,3 +174,4 @@ export declare class LambderApiPolicyEngine {
         ttlSeconds?: number;
     }, exec: () => Promise<LambderResponse>): Promise<LambderResponse>;
 }
+export {};

package/dist/LambderApiPolicies.js

@@ -5,6 +5,8 @@ const IDEMPOTENCY_PENDING_TTL_SECONDS = 300;
 /** Responses above this size skip replay storage (DynamoDB item limit is 400KB). */
 const IDEMPOTENCY_MAX_STORED_BODY_BYTES = 350_000;
 const RATE_LIMIT_WINDOW_KEYS = ["perMin", "per10Min", "perHour", "perDay", "perWeek", "perMonth"];
+export function lambderRateLimitKey(key) { return key; }
+export function lambderGuard(guard) { return guard; }
 const toList = (value) => value === undefined ? [] : typeof value === "string" ? [value] : value;
 /**
  * Runtime side of the declarative API options: holds what the enable/define
@@ -24,8 +26,10 @@ export class LambderApiPolicyEngine {
         if (this.limiter)
             throw new Error("Lambder: enableApiRateLimits() was already called.");
         for (const [name, policy] of Object.entries(config.policies)) {
-            if (!policy.per)
-                throw new Error(`Lambder: rate-limit policy "${name}" is missing its "per" key source.`);
+            const per = policy.per;
+            if (!per || (per !== "ip" && per !== "session" && typeof per.handler !== "function")) {
+                throw new Error(`Lambder: rate-limit policy "${name}" needs per: "ip", "session", or a { input?, handler } key.`);
+            }
             if (!RATE_LIMIT_WINDOW_KEYS.some((key) => policy[key])) {
                 throw new Error(`Lambder: rate-limit policy "${name}" declares no window (${RATE_LIMIT_WINDOW_KEYS.join("/")}).`);
             }
@@ -34,10 +38,12 @@ export class LambderApiPolicyEngine {
         this.rateLimitPolicies = { ...config.policies };
     }
     addGuards(guards) {
-        for (const [name, guardFn] of Object.entries(guards)) {
+        for (const [name, guardDef] of Object.entries(guards)) {
             if (this.guards[name])
                 throw new Error(`Lambder: guard "${name}" is already defined.`);
-            this.guards[name] = guardFn;
+            if (typeof guardDef?.handler !== "function")
+                throw new Error(`Lambder: guard "${name}" has no handler function.`);
+            this.guards[name] = guardDef;
         }
     }
     setIdempotency(config) {
@@ -73,7 +79,7 @@ export class LambderApiPolicyEngine {
             const policy = this.rateLimitPolicies[name];
             if (!policy || !this.limiter)
                 throw new Error(`Lambder: rate-limit policy "${name}" is not configured.`);
-            const key = await this.resolveRateLimitKey(ctx, policy.per);
+            const key = await this.resolveRateLimitKey(ctx, resolver, policy.per);
             const limited = await this.limiter.isRateLimited(`api|${apiName}|${name}|${key}`, policy);
             if (limited) {
                 throw new LambderApiError(`Rate limited: "${apiName}" exceeded policy "${name}".`, {
@@ -83,13 +89,29 @@ export class LambderApiPolicyEngine {
             }
         }
         for (const name of toList(options.guards)) {
-            const guardFn = this.guards[name];
-            if (!guardFn)
+            const guardDef = this.guards[name];
+            if (!guardDef)
                 throw new Error(`Lambder: guard "${name}" is not configured.`);
-            await guardFn(ctx, resolver);
+            const payload = this.parseSlice(guardDef.input, ctx, resolver);
+            await guardDef.handler(ctx, payload, resolver);
+        }
+    }
+    /**
+     * Validate a preflight input slice against the raw payload. Runs before
+     * the API's own validation, so guard/key requirements hold even when the
+     * API schema does not declare (and would strip) those fields. Failures
+     * answer the same 422 shape as regular input validation.
+     */
+    parseSlice(input, ctx, resolver) {
+        if (!input)
+            return undefined;
+        const parsed = input.safeParse(ctx.post?.payload);
+        if (!parsed.success) {
+            throw resolver.json({ error: "Input validation failed", zodError: parsed.error }, { statusCode: 422 });
         }
+        return parsed.data;
     }
-    async resolveRateLimitKey(ctx, per) {
+    async resolveRateLimitKey(ctx, resolver, per) {
         if (per === "ip")
             return `ip:${ctx.ip}`;
         if (per === "session") {
@@ -98,7 +120,8 @@ export class LambderApiPolicyEngine {
                 throw new Error('Lambder: rate-limit per "session" evaluated without a session on the context.');
             return `session:${sessionKey}`;
         }
-        return `custom:${await per(ctx)}`;
+        const payload = this.parseSlice(per.input, ctx, resolver);
+        return `custom:${await per.handler(ctx, payload)}`;
     }
     /**
      * Idempotency wrapper around validation-passed handler execution. Without

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import Lambder from './Lambder.js';
 export default Lambder;
 export { default as LambderCaller } from "./LambderCaller.js";
 export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions } from "./LambderCaller.js";
-export { LambderApiError, isLambderApiError } from "./LambderApiError.js";
-export type { LambderApiErrorOptions } from "./LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse } from "./LambderApiError.js";
+export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefuseOptions } from "./LambderApiError.js";
 export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
 export { default as LambderResolver } from "./LambderResolver.js";
 export { default as LambderSessionManager } from "./LambderSessionManager.js";
@@ -27,7 +27,8 @@ export { LambderDdbRateLimiter } from "./LambderDdbRateLimiter.js";
 export type { LambderDdbRateLimiterOptions, LambderRateLimitPolicy, LambderRateLimitExceededMap, LambderRateLimitResult, } from "./LambderDdbRateLimiter.js";
 export { LambderDdbIdempotency } from "./LambderDdbIdempotency.js";
 export type { LambderDdbIdempotencyOptions, LambderIdempotencyBeginResult, } from "./LambderDdbIdempotency.js";
-export type { LambderApiGuardFunction, LambderRateLimitPer, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderApiIdempotencyConfig, LambderApiRegistrationOptions, LambderPublicRateLimitNames, } from "./LambderApiPolicies.js";
+export { lambderGuard, lambderRateLimitKey } from "./LambderApiPolicies.js";
+export type { LambderApiGuard, LambderRateLimitKeyFn, LambderRateLimitPer, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderApiIdempotencyConfig, LambderPublicRateLimitNames, LambderGuardPayload, LambderGuardPayloadMap, LambderPolicyPayload, LambderGuardsRequirement, LambderPoliciesRequirement, LambderMergedInput, } from "./LambderApiPolicies.js";
 export { createLambderI18n } from "./LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./LambderI18n.js";
 export { type ApiContractShape, } from "./LambderApiContract.js";

package/dist/index.js

@@ -2,7 +2,7 @@ import Lambder from './Lambder.js';
 export default Lambder;
 export { default as LambderCaller } from "./LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere)
-export { LambderApiError, isLambderApiError } from "./LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse } from "./LambderApiError.js";
 export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
 export { default as LambderResolver } from "./LambderResolver.js";
 export { default as LambderSessionManager } from "./LambderSessionManager.js";
@@ -23,6 +23,8 @@ export { LambderDdbCache } from "./LambderDdbCache.js";
 export { LambderDdbRateLimiter } from "./LambderDdbRateLimiter.js";
 // DynamoDB-backed idempotency records (standalone, server-only)
 export { LambderDdbIdempotency } from "./LambderDdbIdempotency.js";
+// Declarative per-API policies (rate limits, guards, idempotency)
+export { lambderGuard, lambderRateLimitKey } from "./LambderApiPolicies.js";
 // Typed translations (standalone, isomorphic)
 export { createLambderI18n } from "./LambderI18n.js";
 export { createContext, isV2HttpEvent } from "./LambderContext.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "3.5.2",
+  "version": "3.7.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",