lambder 4.1.1 → 4.2.3

package/Readme.md

@@ -2,10 +2,18 @@
 
 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 4.2:**
+
+- **Rate-limit budgets**: a policy's `budget` is `"perApi"` (default: each referencing API gets its own counter, so the numbers are a per-API ceiling and three APIs on a 60/min policy allow one IP 180/min in total) or `"perPolicy"` (one counter shared by every API referencing the policy). The policy is the group, and two separate shared budgets are two policies.
+- **Per-API tuning**: the `rateLimit` option gained a map form like guards, `rateLimit: { lookupPerIp: { perMin: 20 } }`, which merges window overrides over a perApi policy's own (a tighter burst keeps the policy's daily cap). Overriding the windows of a perPolicy policy is a startup error; `errorMessage` is overridable on either.
+- **Retry-After**: a 429 carries the exceeded window's reset as a `Retry-After` header (CORS exposes it by default via the new `exposeHeaders` option), `LambderCaller` failure outcomes surface it as `retryAfterSeconds`, `LambderDdbRateLimiter.isRateLimited()` answers `false | { window, limit, resetAt }`, and `LambderApiError`/`refuse()` accept `headers`.
+- **One refusal shape, with codes**: `LambderRefusalMessage` gained an optional machine-readable `code` (`refuse(content, { code })`), so clients branch and translate on an identifier instead of string-matching prose. Every refusal the framework itself authors (rate limit 429, idempotency 409 and 400, unknown API) is a `LambderRefusalMessage` stamped with a `LAMBDER_REFUSAL_CODES` constant under the reserved `lambder/` prefix; a rate-limit policy's own `errorMessage` (typed as a refusal message) inherits `lambder/rate-limited` unless it sets a code.
+- **One validation path**: preflight slices (guard `apiInput`/`guardInput`, rate-limit `apiInput` keys) answer through `setApiInputValidationErrorHandler` exactly like the API's own schema.
+
 **New in v4:**
 
 - **Declarative auth as guards**: guards take per-API params (`guards: { orgPermission: "SOME.PERMISSION" }`), can require a session (`session: true`, compile-checked), and RETURN typed values that land on the handler's `ctx.guardData[name]`. Together with the apiInput/guardInput input modes, permission checks and device auth become registration-time declarations instead of per-handler boilerplate.
-- **Hardened policy layer**: rate-limit policies can share one counter across APIs (`scope: "policy"`); idempotency replays answer before rate limits, survive client IP changes (key-scoped for public APIs, 16-char minimum keys), store full response headers, refuse to store Set-Cookie responses, and Brotli-compress stored bodies of 1KB+ so the ~350KB replay budget applies to compressed bytes.
+- **Hardened policy layer**: rate-limit policies can share one counter across APIs (now `budget: "perPolicy"`); idempotency replays answer before rate limits, survive client IP changes (key-scoped for public APIs, 16-char minimum keys), store full response headers, refuse to store Set-Cookie responses, and Brotli-compress stored bodies of 1KB+ so the ~350KB replay budget applies to compressed bytes.
 - **Secrets hashed at rest**: session records store only sha256 hashes of the bearer secrets, so a session-table read yields no usable cookies; `LambderSessionReadError` keeps a DynamoDB blip from reading as a logout.
 - **Three package entry points**: `lambder` (server), `lambder/client` (browser-safe by construction: no AWS SDK, no Node built-ins), `lambder/testing` (`LambderMSW`); sources organized into core/policies/session/stores/client/shared.
 - **Configuration at creation**: `initLambder<SessionData>().create({...})` takes the WHOLE configuration (serving options, session, cors, rate limits, guards, idempotency) in one declaration; the enable/define chain methods are gone, so nothing can be half-configured or wired in the wrong order, and api modules annotate with `typeof lambderApp` derived from the real instance. Plus `LambderCaller.createIdempotencyKeyScope()` for one self-rotating key per logical operation, and fail-open rate limiting logs its passes.
@@ -471,7 +479,7 @@ Responses are finalized once at the end of the request: automatic gzip (when the
 
 ### Typed API Refusals (refuse / 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. The one-liner for the common case is `refuse()`: callable from anywhere in an API call's stack, it throws a typed refusal carrying the standard `LambderRefusalMessage` shape (`{ type, title?, content }`) that the pipeline maps onto the envelope's `errorMessage`, so refusals never pollute crash logging and clients get a parseable response:
+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. The one-liner for the common case is `refuse()`: callable from anywhere in an API call's stack, it throws a typed refusal carrying the standard `LambderRefusalMessage` shape (`{ type, code?, title?, content }`) that the pipeline maps onto the envelope's `errorMessage`, so refusals never pollute crash logging and clients get a parseable response:
 
 ```typescript
 import { refuse } from "lambder";
@@ -479,9 +487,12 @@ import { refuse } from "lambder";
 if (!row) refuse("Record not found.");                                  // { type: "warning", content }
 if (!isAdmin) refuse("Admins only.", { notAuthorized: true });          // + envelope flag
 refuse("Too many attempts.", { type: "error", statusCode: 429 });       // custom rendering intent + status
+if (exists) refuse("Already reported.", { code: "ALREADY_REPORTED" }); // + machine-readable identity
 // TypeScript applies never-return narrowing: after `if (!row) refuse(...)`, row is defined.
 ```
 
+`code` is the refusal's identity for machines: clients branch and translate on it (a translated client never displays `content`, it looks the code up), and `content` stays the human-readable fallback for codes a client does not know yet. Keep your app's codes as one typed vocabulary in shared code. The framework stamps the refusals it authors itself with `LAMBDER_REFUSAL_CODES` (exported from `lambder` and `lambder/client`) under the reserved `lambder/` prefix, so app codes never collide: `rateLimited`, `duplicateInFlight`, `invalidIdempotencyKey`, `apiNotFound`. A rate-limit policy's own `errorMessage` inherits `lambder/rate-limited` unless it sets a code, so an `errorMessageHandler` can treat every rate limit alike and still special-case the ones you name.
+
 For full control of the errorMessage payload (apps with their own message vocabulary), throw `LambderApiError` directly; `refuse()` is sugar over it:
 
 ```typescript
@@ -512,7 +523,12 @@ import { initLambder, LambderDdbRateLimiter, LambderDdbIdempotency, lambderGuard
 const lambder = initLambder<SessionData>().create({
     apiPath: "/api",
     // 1. Rate limiting: your limiter instance + named policies. Each policy
-    //    declares its windows AND what one counter tracks ("per").
+    //    declares its windows, what one counter tracks ("per"), and what one
+    //    budget spans ("budget"): "perApi" (default) gives every referencing
+    //    API its own counter, so three APIs on a 60/min policy allow one IP
+    //    180/min in total; "perPolicy" makes every referencing API share ONE
+    //    counter. The policy IS the group: separate shared budgets for, say,
+    //    user APIs and report APIs are two policies.
     rateLimits: {
         limiter: new LambderDdbRateLimiter({ tableName: "app-rate-limiter", region: "us-east-1", failOpen: true }),
         policies: {
@@ -520,10 +536,9 @@ const lambder = initLambder<SessionData>().create({
             writePerUser: { perMin: 30, per: "session" },   // only referable from addSessionApi (also enforced at compile time)
             codePerEmail: {
                 perMin: 3,
-                // scope "policy": ONE combined budget across every API that
-                // references this policy (send + register + reset share the
-                // 3/min). Default scope "api" gives each API its own counter.
-                scope: "policy",
+                // ONE combined budget across every API that references this
+                // policy: send + register + reset share the 3/min.
+                budget: "perPolicy",
                 // 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`.
@@ -580,14 +595,18 @@ lambder.addApi("public.resetPassword", {
     // 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)
+    rateLimit: ["authPerIp", "codePerEmail"],   // stacked: checked in order, first exceeded refuses (429 envelope + Retry-After)
     guards: "captcha",                          // one name, a list of names, or a { name: param } map
 }, handler);
 
 lambder.addSessionApi("secure.order.create", {
     input: OrderSchema,
     output: OrderResultSchema,
-    rateLimit: "writePerUser",
+    // Map form: tune a perApi policy for this API. Overrides merge over the
+    // policy's windows (perMin here, the policy's other windows still apply)
+    // and errorMessage is overridable too. Window overrides on a perPolicy
+    // policy are a startup error: one shared counter has one set of limits.
+    rateLimit: { writePerUser: { perMin: 10 } },
     guards: { orgPermission: "ORDERS.CREATE" }, // param typed per guard; entries run in insertion order
     idempotency: true,                          // or { ttlSeconds: 3600 }; type error unless created with idempotency
 }, async (ctx, res) => {
@@ -619,7 +638,11 @@ const lambder = lambderApp.addHook(...).use(orderApi)...;
 export const handler = lambder.getHandler();
 ```
 
-Request flow per API: session (session APIs) → idempotency replay lookup → rate limits → guards → zod validation → idempotency claim → handler → idempotency store. The replay lookup runs first on purpose: a completed idempotent request answers its stored response without burning rate-limit quota or re-running guards (the original already passed them, and no handler executes either way). Refusals ride the envelope via `LambderApiError` (429 rate limited, 409 duplicate in flight), so the caller's `errorMessageHandler` surfaces them with zero client code.
+Request flow per API: session (session APIs) → idempotency replay lookup → rate limits → guards → zod validation → idempotency claim → handler → idempotency store. The replay lookup runs first on purpose: a completed idempotent request answers its stored response without burning rate-limit quota or re-running guards (the original already passed them, and no handler executes either way). Refusals ride the envelope via `LambderApiError` (429 rate limited, 409 duplicate in flight), carrying the standard `LambderRefusalMessage` shape unless a policy names its own `errorMessage`, so the caller's `errorMessageHandler` surfaces them with zero client code. A 429 also carries `Retry-After` (the exceeded fixed window's reset; `LambderCaller` outcomes expose it as `retryAfterSeconds`, and the CORS layer lists it in `Access-Control-Expose-Headers` by default).
+
+**Rate limits count attempts, not successes.** Each window is one atomic conditional increment, and a refused request keeps every increment made before the refusal: the smaller windows of the refusing policy, every policy listed before it, and all of them when a later guard or the input validation refuses. There is no compensating decrement (it would give up the conditional-ADD atomicity and add a write per refusal). So order stacked policies by which counter you want charged on refusals: `["authPerIp", "codePerEmail"]` still charges the IP when the per-email cap refuses, which is the abuse-resistant direction.
+
+Preflight input slices (guard `apiInput`/`guardInput` values, rate-limit `apiInput` keys) answer a rejection through the same path as the API's own schema: `setApiInputValidationErrorHandler` when set, otherwise the standard 422 body. One failure, one shape, whichever schema rejected it.
 
 **Idempotency semantics**: the client sends an `idempotencyKey` per call (see LambderCaller below); generate it once per logical operation with `LambderCaller.createIdempotencyKey()` and reuse it on retries. Keys must be 16-200 characters and UNGUESSABLE random (shorter keys refuse with 400): on session APIs the scope is session + API name + key, and on public APIs it is the key itself + API name, deliberately NOT the client IP, because the retry idempotency exists for (a timeout followed by a network switch) frequently arrives from a new IP. Concurrent duplicates of an in-flight request refuse with 409, repeats of a completed one replay the stored response verbatim until the TTL (response headers included, so headers set via `res.setHeader`/`res.addHeader` replay too), and a crashed original releases its claim so a retry actually retries. The replay rule for failures: RESPONSES are stored and replayed, refusals returned as envelopes (`res.api(null, { errorMessage })`) and thrown responses (`res.die.*`) included; EXCEPTIONS are not, so a thrown `LambderApiError`/`refuse()` releases the claim and a retry re-executes and decides afresh. Stored bodies of 1KB or more are Brotli-compressed (the same scheme as LambderDdbCache; `compressionQuality` on the store, default 5): JSON envelopes typically shrink 5-10x, which cuts DynamoDB write cost, and the ~350KB item budget applies to the COMPRESSED bytes, so even large responses usually stay replayable. Responses with status ≥ 500, bodies over the budget even compressed, and responses that set cookies are never stored (replaying one request's Set-Cookie, e.g. session tokens, into another would be wrong; such APIs still get in-flight 409 dedupe, just not replays). 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.
 

package/dist/client/LambderCaller.d.ts

@@ -60,6 +60,8 @@ export type LambderApiOutcome<T> = {
     status?: number;
     /** Envelope errorMessage, when the server provided one. */
     errorMessage?: any;
+    /** Seconds to wait before retrying, from the response's Retry-After header (rate-limit refusals send it). */
+    retryAfterSeconds?: number;
     /** Underlying Error for network/timeout/server/unknown failures. */
     error?: Error;
     /** Zod issue detail for 'validation'. */

package/dist/client/LambderCaller.js

@@ -222,6 +222,10 @@ export default class LambderCaller {
                 }
                 return { ok: false, reason: 'validation', status: res.status, zodError };
             }
+            // Retry-After (delta-seconds) rides every refusal that knows its
+            // reset time, e.g. a rate limit; absent or unreadable is undefined.
+            const retryAfterValue = Number(res.headers.get("retry-after") ?? NaN);
+            const retryAfter = Number.isFinite(retryAfterValue) && retryAfterValue >= 0 ? { retryAfterSeconds: retryAfterValue } : {};
             let data;
             try {
                 data = await res.json();
@@ -248,7 +252,7 @@ export default class LambderCaller {
                 else {
                     await reportError(new Error("Version Expired; Please refresh;"));
                 }
-                return { ok: false, reason: 'versionExpired', status: res.status, errorMessage: data.errorMessage, response: data };
+                return { ok: false, reason: 'versionExpired', status: res.status, errorMessage: data.errorMessage, response: data, ...retryAfter };
             }
             if (data.sessionExpired) {
                 this.clearSessionCookies();
@@ -258,7 +262,7 @@ export default class LambderCaller {
                 else {
                     await reportError(new Error("Session Expired; Please log in again;"));
                 }
-                return { ok: false, reason: 'sessionExpired', status: res.status, errorMessage: data.errorMessage, response: data };
+                return { ok: false, reason: 'sessionExpired', status: res.status, errorMessage: data.errorMessage, response: data, ...retryAfter };
             }
             if (data.notAuthorized) {
                 if (notAuthorizedHandler) {
@@ -267,7 +271,7 @@ export default class LambderCaller {
                 else {
                     await reportError(new Error("Not Authorized;"));
                 }
-                return { ok: false, reason: 'notAuthorized', status: res.status, errorMessage: data.errorMessage, response: data };
+                return { ok: false, reason: 'notAuthorized', status: res.status, errorMessage: data.errorMessage, response: data, ...retryAfter };
             }
             if (data.message && messageHandler) {
                 await messageHandler(data.message);
@@ -276,7 +280,7 @@ export default class LambderCaller {
                 if (errorMessageHandler) {
                     await errorMessageHandler(data.errorMessage);
                 }
-                return { ok: false, reason: 'errorMessage', status: res.status, errorMessage: data.errorMessage, response: data };
+                return { ok: false, reason: 'errorMessage', status: res.status, errorMessage: data.errorMessage, response: data, ...retryAfter };
             }
             return { ok: true, payload: data.payload, response: data };
         }

package/dist/client.d.ts

@@ -8,8 +8,8 @@
  */
 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 { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
+export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/LambderApiError.js";
 export type { ApiContractShape, LambderApiResponse, LambderApiResponseConfig } from "./shared/LambderApiContract.js";
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";

package/dist/client.js

@@ -10,7 +10,7 @@
 export { default as LambderCaller } from "./client/LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;
 // in the browser they are plain Errors).
-export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
 // Type-safe templating (tagged templates with auto-escaping)
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
 // Typed translations (standalone, isomorphic)

package/dist/core/Lambder.d.ts

@@ -9,7 +9,7 @@ import { type LambderSessionDataRefreshConfig } from "../session/LambderSessionM
 import LambderSessionController, { type LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
 import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../policies/LambderApiGuards.js";
-import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames } from "../policies/LambderApiRateLimits.js";
+import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderRateLimitOption } from "../policies/LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "../policies/LambderApiIdempotency.js";
 import type { MergeContract } from "../shared/LambderApiContract.js";
 import { type LambderHttpEvent, type LambderRenderContext, type LambderSessionRenderContext } from "./LambderContext.js";
@@ -205,6 +205,13 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     /** Apply the serveIndexHtml gates; null means fall through. */
     private tryServeIndexHtml;
     private getOrCreatePolicyEngine;
+    /**
+     * The response for a rejected input: the app's
+     * setApiInputValidationErrorHandler when set, otherwise the standard 422
+     * body. The API's own schema and every preflight slice (guard inputs,
+     * rate-limit keys) answer through here, so one failure has one shape.
+     */
+    private inputValidationRefusal;
     /** 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;
@@ -212,11 +219,11 @@ 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 LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, false> | readonly LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, false>[] = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, false> = never>(name: TName, schema: {
+    addApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, false> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, false> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
-        /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
+        /** Named rate limits, checked in declared order before guards and validation: a name, a list of names, or a { name: true | override } map (windows overridable on perApi budgets, errorMessage on any). The first exceeded one refuses (429 envelope + Retry-After); attempts count on every counter checked before it. */
         rateLimit?: TRateOpt;
         /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
         guards?: TGuardsOpt;
@@ -225,11 +232,11 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
             ttlSeconds?: number;
         }) : never;
     }, handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, 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 LambderGuardsOption<_TGuards, z.infer<TInput>, true> = never>(name: TName, schema: {
+    addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, true> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
-        /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
+        /** Named rate limits, checked in declared order before guards and validation: a name, a list of names, or a { name: true | override } map (windows overridable on perApi budgets, errorMessage on any). The first exceeded one refuses (429 envelope + Retry-After); attempts count on every counter checked before it. */
         rateLimit?: TRateOpt;
         /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
         guards?: TGuardsOpt;

package/dist/core/Lambder.js

@@ -6,7 +6,7 @@ import { applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
 import LambderSessionController from "../session/LambderSessionController.js";
 import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
-import { isLambderApiError } from "../shared/LambderApiError.js";
+import { isLambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.js";
 /**
@@ -173,10 +173,23 @@ export default class Lambder {
         return response;
     }
     getOrCreatePolicyEngine() {
+        // Late-bound: the handler may be set after creation, so the engine
+        // asks at request time rather than capturing it here.
         if (!this.apiPolicyEngine)
-            this.apiPolicyEngine = new LambderApiPolicyEngine();
+            this.apiPolicyEngine = new LambderApiPolicyEngine((ctx, resolver, zodError) => this.inputValidationRefusal(ctx, resolver, zodError));
         return this.apiPolicyEngine;
     }
+    /**
+     * The response for a rejected input: the app's
+     * setApiInputValidationErrorHandler when set, otherwise the standard 422
+     * body. The API's own schema and every preflight slice (guard inputs,
+     * rate-limit keys) answer through here, so one failure has one shape.
+     */
+    async inputValidationRefusal(ctx, resolver, zodError) {
+        if (this.apiInputValidationErrorHandler)
+            return await this.apiInputValidationErrorHandler(ctx, resolver, zodError);
+        return resolver.json({ error: "Input validation failed", zodError }, { statusCode: 422 });
+    }
     /** Registration-time checks shared by addApi/addSessionApi. */
     assertApiRegistration(name, mode, options) {
         if (this.registeredApiNames.has(name)) {
@@ -233,12 +246,8 @@ export default class Lambder {
                 if (this.apiPolicyEngine)
                     await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);
-                if (!inputResult.success) {
-                    if (this.apiInputValidationErrorHandler) {
-                        return await this.apiInputValidationErrorHandler(ctx, resolver, inputResult.error);
-                    }
-                    return resolver.json({ error: "Input validation failed", zodError: inputResult.error }, { statusCode: 422 });
-                }
+                if (!inputResult.success)
+                    return await this.inputValidationRefusal(ctx, resolver, inputResult.error);
                 ctx.apiPayload = inputResult.data;
                 const run = async () => await handler(ctx, resolver);
                 if (this.apiPolicyEngine && schema.idempotency)
@@ -265,12 +274,8 @@ export default class Lambder {
                 if (this.apiPolicyEngine)
                     await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);
-                if (!inputResult.success) {
-                    if (this.apiInputValidationErrorHandler) {
-                        return await this.apiInputValidationErrorHandler(ctx, resolver, inputResult.error);
-                    }
-                    return resolver.json({ error: "Input validation failed", zodError: inputResult.error }, { statusCode: 422 });
-                }
+                if (!inputResult.success)
+                    return await this.inputValidationRefusal(ctx, resolver, inputResult.error);
                 ctx.apiPayload = inputResult.data;
                 const run = async () => await handler(ctx, resolver);
                 if (this.apiPolicyEngine && schema.idempotency)
@@ -341,7 +346,10 @@ export default class Lambder {
             ...(err.errorMessage !== undefined ? { errorMessage: err.errorMessage } : {}),
             ...(err.notAuthorized ? { notAuthorized: true } : {}),
             ...(err.sessionExpired ? { sessionExpired: true } : {}),
-        }, err.statusCode !== undefined ? { statusCode: err.statusCode } : undefined);
+        }, {
+            ...(err.statusCode !== undefined ? { statusCode: err.statusCode } : {}),
+            ...(err.headers ? { headers: err.headers } : {}),
+        });
     }
     getHandler() {
         return ((event, context) => Lambder.isHttpEvent(event)
@@ -415,7 +423,7 @@ export default class Lambder {
         if (isAPI) {
             if (this.apiFallbackHandler)
                 return await this.apiFallbackHandler(ctx, resolver);
-            return resolver.api(null, { errorMessage: "API not found." });
+            return resolver.api(null, { errorMessage: { type: "warning", code: LAMBDER_REFUSAL_CODES.apiNotFound, content: "API not found." } });
         }
         if (this.publicFilesHandler) {
             const fileResponse = await this.publicFilesHandler.handle(ctx);

package/dist/core/LambderCors.d.ts

@@ -6,6 +6,12 @@ export type LambderCorsConfig = {
     credentials?: boolean;
     methods?: string[];
     allowHeaders?: string[];
+    /**
+     * Response headers a cross-origin browser caller may read. Default:
+     * ["Retry-After"], so rate-limit refusals stay readable (it is not on the
+     * CORS safelist, and a hidden header reads as null, not as an error).
+     */
+    exposeHeaders?: string[];
     maxAge?: number;
 };
 /** Mutate the response with the CORS headers the config allows for this request. */

package/dist/core/LambderCors.js

@@ -27,4 +27,9 @@ export const applyCorsHeaders = (config, ctx, response, isPreflight) => {
         if (config.maxAge !== undefined)
             response.setHeader("Access-Control-Max-Age", String(config.maxAge));
     }
+    else {
+        const exposeHeaders = config.exposeHeaders ?? ["Retry-After"];
+        if (exposeHeaders.length)
+            response.setHeader("Access-Control-Expose-Headers", exposeHeaders.join(", "));
+    }
 };

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export default Lambder;
 export { initLambder } from './core/Lambder.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 { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
+export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefusalCode, 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";
@@ -23,13 +23,13 @@ export { LambderSessionDataRefreshError, LambderSessionReadError } from "./sessi
 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 type { LambderDdbRateLimiterOptions, LambderRateLimitWindow, LambderRateLimitPolicy, LambderRateLimitExceeded, 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 { LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderRateLimitOverride, LambderRateLimitOption, LambderRateLimitOptionValue, } 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";

package/dist/index.js

@@ -3,7 +3,7 @@ export default Lambder;
 export { initLambder } from './core/Lambder.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 "./shared/LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } 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";

package/dist/policies/LambderApiGuards.d.ts

@@ -1,6 +1,7 @@
 import type { z } from "zod";
 import type { LambderRenderContext, LambderSessionRenderContext } from "../core/LambderContext.js";
 import type LambderResolver from "../core/LambderResolver.js";
+import type { LambderResponse } from "../core/LambderResponse.js";
 /**
  * A named guard, run before the API's own input validation. Three input
  * modes:
@@ -30,9 +31,10 @@ import type LambderResolver from "../core/LambderResolver.js";
  *   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.
+ * A validation failure answers like the API's own input validation (the
+ * app's setApiInputValidationErrorHandler when set, else the standard 422),
+ * 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;
@@ -198,20 +200,29 @@ type GuardInputsEntries<TGuards, TOpt> = {
 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>>;
+/**
+ * How a rejected input answers. Lambder binds this to its own decision
+ * (setApiInputValidationErrorHandler when set, else the standard 422 body),
+ * so the API's schema and every preflight slice refuse with one shape.
+ */
+export type LambderInputValidationRefusal = (ctx: LambderRenderContext, resolver: LambderResolver, zodError: z.ZodError) => Promise<LambderResponse>;
 /**
  * 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.
+ * own validation; a failure throws the response `onInvalid` decides, the
+ * same one regular input validation answers. Shared with the rate-limit
+ * engine's apiInput-keyed policies.
  */
-export declare const parsePreflightSlice: (input: z.ZodTypeAny, value: unknown, resolver: LambderResolver) => unknown;
+export declare const parsePreflightSlice: (input: z.ZodTypeAny, value: unknown, ctx: LambderRenderContext, resolver: LambderResolver, onInvalid: LambderInputValidationRefusal) => Promise<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 readonly onInvalidInput;
     private guards;
+    constructor(onInvalidInput: LambderInputValidationRefusal);
     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;

package/dist/policies/LambderApiGuards.js

@@ -14,14 +14,14 @@ const toGuardEntries = (value) => {
 /**
  * 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.
+ * own validation; a failure throws the response `onInvalid` decides, the
+ * same one regular input validation answers. Shared with the rate-limit
+ * engine's apiInput-keyed policies.
  */
-export const parsePreflightSlice = (input, value, resolver) => {
+export const parsePreflightSlice = async (input, value, ctx, resolver, onInvalid) => {
     const parsed = input.safeParse(value);
-    if (!parsed.success) {
-        throw resolver.json({ error: "Input validation failed", zodError: parsed.error }, { statusCode: 422 });
-    }
+    if (!parsed.success)
+        throw await onInvalid(ctx, resolver, parsed.error);
     return parsed.data;
 };
 /**
@@ -30,7 +30,11 @@ export const parsePreflightSlice = (input, value, resolver) => {
  * guards during preflight. Composed into LambderApiPolicyEngine.
  */
 export class LambderApiGuardsEngine {
+    onInvalidInput;
     guards = {};
+    constructor(onInvalidInput) {
+        this.onInvalidInput = onInvalidInput;
+    }
     addGuards(guards) {
         for (const [name, guardDef] of Object.entries(guards)) {
             if (this.guards[name])
@@ -63,10 +67,10 @@ export class LambderApiGuardsEngine {
             const post = ctx.post;
             let payload;
             if (guardDef.apiInput) {
-                payload = parsePreflightSlice(guardDef.apiInput, post?.payload, resolver);
+                payload = await parsePreflightSlice(guardDef.apiInput, post?.payload, ctx, resolver, this.onInvalidInput);
             }
             else if (guardDef.guardInput) {
-                payload = parsePreflightSlice(guardDef.guardInput, post?.guardInputs?.[name], resolver);
+                payload = await parsePreflightSlice(guardDef.guardInput, post?.guardInputs?.[name], ctx, resolver, this.onInvalidInput);
             }
             // A guard's return value becomes the handler's typed
             // ctx.guardData[name]; check-only guards return undefined.

package/dist/policies/LambderApiIdempotency.js

@@ -1,4 +1,4 @@
-import { LambderApiError } from "../shared/LambderApiError.js";
+import { LambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { LambderResponse, normalizeHeaders } from "../core/LambderResponse.js";
 /** A crashed original must not block retries forever: pending claims expire on their own. */
 const IDEMPOTENCY_PENDING_TTL_SECONDS = 300;
@@ -37,7 +37,11 @@ export class LambderApiIdempotencyEngine {
         if (rawKey === undefined || rawKey === null)
             return null;
         if (typeof rawKey !== "string" || rawKey.length < IDEMPOTENCY_MIN_KEY_LENGTH || rawKey.length > IDEMPOTENCY_MAX_KEY_LENGTH) {
-            throw new LambderApiError(`Invalid idempotency key: must be a string of ${IDEMPOTENCY_MIN_KEY_LENGTH}-${IDEMPOTENCY_MAX_KEY_LENGTH} characters.`, { statusCode: 400 });
+            const content = `Invalid idempotency key: must be a string of ${IDEMPOTENCY_MIN_KEY_LENGTH}-${IDEMPOTENCY_MAX_KEY_LENGTH} characters.`;
+            throw new LambderApiError(content, {
+                statusCode: 400,
+                errorMessage: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidIdempotencyKey, content },
+            });
         }
         return rawKey;
     }
@@ -112,7 +116,7 @@ export class LambderApiIdempotencyEngine {
         if (begun.state === "pending") {
             throw new LambderApiError(`Duplicate request for "${apiName}": the original is still processing.`, {
                 statusCode: 409,
-                errorMessage: "This request is already being processed.",
+                errorMessage: { type: "warning", code: LAMBDER_REFUSAL_CODES.duplicateInFlight, content: "This request is already being processed." },
             });
         }
         if (begun.state === "done") {

package/dist/policies/LambderApiPolicies.d.ts

@@ -1,12 +1,12 @@
 import type { LambderRenderContext } from "../core/LambderContext.js";
 import type LambderResolver from "../core/LambderResolver.js";
 import type { LambderResponse } from "../core/LambderResponse.js";
-import { type LambderApiGuard, type LambderGuardsOptionValue } from "./LambderApiGuards.js";
-import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
+import { type LambderApiGuard, type LambderGuardsOptionValue, type LambderInputValidationRefusal } from "./LambderApiGuards.js";
+import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderRateLimitOptionValue } from "./LambderApiRateLimits.js";
 import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
 /** The declarative options one API registration may carry. */
 type LambderApiPolicyOptions = {
-    rateLimit?: string | readonly string[];
+    rateLimit?: LambderRateLimitOptionValue;
     guards?: LambderGuardsOptionValue;
     idempotency?: unknown;
 };
@@ -23,6 +23,8 @@ export declare class LambderApiPolicyEngine {
     private rateLimits;
     private guards;
     private idempotency;
+    /** `onInvalidInput` is Lambder's input-validation refusal, so preflight slices answer exactly like the API's own schema. */
+    constructor(onInvalidInput: LambderInputValidationRefusal);
     setRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
     addGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
     setIdempotency(config: LambderApiIdempotencyConfig): void;

package/dist/policies/LambderApiPolicies.js

@@ -11,9 +11,14 @@ import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
  * per-API options.
  */
 export class LambderApiPolicyEngine {
-    rateLimits = new LambderApiRateLimitsEngine();
-    guards = new LambderApiGuardsEngine();
+    rateLimits;
+    guards;
     idempotency = new LambderApiIdempotencyEngine();
+    /** `onInvalidInput` is Lambder's input-validation refusal, so preflight slices answer exactly like the API's own schema. */
+    constructor(onInvalidInput) {
+        this.rateLimits = new LambderApiRateLimitsEngine(onInvalidInput);
+        this.guards = new LambderApiGuardsEngine(onInvalidInput);
+    }
     setRateLimits(config) {
         this.rateLimits.configure(config);
     }

package/dist/policies/LambderApiRateLimits.d.ts

@@ -1,15 +1,18 @@
 import type { z } from "zod";
 import type { LambderRenderContext } from "../core/LambderContext.js";
 import type LambderResolver from "../core/LambderResolver.js";
-import type { LambderRateLimitPolicy, LambderDdbRateLimiter } from "../stores/LambderDdbRateLimiter.js";
+import { type LambderRateLimitPolicy, type LambderDdbRateLimiter } from "../stores/LambderDdbRateLimiter.js";
+import { type LambderRefusalMessage } from "../shared/LambderApiError.js";
+import { type LambderInputValidationRefusal } from "./LambderApiGuards.js";
 /**
  * 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`.
+ * payload before `handler` runs (failures answer like regular input
+ * validation, through setApiInputValidationErrorHandler when set) 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> = {
     apiInput: TInput;
@@ -38,19 +41,26 @@ export declare function lambderRateLimitKey(key: {
 };
 /** What one rate-limit counter tracks: the client IP, the session identity, or a custom payload-derived key. */
 export type LambderRateLimitPer = "ip" | "session" | LambderRateLimitKeyFn<any>;
-/** A named rate-limit policy: fixed windows plus the key one counter tracks. */
+/**
+ * What one budget spans:
+ *
+ * - "perApi" (default): every API referencing the policy gets its own
+ *   counter, so the windows are a per-API ceiling (three APIs referencing a
+ *   60/min policy allow one subject 180/min in total). An API may tune the
+ *   windows in its declaration: `rateLimit: { name: { perMin: 20 } }`.
+ * - "perPolicy": every API referencing the policy shares ONE counter, so the
+ *   windows are one combined budget (e.g. one per-email allowance across
+ *   send, register, and reset). The policy IS the group: to give user APIs
+ *   and report APIs separate shared budgets, declare two policies.
+ */
+export type LambderRateLimitBudget = "perApi" | "perPolicy";
+/** A named rate-limit policy: fixed windows, the key one counter tracks, and what one budget spans. */
 export type LambderApiRateLimitPolicyConfig = LambderRateLimitPolicy & {
     per: LambderRateLimitPer;
-    /**
-     * What one counter spans. "api" (default): each API referencing the
-     * policy gets its own counter, so the windows are a per-API budget.
-     * "policy": every API referencing the policy shares one counter, so the
-     * windows are one combined budget (e.g. one per-email allowance across
-     * send, register, and reset endpoints).
-     */
-    scope?: "api" | "policy";
-    /** Envelope errorMessage for refused requests. Default: a generic too-many-requests message. */
-    errorMessage?: any;
+    /** Whether the windows are a per-API ceiling (default) or one budget shared by every referencing API. See LambderRateLimitBudget. */
+    budget?: LambderRateLimitBudget;
+    /** Envelope errorMessage for refused requests; inherits code "lambder/rate-limited" unless it sets its own. Default: a warning saying too many requests. */
+    errorMessage?: LambderRefusalMessage;
 };
 export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>> = {
     /** Your limiter instance; its table, keyPrefix and failOpen apply as configured on it. */
@@ -72,6 +82,29 @@ export type LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession exten
         };
     } ? (TPayload extends z.output<S> ? K : never) : K;
 }[keyof TPolicies] & string;
+/**
+ * What an API may override on a policy it references, in the map form of the
+ * rateLimit option. Windows merge over the policy's own (a tighter burst keeps
+ * the policy's daily cap) and are only overridable on "perApi" budgets: a
+ * shared counter has one set of numbers. errorMessage is per-API text, so it
+ * is overridable on either budget.
+ */
+export type LambderRateLimitOverride = LambderRateLimitPolicy & {
+    errorMessage?: LambderRefusalMessage;
+};
+type LambderRateLimitOverrideFor<TPolicy> = TPolicy extends {
+    budget: "perPolicy";
+} ? Pick<LambderRateLimitOverride, "errorMessage"> : LambderRateLimitOverride;
+/**
+ * The per-API `rateLimit` option: one policy name, an ordered list of names,
+ * or an object map that can carry each policy's override (`true` applies the
+ * policy as declared). Map entries are checked in insertion order.
+ */
+export type LambderRateLimitOption<TPolicies, TPayload, TIncludeSession extends boolean> = LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession> | readonly LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession>[] | {
+    readonly [K in LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession> & keyof TPolicies]?: true | LambderRateLimitOverrideFor<TPolicies[K]>;
+};
+/** The rateLimit option's runtime shape: a name, ordered names, or a name-to-override map (LambderRateLimitOption narrows the names and overrides per policy). */
+export type LambderRateLimitOptionValue = string | readonly string[] | Readonly<Record<string, true | LambderRateLimitOverride | undefined>>;
 /**
  * Runtime side of the rate-limit subsystem: holds the limiter and its named
  * policies, asserts API registrations against them at startup, and checks an
@@ -79,12 +112,21 @@ export type LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession exten
  * LambderApiPolicyEngine.
  */
 export declare class LambderApiRateLimitsEngine {
+    private readonly onInvalidInput;
     private limiter;
     private policies;
+    constructor(onInvalidInput: LambderInputValidationRefusal);
     configure(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
     /** Startup validation of one API registration's rateLimit option. */
-    assertRegistration(apiName: string, mode: "public" | "session", rateLimitOption?: string | readonly string[]): void;
-    /** Check the API's policies in declared order; the first exceeded one refuses with a 429 envelope. */
-    run(apiName: string, ctx: LambderRenderContext, resolver: LambderResolver, rateLimitOption?: string | readonly string[]): Promise<void>;
+    assertRegistration(apiName: string, mode: "public" | "session", rateLimitOption?: LambderRateLimitOptionValue): void;
+    /**
+     * Check the API's policies in declared order; the first exceeded one
+     * refuses with a 429 envelope and a Retry-After header. Attempts count,
+     * not successes: every counter checked before the refusing one (and every
+     * counter, when a later guard or validation refuses) keeps its increment,
+     * so list first the policy you want charged on refusals.
+     */
+    run(apiName: string, ctx: LambderRenderContext, resolver: LambderResolver, rateLimitOption?: LambderRateLimitOptionValue): Promise<void>;
     private resolveKey;
 }
+export {};

package/dist/policies/LambderApiRateLimits.js

@@ -1,8 +1,21 @@
-import { LambderApiError } from "../shared/LambderApiError.js";
+import { RATE_LIMIT_WINDOWS } from "../stores/LambderDdbRateLimiter.js";
+import { LambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { parsePreflightSlice } from "./LambderApiGuards.js";
-const RATE_LIMIT_WINDOW_KEYS = ["perMin", "per10Min", "perHour", "perDay", "perWeek", "perMonth"];
+const RATE_LIMIT_WINDOW_KEYS = RATE_LIMIT_WINDOWS.map((window) => window.key);
+/** Refusal a rate-limited request answers unless the policy or the API's override names its own. */
+const DEFAULT_RATE_LIMIT_REFUSAL = { type: "warning", code: LAMBDER_REFUSAL_CODES.rateLimited, content: "Too many requests. Please try again later." };
 export function lambderRateLimitKey(key) { return key; }
-const toList = (value) => value === undefined ? [] : typeof value === "string" ? [value] : value;
+/** Normalize the three rateLimit-option forms into ordered entries; an explicit `undefined` map value declares nothing. */
+const toRateLimitEntries = (value) => {
+    if (value === undefined)
+        return [];
+    if (typeof value === "string")
+        return [{ name: value }];
+    if (Array.isArray(value))
+        return value.map((name) => ({ name }));
+    return Object.entries(value).flatMap(([name, override]) => override === undefined ? [] : override === true ? [{ name }] : [{ name, override }]);
+};
+const hasWindowOverride = (override) => RATE_LIMIT_WINDOW_KEYS.some((key) => override[key] !== undefined);
 /**
  * Runtime side of the rate-limit subsystem: holds the limiter and its named
  * policies, asserts API registrations against them at startup, and checks an
@@ -10,8 +23,12 @@ const toList = (value) => value === undefined ? [] : typeof value === "string" ?
  * LambderApiPolicyEngine.
  */
 export class LambderApiRateLimitsEngine {
+    onInvalidInput;
     limiter = null;
     policies = {};
+    constructor(onInvalidInput) {
+        this.onInvalidInput = onInvalidInput;
+    }
     configure(config) {
         if (this.limiter)
             throw new Error("Lambder: rateLimits were already configured.");
@@ -23,13 +40,17 @@ export class LambderApiRateLimitsEngine {
             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("/")}).`);
             }
+            const budget = policy.budget;
+            if (budget !== undefined && budget !== "perApi" && budget !== "perPolicy") {
+                throw new Error(`Lambder: rate-limit policy "${name}" has budget "${String(budget)}"; use "perApi" (default: each referencing API counts separately) or "perPolicy" (one counter shared by every referencing API).`);
+            }
         }
         this.limiter = config.limiter;
         this.policies = { ...config.policies };
     }
     /** Startup validation of one API registration's rateLimit option. */
     assertRegistration(apiName, mode, rateLimitOption) {
-        for (const name of toList(rateLimitOption)) {
+        for (const { name, override } of toRateLimitEntries(rateLimitOption)) {
             const policy = this.policies[name];
             if (!policy) {
                 throw new Error(`Lambder: API "${apiName}" references unknown rate-limit policy "${name}". Declare it in the rateLimits option at creation.`);
@@ -37,25 +58,46 @@ export class LambderApiRateLimitsEngine {
             if (policy.per === "session" && mode !== "session") {
                 throw new Error(`Lambder: API "${apiName}" uses rate-limit policy "${name}" (per "session"), which requires addSessionApi.`);
             }
+            if (override && policy.budget === "perPolicy" && hasWindowOverride(override)) {
+                throw new Error(`Lambder: API "${apiName}" overrides the windows of rate-limit policy "${name}", whose budget is "perPolicy": one counter shared by every referencing API has one set of limits. Declare a separate policy instead.`);
+            }
         }
     }
-    /** Check the API's policies in declared order; the first exceeded one refuses with a 429 envelope. */
+    /**
+     * Check the API's policies in declared order; the first exceeded one
+     * refuses with a 429 envelope and a Retry-After header. Attempts count,
+     * not successes: every counter checked before the refusing one (and every
+     * counter, when a later guard or validation refuses) keeps its increment,
+     * so list first the policy you want charged on refusals.
+     */
     async run(apiName, ctx, resolver, rateLimitOption) {
-        for (const name of toList(rateLimitOption)) {
+        for (const { name, override } of toRateLimitEntries(rateLimitOption)) {
             const policy = this.policies[name];
             if (!policy || !this.limiter)
                 throw new Error(`Lambder: rate-limit policy "${name}" is not configured.`);
             const key = await this.resolveKey(ctx, resolver, policy.per);
-            // scope "policy" shares one counter across every API referencing
-            // the policy; the default gives each API its own budget.
-            const trackerKey = policy.scope === "policy"
+            // "perPolicy" shares one counter across every API referencing the
+            // policy; "perApi" keys each API separately, which is also what
+            // lets an API override the windows without colliding.
+            const trackerKey = policy.budget === "perPolicy"
                 ? `policy|${name}|${key}`
                 : `api|${apiName}|${name}|${key}`;
-            const limited = await this.limiter.isRateLimited(trackerKey, policy);
-            if (limited) {
-                throw new LambderApiError(`Rate limited: "${apiName}" exceeded policy "${name}".`, {
-                    errorMessage: policy.errorMessage ?? "Too many requests. Please try again later.",
+            const limits = {};
+            for (const windowKey of RATE_LIMIT_WINDOW_KEYS) {
+                const limit = override?.[windowKey] ?? policy[windowKey];
+                if (limit !== undefined)
+                    limits[windowKey] = limit;
+            }
+            const exceeded = await this.limiter.isRateLimited(trackerKey, limits);
+            if (exceeded) {
+                const retryAfterSeconds = Math.max(1, exceeded.resetAt - Math.floor(Date.now() / 1000));
+                // A policy's (or override's) own message inherits the framework
+                // code unless it sets a more specific one of its own.
+                const message = override?.errorMessage ?? policy.errorMessage;
+                throw new LambderApiError(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, {
+                    errorMessage: message ? { code: LAMBDER_REFUSAL_CODES.rateLimited, ...message } : DEFAULT_RATE_LIMIT_REFUSAL,
                     statusCode: 429,
+                    headers: { "Retry-After": String(retryAfterSeconds) },
                 });
             }
         }
@@ -70,7 +112,7 @@ export class LambderApiRateLimitsEngine {
             return `session:${sessionKey}`;
         }
         const payload = per.apiInput
-            ? parsePreflightSlice(per.apiInput, ctx.post?.payload, resolver)
+            ? await parsePreflightSlice(per.apiInput, ctx.post?.payload, ctx, resolver, this.onInvalidInput)
             : undefined;
         return `custom:${await per.handler(ctx, payload)}`;
     }

package/dist/shared/LambderApiError.d.ts

@@ -18,6 +18,8 @@ export type LambderApiErrorOptions = {
      * 422 (reserved for input validation).
      */
     statusCode?: HttpStatusCode;
+    /** Extra response headers on the refusal (e.g. Retry-After on a rate limit). */
+    headers?: Record<string, string>;
     /** Underlying cause, preserved on the standard Error `cause` property. */
     cause?: unknown;
 };
@@ -48,23 +50,50 @@ export declare class LambderApiError extends Error {
     readonly notAuthorized?: boolean;
     readonly sessionExpired?: boolean;
     readonly statusCode?: HttpStatusCode;
+    readonly headers?: Record<string, string>;
     constructor(message: string, options?: LambderApiErrorOptions);
 }
 /** Brand-based type guard (see LambderApiError.isLambderApiError). */
 export declare const isLambderApiError: (err: unknown) => err is LambderApiError;
 /**
  * The standard shape refusals carry on the envelope's errorMessage field.
- * The caller's errorMessageHandler receives it as-is; apps with their own
- * errorMessage vocabulary can keep using LambderApiError directly instead.
+ * `code` is the refusal's machine-readable identity: clients branch and
+ * translate on it and never string-match `content`, which stays the
+ * human-readable fallback for codes a client does not know yet. Apps keep
+ * their own typed code vocabulary; the framework's own refusals carry a
+ * LambderRefusalCode. The caller's errorMessageHandler receives the object
+ * as-is; apps with their own errorMessage vocabulary can keep using
+ * LambderApiError directly instead.
  */
 export type LambderRefusalMessage = {
     type: "warning" | "error" | "info";
+    /** Machine-readable identity of the refusal (the app's own vocabulary, or a LambderRefusalCode). */
+    code?: string;
     title?: string;
     content: string;
 };
+/**
+ * Codes the framework stamps on the refusals it authors itself, under the
+ * reserved `lambder/` prefix so app codes never collide. Compare against
+ * these constants on the client (exported from `lambder/client` too) rather
+ * than retyping the strings.
+ */
+export declare const LAMBDER_REFUSAL_CODES: {
+    /** A rate-limit policy refused (429). A policy's own errorMessage inherits this unless it sets a code. */
+    readonly rateLimited: "lambder/rate-limited";
+    /** The original of an idempotent request is still processing (409). */
+    readonly duplicateInFlight: "lambder/duplicate-in-flight";
+    /** The idempotencyKey is malformed (400). */
+    readonly invalidIdempotencyKey: "lambder/invalid-idempotency-key";
+    /** No API is registered under the requested name. */
+    readonly apiNotFound: "lambder/api-not-found";
+};
+export type LambderRefusalCode = (typeof LAMBDER_REFUSAL_CODES)[keyof typeof LAMBDER_REFUSAL_CODES];
 export type LambderRefuseOptions = {
     /** Rendering intent for the client's errorMessageHandler. Default: "warning". */
     type?: LambderRefusalMessage["type"];
+    /** Machine-readable identity of the refusal, for clients to branch and translate on. */
+    code?: string;
     /** Optional heading shown above the content. */
     title?: string;
     /** Sets the envelope's notAuthorized flag (routed to the caller's notAuthorizedHandler). */
@@ -73,6 +102,8 @@ export type LambderRefuseOptions = {
     sessionExpired?: boolean;
     /** HTTP status of the refusal. Default 200; avoid 5xx (caller treats as crash) and 422 (reserved for validation). */
     statusCode?: HttpStatusCode;
+    /** Extra response headers on the refusal (e.g. Retry-After). */
+    headers?: Record<string, string>;
     /** Underlying cause, preserved on the Error cause property. */
     cause?: unknown;
 };

package/dist/shared/LambderApiError.js

@@ -25,6 +25,7 @@ export class LambderApiError extends Error {
     notAuthorized;
     sessionExpired;
     statusCode;
+    headers;
     constructor(message, options = {}) {
         super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
         this.name = "LambderApiError";
@@ -32,10 +33,27 @@ export class LambderApiError extends Error {
         this.notAuthorized = options.notAuthorized;
         this.sessionExpired = options.sessionExpired;
         this.statusCode = options.statusCode;
+        this.headers = options.headers;
     }
 }
 /** Brand-based type guard (see LambderApiError.isLambderApiError). */
 export const isLambderApiError = (err) => err instanceof Error && err.isLambderApiError === true;
+/**
+ * Codes the framework stamps on the refusals it authors itself, under the
+ * reserved `lambder/` prefix so app codes never collide. Compare against
+ * these constants on the client (exported from `lambder/client` too) rather
+ * than retyping the strings.
+ */
+export const LAMBDER_REFUSAL_CODES = {
+    /** A rate-limit policy refused (429). A policy's own errorMessage inherits this unless it sets a code. */
+    rateLimited: "lambder/rate-limited",
+    /** The original of an idempotent request is still processing (409). */
+    duplicateInFlight: "lambder/duplicate-in-flight",
+    /** The idempotencyKey is malformed (400). */
+    invalidIdempotencyKey: "lambder/invalid-idempotency-key",
+    /** No API is registered under the requested name. */
+    apiNotFound: "lambder/api-not-found",
+};
 /**
  * Refuse the current API call: a routine business "no" (not found, invalid
  * input, not allowed) with a user-facing message. Throws a LambderApiError
@@ -52,12 +70,14 @@ export const refuse = (content, options = {}) => {
     throw new LambderApiError(content, {
         errorMessage: {
             type: options.type ?? "warning",
+            ...(options.code !== undefined ? { code: options.code } : {}),
             ...(options.title !== undefined ? { title: options.title } : {}),
             content,
         },
         notAuthorized: options.notAuthorized,
         sessionExpired: options.sessionExpired,
         statusCode: options.statusCode,
+        headers: options.headers,
         cause: options.cause,
     });
 };

package/dist/stores/LambderDdbRateLimiter.d.ts

@@ -1,15 +1,42 @@
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-export interface LambderRateLimitPolicy {
-    perMin?: number;
-    per10Min?: number;
-    perHour?: number;
-    perDay?: number;
-    perWeek?: number;
-    perMonth?: number;
-}
-export type LambderRateLimitExceededMap = Partial<Record<keyof LambderRateLimitPolicy, number>>;
-/** `false` when allowed, otherwise the window(s) whose limit was hit. */
-export type LambderRateLimitResult = false | LambderRateLimitExceededMap;
+/**
+ * The fixed windows a policy may cap, smallest first (the evaluation order),
+ * with their length. The policy type derives from this table, so the two can
+ * never drift.
+ */
+export declare const RATE_LIMIT_WINDOWS: readonly [{
+    readonly key: "perMin";
+    readonly seconds: 60;
+}, {
+    readonly key: "per10Min";
+    readonly seconds: number;
+}, {
+    readonly key: "perHour";
+    readonly seconds: number;
+}, {
+    readonly key: "perDay";
+    readonly seconds: number;
+}, {
+    readonly key: "perWeek";
+    readonly seconds: number;
+}, {
+    readonly key: "perMonth";
+    readonly seconds: number;
+}];
+export type LambderRateLimitWindow = (typeof RATE_LIMIT_WINDOWS)[number]["key"];
+/** Per-window caps. A window that is absent or 0 is not enforced. */
+export type LambderRateLimitPolicy = Partial<Record<LambderRateLimitWindow, number>>;
+/**
+ * The window that refused: which one, its limit, and the epoch second at
+ * which that fixed window resets (Retry-After derives from it).
+ */
+export type LambderRateLimitExceeded = {
+    window: LambderRateLimitWindow;
+    limit: number;
+    resetAt: number;
+};
+/** `false` when allowed, otherwise the window whose limit was hit. */
+export type LambderRateLimitResult = false | LambderRateLimitExceeded;
 export interface LambderDdbRateLimiterOptions {
     tableName: string;
     region?: string;
@@ -27,8 +54,11 @@ export interface LambderDdbRateLimiterOptions {
  * Each window is a single item counted with a conditional `ADD`, so the
  * increment and the limit check happen atomically in one request. Windows are
  * evaluated from smallest to largest and evaluation stops at the first
- * exceeded window, which keeps blocked requests cheap and avoids inflating the
- * larger counters. Items carry an `expiresAt` attribute for DynamoDB TTL.
+ * exceeded window, which keeps blocked requests cheap and spares the larger
+ * counters. Attempts count, not successes: a counter checked before the
+ * refusing one keeps its increment (there is no compensating decrement, which
+ * would give up the conditional-ADD atomicity). Items carry an `expiresAt`
+ * attribute for DynamoDB TTL.
  *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on `expiresAt`.
  * Items are prefixed `RL#` by default, so the table can be shared with
@@ -44,7 +74,8 @@ export declare class LambderDdbRateLimiter {
     constructor(options: LambderDdbRateLimiterOptions);
     /**
      * Increment every configured window for `trackerKey` (IP, session, user id, ...)
-     * and report whether any of them is over its limit.
+     * and report whether any of them is over its limit, with the window's
+     * reset time when so.
      */
     isRateLimited(trackerKey: string, policy: LambderRateLimitPolicy): Promise<LambderRateLimitResult>;
     /** Increments one window counter. Returns true when the limit was already reached. */

package/dist/stores/LambderDdbRateLimiter.js

@@ -1,5 +1,10 @@
 import { DynamoDBClient, UpdateItemCommand, } from "@aws-sdk/client-dynamodb";
-const WINDOW_CONFIG = [
+/**
+ * The fixed windows a policy may cap, smallest first (the evaluation order),
+ * with their length. The policy type derives from this table, so the two can
+ * never drift.
+ */
+export const RATE_LIMIT_WINDOWS = [
     { key: "perMin", seconds: 60 },
     { key: "per10Min", seconds: 10 * 60 },
     { key: "perHour", seconds: 60 * 60 },
@@ -13,8 +18,11 @@ const WINDOW_CONFIG = [
  * Each window is a single item counted with a conditional `ADD`, so the
  * increment and the limit check happen atomically in one request. Windows are
  * evaluated from smallest to largest and evaluation stops at the first
- * exceeded window, which keeps blocked requests cheap and avoids inflating the
- * larger counters. Items carry an `expiresAt` attribute for DynamoDB TTL.
+ * exceeded window, which keeps blocked requests cheap and spares the larger
+ * counters. Attempts count, not successes: a counter checked before the
+ * refusing one keeps its increment (there is no compensating decrement, which
+ * would give up the conditional-ADD atomicity). Items carry an `expiresAt`
+ * attribute for DynamoDB TTL.
  *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on `expiresAt`.
  * Items are prefixed `RL#` by default, so the table can be shared with
@@ -41,23 +49,24 @@ export class LambderDdbRateLimiter {
     }
     /**
      * Increment every configured window for `trackerKey` (IP, session, user id, ...)
-     * and report whether any of them is over its limit.
+     * and report whether any of them is over its limit, with the window's
+     * reset time when so.
      */
     async isRateLimited(trackerKey, policy) {
-        for (const { key, seconds } of WINDOW_CONFIG) {
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        for (const { key, seconds } of RATE_LIMIT_WINDOWS) {
             const limit = policy[key];
             if (!limit)
                 continue;
-            const exceeded = await this.incrementWindow(trackerKey, key, seconds, limit);
+            const windowStart = Math.floor(nowSeconds / seconds) * seconds;
+            const exceeded = await this.incrementWindow(trackerKey, key, windowStart, seconds, limit, nowSeconds);
             if (exceeded)
-                return { [key]: limit };
+                return { window: key, limit, resetAt: windowStart + seconds };
         }
         return false;
     }
     /** Increments one window counter. Returns true when the limit was already reached. */
-    async incrementWindow(trackerKey, sortKeyPrefix, windowSeconds, limit) {
-        const nowSeconds = Math.floor(Date.now() / 1000);
-        const windowStart = Math.floor(nowSeconds / windowSeconds) * windowSeconds;
+    async incrementWindow(trackerKey, sortKeyPrefix, windowStart, windowSeconds, limit, nowSeconds) {
         const expiresAt = nowSeconds + Math.ceil(windowSeconds * this.ttlWindowMultiplier);
         const input = {
             TableName: this.tableName,

package/package.json

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