lambder 3.8.1 → 4.0.1

package/dist/{LambderResponseBuilder.d.ts → core/LambderResponseBuilder.d.ts}

@@ -1,7 +1,9 @@
 import type { LambderRenderContext } from "./LambderContext.js";
 import { LambderResponse, type HttpStatusCode, type LambderHeadersInput } from "./LambderResponse.js";
-import { LambderSafeHtml } from "./LambderHtml.js";
+import { LambderSafeHtml } from "../shared/LambderHtml.js";
 import { type LambderTemplateData } from "./LambderTemplatingEngine.js";
+import type { LambderApiResponseConfig } from "../shared/LambderApiContract.js";
+export type { LambderApiResponse, LambderApiResponseConfig } from "../shared/LambderApiContract.js";
 export type LambderResponseOptions = {
     statusCode?: HttpStatusCode;
     headers?: LambderHeadersInput;
@@ -12,23 +14,9 @@ export type LambderResponseOptions = {
     /** "auto" (default): ETag on GET/HEAD 200 when globally enabled. true: force. false: never. */
     etag?: boolean | "auto";
 };
-export type LambderApiResponseConfig = {
-    versionExpired?: boolean;
-    sessionExpired?: boolean;
-    notAuthorized?: boolean;
-    message?: any;
-    errorMessage?: any;
-    logList?: any[];
-};
-export type LambderApiResponse<T> = LambderApiResponseConfig & {
-    apiVersion?: string | null;
-    payload?: T | null;
-};
 export type LambderRawResponseInit = {
     statusCode: HttpStatusCode;
     headers?: LambderHeadersInput;
-    /** Legacy alias for headers (API Gateway naming). */
-    multiValueHeaders?: Record<string, string[]>;
     body: string | Buffer | null;
     /** True when body is already a base64-encoded string. */
     isBase64Encoded?: boolean;

package/dist/{LambderResponseBuilder.js → core/LambderResponseBuilder.js}

@@ -1,5 +1,5 @@
 import mimeTypeResolver from "mime-types";
-import { getFS, getPath } from "./node-polyfills.js";
+import { getFS, getPath } from "../shared/node-polyfills.js";
 import { LambderResponse } from "./LambderResponse.js";
 import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
 // Compiled templates survive across requests (builder instances are per-request).
@@ -72,7 +72,7 @@ export default class LambderResponseBuilder {
     raw(init) {
         return new LambderResponse({
             statusCode: init.statusCode,
-            headers: init.headers ?? init.multiValueHeaders,
+            headers: init.headers,
             body: init.body,
             isBodyBase64: init.isBase64Encoded ?? false,
             compress: init.compress ?? (init.isBase64Encoded ? false : "auto"),

package/dist/{LambderTemplatingEngine.d.ts → core/LambderTemplatingEngine.d.ts}

@@ -1,4 +1,4 @@
-import { type LambderHtmlValue } from "./LambderHtml.js";
+import { type LambderHtmlValue } from "../shared/LambderHtml.js";
 /**
  * LambderTemplatingEngine: a comment-only HTML template engine.
  *

package/dist/{LambderTemplatingEngine.js → core/LambderTemplatingEngine.js}

@@ -1,5 +1,5 @@
-import { getFS } from "./node-polyfills.js";
-import { renderHtmlValue } from "./LambderHtml.js";
+import { getFS } from "../shared/node-polyfills.js";
+import { renderHtmlValue } from "../shared/LambderHtml.js";
 const TOKEN_PATTERN = /<!--\s*(?:(slot:([\w-]+)\s*\/)|(slot:([\w-]+))|(\/slot:([\w-]+))|(if:(!?)([\w-]+))|(else)|(\/if:(!?)([\w-]+)))\s*-->/g;
 /**
  * Fail loudly on slot positions where HTML escaping cannot protect against

package/dist/index.d.ts

@@ -1,36 +1,37 @@
-import Lambder from './Lambder.js';
+import Lambder from './core/Lambder.js';
 export default Lambder;
-export { default as LambderCaller } from "./LambderCaller.js";
-export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions } from "./LambderCaller.js";
-export { LambderApiError, isLambderApiError, refuse } from "./LambderApiError.js";
-export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefuseOptions } from "./LambderApiError.js";
-export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
-export { default as LambderResolver } from "./LambderResolver.js";
-export { default as LambderSessionManager } from "./LambderSessionManager.js";
-export { default as LambderSessionController } from "./LambderSessionController.js";
-export { default as LambderMSW } from "./LambderMSW.js";
-export type { LambderMswModule } from "./LambderMSW.js";
-export { LambderResponse, finalizeResponse, acceptsEncoding, type HttpStatusCode, type LambderHttpResponse, type LambderHttpEventFormat, type LambderHeadersInput, type LambderFinalizeOptions, } from "./LambderResponse.js";
-export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./LambderHtml.js";
-export { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
-export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./LambderTemplatingEngine.js";
-export type { LambderResponseOptions, LambderApiResponse, LambderApiResponseConfig, LambderRawResponseInit, } from "./LambderResponseBuilder.js";
-export type { LambderRouteMatcher, LambderCorsConfig, LambderConstructorOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, } from "./Lambder.js";
-export { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
-export type { LambderPublicFilesOptions } from "./LambderPublicFiles.js";
-export type { LambderSessionCookieOptions } from "./LambderSessionController.js";
-export type { LambderSessionContext, LambderSessionDataRefreshConfig } from "./LambderSessionManager.js";
-export { LambderSessionDataRefreshError } from "./LambderSessionManager.js";
-export { LambderDdbCache } from "./LambderDdbCache.js";
-export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./LambderDdbCache.js";
-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 { 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";
-export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent } from "./LambderContext.js";
-export { createContext, isV2HttpEvent } from "./LambderContext.js";
+export { default as LambderCaller } from "./client/LambderCaller.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderIdempotencyKeyScope } from "./client/LambderCaller.js";
+export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefuseOptions } from "./shared/LambderApiError.js";
+export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
+export { default as LambderResolver } from "./core/LambderResolver.js";
+export { default as LambderSessionManager } from "./session/LambderSessionManager.js";
+export { default as LambderSessionController } from "./session/LambderSessionController.js";
+export { LambderResponse, finalizeResponse, acceptsEncoding, type HttpStatusCode, type LambderHttpResponse, type LambderHttpEventFormat, type LambderHeadersInput, type LambderFinalizeOptions, } from "./core/LambderResponse.js";
+export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
+export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
+export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
+export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/LambderResponseBuilder.js";
+export type { LambderRouteMatcher, LambderCorsConfig, LambderConstructorOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, LambderApp, } from "./core/Lambder.js";
+export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
+export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
+export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
+export type { LambderSessionContext, LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
+export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
+export { LambderDdbCache } from "./stores/LambderDdbCache.js";
+export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./stores/LambderDdbCache.js";
+export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
+export type { LambderDdbRateLimiterOptions, LambderRateLimitPolicy, LambderRateLimitExceededMap, LambderRateLimitResult, } from "./stores/LambderDdbRateLimiter.js";
+export { LambderDdbIdempotency } from "./stores/LambderDdbIdempotency.js";
+export type { LambderDdbIdempotencyOptions, LambderIdempotencyBeginResult, LambderIdempotencyDoneRecord, } from "./stores/LambderDdbIdempotency.js";
+export { lambderGuard } from "./policies/LambderApiGuards.js";
+export type { LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderAllowedGuardNames, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardsOptionValue, LambderGuardDataOf, LambderGuardInputsOf, } from "./policies/LambderApiGuards.js";
+export { lambderRateLimitKey } from "./policies/LambderApiRateLimits.js";
+export type { LambderRateLimitKeyFn, LambderRateLimitPer, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, } from "./policies/LambderApiRateLimits.js";
+export type { LambderApiIdempotencyConfig } from "./policies/LambderApiIdempotency.js";
+export { createLambderI18n } from "./shared/LambderI18n.js";
+export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
+export { type ApiContractShape, type LambderApiResponse, type LambderApiResponseConfig, } from "./shared/LambderApiContract.js";
+export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent } from "./core/LambderContext.js";
+export { createContext, isV2HttpEvent } from "./core/LambderContext.js";

package/dist/index.js

@@ -1,30 +1,31 @@
-import Lambder from './Lambder.js';
+import Lambder from './core/Lambder.js';
 export default Lambder;
-export { default as LambderCaller } from "./LambderCaller.js";
+export { default as LambderCaller } from "./client/LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere)
-export { LambderApiError, isLambderApiError, refuse } from "./LambderApiError.js";
-export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
-export { default as LambderResolver } from "./LambderResolver.js";
-export { default as LambderSessionManager } from "./LambderSessionManager.js";
-export { default as LambderSessionController } from "./LambderSessionController.js";
-export { default as LambderMSW } from "./LambderMSW.js";
+export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
+export { default as LambderResolver } from "./core/LambderResolver.js";
+export { default as LambderSessionManager } from "./session/LambderSessionManager.js";
+export { default as LambderSessionController } from "./session/LambderSessionController.js";
 // Response model
-export { LambderResponse, finalizeResponse, acceptsEncoding, } from "./LambderResponse.js";
+export { LambderResponse, finalizeResponse, acceptsEncoding, } from "./core/LambderResponse.js";
 // Type-safe templating (tagged templates with auto-escaping)
-export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./LambderHtml.js";
+export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
 // Comment-based HTML templating engine (build-pipeline-safe slots and conditionals, standalone)
-export { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
+export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 // Public file serving
-export { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
-export { LambderSessionDataRefreshError } from "./LambderSessionManager.js";
+export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
+export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 // DynamoDB-backed compressed cache (standalone, server-only)
-export { LambderDdbCache } from "./LambderDdbCache.js";
+export { LambderDdbCache } from "./stores/LambderDdbCache.js";
 // DynamoDB-backed fixed-window rate limiter (standalone, server-only)
-export { LambderDdbRateLimiter } from "./LambderDdbRateLimiter.js";
+export { LambderDdbRateLimiter } from "./stores/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";
+export { LambderDdbIdempotency } from "./stores/LambderDdbIdempotency.js";
+// Declarative per-API policies: guards
+export { lambderGuard } from "./policies/LambderApiGuards.js";
+// Declarative per-API policies: rate limits
+export { lambderRateLimitKey } from "./policies/LambderApiRateLimits.js";
 // Typed translations (standalone, isomorphic)
-export { createLambderI18n } from "./LambderI18n.js";
-export { createContext, isV2HttpEvent } from "./LambderContext.js";
+export { createLambderI18n } from "./shared/LambderI18n.js";
+export { createContext, isV2HttpEvent } from "./core/LambderContext.js";

package/dist/policies/LambderApiGuards.d.ts

@@ -0,0 +1,221 @@
+import type { z } from "zod";
+import type { LambderRenderContext, LambderSessionRenderContext } from "../core/LambderContext.js";
+import type LambderResolver from "../core/LambderResolver.js";
+/**
+ * A named guard, run before the API's own input validation. Three input
+ * 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.
+ * - neither: the guard reads only the context.
+ *
+ * Orthogonally, a guard may also:
+ *
+ * - declare `session: true`: the guard needs ctx.session, so it is only
+ *   declarable on addSessionApi (compile error and startup assert on public
+ *   APIs) and its handler receives the session-typed context.
+ * - take a PARAMETER: annotate a 4th handler argument
+ *   (`(ctx, payload, res, param: YourType) => ...`) and APIs pass the value
+ *   in their declaration: `guards: { yourGuard: paramValue }`. The value is
+ *   trusted registration-time code (never client data), typed per guard.
+ * - RETURN a value: whatever the handler returns (awaited) is attached to
+ *   the API handler's context as `ctx.guardData[guardName]`, fully typed.
+ *   Guards that return nothing never appear in guardData.
+ *
+ * A validation failure answers the standard 422 shape, and the handler
+ * refuses by throwing (typically refuse()/LambderApiError). Build with
+ * lambderGuard() so the handler's payload/ctx/param types line up.
+ */
+export type LambderApiGuard<TInput extends z.ZodTypeAny = z.ZodTypeAny, TParam = any, TOutput = any> = {
+    apiInput: TInput;
+    guardInput?: undefined;
+    session?: boolean;
+    handler: (ctx: any, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+} | {
+    guardInput: TInput;
+    apiInput?: undefined;
+    session?: boolean;
+    handler: (ctx: any, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+} | {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    session?: boolean;
+    handler: (ctx: any, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+type GuardCtx = LambderRenderContext;
+type GuardSessionCtx = LambderSessionRenderContext<any, any>;
+/**
+ * Builder that ties the handler's payload, context, param, and output types
+ * together inside one literal. Returns the exact shape so type extraction
+ * (mode, session, param, output) works downstream. The param type is
+ * inferred from the handler's 4th argument annotation; the output from its
+ * return type.
+ */
+export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+    apiInput: TInput;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    apiInput: TInput;
+    guardInput?: undefined;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+    apiInput: TInput;
+    handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    apiInput: TInput;
+    guardInput?: undefined;
+    session?: undefined;
+    handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+    guardInput: TInput;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    guardInput: TInput;
+    apiInput?: undefined;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+    guardInput: TInput;
+    handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    guardInput: TInput;
+    apiInput?: undefined;
+    session?: undefined;
+    handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TParam = undefined, TOutput = void>(guard: {
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TParam = undefined, TOutput = void>(guard: {
+    handler: (ctx: GuardCtx, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    session?: undefined;
+    handler: (ctx: GuardCtx, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+/** The param type a guard's handler declares as its 4th argument; undefined for paramless guards. */
+type LambderGuardParamOf<G> = G extends {
+    handler: (...args: infer A) => any;
+} ? (A extends [any, any, any, infer P, ...any[]] ? P : undefined) : undefined;
+/** What a guard's handler returns (awaited); void for check-only guards. */
+type LambderGuardOutputOf<G> = G extends {
+    handler: (...args: any[]) => infer R;
+} ? Awaited<R> : never;
+/** Per-guard metadata carried on the Lambder instance: input mode, session requirement, param type, output 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>;
+} : {}) & (G extends {
+    session: true;
+} ? {
+    session: true;
+} : {}) & {
+    param: LambderGuardParamOf<G>;
+    output: LambderGuardOutputOf<G>;
+};
+export type LambderGuardMetaMap<TGuards> = {
+    [K in keyof TGuards]: LambderGuardMeta<TGuards[K]>;
+};
+/** Guard names referenced by a guards option, whichever of its three forms is used. */
+type NamesIn<TOpt> = TOpt extends string ? TOpt : TOpt extends readonly (infer N extends string)[] ? N : TOpt extends object ? keyof TOpt & string : never;
+type LambderGuardNameIfPayloadOk<TGuards, K extends keyof TGuards, TPayload> = TGuards[K] extends {
+    apiInput: infer R;
+} ? (TPayload extends R ? K : never) : K;
+/**
+ * Guard names an API may declare: apiInput-mode guards only when the API's
+ * payload carries their fields, session guards only on session APIs.
+ */
+export type LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession extends boolean = true> = {
+    [K in keyof TGuards]: TGuards[K] extends {
+        session: true;
+    } ? (TIncludeSession extends true ? LambderGuardNameIfPayloadOk<TGuards, K, TPayload> : never) : LambderGuardNameIfPayloadOk<TGuards, K, TPayload>;
+}[keyof TGuards] & string;
+/** The allowed guard names whose handler takes no param (usable in the string/array forms). */
+export type LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession extends boolean> = {
+    [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]: TGuards[K] extends {
+        param: undefined;
+    } ? K & string : never;
+}[LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards];
+/**
+ * The per-API `guards` option: one paramless guard name, an ordered list of
+ * paramless names, or an object map that can carry each guard's param
+ * (`true` enables a paramless guard). Map entries run in insertion order.
+ */
+export type LambderGuardsOption<TGuards, TPayload, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession> | readonly LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>[] | {
+    readonly [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]?: TGuards[K] extends {
+        param: undefined;
+    } ? true : TGuards[K] extends {
+        param: infer P;
+    } ? P : true;
+};
+/**
+ * The typed ctx.guardData an API's handler sees: declared guards that return
+ * a value, keyed by name. Check-only (void) guards never appear.
+ */
+export type LambderGuardDataOf<TGuards, TOpt> = {
+    [K in NamesIn<TOpt> & keyof TGuards as [
+        TGuards[K] extends {
+            output: infer O;
+        } ? O : never
+    ] extends [void] ? never : K & string]: TGuards[K] extends {
+        output: infer O;
+    } ? O : 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>;
+/** The guards option's runtime shape: a name, ordered names, or a name-to-param map. */
+export type LambderGuardsOptionValue = string | readonly string[] | Readonly<Record<string, unknown>>;
+/**
+ * Validate a preflight input slice (an apiInput slice of the raw payload, or
+ * a guardInput value from the raw guardInputs map). Runs before the API's
+ * own validation; failures answer the same 422 shape as regular input
+ * validation. Shared with the rate-limit engine's apiInput-keyed policies.
+ */
+export declare const parsePreflightSlice: (input: z.ZodTypeAny, value: unknown, resolver: LambderResolver) => unknown;
+/**
+ * Runtime side of the guards subsystem: holds the defined guards, asserts
+ * API registrations against them at startup, and executes an API's declared
+ * guards during preflight. Composed into LambderApiPolicyEngine.
+ */
+export declare class LambderApiGuardsEngine {
+    private guards;
+    addGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
+    /** Startup validation of one API registration's guards option. */
+    assertRegistration(apiName: string, mode: "public" | "session", guardsOption?: LambderGuardsOptionValue): void;
+    /** Run the API's guards in declared order. Refusals throw; outputs land on ctx.guardData. */
+    run(ctx: LambderRenderContext, resolver: LambderResolver, guardsOption?: LambderGuardsOptionValue): Promise<void>;
+}
+export {};

package/dist/policies/LambderApiGuards.js

@@ -0,0 +1,79 @@
+export function lambderGuard(guard) { return guard; }
+/** Normalize the three guards-option forms into ordered { name, param } entries. */
+const toGuardEntries = (value) => {
+    if (value === undefined)
+        return [];
+    if (typeof value === "string")
+        return [{ name: value, param: undefined }];
+    if (Array.isArray(value))
+        return value.map((name) => ({ name: String(name), param: undefined }));
+    // Object form: insertion order, params passed verbatim (paramless guards
+    // are declared with `true` and their handlers take no param argument).
+    return Object.entries(value).map(([name, param]) => ({ name, param }));
+};
+/**
+ * Validate a preflight input slice (an apiInput slice of the raw payload, or
+ * a guardInput value from the raw guardInputs map). Runs before the API's
+ * own validation; failures answer the same 422 shape as regular input
+ * validation. Shared with the rate-limit engine's apiInput-keyed policies.
+ */
+export const parsePreflightSlice = (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;
+};
+/**
+ * Runtime side of the guards subsystem: holds the defined guards, asserts
+ * API registrations against them at startup, and executes an API's declared
+ * guards during preflight. Composed into LambderApiPolicyEngine.
+ */
+export class LambderApiGuardsEngine {
+    guards = {};
+    addGuards(guards) {
+        for (const [name, guardDef] of Object.entries(guards)) {
+            if (this.guards[name])
+                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;
+        }
+    }
+    /** Startup validation of one API registration's guards option. */
+    assertRegistration(apiName, mode, guardsOption) {
+        for (const { name } of toGuardEntries(guardsOption)) {
+            const guardDef = this.guards[name];
+            if (!guardDef) {
+                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Define it via defineApiGuards() before registering the API.`);
+            }
+            if (guardDef.session && mode !== "session") {
+                throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true), which requires addSessionApi.`);
+            }
+        }
+    }
+    /** Run the API's guards in declared order. Refusals throw; outputs land on ctx.guardData. */
+    async run(ctx, resolver, guardsOption) {
+        for (const { name, param } of toGuardEntries(guardsOption)) {
+            const guardDef = this.guards[name];
+            if (!guardDef)
+                throw new Error(`Lambder: guard "${name}" is not configured.`);
+            const post = ctx.post;
+            let payload;
+            if (guardDef.apiInput) {
+                payload = parsePreflightSlice(guardDef.apiInput, post?.payload, resolver);
+            }
+            else if (guardDef.guardInput) {
+                payload = parsePreflightSlice(guardDef.guardInput, post?.guardInputs?.[name], resolver);
+            }
+            // A guard's return value becomes the handler's typed
+            // ctx.guardData[name]; check-only guards return undefined.
+            const output = await guardDef.handler(ctx, payload, resolver, param);
+            if (output !== undefined) {
+                ctx.guardData[name] = output;
+            }
+        }
+    }
+}

package/dist/policies/LambderApiIdempotency.d.ts

@@ -0,0 +1,58 @@
+import type { LambderRenderContext } from "../core/LambderContext.js";
+import type { LambderDdbIdempotency } from "../stores/LambderDdbIdempotency.js";
+import { LambderResponse } from "../core/LambderResponse.js";
+export type LambderApiIdempotencyConfig = {
+    /** Your idempotency store instance; may share the rate limiter's table (distinct key prefix). */
+    store: LambderDdbIdempotency;
+    /** Seconds a stored response replays for. Default: 86400 (24h). Per-API override: idempotency: { ttlSeconds }. */
+    defaultTtlSeconds?: number;
+    /** Skip idempotency (execute normally) when DynamoDB errors, instead of failing the request. Default: true. */
+    failOpen?: boolean;
+};
+/**
+ * Runtime side of the idempotency subsystem: claims a per-operation scope
+ * around handler execution, replays stored responses, and settles claims.
+ * Composed into LambderApiPolicyEngine.
+ */
+export declare class LambderApiIdempotencyEngine {
+    private store;
+    private defaultTtlSeconds;
+    private failOpen;
+    configure(config: LambderApiIdempotencyConfig): void;
+    /** True once enableApiIdempotency() ran; registration asserts check it. */
+    get isConfigured(): boolean;
+    /**
+     * The request's idempotencyKey: null when absent, the key when valid, a
+     * 400 refusal when malformed. The minimum length matters for security:
+     * see IDEMPOTENCY_MIN_KEY_LENGTH.
+     */
+    private readKey;
+    /**
+     * The record's scope. Session APIs scope per session, so even a leaked
+     * key cannot cross users. Public APIs scope by the key alone: the key is
+     * required to be long (and documented to be random), and identity proxies
+     * like the client IP are deliberately NOT part of the scope, because the
+     * retry idempotency exists for (a timeout followed by a network change)
+     * frequently arrives from a different IP.
+     */
+    private scopeOf;
+    /**
+     * Replay fast path, run BEFORE rate limits and guards: a completed record
+     * answers with its stored response so a legitimate retry neither burns
+     * rate-limit quota nor re-runs guards (the original already passed them,
+     * and no handler executes). Misses fall through to the normal pipeline;
+     * store errors follow the failOpen setting.
+     */
+    findReplay(apiName: string, ctx: LambderRenderContext): Promise<LambderResponse | null>;
+    /**
+     * Idempotency wrapper around validation-passed handler execution. Without
+     * a client idempotencyKey the handler just runs; with one, the scope
+     * (identity + api + key) is claimed atomically: duplicates of an
+     * in-flight original refuse with 409, replays of a completed one return
+     * the stored response verbatim, and a crashed original releases its claim
+     * so a retry actually retries.
+     */
+    withIdempotency(apiName: string, ctx: LambderRenderContext, config: boolean | {
+        ttlSeconds?: number;
+    }, exec: () => Promise<LambderResponse>): Promise<LambderResponse>;
+}