lambder 4.0.1 → 4.1.1

package/Readme.md

@@ -8,9 +8,9 @@ Lambder is a highly opinionated dynamic serverless framework designed to facilit
 - **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.
 - **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 +63,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 +284,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 +318,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,12 +507,13 @@ 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({
+    rateLimits: {
         limiter: new LambderDdbRateLimiter({ tableName: "app-rate-limiter", region: "us-east-1", failOpen: true }),
         policies: {
             authPerIp:    { perMin: 5, perHour: 30, per: "ip" },
@@ -521,14 +534,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 +552,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 +570,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
@@ -575,7 +589,7 @@ lambder.addSessionApi("secure.order.create", {
     output: OrderResultSchema,
     rateLimit: "writePerUser",
     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,15 +598,25 @@ 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.

package/dist/core/Lambder.d.ts

@@ -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,39 +204,6 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     serveIndexHtml(handler?: FallbackHandlerFunction, options?: LambderIndexHtmlOptions): this;
     /** Apply the serveIndexHtml gates; null means fall through. */
     private tryServeIndexHtml;
-    /**
-     * Wire declarative per-API rate limiting: your LambderDdbRateLimiter
-     * instance plus named policies, each declaring its windows and what one
-     * counter tracks (`per`: "ip", "session", or a custom key function).
-     * APIs then reference policies by name via the `rateLimit` option; the
-     * returned type narrows so only declared names are accepted, and
-     * policies keyed per "session" are only referable from addSessionApi.
-     * Callable once; call it before the API registrations that use it.
-     */
-    enableApiRateLimits<const TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>>(config: LambderApiRateLimitsConfig<TPolicies>): Lambder<TSessionData, _TContract, TPolicies, _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.
-     */
-    defineApiGuards<TGuards extends Record<string, LambderApiGuard<any, any, any>>>(guards: TGuards): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards & LambderGuardMetaMap<TGuards>, _TIdempotencyEnabled>;
     private getOrCreatePolicyEngine;
     /** Registration-time checks shared by addApi/addSessionApi. */
     private assertApiRegistration;
@@ -230,7 +220,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         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;
@@ -243,7 +233,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         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 +283,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>;
+};

package/dist/core/Lambder.js

@@ -10,19 +10,22 @@ import { isLambderApiError } from "../shared/LambderApiError.js";
 import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.js";
 /**
- * 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);
  * ```
@@ -73,26 +76,33 @@ export default class Lambder {
             etag: options.etag ?? DEFAULT_FINALIZE_OPTIONS.etag,
             maxResponseBytes: options.maxResponseBytes ?? DEFAULT_FINALIZE_OPTIONS.maxResponseBytes,
         };
-    }
-    enableCors(config) {
-        this.corsConfig = config === true ? {} : (config === false ? null : config);
-        return this;
-    }
-    enableDdbSession({ tableName, tableRegion, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, cookie, partitionKey, sortKey, dataRefresh, }) {
-        this.lambderSessionManager = new LambderSessionManager({
-            tableName, tableRegion,
-            partitionKey: partitionKey ?? "pk",
-            sortKey: sortKey ?? "sk",
-            sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds,
-            dataRefresh,
-        });
-        this.sessionCookieOptions = cookie ?? {};
-        return this;
-    }
-    setSessionCookieKey(sessionTokenCookieKey, sessionCsrfCookieKey) {
-        this.sessionTokenCookieKey = sessionTokenCookieKey;
-        this.sessionCsrfCookieKey = sessionCsrfCookieKey;
-        return this;
+        if (options.cors !== undefined && options.cors !== false) {
+            this.corsConfig = options.cors === true ? {} : options.cors;
+        }
+        if (options.session) {
+            const session = options.session;
+            this.lambderSessionManager = new LambderSessionManager({
+                tableName: session.tableName,
+                tableRegion: session.tableRegion,
+                partitionKey: session.partitionKey ?? "pk",
+                sortKey: session.sortKey ?? "sk",
+                sessionSalt: session.sessionSalt,
+                enableSlidingExpiration: session.enableSlidingExpiration,
+                slidingWriteIntervalSeconds: session.slidingWriteIntervalSeconds,
+                dataRefresh: session.dataRefresh,
+            });
+            this.sessionCookieOptions = session.cookie ?? {};
+            if (session.tokenCookieKey)
+                this.sessionTokenCookieKey = session.tokenCookieKey;
+            if (session.csrfCookieKey)
+                this.sessionCsrfCookieKey = session.csrfCookieKey;
+        }
+        if (options.rateLimits)
+            this.getOrCreatePolicyEngine().setRateLimits(options.rateLimits);
+        if (options.guards)
+            this.getOrCreatePolicyEngine().addGuards(options.guards);
+        if (options.idempotency)
+            this.getOrCreatePolicyEngine().setIdempotency(options.idempotency);
     }
     setRouteFallbackHandler(routeFallbackHandler) {
         this.routeFallbackHandler = routeFallbackHandler;
@@ -162,51 +172,6 @@ export default class Lambder {
         }
         return response;
     }
-    // ---------------------------------------------------------------------
-    // Declarative API policies (rate limits, guards, idempotency)
-    // ---------------------------------------------------------------------
-    /**
-     * Wire declarative per-API rate limiting: your LambderDdbRateLimiter
-     * instance plus named policies, each declaring its windows and what one
-     * counter tracks (`per`: "ip", "session", or a custom key function).
-     * APIs then reference policies by name via the `rateLimit` option; the
-     * returned type narrows so only declared names are accepted, and
-     * policies keyed per "session" are only referable from addSessionApi.
-     * Callable once; call it before the API registrations that use it.
-     */
-    enableApiRateLimits(config) {
-        this.getOrCreatePolicyEngine().setRateLimits(config);
-        return this;
-    }
-    /**
-     * Wire declarative idempotency: your LambderDdbIdempotency instance plus
-     * replay defaults. APIs opt in via `idempotency: true | { ttlSeconds }`;
-     * the option is a type error until this is called. Requests carrying a
-     * client `idempotencyKey` (sent by LambderCaller) claim an
-     * identity+api+key scope atomically: concurrent duplicates refuse with
-     * 409, replays of a completed request return the stored response, and a
-     * crashed original releases its claim. Callable once.
-     */
-    enableApiIdempotency(config) {
-        this.getOrCreatePolicyEngine().setIdempotency(config);
-        return this;
-    }
-    /**
-     * Define named guards that APIs reference (typed) via the `guards`
-     * option. 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.
-     */
-    defineApiGuards(guards) {
-        this.getOrCreatePolicyEngine().addGuards(guards);
-        return this;
-    }
     getOrCreatePolicyEngine() {
         if (!this.apiPolicyEngine)
             this.apiPolicyEngine = new LambderApiPolicyEngine();
@@ -222,7 +187,7 @@ export default class Lambder {
         if (!usesPolicies)
             return;
         if (!this.apiPolicyEngine) {
-            throw new Error(`Lambder: API "${name}" declares rateLimit/guards/idempotency, but none of enableApiRateLimits()/defineApiGuards()/enableApiIdempotency() was called first.`);
+            throw new Error(`Lambder: API "${name}" declares rateLimit/guards/idempotency, but none of rateLimits/guards/idempotency was configured at creation.`);
         }
         this.apiPolicyEngine.assertRegistration(name, mode, options);
     }
@@ -345,7 +310,7 @@ export default class Lambder {
     }
     getSessionController(ctx) {
         if (!this.lambderSessionManager)
-            throw new Error("Session is not enabled. Use lambder.enableDdbSession(...) to enable.");
+            throw new Error("Session is not enabled. Configure the session option at creation.");
         return new LambderSessionController({
             lambderSessionManager: this.lambderSessionManager,
             sessionTokenCookieKey: this.sessionTokenCookieKey,
@@ -582,6 +547,46 @@ export default class Lambder {
         }
     }
 }
+/**
+ * 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
+ * // 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();
+ * ```
+ *
+ * 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 const initLambder = () => ({
+    create(options) {
+        return new Lambder(options);
+    },
+});
 /** Rebuild the query string from the API Gateway event for redirects. */
 const buildQueryString = (ctx) => {
     if (isV2HttpEvent(ctx.event)) {

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import Lambder from './core/Lambder.js';
 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";
@@ -13,7 +14,7 @@ export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtm
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
 export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/LambderResponseBuilder.js";
-export type { LambderRouteMatcher, LambderCorsConfig, LambderConstructorOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, LambderApp, } from "./core/Lambder.js";
+export type { LambderRouteMatcher, LambderCorsConfig, LambderCreateOptions, LambderSessionOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, } from "./core/Lambder.js";
 export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
 export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import Lambder from './core/Lambder.js';
 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";

package/dist/policies/LambderApiGuards.js

@@ -47,7 +47,7 @@ export class LambderApiGuardsEngine {
         for (const { name } of toGuardEntries(guardsOption)) {
             const guardDef = this.guards[name];
             if (!guardDef) {
-                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Define it via defineApiGuards() before registering the API.`);
+                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Declare it in the guards option at creation.`);
             }
             if (guardDef.session && mode !== "session") {
                 throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true), which requires addSessionApi.`);

package/dist/policies/LambderApiIdempotency.d.ts

@@ -19,7 +19,7 @@ export declare class LambderApiIdempotencyEngine {
     private defaultTtlSeconds;
     private failOpen;
     configure(config: LambderApiIdempotencyConfig): void;
-    /** True once enableApiIdempotency() ran; registration asserts check it. */
+    /** True once the idempotency option was configured; registration asserts check it. */
     get isConfigured(): boolean;
     /**
      * The request's idempotencyKey: null when absent, the key when valid, a

package/dist/policies/LambderApiIdempotency.js

@@ -20,12 +20,12 @@ export class LambderApiIdempotencyEngine {
     failOpen = true;
     configure(config) {
         if (this.store)
-            throw new Error("Lambder: enableApiIdempotency() was already called.");
+            throw new Error("Lambder: idempotency was already configured.");
         this.store = config.store;
         this.defaultTtlSeconds = config.defaultTtlSeconds ?? 24 * 3600;
         this.failOpen = config.failOpen ?? true;
     }
-    /** True once enableApiIdempotency() ran; registration asserts check it. */
+    /** True once the idempotency option was configured; registration asserts check it. */
     get isConfigured() { return this.store !== null; }
     /**
      * The request's idempotencyKey: null when absent, the key when valid, a

package/dist/policies/LambderApiPolicies.d.ts

@@ -16,7 +16,7 @@ type LambderApiPolicyOptions = {
  * ./LambderApiGuards.ts, idempotency in ./LambderApiIdempotency.ts), asserts
  * registrations against them at startup, and executes them around handlers
  * at request time. Internal to Lambder; apps interact through
- * enableApiRateLimits(), enableApiIdempotency(), defineApiGuards() and the
+ * the create() options (rateLimits, guards, idempotency) and the
  * per-API options.
  */
 export declare class LambderApiPolicyEngine {

package/dist/policies/LambderApiPolicies.js

@@ -7,7 +7,7 @@ import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
  * ./LambderApiGuards.ts, idempotency in ./LambderApiIdempotency.ts), asserts
  * registrations against them at startup, and executes them around handlers
  * at request time. Internal to Lambder; apps interact through
- * enableApiRateLimits(), enableApiIdempotency(), defineApiGuards() and the
+ * the create() options (rateLimits, guards, idempotency) and the
  * per-API options.
  */
 export class LambderApiPolicyEngine {
@@ -28,7 +28,7 @@ export class LambderApiPolicyEngine {
         this.rateLimits.assertRegistration(apiName, mode, options.rateLimit);
         this.guards.assertRegistration(apiName, mode, options.guards);
         if (options.idempotency !== undefined && !this.idempotency.isConfigured) {
-            throw new Error(`Lambder: API "${apiName}" declares idempotency but enableApiIdempotency() was not called first.`);
+            throw new Error(`Lambder: API "${apiName}" declares idempotency but no idempotency store was configured at creation.`);
         }
     }
     /** Rate limits then guards, in declared order. Refusals throw (LambderApiError or a guard's own throw). */

package/dist/policies/LambderApiRateLimits.js

@@ -14,7 +14,7 @@ export class LambderApiRateLimitsEngine {
     policies = {};
     configure(config) {
         if (this.limiter)
-            throw new Error("Lambder: enableApiRateLimits() was already called.");
+            throw new Error("Lambder: rateLimits were already configured.");
         for (const [name, policy] of Object.entries(config.policies)) {
             const per = policy.per;
             if (!per || (per !== "ip" && per !== "session" && typeof per.handler !== "function")) {
@@ -32,7 +32,7 @@ export class LambderApiRateLimitsEngine {
         for (const name of toList(rateLimitOption)) {
             const policy = this.policies[name];
             if (!policy) {
-                throw new Error(`Lambder: API "${apiName}" references unknown rate-limit policy "${name}". Declare it via enableApiRateLimits() before registering the API.`);
+                throw new Error(`Lambder: API "${apiName}" references unknown rate-limit policy "${name}". Declare it in the rateLimits option at creation.`);
             }
             if (policy.per === "session" && mode !== "session") {
                 throw new Error(`Lambder: API "${apiName}" uses rate-limit policy "${name}" (per "session"), which requires addSessionApi.`);

package/dist/session/LambderSessionController.d.ts

@@ -37,7 +37,7 @@ export default class LambderSessionController<TSessionData = any> {
     isSessionValid(session: any): boolean;
     updateSessionData(newData: any): Promise<LambderSessionContext>;
     /**
-     * Force-runs the dataRefresh callback now (see enableDdbSession) and
+     * Force-runs the dataRefresh callback now (see the session option of create) and
      * persists the result onto the current session. Returns the updated
      * session, or null when the callback ended it: the record is deleted and
      * the session cookies are cleared.

package/dist/session/LambderSessionController.js

@@ -124,7 +124,7 @@ export default class LambderSessionController {
     }
     ;
     /**
-     * Force-runs the dataRefresh callback now (see enableDdbSession) and
+     * Force-runs the dataRefresh callback now (see the session option of create) and
      * persists the result onto the current session. Returns the updated
      * session, or null when the callback ended it: the record is deleted and
      * the session cookies are cleared.

package/dist/session/LambderSessionManager.js

@@ -230,7 +230,7 @@ export default class LambderSessionManager {
      */
     async refreshSessionData(session) {
         if (!this.dataRefresh)
-            throw new Error("dataRefresh is not configured. Pass dataRefresh to enableDdbSession(...) to enable.");
+            throw new Error("dataRefresh is not configured. Pass session.dataRefresh at creation to enable.");
         if (!session)
             throw new Error("Invalid session");
         let newData;

package/package.json

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