lambder 4.0.1 → 4.2.1

package/Readme.md

@@ -2,15 +2,23 @@
 
 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 are explicit**: every policy declares `budget: "perApi"` (each referencing API gets its own counter, so the numbers are a per-API ceiling) or `budget: "perPolicy"` (one counter shared by every API referencing the policy). There is no default, so a declaration always says what its numbers span; 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**: every refusal the framework itself authors (rate limit 429, idempotency 409 and 400, unknown API) is a `LambderRefusalMessage` (`{ type, content }`), and a policy's `errorMessage` is typed as one, so an `errorMessageHandler` reading `.content` works everywhere.
+- **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.
-- **Quality of life**: the `LambderApp` alias for annotating api modules, `LambderCaller.createIdempotencyKeyScope()` for one self-rotating key per logical operation, fail-open rate limiting logs its passes.
+- **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.
 
-**Breaking in v4** (from 3.x): session records are reshaped (hashes at rest; live sessions invalidate once on upgrade, clients just re-login) and the manager-level `createSession`/`regenerateSession` return `LambderCreatedSession` (`{ session, sessionToken, csrfToken }`; the controller API is unchanged); `LambderMSW` moved from the root entry to `lambder/testing`; `LambderCaller.apiRaw()` is removed (use `apiOutcome()`, whose failure outcomes carry the envelope on `response`); the `multiValueHeaders` alias on `res.raw()` is removed (use `headers`); `LambderDdbIdempotency.complete()` answers `"stored" | "too-large" | "lost"`; idempotency keys must be 16-200 chars.
+**Breaking in v4** (from 3.x): configuration moved entirely to creation, removing `enableCors`, `enableDdbSession`, `setSessionCookieKey`, `enableApiRateLimits`, `enableApiIdempotency`, and `defineApiGuards` in favor of the `cors`/`session`/`rateLimits`/`guards`/`idempotency` options of `initLambder().create({...})`; session records are reshaped (hashes at rest; live sessions invalidate once on upgrade, clients just re-login) and the manager-level `createSession`/`regenerateSession` return `LambderCreatedSession` (`{ session, sessionToken, csrfToken }`; the controller API is unchanged); `LambderMSW` moved from the root entry to `lambder/testing`; `LambderCaller.apiRaw()` is removed (use `apiOutcome()`, whose failure outcomes carry the envelope on `response`); the `multiValueHeaders` alias on `res.raw()` is removed (use `headers`); `LambderDdbIdempotency.complete()` answers `"stored" | "too-large" | "lost"`; idempotency keys must be 16-200 chars.
 
 v3 (public file serving, `addAction()`, gzip + ETag, thrown responses, `LambderTemplatingEngine`, `html`/`xml` tags, payload v2 support, `LambderDdbCache`, `createLambderI18n`, `LambderApiError`/`refuse()`, `apiOutcome()`, the declarative policy foundations) is documented in the git history.
 
@@ -63,25 +71,32 @@ Source layout mirrors this: `src/core/` (request pipeline), `src/policies/` (dec
 
 ### Basic Setup
 
+The whole configuration is given at creation, in one declaration; only
+registration (routes, apis, hooks, `use()`) chains afterwards. `initLambder`
+is curried so the session data type is fixed first and everything else
+(policy names, guard metadata) is INFERRED from the options; TypeScript type
+arguments are all-or-nothing per call, so a plain `new Lambder<SessionData>({...})`
+would silently widen the inferred policy types, which is why the curried
+creator is the canonical entry.
+
 ```typescript
-import Lambder from 'lambder';
+import { initLambder } from 'lambder';
 import { z } from 'zod';
 import * as path from 'path';
 
-const lambder = new Lambder({
+interface SessionData { userId: string; }
+
+const lambder = initLambder<SessionData>().create({
     apiPath: "/api",
     publicPath: path.resolve(`./public`),
-});
-
-// Enable session and CORS
-lambder
-    .enableDdbSession({
+    session: {
         tableName: "website-session",
         tableRegion: "us-east-1",
-        sessionSalt: "CHANGE-THIS-TO-A-SECURE-RANDOM-STRING"
-    })
+        sessionSalt: "CHANGE-THIS-TO-A-SECURE-RANDOM-STRING",
+    },
     // true allows any origin; or configure: { origins: ["https://app.example.com"], credentials: true }
-    .enableCors(true);
+    cors: true,
+});
 
 // Define type-safe APIs with Zod schemas
 lambder
@@ -277,18 +292,21 @@ lambder
 
 ### Session Management
 
-Enable DynamoDB-based sessions with `enableDdbSession()`. Optional configuration:
+Enable DynamoDB-based sessions with the `session` option at creation:
 
 ```typescript
-lambder
-    .enableDdbSession({
+const lambder = initLambder<SessionData>().create({
+    apiPath: "/api",
+    session: {
         tableName: "website-session",
         tableRegion: "us-east-1",
         sessionSalt: "CHANGE-THIS-TO-A-SECURE-RANDOM-STRING",
-        enableSlidingExpiration: true // Optional: extend session on each access
-    })
-    // Optionally customize session cookie names (defaults: LMDRSESSIONTKID, LMDRSESSIONCSTK)
-    .setSessionCookieKey("MY_SESSION_TOKEN", "MY_CSRF_TOKEN");
+        enableSlidingExpiration: true, // Optional: extend session on each access
+        // Optionally customize cookie names (defaults: LMDRSESSIONTKID, LMDRSESSIONCSTK)
+        tokenCookieKey: "MY_SESSION_TOKEN",
+        csrfCookieKey: "MY_CSRF_TOKEN",
+    },
+});
 ```
 
 #### DynamoDB Session Table Structure
@@ -308,16 +326,18 @@ The session cookie is `pkHash:secret`: `pkHash = sha256(sessionKey + sessionSalt
 Session data often caches values derived from external state: roles, permissions, feature flags. Opt in to `dataRefresh` to give that data a shelf life. Every session read checks it, and once `ttlSeconds` have passed your `refresh` callback rebuilds the data, which is persisted onto the same session record: same tokens, same cookies, the session itself is untouched. Changes to the source of truth then reach every live session within `ttlSeconds`, with no mass session invalidation.
 
 ```typescript
-lambder.enableDdbSession({
-    tableName: "website-session",
-    tableRegion: "us-east-1",
-    sessionSalt: "CHANGE-THIS-TO-A-SECURE-RANDOM-STRING",
-    dataRefresh: {
-        ttlSeconds: 600, // data is renewed at most every 10 minutes
-        refresh: async (session) => {
-            const user = await loadUser(session.data.userId);
-            if (!user || user.disabled) return null; // null ends the session
-            return buildSessionData(user);
+const lambder = initLambder<SessionData>().create({
+    session: {
+        tableName: "website-session",
+        tableRegion: "us-east-1",
+        sessionSalt: "CHANGE-THIS-TO-A-SECURE-RANDOM-STRING",
+        dataRefresh: {
+            ttlSeconds: 600, // data is renewed at most every 10 minutes
+            refresh: async (session) => {
+                const user = await loadUser(session.data.userId);
+                if (!user || user.disabled) return null; // null ends the session
+                return buildSessionData(user);
+            },
         },
     },
 });
@@ -495,22 +515,27 @@ Related: when an API call crashes with no `setGlobalErrorHandler` (or the handle
 Declare named building blocks once; reference them from API definitions with full type inference (unknown names are compile errors, and everything is re-asserted at registration time for plain-JS safety). Each piece is independent and optional.
 
 ```typescript
-import Lambder, { LambderDdbRateLimiter, LambderDdbIdempotency, lambderGuard, lambderRateLimitKey, refuse } from "lambder";
+import { initLambder, LambderDdbRateLimiter, LambderDdbIdempotency, lambderGuard, lambderRateLimitKey, refuse } from "lambder";
 
-const lambder = new Lambder<SessionData>({ apiPath: "/api" })
+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").
-    .enableApiRateLimits({
+    //    declares its windows, what one counter tracks ("per"), and what one
+    //    budget spans ("budget", required so the numbers are never ambiguous):
+    //    "perApi" gives every referencing API its own counter (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: {
-            authPerIp:    { perMin: 5, perHour: 30, per: "ip" },
-            writePerUser: { perMin: 30, per: "session" },   // only referable from addSessionApi (also enforced at compile time)
+            authPerIp:    { perMin: 5, perHour: 30, per: "ip", budget: "perApi" },
+            writePerUser: { perMin: 30, per: "session", budget: "perApi" },   // 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`.
@@ -521,14 +546,14 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
                 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({
+    idempotency: {
         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. Input modes: apiInput checks a slice of the API's own
     //    payload (the schema keeps the field; the guard is declarable only
     //    where the payload type passes both); guardInput is the guard's OWN
@@ -539,7 +564,7 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
     //    (session: true, declarable only on addSessionApi), take a per-API
     //    PARAM (annotate a 4th handler argument), and RETURN a value that
     //    lands typed on the API handler's ctx.guardData[name].
-    .defineApiGuards({
+    guards: {
         captcha: lambderGuard({
             guardInput: z.object({ captchaToken: z.string() }),
             handler: async (ctx, { captchaToken }) => {
@@ -557,7 +582,8 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
             handler: (ctx, _payload, _res, permission: PermissionString) =>
                 requirePermissionOrRefuse(ctx.session, permission),   // return value → ctx.guardData.orgPermission
         }),
-    });
+    },
+});
 
 lambder.addApi("public.resetPassword", {
     // captchaToken is NOT declared here: it travels in the separate
@@ -566,16 +592,20 @@ 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 until enableApiIdempotency()
+    idempotency: true,                          // or { ttlSeconds: 3600 }; type error unless created with idempotency
 }, async (ctx, res) => {
     const { organizationId } = ctx.guardData.orgPermission;  // typed guard output
     // ...
@@ -584,18 +614,32 @@ lambder.addSessionApi("secure.order.create", {
 
 Guard results are typed end to end: the handler's `ctx.guardData` carries exactly the declared guards that return a value, a session guard on a public API is a compile error (and a startup assert), an apiInput guard is declarable only where the API's schema carries its fields, and a parameterized guard's param is typechecked in the declaration.
 
-For api modules split across files, annotate their `lambder` parameter with the `LambderApp` alias instead of hand-writing the instance generics:
+For api modules split across files, DERIVE the annotation type from the real instance instead of writing it by hand: create the instance next to the policy declarations and export `typeof` it. The type can never drift from what actually runs, and modules import it without a cycle (the app file imports no modules):
 
 ```typescript
-export type AppLambder = LambderApp<SessionData, {
-    policies: typeof apiRateLimitPolicies;   // what enableApiRateLimits({ policies }) receives
-    guards: typeof apiGuards;                // what defineApiGuards(...) receives
-    idempotency: true;                       // enableApiIdempotency(...) is called
-}>;
+// app.ts: declarations + the fully configured instance
+export const lambderApp = initLambder<SessionData>().create({
+    apiPath: "/api",
+    session: { tableName: "app-session", tableRegion: "us-east-1", sessionSalt: "..." },
+    rateLimits: { limiter, policies: apiRateLimitPolicies },
+    idempotency: { store: idempotencyStore },
+    guards: apiGuards,
+});
+export type AppLambder = typeof lambderApp;
+
+// orders.ts: an api module
 export const orderApi = (lambder: AppLambder) => lambder.addSessionApi(...);
+
+// index.ts: registration only (hooks, routes, modules)
+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/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";
@@ -64,7 +64,40 @@ export type LambderHandler = {
     (event: LambderHttpEvent, context: Context): Promise<LambderHttpResponse>;
     (event: unknown, context: Context): Promise<unknown>;
 };
-export type LambderConstructorOptions = {
+/** DynamoDB session configuration (the `session` option of create/new). */
+export type LambderSessionOptions<TSessionData = any> = {
+    tableName: string;
+    tableRegion: string;
+    sessionSalt: string;
+    enableSlidingExpiration?: boolean;
+    /** Min seconds between sliding-expiration writes. Default: max(60, 5% of TTL). */
+    slidingWriteIntervalSeconds?: number;
+    /** Session cookie attributes, e.g. { domain: ".example.com" } for cross-subdomain sessions. `domain` may be a (hostname) => string function for multi-domain deployments. */
+    cookie?: LambderSessionCookieOptions;
+    /** Session cookie names. Defaults: LMDRSESSIONTKID / LMDRSESSIONCSTK. */
+    tokenCookieKey?: string;
+    csrfCookieKey?: string;
+    partitionKey?: string;
+    sortKey?: string;
+    /**
+     * Opt-in freshness for session.data derived from external state (roles,
+     * permissions, feature flags...). Every session read renews data past
+     * its ttlSeconds via your refresh callback, persisting in place on the
+     * same record: same tokens, same cookies. Return null from refresh to
+     * end the session. See LambderSessionDataRefreshConfig for the exact
+     * semantics.
+     */
+    dataRefresh?: LambderSessionDataRefreshConfig<TSessionData>;
+};
+/**
+ * Everything an instance is configured with, in ONE declaration: base
+ * serving options plus the type-affecting policy layer (rate limits,
+ * guards, idempotency) and session/CORS config. There are no enable/define
+ * chain methods; the instance is born fully configured and fully typed
+ * (via initLambder), so no ordering rules exist and no partially-configured
+ * instance type ever needs a name.
+ */
+export type LambderCreateOptions<TSessionData = any> = {
     publicPath?: string;
     apiPath?: string;
     apiVersion?: string;
@@ -76,21 +109,34 @@ export type LambderConstructorOptions = {
     etag?: boolean;
     /** Guard threshold for Lambda's ~6MB response cap. Default: 5,500,000. */
     maxResponseBytes?: number;
+    /** CORS: true allows any origin; or pass a LambderCorsConfig. Default: off. */
+    cors?: boolean | LambderCorsConfig;
+    /** DynamoDB-backed sessions; required for addSessionApi/addSessionRoute. */
+    session?: LambderSessionOptions<TSessionData>;
+    /** Declarative per-API rate limiting: your limiter plus named policies APIs reference (typed) via the `rateLimit` option. */
+    rateLimits?: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>;
+    /** Named guards APIs reference (typed) via the `guards` option; build each with lambderGuard(). */
+    guards?: Record<string, LambderApiGuard<any, any, any>>;
+    /** Declarative idempotency: your store plus replay defaults; APIs opt in via `idempotency: true | { ttlSeconds }`. */
+    idempotency?: LambderApiIdempotencyConfig;
 };
 /**
- * Main Lambder class for building type-safe serverless APIs
+ * Main Lambder class for building type-safe serverless APIs. Create
+ * instances with initLambder<SessionData>().create({...}) (see below): the
+ * whole configuration, including the typed policy layer, is given at
+ * construction, and only registration (routes, apis, hooks, use) chains.
  *
  * @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 _TGuards - @internal Guard name to required-payload map, accumulated by defineApiGuards (do not pass manually)
- * @typeParam _TIdempotencyEnabled - @internal Flipped by enableApiIdempotency (do not pass manually)
+ * @typeParam _TRateLimitPolicies - @internal Inferred from create()'s rateLimits.policies (do not pass manually)
+ * @typeParam _TGuards - @internal Guard metadata map inferred from create()'s guards (do not pass manually)
+ * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
  *
  * @example
  * ```typescript
  * interface SessionData { userId: string; role: string; }
  *
- * const lambder = new Lambder<SessionData>({ apiPath: '/api' })
+ * const lambder = initLambder<SessionData>().create({ apiPath: '/api' })
  *   .addApi('getUser', { input: z.object({...}), output: z.object({...}) }, handler)
  *   .addApi('createUser', { input: z.object({...}), output: z.object({...}) }, handler);
  * ```
@@ -130,30 +176,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private sessionCookieOptions;
     private sessionTokenCookieKey;
     private sessionCsrfCookieKey;
-    constructor(options?: LambderConstructorOptions);
-    enableCors(config: boolean | LambderCorsConfig): this;
-    enableDdbSession({ tableName, tableRegion, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, cookie, partitionKey, sortKey, dataRefresh, }: {
-        tableName: string;
-        tableRegion: string;
-        sessionSalt: string;
-        enableSlidingExpiration?: boolean;
-        /** Min seconds between sliding-expiration writes. Default: max(60, 5% of TTL). */
-        slidingWriteIntervalSeconds?: number;
-        /** Session cookie attributes, e.g. { domain: ".example.com" } for cross-subdomain sessions. `domain` may be a (hostname) => string function for multi-domain deployments. */
-        cookie?: LambderSessionCookieOptions;
-        partitionKey?: string;
-        sortKey?: string;
-        /**
-         * Opt-in freshness for session.data derived from external state
-         * (roles, permissions, feature flags...). Every session read
-         * renews data past its ttlSeconds via your refresh callback,
-         * persisting in place on the same record: same tokens, same
-         * cookies. Return null from refresh to end the session. See
-         * LambderSessionDataRefreshConfig for the exact semantics.
-         */
-        dataRefresh?: LambderSessionDataRefreshConfig<TSessionData>;
-    }): this;
-    setSessionCookieKey(sessionTokenCookieKey: string, sessionCsrfCookieKey: string): this;
+    constructor(options?: LambderCreateOptions<TSessionData>);
     setRouteFallbackHandler(routeFallbackHandler: FallbackHandlerFunction): this;
     setApiFallbackHandler(apiFallbackHandler: FallbackHandlerFunction): this;
     setApiInputValidationErrorHandler(apiInputValidationErrorHandler: ApiInputValidationErrorHandlerFunction): this;
@@ -181,40 +204,14 @@ 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;
+    private getOrCreatePolicyEngine;
     /**
-     * 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, _TGuards, _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, _TGuards, true>;
-    /**
-     * Define named guards that APIs reference (typed) via the `guards`
-     * option. Each guard is built with lambderGuard(): its input mode
-     * (apiInput slice of the API's own payload, a separate client-sent
-     * guardInput, or none), an optional `session: true` requirement, an
-     * optional parameter APIs pass in their declaration (`guards: { name:
-     * param }`), and an optional return value that lands typed on the
-     * handler's ctx.guardData[name]. Guards run before input validation, in
-     * the order the API declares them; a handler refuses by throwing
-     * (typically refuse()). Callable multiple times so domain modules can
-     * contribute their own; names must not collide.
+     * 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.
      */
-    defineApiGuards<TGuards extends Record<string, LambderApiGuard<any, any, any>>>(guards: TGuards): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards & LambderGuardMetaMap<TGuards>, _TIdempotencyEnabled>;
-    private getOrCreatePolicyEngine;
+    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;
@@ -222,28 +219,28 @@ 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;
-        /** Replay-protect this API per client idempotencyKey. Requires enableApiIdempotency() first. */
+        /** Replay-protect this API per client idempotencyKey. Requires the idempotency option at creation. */
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             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;
-        /** Replay-protect this API per client idempotencyKey. Requires enableApiIdempotency() first. */
+        /** Replay-protect this API per client idempotencyKey. Requires the idempotency option at creation. */
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             ttlSeconds?: number;
         }) : never;
@@ -293,25 +290,42 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     render(event: LambderHttpEvent, lambdaContext: Context): Promise<LambderHttpResponse>;
 }
 /**
- * The app's configured Lambder instance type, for annotating the parameter
- * of api modules used via lambder.use(...). Name the pieces you wired in
- * index.ts and the guard metadata mapping happens for you:
+ * The canonical way to create an instance: fix the session data type first,
+ * then create with the full configuration in one declaration; the policy,
+ * guard, and idempotency types are INFERRED from the options, so the
+ * instance is born fully typed and `typeof lambderApp` is the annotation
+ * type for api modules. No enable/define chain exists, so there are no
+ * ordering rules and nothing can be half-configured.
  *
  * ```typescript
- * export type AppLambder = LambderApp<SessionData, {
- *     policies: typeof apiRateLimitPolicies;   // enableApiRateLimits({ policies })
- *     guards: typeof apiGuards;                // defineApiGuards(apiGuards)
- *     idempotency: true;                       // enableApiIdempotency(...) was called
- * }>;
+ * // app.ts (imports no api modules, so modules can import the type back)
+ * export const lambderApp = initLambder<SessionData>().create({
+ *     apiPath: "/api",
+ *     session: { tableName: "app-session", tableRegion: "us-east-1", sessionSalt: "..." },
+ *     rateLimits: { limiter, policies },
+ *     guards,
+ *     idempotency: { store },
+ * });
+ * export type AppLambder = typeof lambderApp;
+ *
+ * // orders.ts
+ * export const orderApi = (lambder: AppLambder) => lambder.addSessionApi(...);
+ *
+ * // index.ts: registration only
+ * const lambder = lambderApp.addHook(...).use(orderApi)...;
+ * export const handler = lambder.getHandler();
  * ```
  *
- * Every field is optional; omit what the app does not wire. The declaration
- * is still an assertion about index.ts (registration-time asserts backstop a
- * mismatch at cold start), but derive the fields from the same exported
- * consts the enable calls receive and the types cannot drift.
+ * Why curried (`initLambder<S>().create(...)` rather than
+ * `new Lambder<S>(...)`): TypeScript type arguments are all-or-nothing per
+ * call, so explicitly passing the session data type to the constructor
+ * would silently WIDEN the inferred policy and guard types to their {}
+ * defaults. Fixing the session type in the first call lets the second call
+ * infer everything else from the options. `new Lambder(options)` remains
+ * for untyped or session-data-free instances.
  */
-export type LambderApp<TSessionData, TConfig extends {
-    policies?: Record<string, LambderApiRateLimitPolicyConfig>;
-    guards?: Record<string, LambderApiGuard<any, any, any>>;
-    idempotency?: boolean;
-} = {}> = Lambder<TSessionData, {}, TConfig["policies"] extends Record<string, LambderApiRateLimitPolicyConfig> ? TConfig["policies"] : {}, TConfig["guards"] extends Record<string, LambderApiGuard<any, any, any>> ? LambderGuardMetaMap<TConfig["guards"]> : {}, TConfig["idempotency"] extends true ? true : false>;
+export declare const initLambder: <TSessionData = any>() => {
+    create<const TOptions extends LambderCreateOptions<TSessionData>>(options: TOptions): Lambder<TSessionData, {}, TOptions["rateLimits"] extends {
+        policies: infer TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>;
+    } ? TPolicies : {}, TOptions["guards"] extends Record<string, LambderApiGuard<any, any, any>> ? LambderGuardMetaMap<TOptions["guards"]> : {}, TOptions["idempotency"] extends LambderApiIdempotencyConfig ? true : false>;
+};