lambder 3.8.1 → 4.1.1

package/Readme.md

@@ -1,8 +1,18 @@
-# Lambder - Serverless NodeJS Web Framework (v3)
+# Lambder - Serverless NodeJS Web Framework (v4)
 
 Lambder is a highly opinionated dynamic serverless framework designed to facilitate the management and implementation of routes and APIs within AWS Lambda functions, specifically tailored for TypeScript projects. It provides a streamlined approach to handling HTTP requests, managing sessions, and defining API routes, making serverless application development more intuitive and structured.
 
-**New in v3:** Public file serving with `servePublicFiles()` + `serveIndexHtml()`, unified `addAction()` for non-HTTP triggers, automatic gzip + ETag, thrown responses with a real `die`, the comment-based `LambderTemplatingEngine`, type-safe `html`/`xml` tagged templates, API Gateway HTTP API (payload v2) / Lambda Function URL support, the `LambderDdbCache` DynamoDB cache (3.1), typed translations with `createLambderI18n` (3.2), and in 3.5: typed API refusals with `LambderApiError`, caller outcomes/timeouts with `apiOutcome()`, plus declarative per-API rate limits, guards, and idempotency; 3.8 gives guards and custom rate-limit keys two typed modes: apiInput (checks a slice of the API's own payload; declarable only where the schema carries those fields) and guardInput (a separate client-sent guardInputs channel the contract makes mandatory at the call site).
+**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.
+- **Secrets hashed at rest**: session records store only sha256 hashes of the bearer secrets, so a session-table read yields no usable cookies; `LambderSessionReadError` keeps a DynamoDB blip from reading as a logout.
+- **Three package entry points**: `lambder` (server), `lambder/client` (browser-safe by construction: no AWS SDK, no Node built-ins), `lambder/testing` (`LambderMSW`); sources organized into core/policies/session/stores/client/shared.
+- **Configuration at creation**: `initLambder<SessionData>().create({...})` takes the WHOLE configuration (serving options, session, cors, rate limits, guards, idempotency) in one declaration; the enable/define chain methods are gone, so nothing can be half-configured or wired in the wrong order, and api modules annotate with `typeof lambderApp` derived from the real instance. Plus `LambderCaller.createIdempotencyKeyScope()` for one self-rotating key per logical operation, and fail-open rate limiting logs its passes.
+
+**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.
 
 ## Features
 
@@ -35,29 +45,50 @@ npm install lambder zod
 yarn add lambder zod
 ```
 
+## Package Entry Points
+
+The package ships three entry points; pick by where the code runs:
+
+| Entry | Runs in | Carries |
+|-------|---------|---------|
+| `lambder` | Server (Lambda) | The full framework: pipeline, sessions, DDB stores, policies, plus everything from `lambder/client` |
+| `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiError`/`refuse`, the API contract and envelope types, `html`/`xml` tagged templates, `createLambderI18n` |
+| `lambder/testing` | Dev and test tooling | `LambderMSW`, the MSW adapter that serves your typed contract from mock handlers |
+
+Frontends and shared isomorphic packages should import from `lambder/client` only; the entry's module graph contains no AWS SDK, Node built-ins, or server pipeline, so the browser boundary is structural rather than left to tree-shaking.
+
+Source layout mirrors this: `src/core/` (request pipeline), `src/policies/` (declarative rate limits, guards, idempotency), `src/session/`, `src/stores/` (DynamoDB primitives), `src/client/`, and `src/shared/` (isomorphic modules both entries re-export).
+
 ## Backend Usage
 
 ### 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
@@ -253,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
@@ -275,21 +309,27 @@ lambder
 
 See [docs/DYNAMODB_SETUP.md](docs/DYNAMODB_SETUP.md) for detailed setup instructions.
 
+#### How the secrets are stored
+
+The session cookie is `pkHash:secret`: `pkHash = sha256(sessionKey + sessionSalt)` and `secret` is 256 random bits. At rest the record stores only HASHES of the bearer secrets: the range key is `sha256(secret)` (so the lookup itself proves possession of the raw secret) and the CSRF token is stored as `csrfTokenHash`. The raw values exist only in the client's cookies and, transiently, on the `LambderCreatedSession` result the manager returns at creation; a read of the session table (backup leak, over-broad IAM, insider) therefore yields no usable cookies. Fast sha256 is the correct construction here rather than a password KDF: the secrets are 256-bit random, so there is nothing to brute-force, while `sessionSalt` peppers the identity-to-partition-key mapping so partition keys and cookie prefixes cannot be derived from (or linked to) known user ids.
+
 #### Keeping session data fresh (`dataRefresh`)
 
 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);
+            },
         },
     },
 });
@@ -300,6 +340,7 @@ Semantics:
 - The callback must be a pure derivation of external state: concurrent reads may run it in parallel, last write wins.
 - Returning `null` deletes the session; the request is answered as session-expired.
 - Thrown errors fail the request as a `LambderSessionDataRefreshError` and leave the session untouched (they are never mistaken for a logout). Catch inside and return `session.data` to explicitly serve stale instead.
+- Similarly, a DynamoDB failure while READING a session fails the request as a `LambderSessionReadError` instead of reading as "no session": answering session-expired there would make LambderCaller clear the client's cookies, turning an infra blip into a forced logout.
 - The renewal write and the sliding-expiration write share a single DynamoDB put when both are due.
 - Records created before `dataRefresh` was enabled renew on their first read.
 - `updateSessionData()` marks data fresh (it was just written deliberately); `regenerateSession()` carries the old freshness stamp over.
@@ -466,18 +507,23 @@ 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" },
             writePerUser: { perMin: 30, per: "session" },   // only referable from addSessionApi (also enforced at compile time)
             codePerEmail: {
                 perMin: 3,
+                // scope "policy": ONE combined budget across every API that
+                // references this policy (send + register + reset share the
+                // 3/min). Default scope "api" gives each API its own counter.
+                scope: "policy",
                 // 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`.
@@ -488,28 +534,44 @@ 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, two modes. apiInput checks a slice of the API's own
+    },
+    // 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
+    //    where the payload type passes both); guardInput is the guard's OWN
     //    value, sent separately by the caller via options.guardInputs and
     //    made mandatory by the contract, so forgetting it is a compile error
-    //    at the call site. Both are validated pre-run and typed in the handler.
-    .defineApiGuards({
+    //    at the call site; or neither. Both are validated pre-run and typed
+    //    in the handler. On top of that a guard may require a session
+    //    (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].
+    guards: {
         captcha: lambderGuard({
             guardInput: z.object({ captchaToken: z.string() }),
             handler: async (ctx, { captchaToken }) => {
                 if (!await verifyCaptcha(captchaToken, ctx.ip)) refuse("Verification failed, please retry.");
             },
         }),
-    });
+        deviceAuth: lambderGuard({
+            apiInput: z.object({ deviceToken: z.string() }),
+            // Returns a value: the API handler reads ctx.guardData.deviceAuth.
+            handler: async (_ctx, { deviceToken }) => await resolveDeviceOrRefuse(deviceToken),
+        }),
+        orgPermission: lambderGuard({
+            session: true,
+            // Parameterized: APIs declare guards: { orgPermission: "SOME.PERMISSION" }.
+            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
@@ -519,20 +581,47 @@ lambder.addApi("public.resetPassword", {
     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)
-    guards: "captcha",
+    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",
-    idempotency: true,                          // or { ttlSeconds: 3600 }; type error until enableApiIdempotency()
-}, handler);
+    guards: { orgPermission: "ORDERS.CREATE" }, // param typed per guard; entries run in insertion order
+    idempotency: true,                          // or { ttlSeconds: 3600 }; type error unless created with idempotency
+}, async (ctx, res) => {
+    const { organizationId } = ctx.guardData.orgPermission;  // typed guard output
+    // ...
+});
+```
+
+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, 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
+// 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) → rate limits → guards → zod validation → idempotency claim → handler → idempotency store. Refusals ride the envelope via `LambderApiError` (429 rate limited, 409 duplicate in flight), so the caller's `errorMessageHandler` surfaces them with zero client code.
+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.
 
-**Idempotency semantics**: the client sends an `idempotencyKey` per call (see LambderCaller below); generate it once per logical operation and reuse it on retries. The scope is identity (session key, or IP for public APIs) + API name + key: concurrent duplicates of an in-flight request refuse with 409, repeats of a completed one replay the stored response verbatim until the TTL, and a crashed original releases its claim so a retry actually retries. A response delivered by throwing (`res.die.*`, `throw res.api(...)`) counts as a completion and is stored like a returned one; thrown `LambderApiError` refusals release the claim instead. Responses with status ≥ 500 are never stored. Claims are owner-checked, so an original that stalls past the pending window can no longer overwrite or delete the claim a retry has since taken. Requests without a key execute normally.
+**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.
 
 Also enforced at registration: **duplicate API names throw** (dispatch is first-match, so a second registration of the same name would be silently dead code).
 
@@ -583,12 +672,12 @@ cI18n.forLanguage("tr")("compute"); // explicit (per-request backend use)
 
 ## Frontend Usage with LambderCaller
 
-LambderCaller is a frontend companion library for Lambder (only 2kb compressed) designed to simplify making type-safe API requests to your Lambder backend.
+LambderCaller is a frontend companion library for Lambder (only 2kb compressed) designed to simplify making type-safe API requests to your Lambder backend. Import it from the `lambder/client` entry: everything reachable from there is browser-safe by construction (no AWS SDK, no Node built-ins, no server pipeline), so your bundle can never pick up server code.
 
 ### Basic Setup with Type Safety
 
 ```typescript
-import { LambderCaller } from "lambder";
+import { LambderCaller } from "lambder/client";
 import type { ApiContractType } from "./backend/handler"; // Import the inferred contract type
 
 const lambderCaller = new LambderCaller<ApiContractType>({
@@ -637,9 +726,9 @@ Every configured handler still fires on the matching failure, so global UX (toas
 Also available:
 
 - **Timeouts**: pass `timeoutMs` in the constructor for a default (API Gateway caps around 29s, so ~30000 is sensible) and/or per call; timed-out calls abort the fetch and report `reason: 'timeout'`. A per-call `signal` combines with the timeout.
-- **Per-call handler overrides**: every constructor handler (`errorHandler`, `sessionExpiredHandler`, `errorMessageHandler`, ...) can be overridden in the options of a single `api`/`apiRaw`/`apiOutcome` call.
+- **Per-call handler overrides**: every constructor handler (`errorHandler`, `sessionExpiredHandler`, `errorMessageHandler`, ...) can be overridden in the options of a single `api`/`apiOutcome` call.
 - **Guard inputs**: for APIs whose guards run in guardInput mode, pass their values per call as `guardInputs: { <guardName>: value }`; the typed contract makes the options argument (and the correct value shape) mandatory for those APIs.
-- **Idempotency keys**: pass `idempotencyKey` per call for APIs declared idempotent on the server (see Declarative API Policies). Generate it once per logical operation with `LambderCaller.createIdempotencyKey()` (safe in insecure contexts where `crypto.randomUUID` is missing) and send the same key on retries; rotate after a confirmed success.
+- **Idempotency keys**: pass `idempotencyKey` per call for APIs declared idempotent on the server (see Declarative API Policies). Generate it once per logical operation with `LambderCaller.createIdempotencyKey()` (safe in insecure contexts where `crypto.randomUUID` is missing) and send the same key on retries; rotate after a confirmed success. `LambderCaller.createIdempotencyKeyScope()` packages that pattern for a component performing one operation repeatedly: read `scope.current` on every attempt, call `scope.rotate()` after a confirmed success. Keys must be unguessable random and 16-200 characters (they scope the replay record for logged-out clients); the server refuses shorter keys with a 400.
 
 ### Benefits
 
@@ -657,7 +746,7 @@ Also available:
 LambderMSW provides seamless integration with [MSW (Mock Service Worker)](https://mswjs.io/) for testing your APIs with full type safety.
 
 ```typescript
-import { LambderMSW } from 'lambder';
+import { LambderMSW } from 'lambder/testing';
 import { setupServer } from 'msw/node';
 import type { ApiContractType } from './backend/handler';
 

package/dist/{LambderCaller.d.ts → client/LambderCaller.d.ts}

@@ -1,5 +1,5 @@
-import { LambderApiResponse } from './LambderResponseBuilder';
-import type { ApiContractShape } from './LambderApiContract';
+import type { LambderApiResponse } from '../shared/LambderApiContract.js';
+import type { ApiContractShape } from '../shared/LambderApiContract.js';
 import type { z } from "zod";
 type IsAny<T> = 0 extends (1 & T) ? true : false;
 type GuardInputsOf<TEntry> = TEntry extends {
@@ -36,6 +36,13 @@ type FetchEndEventHandler = (params: {
 type ErrorHandler = (err: Error) => void | Promise<void>;
 type ValidationErrorHandler = (zodError: z.ZodError) => (void | false) | Promise<(void | false)>;
 type MessageHandler = (message: any) => void | Promise<void>;
+/** One logical operation's rotating idempotency key: see LambderCaller.createIdempotencyKeyScope(). */
+export type LambderIdempotencyKeyScope = {
+    /** The key for the operation currently in progress. */
+    readonly current: string;
+    /** Call after a confirmed success: the next operation is a new intent. Returns the new key. */
+    rotate(): string;
+};
 export type LambderApiFailureReason = 'network' | 'timeout' | 'server' | 'validation' | 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'errorMessage' | 'unknown';
 /**
  * Discriminated result of an API call: `ok: true` carries the payload, every
@@ -75,10 +82,12 @@ export type LambderCallOptions = {
     guardInputs?: Record<string, unknown>;
     /**
      * Replay-protection key for APIs declared idempotent on the server.
-     * Generate once per logical operation (e.g. crypto.randomUUID() when the
-     * form opens) and send the same key on retries: duplicates of an
-     * in-flight request refuse, and repeats of a completed one replay its
-     * stored response instead of re-executing.
+     * Generate once per logical operation with createIdempotencyKey() and
+     * send the same key on retries: duplicates of an in-flight request
+     * refuse, and repeats of a completed one replay its stored response
+     * instead of re-executing. Must be UNGUESSABLE random (it scopes the
+     * replay record for logged-out clients) and at least 16 characters; the
+     * server refuses shorter keys with a 400.
      */
     idempotencyKey?: string;
     versionExpiredHandler?: VoidFunction;
@@ -129,6 +138,21 @@ export default class LambderCaller<TContract extends ApiContractShape = any> {
         sessionCookieDomain?: string | ((hostname: string) => string | undefined | null);
     });
     setSessionCookieKey(sessionTokenCookieKey: string, sessionCsrfCookieKey: string): void;
+    /**
+     * A self-rotating idempotency key for a component or form that performs
+     * the same logical operation repeatedly. `current` is the key for the
+     * operation in progress: send it with every attempt (first try, retry
+     * after a failure, double-tap) so the server collapses them. Call
+     * `rotate()` after a confirmed success so the next operation is a new
+     * intent with its own key.
+     *
+     * ```typescript
+     * const submitKey = LambderCaller.createIdempotencyKeyScope();
+     * await caller.api("order.create", payload, { idempotencyKey: submitKey.current });
+     * submitKey.rotate();
+     * ```
+     */
+    static createIdempotencyKeyScope(): LambderIdempotencyKeyScope;
     /**
      * Generate an idempotency key for one logical operation. Create it when
      * the operation begins (a form opens, a draft starts), send the same key
@@ -146,12 +170,6 @@ export default class LambderCaller<TContract extends ApiContractShape = any> {
      * instead of collapsing every failure to null. Never throws.
      */
     apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<LambderApiOutcome<TOutput>>;
-    /**
-     * Legacy shape: the parsed envelope on success (and on structured
-     * errorMessage refusals, which carry an envelope), null on every other
-     * failure. Prefer apiOutcome() when the call site needs to know why.
-     */
-    apiRaw<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<LambderApiResponse<TOutput> | null | undefined>;
     /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
     api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<TOutput | null | undefined>;
 }

package/dist/{LambderCaller.js → client/LambderCaller.js}

@@ -39,6 +39,27 @@ export default class LambderCaller {
         this.sessionTokenCookieKey = sessionTokenCookieKey;
         this.sessionCsrfCookieKey = sessionCsrfCookieKey;
     }
+    /**
+     * A self-rotating idempotency key for a component or form that performs
+     * the same logical operation repeatedly. `current` is the key for the
+     * operation in progress: send it with every attempt (first try, retry
+     * after a failure, double-tap) so the server collapses them. Call
+     * `rotate()` after a confirmed success so the next operation is a new
+     * intent with its own key.
+     *
+     * ```typescript
+     * const submitKey = LambderCaller.createIdempotencyKeyScope();
+     * await caller.api("order.create", payload, { idempotencyKey: submitKey.current });
+     * submitKey.rotate();
+     * ```
+     */
+    static createIdempotencyKeyScope() {
+        let key = LambderCaller.createIdempotencyKey();
+        return {
+            get current() { return key; },
+            rotate() { key = LambderCaller.createIdempotencyKey(); return key; },
+        };
+    }
     /**
      * Generate an idempotency key for one logical operation. Create it when
      * the operation begins (a form opens, a draft starts), send the same key
@@ -285,18 +306,6 @@ export default class LambderCaller {
         return await this.dispatch(apiName, payload, rest[0]);
     }
     ;
-    /**
-     * Legacy shape: the parsed envelope on success (and on structured
-     * errorMessage refusals, which carry an envelope), null on every other
-     * failure. Prefer apiOutcome() when the call site needs to know why.
-     */
-    async apiRaw(apiName, payload, ...rest) {
-        const outcome = await this.dispatch(apiName, payload, rest[0]);
-        if (outcome.ok)
-            return outcome.response;
-        return outcome.reason === 'errorMessage' ? outcome.response : null;
-    }
-    ;
     /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
     async api(apiName, payload, ...rest) {
         const outcome = await this.dispatch(apiName, payload, rest[0]);

package/dist/{LambderMSW.d.ts → client/LambderMSW.d.ts}

@@ -1,4 +1,4 @@
-import type { ApiContractShape } from './LambderApiContract';
+import type { ApiContractShape } from '../shared/LambderApiContract.js';
 type RequestHandler = any;
 /** The parts of the msw module LambderMSW uses: `import { http, HttpResponse } from "msw"`. */
 export type LambderMswModule = {

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Browser entry point (`import ... from "lambder/client"`).
+ *
+ * Everything reachable from here is browser-safe: no AWS SDK, no Node
+ * built-ins, no server pipeline. Frontends and isomorphic shared packages
+ * import from this entry so their bundles can never pick up server code;
+ * the root entry (`"lambder"`) is the server surface.
+ */
+export { default as LambderCaller } from "./client/LambderCaller.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderIdempotencyKeyScope, } from "./client/LambderCaller.js";
+export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefuseOptions } from "./shared/LambderApiError.js";
+export type { ApiContractShape, LambderApiResponse, LambderApiResponseConfig } from "./shared/LambderApiContract.js";
+export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
+export { createLambderI18n } from "./shared/LambderI18n.js";
+export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";

package/dist/client.js

@@ -0,0 +1,17 @@
+/**
+ * Browser entry point (`import ... from "lambder/client"`).
+ *
+ * Everything reachable from here is browser-safe: no AWS SDK, no Node
+ * built-ins, no server pipeline. Frontends and isomorphic shared packages
+ * import from this entry so their bundles can never pick up server code;
+ * the root entry (`"lambder"`) is the server surface.
+ */
+// The typed API caller.
+export { default as LambderCaller } from "./client/LambderCaller.js";
+// Typed API refusals (isomorphic: shared code may throw them from anywhere;
+// in the browser they are plain Errors).
+export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+// Type-safe templating (tagged templates with auto-escaping)
+export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
+// Typed translations (standalone, isomorphic)
+export { createLambderI18n } from "./shared/LambderI18n.js";