lambder 3.6.1 → 3.8.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.8 gives guards and custom rate-limit keys two typed modes: apiInput (checks a slice of the API's own payload; declarable only where the schema carries those fields) and guardInput (a separate client-sent guardInputs channel the contract makes mandatory at the call site).
 
 ## 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,
+                // apiInput key: derives from the API's OWN payload. Validated
+                // before it runs, typed in the handler, and the policy is only
+                // referable from APIs whose input schema carries `email`.
+                per: lambderRateLimitKey({
+                    apiInput: 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,27 @@ 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, two modes. apiInput checks a slice of the API's own
+    //    payload (the schema keeps the field; the guard is declarable only
+    //    where the payload type passes both). guardInput is the guard's OWN
+    //    value, sent separately by the caller via options.guardInputs and
+    //    made mandatory by the contract, so forgetting it is a compile error
+    //    at the call site. Both are validated pre-run and typed in the handler.
     .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({
+            guardInput: 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: it travels in the separate
+    // guardInputs channel, so the guard validates and consumes it and the
+    // handler never sees it. `email` IS declared: the codePerEmail key runs
+    // in apiInput mode against the API's own payload.
+    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",
@@ -620,6 +638,7 @@ Also available:
 
 - **Timeouts**: pass `timeoutMs` in the constructor for a default (API Gateway caps around 29s, so ~30000 is sensible) and/or per call; timed-out calls abort the fetch and report `reason: 'timeout'`. A per-call `signal` combines with the timeout.
 - **Per-call handler overrides**: every constructor handler (`errorHandler`, `sessionExpiredHandler`, `errorMessageHandler`, ...) can be overridden in the options of a single `api`/`apiRaw`/`apiOutcome` call.
+- **Guard inputs**: for APIs whose guards run in guardInput mode, pass their values per call as `guardInputs: { <guardName>: value }`; the typed contract makes the options argument (and the correct value shape) mandatory for those APIs.
 - **Idempotency keys**: pass `idempotencyKey` per call for APIs declared idempotent on the server (see Declarative API Policies). Generate it once per logical operation with `LambderCaller.createIdempotencyKey()` (safe in insecure contexts where `crypto.randomUUID` is missing) and send the same key on retries; rotate after a confirmed success.
 
 ### Benefits

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 LambderGuardMetaMap, type LambderAllowedGuardNames, type LambderAllowedPolicyNames, type LambderGuardInputsOf } 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,20 @@ 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).
-     * Callable multiple times so domain modules can contribute their own;
-     * names must not collide.
+     * option. Each guard is built with lambderGuard() in one of two modes:
+     * apiInput (checks a slice of the API's own payload; declarable only on
+     * APIs whose input schema carries those fields, so the payload type
+     * passes both the API input and the guard's apiInput) or guardInput (the
+     * client sends the guard's value separately via options.guardInputs, and
+     * the contract forces it at the call site). 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 & LambderGuardMetaMap<TGuards>, _TIdempotencyEnabled>;
     private getOrCreatePolicyEngine;
     /** Registration-time checks shared by addApi/addSessionApi. */
     private assertApiRegistration;
@@ -214,15 +219,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 LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, false> | readonly LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, false>[] = never, const TGuardsOpt extends LambderAllowedGuardNames<_TGuards, z.infer<TInput>> | readonly LambderAllowedGuardNames<_TGuards, z.infer<TInput>>[] = 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, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
+    addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, true> | readonly LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, true>[] = never, const TGuardsOpt extends LambderAllowedGuardNames<_TGuards, z.infer<TInput>> | readonly LambderAllowedGuardNames<_TGuards, z.infer<TInput>>[] = 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, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _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,10 +193,15 @@ 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).
-     * Callable multiple times so domain modules can contribute their own;
-     * names must not collide.
+     * option. Each guard is built with lambderGuard() in one of two modes:
+     * apiInput (checks a slice of the API's own payload; declarable only on
+     * APIs whose input schema carries those fields, so the payload type
+     * passes both the API input and the guard's apiInput) or guardInput (the
+     * client sends the guard's value separately via options.guardInputs, and
+     * the contract forces it at the call site). 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);

package/dist/LambderApiContract.d.ts

@@ -9,13 +9,19 @@
 export type ApiContractShape = Record<string, {
     input: any;
     output: any;
+    /** Present when the API declares guardInput-mode guards: guard name -> value the client must send via options.guardInputs. */
+    guardInputs?: any;
 }>;
 /**
  * Helper type for merging new API into existing contract during chaining
  */
-export type MergeContract<Old, Name extends string, In, Out> = Old & {
-    [K in Name]: {
+export type MergeContract<Old, Name extends string, In, Out, GuardInputs = never> = Old & {
+    [K in Name]: [GuardInputs] extends [never] ? {
         input: In;
         output: Out;
+    } : {
+        input: In;
+        output: Out;
+        guardInputs: GuardInputs;
     };
 };

package/dist/LambderApiPolicies.d.ts

@@ -1,14 +1,45 @@
+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. `apiInput` names the fields of the API's OWN
+ * payload the key derives from: the slice is validated against the raw
+ * payload before `handler` runs (failures answer the standard 422 validation
+ * shape) and the handler receives it typed. Referencing the policy from an
+ * API whose input schema does not carry those fields is a compile error, so
+ * the API's schema stays the single owner of the field. Build with
+ * lambderRateLimitKey() so the handler's payload type follows `apiInput`.
  */
-export type LambderRateLimitPer = "ip" | "session" | ((ctx: LambderRenderContext) => string | Promise<string>);
+export type LambderRateLimitKeyFn<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
+    apiInput: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
+} | {
+    apiInput?: undefined;
+    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
+};
+/**
+ * Builder that ties the handler's payload type to the `apiInput` schema
+ * inside one literal. Returns the exact union member so type extraction can
+ * see the schema.
+ */
+export declare function lambderRateLimitKey<TInput extends z.ZodTypeAny>(key: {
+    apiInput: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
+}): {
+    apiInput: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
+};
+export declare function lambderRateLimitKey(key: {
+    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
+}): {
+    apiInput?: 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 +61,106 @@ 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. Two modes:
+ *
+ * - `apiInput`: the guard checks fields of the API's OWN payload. The slice
+ *   is validated against the raw payload before `handler` runs and handed to
+ *   it typed. The API's input schema stays the owner of those fields:
+ *   declaring the guard on an API whose schema does not carry them is a
+ *   compile error.
+ * - `guardInput`: the guard has its own value the client sends SEPARATELY,
+ *   outside the API payload, via the caller's options.guardInputs[name].
+ *   The requirement lands on the API's contract (`guardInputs`), so the
+ *   typed caller refuses to compile a call that does not send it. The API
+ *   payload and handler never see the value.
+ *
+ * Either way 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 type follows the schema.
  */
-export type LambderApiGuardFunction = (ctx: LambderRenderContext, res: LambderResolver) => void | Promise<void>;
-/** Names of policies usable on public APIs: everything not keyed per "session". */
-export type LambderPublicRateLimitNames<TPolicies> = {
+export type LambderApiGuard<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
+    apiInput: TInput;
+    guardInput?: undefined;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
+} | {
+    guardInput: TInput;
+    apiInput?: undefined;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
+} | {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    handler: (ctx: LambderRenderContext, payload: undefined, res: LambderResolver) => void | Promise<void>;
+};
+/**
+ * Builder that ties the handler's payload type to the schema inside one
+ * literal. Returns the exact union member so mode/type extraction works.
+ */
+export declare function lambderGuard<TInput extends z.ZodTypeAny>(guard: {
+    apiInput: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
+}): {
+    apiInput: TInput;
+    guardInput?: undefined;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
+};
+export declare function lambderGuard<TInput extends z.ZodTypeAny>(guard: {
+    guardInput: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
+}): {
+    guardInput: TInput;
+    apiInput?: undefined;
+    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>;
+}): {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    handler: (ctx: LambderRenderContext, payload: undefined, res: LambderResolver) => void | Promise<void>;
+};
+/** Per-guard metadata carried on the Lambder instance: mode plus payload type. */
+export type LambderGuardMeta<G> = G extends {
+    apiInput: infer S extends z.ZodTypeAny;
+} ? {
+    apiInput: z.output<S>;
+} : G extends {
+    guardInput: infer S extends z.ZodTypeAny;
+} ? {
+    guardInput: z.output<S>;
+} : {};
+export type LambderGuardMetaMap<TGuards> = {
+    [K in keyof TGuards]: LambderGuardMeta<TGuards[K]>;
+};
+type NamesIn<TOpt> = TOpt extends readonly (infer N extends string)[] ? N : TOpt extends string ? TOpt : never;
+/** Guard names an API may declare: apiInput-mode guards only when the API's payload carries their fields. */
+export type LambderAllowedGuardNames<TGuards, TPayload> = {
+    [K in keyof TGuards]: TGuards[K] extends {
+        apiInput: infer R;
+    } ? (TPayload extends R ? K : never) : K;
+}[keyof TGuards] & string;
+/**
+ * Policy names an API may reference: session-keyed policies only on session
+ * APIs, and apiInput-keyed policies only when the API's payload carries the
+ * key's fields.
+ */
+export type LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession extends boolean> = {
     [K in keyof TPolicies]: TPolicies[K] extends {
         per: "session";
-    } ? never : K;
+    } ? (TIncludeSession extends true ? K : never) : TPolicies[K] extends {
+        per: {
+            apiInput: infer S extends z.ZodTypeAny;
+        };
+    } ? (TPayload extends z.output<S> ? K : 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;
+type GuardInputsEntries<TGuards, TOpt> = {
+    [K in Extract<NamesIn<TOpt>, keyof TGuards> as TGuards[K] extends {
+        guardInput: any;
+    } ? K : never]: TGuards[K] extends {
+        guardInput: infer V;
+    } ? V : never;
 };
+/** The guardInputs map an API's contract requires clients to send; never when no declared guard uses guardInput mode. */
+export type LambderGuardInputsOf<TGuards, TOpt> = keyof GuardInputsEntries<TGuards, TOpt> extends never ? never : GuardInputsEntries<TGuards, TOpt>;
 /**
  * Runtime side of the declarative API options: holds what the enable/define
  * calls declared, asserts registrations against it at startup, and executes
@@ -67,7 +176,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 +189,13 @@ export declare class LambderApiPolicyEngine {
         rateLimit?: string | readonly string[];
         guards?: string | readonly string[];
     }): Promise<void>;
+    /**
+     * 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.
+     */
+    private parseSlice;
     private resolveRateLimitKey;
     /**
      * Idempotency wrapper around validation-passed handler execution. Without
@@ -93,3 +209,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 { apiInput?, 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,14 @@ 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.`);
+            if (guardDef.apiInput && guardDef.guardInput)
+                throw new Error(`Lambder: guard "${name}" declares both apiInput and guardInput; pick one.`);
+            this.guards[name] = guardDef;
         }
     }
     setIdempotency(config) {
@@ -73,7 +81,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 +91,34 @@ 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 post = ctx.post;
+            let payload;
+            if (guardDef.apiInput) {
+                payload = this.parseSlice(guardDef.apiInput, post?.payload, resolver);
+            }
+            else if (guardDef.guardInput) {
+                payload = this.parseSlice(guardDef.guardInput, post?.guardInputs?.[name], resolver);
+            }
+            await guardDef.handler(ctx, payload, resolver);
+        }
+    }
+    /**
+     * 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.
+     */
+    parseSlice(input, value, resolver) {
+        const parsed = input.safeParse(value);
+        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 +127,10 @@ 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 = per.apiInput
+            ? this.parseSlice(per.apiInput, ctx.post?.payload, resolver)
+            : undefined;
+        return `custom:${await per.handler(ctx, payload)}`;
     }
     /**
      * Idempotency wrapper around validation-passed handler execution. Without

package/dist/LambderCaller.d.ts

@@ -1,6 +1,18 @@
 import { LambderApiResponse } from './LambderResponseBuilder';
 import type { ApiContractShape } from './LambderApiContract';
 import type { z } from "zod";
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+type GuardInputsOf<TEntry> = TEntry extends {
+    guardInputs: infer G;
+} ? G : never;
+/**
+ * The options argument: optional normally, REQUIRED (with guardInputs) when
+ * the API's contract declares guardInput-mode guards, so forgetting to send
+ * a guard's value is a compile error at the call site.
+ */
+type CallOptionsArg<TContract, TApiName> = IsAny<TContract> extends true ? [options?: LambderCallOptions] : TApiName extends keyof TContract ? [GuardInputsOf<TContract[TApiName]>] extends [never] ? [options?: LambderCallOptions] : [options: LambderCallOptions & {
+    guardInputs: GuardInputsOf<TContract[TApiName]>;
+}] : [options?: LambderCallOptions];
 type VoidFunction = () => void | Promise<void>;
 type FetchTracker = {
     apiName: string;
@@ -55,6 +67,12 @@ export type LambderCallOptions = {
     timeoutMs?: number;
     /** External abort signal, combined with the timeout when both are set. */
     signal?: AbortSignal;
+    /**
+     * Values for the API's guardInput-mode guards, keyed by guard name; sent
+     * beside the payload and consumed by the guards before validation. The
+     * typed contract makes this REQUIRED for APIs that declare such guards.
+     */
+    guardInputs?: Record<string, unknown>;
     /**
      * Replay-protection key for APIs declared idempotent on the server.
      * Generate once per logical operation (e.g. crypto.randomUUID() when the
@@ -127,14 +145,14 @@ export default class LambderCaller<TContract extends ApiContractShape = any> {
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
      * instead of collapsing every failure to null. Never throws.
      */
-    apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: LambderCallOptions): Promise<LambderApiOutcome<TOutput>>;
+    apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<LambderApiOutcome<TOutput>>;
     /**
      * Legacy shape: the parsed envelope on success (and on structured
      * errorMessage refusals, which carry an envelope), null on every other
      * failure. Prefer apiOutcome() when the call site needs to know why.
      */
-    apiRaw<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: LambderCallOptions): Promise<LambderApiResponse<TOutput> | null | undefined>;
+    apiRaw<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<LambderApiResponse<TOutput> | null | undefined>;
     /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
-    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: LambderCallOptions): Promise<TOutput | null | undefined>;
+    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<TOutput | null | undefined>;
 }
 export {};

package/dist/LambderCaller.js

@@ -149,6 +149,7 @@ export default class LambderCaller {
                     headers: { 'Content-Type': 'application/json', ...(headers || {}) },
                     body: JSON.stringify({
                         apiName, version, token, siteHost, payload,
+                        ...(options?.guardInputs !== undefined ? { guardInputs: options.guardInputs } : {}),
                         ...(options?.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
                     }),
                     ...(signal ? { signal } : {}),
@@ -280,8 +281,8 @@ export default class LambderCaller {
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
      * instead of collapsing every failure to null. Never throws.
      */
-    async apiOutcome(apiName, payload, options) {
-        return await this.dispatch(apiName, payload, options);
+    async apiOutcome(apiName, payload, ...rest) {
+        return await this.dispatch(apiName, payload, rest[0]);
     }
     ;
     /**
@@ -289,16 +290,18 @@ export default class LambderCaller {
      * errorMessage refusals, which carry an envelope), null on every other
      * failure. Prefer apiOutcome() when the call site needs to know why.
      */
-    async apiRaw(apiName, payload, options) {
-        const outcome = await this.dispatch(apiName, payload, options);
+    async apiRaw(apiName, payload, ...rest) {
+        const outcome = await this.dispatch(apiName, payload, rest[0]);
         if (outcome.ok)
             return outcome.response;
         return outcome.reason === 'errorMessage' ? outcome.response : null;
     }
     ;
     /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
-    async api(apiName, payload, options) {
-        const result = await this.apiRaw(apiName, payload, options);
-        return result?.payload;
+    async api(apiName, payload, ...rest) {
+        const outcome = await this.dispatch(apiName, payload, rest[0]);
+        if (outcome.ok)
+            return outcome.response?.payload;
+        return outcome.reason === 'errorMessage' ? outcome.response?.payload : undefined;
     }
 }

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, LambderGuardMeta, LambderGuardMetaMap, LambderAllowedGuardNames, LambderAllowedPolicyNames, LambderGuardInputsOf, } 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.8.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",