lambder 3.8.1 → 4.1.1

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

@@ -5,11 +5,13 @@ import LambderResponseBuilder from "./LambderResponseBuilder.js";
 import { LambderResponse, type LambderHttpResponse } from "./LambderResponse.js";
 import { type ConditionFunction, type LambderRouteMatcher, type PathParamsOf } from "./LambderRouting.js";
 import { type LambderCorsConfig } from "./LambderCors.js";
-import { type LambderSessionDataRefreshConfig } from "./LambderSessionManager.js";
-import LambderSessionController, { type LambderSessionCookieOptions } from "./LambderSessionController.js";
+import { type LambderSessionDataRefreshConfig } from "../session/LambderSessionManager.js";
+import LambderSessionController, { type LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
-import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderApiIdempotencyConfig, type LambderApiGuard, type LambderGuardMetaMap, type LambderAllowedGuardNames, type LambderAllowedPolicyNames, type LambderGuardInputsOf } from "./LambderApiPolicies.js";
-import type { MergeContract } from "./LambderApiContract.js";
+import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../policies/LambderApiGuards.js";
+import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames } 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";
 export type { PathParamsOf, RouteCondition, ConditionFunction, LambderRouteMatcher } from "./LambderRouting.js";
 export type { LambderCorsConfig } from "./LambderCors.js";
@@ -62,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;
@@ -74,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);
  * ```
@@ -128,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;
@@ -179,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() in one of two modes:
-     * apiInput (checks a slice of the API's own payload; declarable only on
-     * APIs whose input schema carries those fields, so the payload type
-     * passes both the API input and the guard's apiInput) or guardInput (the
-     * client sends the guard's value separately via options.guardInputs, and
-     * the contract forces it at the call site). 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>>>(guards: TGuards): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards & LambderGuardMetaMap<TGuards>, _TIdempotencyEnabled>;
     private getOrCreatePolicyEngine;
     /** Registration-time checks shared by addApi/addSessionApi. */
     private assertApiRegistration;
@@ -220,32 +212,32 @@ 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 LambderAllowedGuardNames<_TGuards, z.infer<TInput>> | readonly LambderAllowedGuardNames<_TGuards, z.infer<TInput>>[] = never>(name: TName, schema: {
+    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: {
         input: TInput;
         output: TOutput;
     } & {
         /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
         rateLimit?: TRateOpt;
-        /** Named guards, run in declared order before input validation; their input requirements merge into this API's contract input. */
+        /** 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>>, 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 LambderAllowedGuardNames<_TGuards, z.infer<TInput>> | readonly LambderAllowedGuardNames<_TGuards, z.infer<TInput>>[] = never>(name: TName, schema: {
+    }, 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: {
         input: TInput;
         output: TOutput;
     } & {
         /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
         rateLimit?: TRateOpt;
-        /** Named guards, run in declared order before input validation; their input requirements merge into this API's contract input. */
+        /** 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: LambderSessionRenderContext<z.infer<TInput>, TSessionData>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
+    }, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData, 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>;
     /**
      * Fetch the session or short-circuit the request: API calls get the
      * protocol's { sessionExpired: true } response (handled by LambderCaller),
@@ -290,3 +282,43 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private resolveRequest;
     render(event: LambderHttpEvent, lambdaContext: Context): Promise<LambderHttpResponse>;
 }
+/**
+ * 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 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/{Lambder.js → core/Lambder.js}

@@ -3,26 +3,29 @@ import LambderResponseBuilder from "./LambderResponseBuilder.js";
 import { LambderResponse, finalizeResponse, DEFAULT_FINALIZE_OPTIONS, } from "./LambderResponse.js";
 import { compileRouteMatcher } from "./LambderRouting.js";
 import { applyCorsHeaders } from "./LambderCors.js";
-import LambderSessionManager from "./LambderSessionManager.js";
-import LambderSessionController from "./LambderSessionController.js";
+import LambderSessionManager from "../session/LambderSessionManager.js";
+import LambderSessionController from "../session/LambderSessionController.js";
 import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
-import { isLambderApiError } from "./LambderApiError.js";
-import { LambderApiPolicyEngine, } from "./LambderApiPolicies.js";
+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() in one of two modes:
-     * apiInput (checks a slice of the API's own payload; declarable only on
-     * APIs whose input schema carries those fields, so the payload type
-     * passes both the API input and the guard's apiInput) or guardInput (the
-     * client sends the guard's value separately via options.guardInputs, and
-     * the contract forces it at the call site). 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);
     }
@@ -257,6 +222,14 @@ export default class Lambder {
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
             actionFn: async (ctx, resolver) => {
+                // Replay fast path first: a completed idempotent request must
+                // answer its stored response without burning rate-limit quota
+                // or re-running guards (no handler executes either way).
+                if (this.apiPolicyEngine && schema.idempotency) {
+                    const replay = await this.apiPolicyEngine.findReplay(name, ctx);
+                    if (replay)
+                        return replay;
+                }
                 if (this.apiPolicyEngine)
                     await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);
@@ -282,6 +255,13 @@ export default class Lambder {
             match: (ctx) => ctx.apiName === name ? {} : false,
             actionFn: async (ctx, resolver) => {
                 await this.requireSession(ctx, resolver);
+                // Replay fast path (after the session fetch: the replay scope
+                // is keyed per session): see addApi.
+                if (this.apiPolicyEngine && schema.idempotency) {
+                    const replay = await this.apiPolicyEngine.findReplay(name, ctx);
+                    if (replay)
+                        return replay;
+                }
                 if (this.apiPolicyEngine)
                     await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);
@@ -330,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,
@@ -567,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/{LambderContext.d.ts → core/LambderContext.d.ts}

@@ -1,10 +1,10 @@
 import type { APIGatewayProxyEvent, APIGatewayProxyEventV2, APIGatewayProxyEventHeaders, Context } from "aws-lambda";
-import type { LambderSessionContext } from "./LambderSessionManager.js";
+import type { LambderSessionContext } from "../session/LambderSessionManager.js";
 import type { LambderHttpEventFormat } from "./LambderResponse.js";
 export type LambderHttpEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2;
 /** True for API Gateway HTTP API / Lambda Function URL (payload v2) events. */
 export declare const isV2HttpEvent: (event: unknown) => event is APIGatewayProxyEventV2;
-export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<string, string> = Record<string, string>> = {
+export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}> = {
     host: string;
     path: string;
     pathParams: TPathParams;
@@ -15,6 +15,12 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     session: null;
     apiName: string | null;
     apiPayload: TApiPayload;
+    /**
+     * Outputs of this API's guards, keyed by guard name. Only guards the API
+     * declares AND that return a value appear (typed via the declarative
+     * guards option); void guards never do.
+     */
+    guardData: TGuardData;
     headers: APIGatewayProxyEventHeaders;
     /** Decoded request body, exactly as received (e.g. for webhook signature verification). */
     rawBody: string;
@@ -39,7 +45,7 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
         logToApiResponseAccumulator: any[];
     };
 };
-export type LambderSessionRenderContext<TApiPayload = any, SessionData = any, TPathParams extends Record<string, string> = Record<string, string>> = Omit<LambderRenderContext<TApiPayload, TPathParams>, 'session'> & {
+export type LambderSessionRenderContext<TApiPayload = any, SessionData = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}> = Omit<LambderRenderContext<TApiPayload, TPathParams, TGuardData>, 'session'> & {
     session: LambderSessionContext<SessionData>;
 };
 export declare const createContext: (event: LambderHttpEvent, lambdaContext: Context, apiPath: string) => LambderRenderContext;

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

@@ -77,6 +77,7 @@ export const createContext = (event, lambdaContext, apiPath) => {
         get, post, cookie, event,
         session: null,
         apiName, apiPayload,
+        guardData: {},
         headers, rawBody, ip, header,
         lambdaContext,
         _otherInternal: {

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

@@ -1,5 +1,5 @@
 import mimeTypeResolver from "mime-types";
-import { getFS, getPath } from "./node-polyfills.js";
+import { getFS, getPath } from "../shared/node-polyfills.js";
 import { LambderResponse } from "./LambderResponse.js";
 // Content-hashed build outputs (Vite/webpack/Rollup): a [-.] separated run of
 // 8+ hash chars containing at least one digit, before the extension.

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

@@ -1,4 +1,4 @@
-import { getZlib, getCrypto } from "./node-polyfills.js";
+import { getZlib, getCrypto } from "../shared/node-polyfills.js";
 export const normalizeHeaders = (headers) => Object.fromEntries(Object.entries(headers ?? {}).map(([k, v]) => [k, Array.isArray(v) ? [...v] : [v]]));
 /**
  * Intermediate response object returned by all response builder methods and by

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

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

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

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

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

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

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

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