lambder 3.6.1 → 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
 
@@ -466,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
@@ -476,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
@@ -487,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/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

@@ -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

@@ -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.6.1",
+  "version": "3.7.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",