lambder 3.7.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; 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.
+**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
 
@@ -478,11 +478,11 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
             writePerUser: { perMin: 30, per: "session" },   // only referable from addSessionApi (also enforced at compile time)
             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.
+                // 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({
-                    input: z.object({ email: z.string() }),
+                    apiInput: z.object({ email: z.string() }),
                     handler: (_ctx, { email }) => email.trim().toLowerCase(),
                 }),
                 errorMessage: { type: "warning", content: "Too many attempts for this address." },
@@ -496,14 +496,15 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
         defaultTtlSeconds: 24 * 3600,
         failOpen: true,   // DynamoDB down => execute without dedupe instead of failing
     })
-    // 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.
+    // 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: lambderGuard({
-            input: z.object({ captchaToken: z.string() }),
+            guardInput: z.object({ captchaToken: z.string() }),
             handler: async (ctx, { captchaToken }) => {
                 if (!await verifyCaptcha(captchaToken, ctx.ip)) refuse("Verification failed, please retry.");
             },
@@ -511,9 +512,10 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
     });
 
 lambder.addApi("public.resetPassword", {
-    // captchaToken is NOT declared here: the guard contributes it to the
-    // contract, the guard validates and consumes it, and the handler never
-    // sees it.
+    // 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)
@@ -636,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 LambderApiGuard, type LambderGuardPayloadMap, type LambderGuardsRequirement, type LambderPoliciesRequirement, type LambderMergedInput, 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";
@@ -201,16 +201,17 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     enableApiIdempotency(config: LambderApiIdempotencyConfig): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards, true>;
     /**
      * Define named guards that APIs reference (typed) via the `guards`
-     * 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.
+     * 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, LambderApiGuard<any>>>(guards: TGuards): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards & LambderGuardPayloadMap<TGuards>, _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;
@@ -219,7 +220,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     addSessionRoute<TPath extends Path>(condition: TPath, actionFn: (ctx: LambderSessionRenderContext<any, TSessionData, PathParamsOf<TPath>>, resolver: LambderResolver) => MaybePromise<LambderResponse>): this;
     addSessionRoute(condition: RegExp | ConditionFunction | LambderRouteMatcher, actionFn: SessionActionFunction<TSessionData>): this;
     use<_TNewContract extends Record<string, any>>(plugin: (lambder: Lambder<TSessionData, _TContract, any, any, any>) => 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: {
+    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;
     } & {
@@ -231,8 +232,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         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: {
+    }, 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;
     } & {
@@ -244,7 +245,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         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>;
+    }, 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

@@ -193,14 +193,15 @@ export default class Lambder {
     }
     /**
      * Define named guards that APIs reference (typed) via the `guards`
-     * 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.
+     * 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

@@ -5,36 +5,37 @@ import type { LambderRateLimitPolicy, LambderDdbRateLimiter } from "./LambderDdb
 import type { LambderDdbIdempotency } from "./LambderDdbIdempotency.js";
 import { LambderResponse } from "./LambderResponse.js";
 /**
- * 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`.
+ * 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 LambderRateLimitKeyFn<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
-    input: TInput;
+    apiInput: TInput;
     handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
 } | {
-    input?: undefined;
+    apiInput?: 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.
+ * 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: {
-    input: TInput;
+    apiInput: TInput;
     handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
 }): {
-    input: TInput;
+    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>;
 }): {
-    input?: undefined;
+    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. */
@@ -60,72 +61,106 @@ export type LambderApiIdempotencyConfig = {
     failOpen?: boolean;
 };
 /**
- * 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`.
+ * 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 LambderApiGuard<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
-    input: TInput;
+    apiInput: TInput;
+    guardInput?: undefined;
     handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
 } | {
-    input?: undefined;
+    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 `input` schema inside
- * one literal. Returns the exact union member (not the union), so requirement
- * extraction can see the `input` type.
+ * 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: {
-    input: TInput;
+    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>;
 }): {
-    input: TInput;
+    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>;
 }): {
-    input?: undefined;
+    apiInput?: undefined;
+    guardInput?: 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> = {
+/** 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;
-/** 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]>;
+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;
 };
-/** 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;
+/** 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
@@ -155,10 +190,10 @@ export declare class LambderApiPolicyEngine {
         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.
+     * 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;

package/dist/LambderApiPolicies.js

@@ -28,7 +28,7 @@ export class LambderApiPolicyEngine {
         for (const [name, policy] of Object.entries(config.policies)) {
             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.`);
+                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("/")}).`);
@@ -43,6 +43,8 @@ export class LambderApiPolicyEngine {
                 throw new Error(`Lambder: guard "${name}" is already defined.`);
             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;
         }
     }
@@ -92,20 +94,25 @@ export class LambderApiPolicyEngine {
             const guardDef = this.guards[name];
             if (!guardDef)
                 throw new Error(`Lambder: guard "${name}" is not configured.`);
-            const payload = this.parseSlice(guardDef.input, 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 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.
+     * 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, ctx, resolver) {
-        if (!input)
-            return undefined;
-        const parsed = input.safeParse(ctx.post?.payload);
+    parseSlice(input, value, resolver) {
+        const parsed = input.safeParse(value);
         if (!parsed.success) {
             throw resolver.json({ error: "Input validation failed", zodError: parsed.error }, { statusCode: 422 });
         }
@@ -120,7 +127,9 @@ export class LambderApiPolicyEngine {
                 throw new Error('Lambder: rate-limit per "session" evaluated without a session on the context.');
             return `session:${sessionKey}`;
         }
-        const payload = this.parseSlice(per.input, ctx, resolver);
+        const payload = per.apiInput
+            ? this.parseSlice(per.apiInput, ctx.post?.payload, resolver)
+            : undefined;
         return `custom:${await per.handler(ctx, payload)}`;
     }
     /**

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

@@ -28,7 +28,7 @@ export type { LambderDdbRateLimiterOptions, LambderRateLimitPolicy, LambderRateL
 export { LambderDdbIdempotency } from "./LambderDdbIdempotency.js";
 export type { LambderDdbIdempotencyOptions, LambderIdempotencyBeginResult, } from "./LambderDdbIdempotency.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 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/package.json

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