lambder 3.4.2 → 3.5.2

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) and typed translations with `createLambderI18n` (3.2).
+**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.
 
 ## Features
 
@@ -428,9 +428,88 @@ Responses are finalized once at the end of the request: automatic gzip (when the
 
 **Die Methods**: `res.die.*` - Builds the response and throws it, immediately halting the request at any call depth (handlers, hooks, nested helper functions). Plain `throw res.html(...)` works the same way.
 
+### Typed API Refusals (LambderApiError)
+
+A refusal ("you are not allowed", "quota exceeded") is not a crash. `res.die.*` covers refusals where you hold the resolver, but shared helpers (permission checks, validators) usually don't. Throw `LambderApiError` from anywhere in an API call's stack and the pipeline maps it onto the structured envelope instead of the global error handler, so refusals never pollute crash logging and clients get a parseable response:
+
+```typescript
+import { LambderApiError } from "lambder";
+
+// In any helper, no resolver needed:
+export const requirePermission = (granted: boolean) => {
+    if (!granted) throw new LambderApiError("Permission denied.", {
+        notAuthorized: true,                                    // envelope flag -> caller's notAuthorizedHandler
+        errorMessage: { type: "warning", content: "Not allowed." }, // any shape your errorMessageHandler expects
+        // sessionExpired: true,                                // optional envelope flag
+        // statusCode: 403,                                     // optional; default 200 (avoid 5xx and 422)
+    });
+};
+```
+
+`errorMessage` defaults to the error's message string, so `throw new LambderApiError("Nope.")` alone is already visible to the client. Thrown outside an API call (e.g. in a route handler) it behaves like a normal error. The class is isomorphic and dependency-free, so shared server/browser packages can import it safely. Detection is brand-based (`isLambderApiError`), so it works even when two copies of lambder end up in one bundle.
+
+Related: when an API call crashes with no `setGlobalErrorHandler` (or the handler itself fails), the last-resort 500 is now a JSON envelope (`{ payload: null, errorMessage: "Internal server error." }`) instead of a plain-text page; routes keep the plain-text 500.
+
+### Declarative API Policies (rate limits, guards, idempotency)
+
+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";
+
+const lambder = new Lambder<SessionData>({ apiPath: "/api" })
+    // 1. Rate limiting: your limiter instance + named policies. Each policy
+    //    declares its windows AND what one counter tracks ("per").
+    .enableApiRateLimits({
+        limiter: new LambderDdbRateLimiter({ tableName: "app-rate-limiter", region: "us-east-1", failOpen: true }),
+        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." } },
+        },
+    })
+    // 2. Idempotency: a store instance + replay defaults. May share the rate
+    //    limiter's table (records use an IDEM# key prefix).
+    .enableApiIdempotency({
+        store: new LambderDdbIdempotency({ tableName: "app-rate-limiter", region: "us-east-1" }),
+        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.
+    .defineApiGuards({
+        captcha: async (ctx) => {
+            if (!await verifyCaptcha(ctx.post?.payload?.captchaToken, ctx.ip)) {
+                throw new LambderApiError("Captcha failed", { errorMessage: "Verification failed, please retry." });
+            }
+        },
+    });
+
+lambder.addApi("public.resetPassword", {
+    input: z.object({ email: z.string().email(), captchaToken: z.string() }),
+    output: z.object({ ok: z.boolean() }),
+    rateLimit: ["authPerIp", "codePerEmail"],   // stacked: checked in order, first exceeded refuses (429 envelope)
+    guards: "captcha",
+}, handler);
+
+lambder.addSessionApi("secure.order.create", {
+    input: OrderSchema,
+    output: OrderResultSchema,
+    rateLimit: "writePerUser",
+    idempotency: true,                          // or { ttlSeconds: 3600 }; type error until enableApiIdempotency()
+}, handler);
+```
+
+Request flow per API: session (session APIs) → rate limits → guards → zod validation → idempotency claim → handler → idempotency store. Refusals ride the envelope via `LambderApiError` (429 rate limited, 409 duplicate in flight), so the caller's `errorMessageHandler` surfaces them with zero client code.
+
+**Idempotency semantics**: the client sends an `idempotencyKey` per call (see LambderCaller below); generate it once per logical operation and reuse it on retries. The scope is identity (session key, or IP for public APIs) + API name + key: concurrent duplicates of an in-flight request refuse with 409, repeats of a completed one replay the stored response verbatim until the TTL, and a crashed original releases its claim so a retry actually retries. A response delivered by throwing (`res.die.*`, `throw res.api(...)`) counts as a completion and is stored like a returned one; thrown `LambderApiError` refusals release the claim instead. Responses with status ≥ 500 are never stored. Claims are owner-checked, so an original that stalls past the pending window can no longer overwrite or delete the claim a retry has since taken. Requests without a key execute normally.
+
+Also enforced at registration: **duplicate API names throw** (dispatch is first-match, so a second registration of the same name would be silently dead code).
+
 ### DynamoDB Cache (LambderDdbCache)
 
-Standalone, persistent JSON cache backed by a DynamoDB table (`pk`/`sk` keys + `expiresAt` TTL attribute, same shape as the session table). Brotli-compressed values, in-memory LRU layer, single-flight deduplication, a DynamoDB lease so only one Lambda fills a missing key, and fail-open semantics. Server-only. **Full guide with table setup: [docs/DDB_CACHE.md](./docs/DDB_CACHE.md).**
+Standalone, persistent JSON cache backed by a DynamoDB table (`pk`/`sk` keys + `expiresAt` TTL attribute, same shape as the session table). Items are prefixed `CACHE#<namespace>#`, and the rate limiter (`RL#`) and idempotency store (`IDEM#`) prefix theirs too, so all three non-session systems can share one table without collisions; keep sessions in their own table for IAM scoping. Brotli-compressed values, in-memory LRU layer, single-flight deduplication, a DynamoDB lease so only one Lambda fills a missing key, and fail-open semantics. Server-only. **Full guide with table setup: [docs/DDB_CACHE.md](./docs/DDB_CACHE.md).**
 
 ```typescript
 import { LambderDdbCache } from "lambder";
@@ -505,6 +584,33 @@ const user = await lambderCaller.api("getCompanyPage", { companyName: "Acme" });
 // - Expected output type
 ```
 
+### Failure Semantics (apiOutcome, timeouts, per-call overrides)
+
+`api()` collapses every failure to `null`, which is indistinguishable from a legitimately-null payload. When the call site needs to know why, use `apiOutcome()`; it never throws and resolves to a discriminated union:
+
+```typescript
+const outcome = await lambderCaller.apiOutcome("getCompanyPage", { companyName: "Acme" });
+if (outcome.ok) {
+    render(outcome.payload);
+} else if (outcome.reason === "network" || outcome.reason === "timeout") {
+    showOfflineScreen();
+} else if (outcome.reason === "sessionExpired") {
+    redirectToLogin();
+} else {
+    // 'server' (5xx / non-envelope body), 'validation' (422), 'versionExpired',
+    // 'notAuthorized', 'errorMessage' (structured refusal), 'unknown'
+    showError(outcome.errorMessage);
+}
+```
+
+Every configured handler still fires on the matching failure, so global UX (toasts, re-login prompts) lives in the constructor while individual call sites branch on the outcome.
+
+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.
+- **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
 
 ✅ **No Manual Type Definitions** - Types are inferred from your Zod schemas  

package/dist/Lambder.d.ts

@@ -8,6 +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 { MergeContract } from "./LambderApiContract.js";
 import { type LambderHttpEvent, type LambderRenderContext, type LambderSessionRenderContext } from "./LambderContext.js";
 export type { PathParamsOf, RouteCondition, ConditionFunction, LambderRouteMatcher } from "./LambderRouting.js";
@@ -16,7 +17,7 @@ type MaybePromise<T> = T | Promise<T>;
 type Path = `/${string}`;
 type ActionFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderResponse>;
 type SessionActionFunction<SessionData = any> = (ctx: LambderSessionRenderContext<any, SessionData>, resolver: LambderResolver) => MaybePromise<LambderResponse>;
-type HookCreatedFunction = (lambderInstance: Lambder<any, any>) => void | Promise<void>;
+type HookCreatedFunction = (lambderInstance: Lambder<any, any, any, any, any>) => void | Promise<void>;
 /** Return the (possibly replaced) ctx to continue, a LambderResponse to short-circuit, or an Error to fail. */
 type HookBeforeRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderRenderContext | LambderResponse | Error>;
 type HookAfterRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver, response: LambderResponse) => MaybePromise<LambderResponse | Error>;
@@ -79,6 +80,9 @@ 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 _TIdempotencyEnabled - @internal Flipped by enableApiIdempotency (do not pass manually)
  *
  * @example
  * ```typescript
@@ -89,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> = {}> {
+export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuardName extends string = never, _TIdempotencyEnabled extends boolean = false> {
     apiPath: string;
     apiVersion: null | string;
     publicPath: string;
@@ -105,6 +109,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      */
     readonly ApiContract: _TContract;
     private actionList;
+    private apiPolicyEngine;
+    private registeredApiNames;
     private hookList;
     private createdHooks;
     private initPromise;
@@ -173,19 +179,50 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     serveIndexHtml(handler?: FallbackHandlerFunction, options?: LambderIndexHtmlOptions): this;
     /** Apply the serveIndexHtml gates; null means fall through. */
     private tryServeIndexHtml;
+    /**
+     * Wire declarative per-API rate limiting: your LambderDdbRateLimiter
+     * instance plus named policies, each declaring its windows and what one
+     * counter tracks (`per`: "ip", "session", or a custom key function).
+     * APIs then reference policies by name via the `rateLimit` option; the
+     * returned type narrows so only declared names are accepted, and
+     * 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>;
+    /**
+     * Wire declarative idempotency: your LambderDdbIdempotency instance plus
+     * replay defaults. APIs opt in via `idempotency: true | { ttlSeconds }`;
+     * the option is a type error until this is called. Requests carrying a
+     * client `idempotencyKey` (sent by LambderCaller) claim an
+     * identity+api+key scope atomically: concurrent duplicates refuse with
+     * 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>;
+    /**
+     * 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.
+     */
+    defineApiGuards<TGuards extends Record<string, LambderApiGuardFunction>>(guards: TGuards): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuardName | Extract<keyof TGuards, string>, _TIdempotencyEnabled>;
+    private getOrCreatePolicyEngine;
+    /** Registration-time checks shared by addApi/addSessionApi. */
+    private assertApiRegistration;
     addRoute<TPath extends Path>(condition: TPath, actionFn: (ctx: LambderRenderContext<any, PathParamsOf<TPath>>, resolver: LambderResolver) => MaybePromise<LambderResponse>): this;
     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>) => Lambder<TSessionData, _TNewContract>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract)>;
+    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: {
         input: TInput;
         output: TOutput;
-    }, handler: (ctx: LambderRenderContext<z.infer<TInput>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<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: {
         input: TInput;
         output: TOutput;
-    }, 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>>>;
+    } & 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>;
     /**
      * Fetch the session or short-circuit the request: API calls get the
      * protocol's { sessionExpired: true } response (handled by LambderCaller),
@@ -199,6 +236,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     getSessionController(ctx: LambderRenderContext | LambderSessionRenderContext<any, TSessionData>): LambderSessionController<TSessionData>;
     getResponseBuilder(ctx?: LambderRenderContext): LambderResponseBuilder<any>;
     private getResolver;
+    /** Map a thrown LambderApiError onto the structured API envelope. */
+    private apiErrorResponse;
     getHandler(): LambderHandler;
     /** True when the Lambda event is an API Gateway HTTP event (REST API v1 or HTTP API / Function URL v2). */
     static isHttpEvent(event: unknown): event is LambderHttpEvent;

package/dist/Lambder.js

@@ -6,12 +6,17 @@ import { applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "./LambderSessionManager.js";
 import LambderSessionController from "./LambderSessionController.js";
 import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
+import { isLambderApiError } from "./LambderApiError.js";
+import { LambderApiPolicyEngine, } from "./LambderApiPolicies.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.js";
 /**
  * Main Lambder class for building type-safe serverless APIs
  *
  * @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 _TIdempotencyEnabled - @internal Flipped by enableApiIdempotency (do not pass manually)
  *
  * @example
  * ```typescript
@@ -38,6 +43,8 @@ export default class Lambder {
      */
     ApiContract;
     actionList = [];
+    apiPolicyEngine = null;
+    registeredApiNames = new Set();
     hookList = { "beforeRender": [], "afterRender": [], "fallback": [] };
     createdHooks = [];
     initPromise = null;
@@ -155,6 +162,65 @@ export default class Lambder {
         }
         return response;
     }
+    // ---------------------------------------------------------------------
+    // Declarative API policies (rate limits, guards, idempotency)
+    // ---------------------------------------------------------------------
+    /**
+     * Wire declarative per-API rate limiting: your LambderDdbRateLimiter
+     * instance plus named policies, each declaring its windows and what one
+     * counter tracks (`per`: "ip", "session", or a custom key function).
+     * APIs then reference policies by name via the `rateLimit` option; the
+     * returned type narrows so only declared names are accepted, and
+     * policies keyed per "session" are only referable from addSessionApi.
+     * Callable once; call it before the API registrations that use it.
+     */
+    enableApiRateLimits(config) {
+        this.getOrCreatePolicyEngine().setRateLimits(config);
+        return this;
+    }
+    /**
+     * Wire declarative idempotency: your LambderDdbIdempotency instance plus
+     * replay defaults. APIs opt in via `idempotency: true | { ttlSeconds }`;
+     * the option is a type error until this is called. Requests carrying a
+     * client `idempotencyKey` (sent by LambderCaller) claim an
+     * identity+api+key scope atomically: concurrent duplicates refuse with
+     * 409, replays of a completed request return the stored response, and a
+     * crashed original releases its claim. Callable once.
+     */
+    enableApiIdempotency(config) {
+        this.getOrCreatePolicyEngine().setIdempotency(config);
+        return this;
+    }
+    /**
+     * 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.
+     */
+    defineApiGuards(guards) {
+        this.getOrCreatePolicyEngine().addGuards(guards);
+        return this;
+    }
+    getOrCreatePolicyEngine() {
+        if (!this.apiPolicyEngine)
+            this.apiPolicyEngine = new LambderApiPolicyEngine();
+        return this.apiPolicyEngine;
+    }
+    /** Registration-time checks shared by addApi/addSessionApi. */
+    assertApiRegistration(name, mode, options) {
+        if (this.registeredApiNames.has(name)) {
+            throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
+        }
+        this.registeredApiNames.add(name);
+        const usesPolicies = options.rateLimit !== undefined || options.guards !== undefined || options.idempotency !== undefined;
+        if (!usesPolicies)
+            return;
+        if (!this.apiPolicyEngine) {
+            throw new Error(`Lambder: API "${name}" declares rateLimit/guards/idempotency, but none of enableApiRateLimits()/defineApiGuards()/enableApiIdempotency() was called first.`);
+        }
+        this.apiPolicyEngine.assertRegistration(name, mode, options);
+    }
     addRoute(condition, actionFn) {
         this.actionList.push({
             match: compileRouteMatcher(condition),
@@ -173,14 +239,21 @@ export default class Lambder {
         return this;
     }
     // Plugin system
+    // The policy generics are `any` in the plugin signature on purpose: a
+    // module may annotate its parameter as the bare Lambder<SessionData> or
+    // as the app's narrowed alias, and both must chain. Registration-time
+    // assertions still verify every referenced policy/guard name at runtime.
     use(plugin) {
         return plugin(this);
     }
     // Typed API with Zod
     addApi(name, schema, handler) {
+        this.assertApiRegistration(name, "public", schema);
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
             actionFn: async (ctx, resolver) => {
+                if (this.apiPolicyEngine)
+                    await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);
                 if (!inputResult.success) {
                     if (this.apiInputValidationErrorHandler) {
@@ -189,17 +262,23 @@ export default class Lambder {
                     return resolver.json({ error: "Input validation failed", zodError: inputResult.error }, { statusCode: 422 });
                 }
                 ctx.apiPayload = inputResult.data;
-                return await handler(ctx, resolver);
+                const run = async () => await handler(ctx, resolver);
+                if (this.apiPolicyEngine && schema.idempotency)
+                    return await this.apiPolicyEngine.withIdempotency(name, ctx, schema.idempotency, run);
+                return await run();
             },
         });
         return this;
     }
     // Typed Session API with Zod
     addSessionApi(name, schema, handler) {
+        this.assertApiRegistration(name, "session", schema);
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
             actionFn: async (ctx, resolver) => {
                 await this.requireSession(ctx, resolver);
+                if (this.apiPolicyEngine)
+                    await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);
                 if (!inputResult.success) {
                     if (this.apiInputValidationErrorHandler) {
@@ -208,7 +287,10 @@ export default class Lambder {
                     return resolver.json({ error: "Input validation failed", zodError: inputResult.error }, { statusCode: 422 });
                 }
                 ctx.apiPayload = inputResult.data;
-                return await handler(ctx, resolver);
+                const run = async () => await handler(ctx, resolver);
+                if (this.apiPolicyEngine && schema.idempotency)
+                    return await this.apiPolicyEngine.withIdempotency(name, ctx, schema.idempotency, run);
+                return await run();
             }
         });
         return this;
@@ -268,6 +350,14 @@ export default class Lambder {
         });
     }
     ;
+    /** Map a thrown LambderApiError onto the structured API envelope. */
+    apiErrorResponse(err, resolver) {
+        return resolver.api(null, {
+            ...(err.errorMessage !== undefined ? { errorMessage: err.errorMessage } : {}),
+            ...(err.notAuthorized ? { notAuthorized: true } : {}),
+            ...(err.sessionExpired ? { sessionExpired: true } : {}),
+        }, err.statusCode !== undefined ? { statusCode: err.statusCode } : undefined);
+    }
     getHandler() {
         return ((event, context) => Lambder.isHttpEvent(event)
             ? this.render(event, context)
@@ -401,6 +491,11 @@ export default class Lambder {
                 if (err instanceof LambderResponse) {
                     response = err;
                 }
+                // A thrown LambderApiError on an API call IS a structured refusal
+                // (brand-checked, not instanceof, to survive duplicate installs).
+                else if (isLambderApiError(err) && ctx._otherInternal.isApiCall) {
+                    response = this.apiErrorResponse(err, resolver);
+                }
                 else {
                     throw err;
                 }
@@ -417,6 +512,9 @@ export default class Lambder {
                 if (err instanceof LambderResponse) {
                     response = err;
                 }
+                else if (isLambderApiError(err) && ctx._otherInternal.isApiCall) {
+                    response = this.apiErrorResponse(err, resolver);
+                }
                 else {
                     throw err;
                 }
@@ -450,6 +548,14 @@ export default class Lambder {
                     catch { /* fall through */ }
                 }
             }
+            // Last-resort 500. API calls get the JSON envelope so clients can
+            // parse a structured failure; everything else keeps plain text.
+            if (ctx?._otherInternal.isApiCall) {
+                const apiBody = JSON.stringify({ apiVersion: this.apiVersion, payload: null, errorMessage: "Internal server error." });
+                return eventFormat === "v2"
+                    ? { statusCode: 500, headers: { "Content-Type": "application/json; charset=utf-8" }, body: apiBody, isBase64Encoded: false }
+                    : { statusCode: 500, multiValueHeaders: { "Content-Type": ["application/json; charset=utf-8"] }, body: apiBody, isBase64Encoded: false };
+            }
             return eventFormat === "v2"
                 ? { statusCode: 500, headers: {}, body: "Internal Server Error.", isBase64Encoded: false }
                 : { statusCode: 500, multiValueHeaders: {}, body: "Internal Server Error.", isBase64Encoded: false };

package/dist/LambderApiError.d.ts

@@ -0,0 +1,54 @@
+import type { HttpStatusCode } from "./LambderResponse.js";
+export type LambderApiErrorOptions = {
+    /**
+     * Structured, user-facing failure detail placed on the API envelope's
+     * `errorMessage` field. Any shape the app's errorMessageHandler expects
+     * (e.g. `{ type: "warning", content: "..." }`). Defaults to the error
+     * message string, so a bare `throw new LambderApiError("...")` is still
+     * visible to the client.
+     */
+    errorMessage?: any;
+    /** Sets the envelope's `notAuthorized` flag (routed to the caller's notAuthorizedHandler). */
+    notAuthorized?: boolean;
+    /** Sets the envelope's `sessionExpired` flag (the caller clears session cookies and calls sessionExpiredHandler). */
+    sessionExpired?: boolean;
+    /**
+     * HTTP status of the refusal response. Default 200: the envelope is the
+     * semantic channel. Avoid 5xx (LambderCaller treats those as crashes) and
+     * 422 (reserved for input validation).
+     */
+    statusCode?: HttpStatusCode;
+    /** Underlying cause, preserved on the standard Error `cause` property. */
+    cause?: unknown;
+};
+/**
+ * A typed refusal: "this request is denied/invalid" as opposed to "the server
+ * crashed". Throw it from anywhere in an API call's call stack — handlers,
+ * hooks, or nested helpers that have no access to the per-request resolver —
+ * and the render pipeline maps it onto the structured API envelope
+ * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
+ * of routing it through setGlobalErrorHandler. Refusals therefore never reach
+ * crash logging, and clients receive a parseable response they can surface.
+ *
+ * Thrown outside an API call (e.g. in a route handler) it behaves like any
+ * other error: global error handler, then the default 500.
+ *
+ * Isomorphic and dependency-free, so shared code (validators, permission
+ * checks) may import and throw it from packages used by both server and
+ * browser builds; in the browser it is just an Error.
+ */
+export declare class LambderApiError extends Error {
+    /**
+     * Brand for detection across duplicate lambder installs: when two copies
+     * of the package coexist in one bundle, `instanceof LambderApiError` fails
+     * across them while this marker does not. The pipeline checks the brand.
+     */
+    readonly isLambderApiError = true;
+    readonly errorMessage?: any;
+    readonly notAuthorized?: boolean;
+    readonly sessionExpired?: boolean;
+    readonly statusCode?: HttpStatusCode;
+    constructor(message: string, options?: LambderApiErrorOptions);
+}
+/** Brand-based type guard (see LambderApiError.isLambderApiError). */
+export declare const isLambderApiError: (err: unknown) => err is LambderApiError;

package/dist/LambderApiError.js

@@ -0,0 +1,38 @@
+/**
+ * A typed refusal: "this request is denied/invalid" as opposed to "the server
+ * crashed". Throw it from anywhere in an API call's call stack — handlers,
+ * hooks, or nested helpers that have no access to the per-request resolver —
+ * and the render pipeline maps it onto the structured API envelope
+ * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
+ * of routing it through setGlobalErrorHandler. Refusals therefore never reach
+ * crash logging, and clients receive a parseable response they can surface.
+ *
+ * Thrown outside an API call (e.g. in a route handler) it behaves like any
+ * other error: global error handler, then the default 500.
+ *
+ * Isomorphic and dependency-free, so shared code (validators, permission
+ * checks) may import and throw it from packages used by both server and
+ * browser builds; in the browser it is just an Error.
+ */
+export class LambderApiError extends Error {
+    /**
+     * Brand for detection across duplicate lambder installs: when two copies
+     * of the package coexist in one bundle, `instanceof LambderApiError` fails
+     * across them while this marker does not. The pipeline checks the brand.
+     */
+    isLambderApiError = true;
+    errorMessage;
+    notAuthorized;
+    sessionExpired;
+    statusCode;
+    constructor(message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "LambderApiError";
+        this.errorMessage = options.errorMessage ?? message;
+        this.notAuthorized = options.notAuthorized;
+        this.sessionExpired = options.sessionExpired;
+        this.statusCode = options.statusCode;
+    }
+}
+/** Brand-based type guard (see LambderApiError.isLambderApiError). */
+export const isLambderApiError = (err) => err instanceof Error && err.isLambderApiError === true;

package/dist/LambderApiPolicies.d.ts

@@ -0,0 +1,95 @@
+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.
+ */
+export type LambderRateLimitPer = "ip" | "session" | ((ctx: LambderRenderContext) => string | Promise<string>);
+/** A named rate-limit policy: fixed windows plus the key one counter tracks. */
+export type LambderApiRateLimitPolicyConfig = LambderRateLimitPolicy & {
+    per: LambderRateLimitPer;
+    /** Envelope errorMessage for refused requests. Default: a generic too-many-requests message. */
+    errorMessage?: any;
+};
+export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>> = {
+    /** Your limiter instance; its table, keyPrefix and failOpen apply as configured on it. */
+    limiter: LambderDdbRateLimiter;
+    /** Named policies referenced (typed) from addApi/addSessionApi. */
+    policies: TPolicies;
+};
+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;
+};
+/**
+ * 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.
+ */
+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> = {
+    [K in keyof TPolicies]: TPolicies[K] extends {
+        per: "session";
+    } ? never : K;
+}[keyof TPolicies] & string;
+/** Declarative per-API options carried in the addApi/addSessionApi schema object. */
+export type LambderApiRegistrationOptions<TRateLimitName extends string, TGuardName extends string, TIdempotencyEnabled extends boolean> = {
+    /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
+    rateLimit?: TRateLimitName | readonly TRateLimitName[];
+    /** Named guards, run in declared order before input validation; refuse by throwing. */
+    guards?: TGuardName | readonly TGuardName[];
+    /** Replay-protect this API per client idempotencyKey. Requires enableApiIdempotency() first. */
+    idempotency?: TIdempotencyEnabled extends true ? (boolean | {
+        ttlSeconds?: number;
+    }) : never;
+};
+/**
+ * Runtime side of the declarative API options: holds what the enable/define
+ * calls declared, asserts registrations against it at startup, and executes
+ * rate limits, guards, and idempotency around handlers at request time.
+ * Internal to Lambder; apps interact through enableApiRateLimits(),
+ * enableApiIdempotency(), defineApiGuards() and the per-API options.
+ */
+export declare class LambderApiPolicyEngine {
+    private limiter;
+    private rateLimitPolicies;
+    private guards;
+    private idempotencyStore;
+    private idempotencyDefaultTtlSeconds;
+    private idempotencyFailOpen;
+    setRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
+    addGuards(guards: Record<string, LambderApiGuardFunction>): void;
+    setIdempotency(config: LambderApiIdempotencyConfig): void;
+    /** Startup validation of one API registration's declarative options. */
+    assertRegistration(apiName: string, mode: "public" | "session", options: {
+        rateLimit?: string | readonly string[];
+        guards?: string | readonly string[];
+        idempotency?: unknown;
+    }): void;
+    /** Rate limits then guards, in declared order. Refusals throw (LambderApiError or a guard's own throw). */
+    runPreflight(apiName: string, ctx: LambderRenderContext, resolver: LambderResolver, options: {
+        rateLimit?: string | readonly string[];
+        guards?: string | readonly string[];
+    }): Promise<void>;
+    private resolveRateLimitKey;
+    /**
+     * 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>;
+}