lambder 6.0.1 → 7.0.1

package/dist/policies/LambderApiIdempotency.js

@@ -1,219 +0,0 @@
-import { LambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
-import { LambderResponse, normalizeHeaders } from "../core/LambderResponse.js";
-/** A crashed original must not block retries forever: pending claims expire on their own. */
-const IDEMPOTENCY_PENDING_TTL_SECONDS = 300;
-/**
- * Keys must be unguessable: without a session, the replay scope is the key
- * itself, so a guessable key would let one client read another's stored
- * response. LambderCaller.createIdempotencyKey() returns 36 chars.
- */
-const IDEMPOTENCY_MIN_KEY_LENGTH = 16;
-const IDEMPOTENCY_MAX_KEY_LENGTH = 200;
-/**
- * Runtime side of the idempotency subsystem: claims a per-operation scope
- * around handler execution, replays stored responses, and settles claims.
- * Composed into LambderApiPolicyEngine.
- */
-export class LambderApiIdempotencyEngine {
-    store = null;
-    defaultTtlSeconds = 24 * 3600;
-    failOpen = true;
-    configure(config) {
-        if (this.store)
-            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 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
-     * 400 refusal when malformed. The minimum length matters for security:
-     * see IDEMPOTENCY_MIN_KEY_LENGTH.
-     */
-    readKey(ctx) {
-        const rawKey = ctx.post?.idempotencyKey;
-        if (rawKey === undefined || rawKey === null)
-            return null;
-        if (typeof rawKey !== "string" || rawKey.length < IDEMPOTENCY_MIN_KEY_LENGTH || rawKey.length > IDEMPOTENCY_MAX_KEY_LENGTH) {
-            const content = `Invalid idempotency key: must be a string of ${IDEMPOTENCY_MIN_KEY_LENGTH}-${IDEMPOTENCY_MAX_KEY_LENGTH} characters.`;
-            throw new LambderApiError(content, {
-                statusCode: 400,
-                errorMessage: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidIdempotencyKey, content },
-            });
-        }
-        return rawKey;
-    }
-    /**
-     * The record's scope. Session APIs scope per session, so even a leaked
-     * key cannot cross users. Public APIs scope by the key alone: the key is
-     * required to be long (and documented to be random), and identity proxies
-     * like the client IP are deliberately NOT part of the scope, because the
-     * retry idempotency exists for (a timeout followed by a network change)
-     * frequently arrives from a different IP.
-     */
-    scopeOf(apiName, ctx, key) {
-        const sessionKey = ctx.session?.sessionKey;
-        return `${sessionKey ? `s:${sessionKey}` : "k"}|${apiName}|${key}`;
-    }
-    /**
-     * Replay fast path, run BEFORE rate limits and guards: a completed record
-     * answers with its stored response so a legitimate retry neither burns
-     * rate-limit quota nor re-runs guards (the original already passed them,
-     * and no handler executes). Misses fall through to the normal pipeline;
-     * store errors follow the failOpen setting.
-     */
-    async findReplay(apiName, ctx) {
-        const store = this.store;
-        if (!store)
-            return null;
-        const key = this.readKey(ctx);
-        if (key === null)
-            return null;
-        try {
-            const done = await store.peek(this.scopeOf(apiName, ctx, key));
-            if (!done)
-                return null;
-            return new LambderResponse({
-                statusCode: done.statusCode,
-                headers: done.headers,
-                body: done.body,
-            });
-        }
-        catch (err) {
-            if (this.failOpen)
-                return null;
-            throw err;
-        }
-    }
-    /**
-     * Idempotency wrapper around validation-passed handler execution. Without
-     * a client idempotencyKey the handler just runs; with one, the scope
-     * (identity + api + key) is claimed atomically: duplicates of an
-     * in-flight original refuse with 409, replays of a completed one return
-     * the stored response verbatim, and a crashed original releases its claim
-     * so a retry actually retries.
-     */
-    async withIdempotency(apiName, ctx, config, exec) {
-        const store = this.store;
-        if (!store)
-            return await exec();
-        const rawKey = this.readKey(ctx);
-        if (rawKey === null)
-            return await exec();
-        const ttlSeconds = (typeof config === "object" ? config.ttlSeconds : undefined) ?? this.defaultTtlSeconds;
-        const scopeKey = this.scopeOf(apiName, ctx, rawKey);
-        let begun;
-        try {
-            begun = await store.begin(scopeKey, { pendingTtlSeconds: IDEMPOTENCY_PENDING_TTL_SECONDS });
-        }
-        catch (err) {
-            if (this.failOpen)
-                return await exec();
-            throw err;
-        }
-        if (begun.state === "pending") {
-            throw new LambderApiError(`Duplicate request for "${apiName}": the original is still processing.`, {
-                statusCode: 409,
-                errorMessage: { type: "warning", code: LAMBDER_REFUSAL_CODES.duplicateInFlight, content: "This request is already being processed." },
-            });
-        }
-        if (begun.state === "done") {
-            return new LambderResponse({
-                statusCode: begun.statusCode,
-                headers: begun.headers,
-                body: begun.body,
-            });
-        }
-        const ownerToken = begun.ownerToken;
-        // Headers pushed via res.setHeader/res.addHeader (and session cookie
-        // writes) land on ctx accumulators and are applied AFTER this wrapper
-        // returns, so snapshot the baseline: entries added during exec belong
-        // to this response and must be stored with it, and a Set-Cookie among
-        // them makes the response uncacheable (replaying another request's
-        // cookies, e.g. session tokens, would be wrong).
-        const setBaseline = ctx._otherInternal.setHeaderFnAccumulator.length;
-        const addBaseline = ctx._otherInternal.addHeaderFnAccumulator.length;
-        // Store the response for replays when it qualifies, release the claim
-        // otherwise. Settle failures only surface when failing closed.
-        const settleClaim = async (response) => {
-            const execSetHeaders = ctx._otherInternal.setHeaderFnAccumulator.slice(setBaseline);
-            const execAddHeaders = ctx._otherInternal.addHeaderFnAccumulator.slice(addBaseline);
-            const setsCookie = response.getHeader("Set-Cookie") !== undefined
-                || [...execSetHeaders, ...execAddHeaders].some((h) => h.key.toLowerCase() === "set-cookie");
-            // The store owns the size decision: bodies are Brotli-compressed
-            // there, and only ones exceeding the item budget even compressed
-            // come back as "too-large".
-            const cacheable = response.statusCode < 500
-                && !setsCookie
-                && typeof response.body === "string"
-                && !response.isBodyBase64;
-            try {
-                if (cacheable) {
-                    // Merge during-exec accumulator headers into the stored
-                    // copy (same replace/append semantics the render pipeline
-                    // applies), so a replay reproduces the full header set.
-                    const storedResponse = new LambderResponse({
-                        statusCode: response.statusCode,
-                        headers: normalizeHeaders(response.headers),
-                        body: response.body,
-                    });
-                    for (const header of execSetHeaders)
-                        storedResponse.setHeader(header.key, header.value);
-                    for (const header of execAddHeaders)
-                        storedResponse.addHeader(header.key, header.value);
-                    const completion = await store.complete(scopeKey, ownerToken, {
-                        statusCode: response.statusCode,
-                        headers: storedResponse.headers,
-                        body: response.body,
-                        ttlSeconds,
-                    });
-                    if (completion !== "too-large")
-                        return;
-                    // Too large to replay: fall through to release the claim
-                    // so retries re-execute instead of 409ing.
-                }
-                await store.abandon(scopeKey, ownerToken);
-            }
-            catch (storeErr) {
-                // A failed complete() must not leave the pending claim
-                // dangling (it would 409 retries until the pending TTL).
-                try {
-                    await store.abandon(scopeKey, ownerToken);
-                }
-                catch { /* claim expires on its own */ }
-                if (!this.failOpen)
-                    throw storeErr;
-            }
-        };
-        try {
-            const response = await exec();
-            await settleClaim(response);
-            return response;
-        }
-        catch (err) {
-            // A thrown LambderResponse IS the response (res.die.*, throw
-            // res.api(...)): settle the claim like a returned one so its side
-            // effect replays, then rethrow so the pipeline emits it.
-            if (err instanceof LambderResponse) {
-                await settleClaim(err);
-                throw err;
-            }
-            // A real crash (or a thrown refusal like LambderApiError /
-            // refuse()) releases the claim so a retry actually retries. This
-            // is the deliberate rule: RESPONSES are stored and replayed,
-            // refusals delivered as returned envelopes included; EXCEPTIONS
-            // are not, so a thrown refusal re-executes on retry and the
-            // handler decides afresh. Pick the idiom accordingly.
-            try {
-                await store.abandon(scopeKey, ownerToken);
-            }
-            catch (cleanupErr) {
-                if (!this.failOpen)
-                    throw cleanupErr;
-            }
-            throw err;
-        }
-    }
-}

package/dist/policies/LambderApiPolicies.d.ts

@@ -1,42 +0,0 @@
-import type { LambderRenderContext } from "../core/LambderContext.js";
-import type LambderResolver from "../core/LambderResolver.js";
-import type { LambderResponse } from "../core/LambderResponse.js";
-import { type LambderApiGuard, type LambderGuardsOptionValue, type LambderInputValidationRefusal } from "./LambderApiGuards.js";
-import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderRateLimitOptionValue } from "./LambderApiRateLimits.js";
-import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
-/** The declarative options one API registration may carry. */
-type LambderApiPolicyOptions = {
-    rateLimit?: LambderRateLimitOptionValue;
-    guards?: LambderGuardsOptionValue;
-    idempotency?: unknown;
-};
-/**
- * Runtime side of the declarative API options: composes the three policy
- * subsystems (rate limits in ./LambderApiRateLimits.ts, guards in
- * ./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
- * the create() options (rateLimits, guards, idempotency) and the
- * per-API options.
- */
-export declare class LambderApiPolicyEngine {
-    private rateLimits;
-    private guards;
-    private idempotency;
-    /** `onInvalidInput` is Lambder's input-validation refusal, so preflight slices answer exactly like the API's own schema. */
-    constructor(onInvalidInput: LambderInputValidationRefusal);
-    setRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
-    addGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
-    setIdempotency(config: LambderApiIdempotencyConfig): void;
-    /** Startup validation of one API registration's declarative options. */
-    assertRegistration(apiName: string, mode: "public" | "session", options: LambderApiPolicyOptions): void;
-    /** Rate limits then guards, in declared order. Refusals throw (LambderApiError or a guard's own throw). */
-    runPreflight(apiName: string, ctx: LambderRenderContext, resolver: LambderResolver, options: LambderApiPolicyOptions): Promise<void>;
-    /** Idempotency replay fast path, run before the preflight: see LambderApiIdempotencyEngine.findReplay. */
-    findReplay(apiName: string, ctx: LambderRenderContext): Promise<LambderResponse | null>;
-    /** Idempotency claim/replay wrapper around handler execution: see LambderApiIdempotencyEngine.withIdempotency. */
-    withIdempotency(apiName: string, ctx: LambderRenderContext, config: boolean | {
-        ttlSeconds?: number;
-    }, exec: () => Promise<LambderResponse>): Promise<LambderResponse>;
-}
-export {};

package/dist/policies/LambderApiPolicies.js

@@ -1,52 +0,0 @@
-import { LambderApiGuardsEngine } from "./LambderApiGuards.js";
-import { LambderApiRateLimitsEngine } from "./LambderApiRateLimits.js";
-import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
-/**
- * Runtime side of the declarative API options: composes the three policy
- * subsystems (rate limits in ./LambderApiRateLimits.ts, guards in
- * ./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
- * the create() options (rateLimits, guards, idempotency) and the
- * per-API options.
- */
-export class LambderApiPolicyEngine {
-    rateLimits;
-    guards;
-    idempotency = new LambderApiIdempotencyEngine();
-    /** `onInvalidInput` is Lambder's input-validation refusal, so preflight slices answer exactly like the API's own schema. */
-    constructor(onInvalidInput) {
-        this.rateLimits = new LambderApiRateLimitsEngine(onInvalidInput);
-        this.guards = new LambderApiGuardsEngine(onInvalidInput);
-    }
-    setRateLimits(config) {
-        this.rateLimits.configure(config);
-    }
-    addGuards(guards) {
-        this.guards.addGuards(guards);
-    }
-    setIdempotency(config) {
-        this.idempotency.configure(config);
-    }
-    /** Startup validation of one API registration's declarative options. */
-    assertRegistration(apiName, mode, options) {
-        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 no idempotency store was configured at creation.`);
-        }
-    }
-    /** Rate limits then guards, in declared order. Refusals throw (LambderApiError or a guard's own throw). */
-    async runPreflight(apiName, ctx, resolver, options) {
-        await this.rateLimits.run(apiName, ctx, resolver, options.rateLimit);
-        await this.guards.run(ctx, resolver, options.guards);
-    }
-    /** Idempotency replay fast path, run before the preflight: see LambderApiIdempotencyEngine.findReplay. */
-    async findReplay(apiName, ctx) {
-        return await this.idempotency.findReplay(apiName, ctx);
-    }
-    /** Idempotency claim/replay wrapper around handler execution: see LambderApiIdempotencyEngine.withIdempotency. */
-    async withIdempotency(apiName, ctx, config, exec) {
-        return await this.idempotency.withIdempotency(apiName, ctx, config, exec);
-    }
-}

package/dist/policies/LambderApiRateLimits.d.ts

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

package/dist/policies/LambderApiRateLimits.js

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

package/dist/shared/LambderApiContract.d.ts

@@ -1,57 +0,0 @@
-/**
- * Lambder API Contract System
- *
- * Contracts are built via method chaining and inferred using typeof lambder.ApiContract
- */
-/**
- * Base shape for API contracts - used by LambderCaller and LambderMSW
- */
-export type ApiContractShape = Record<string, {
-    input: any;
-    output: any;
-    /** Present when the API declares guardInput-mode guards: guard name -> value the client must send via options.guardInputs. */
-    guardInputs?: any;
-    /**
-     * Present when the API declares guards: the `guards` option exactly as
-     * written at registration, so a client-side copy of "what does this API
-     * need" can be pinned to the server's own declaration with `satisfies`
-     * rather than kept honest by a test that reads the source.
-     */
-    guards?: any;
-}>;
-import type { LambderCrashDetail } from "./LambderCrashDetail.js";
-/** Envelope flags/channels the server may set beside (or instead of) the payload. */
-export type LambderApiResponseConfig = {
-    versionExpired?: boolean;
-    sessionExpired?: boolean;
-    notAuthorized?: boolean;
-    message?: any;
-    errorMessage?: any;
-    logList?: any[];
-    /**
-     * A crash described in full (name, message, stack, cause chain, where it
-     * happened), for a caller that is allowed to see it: a global error
-     * handler answering a trusted invoker sets it with describeCrash().
-     * LambderInvokeCaller reads it back as the cause of the error it throws;
-     * the browser caller ignores it.
-     */
-    crash?: LambderCrashDetail;
-};
-/** The API wire envelope both sides speak: res.api() emits it, LambderCaller parses it. */
-export type LambderApiResponse<T> = LambderApiResponseConfig & {
-    apiVersion?: string | null;
-    payload?: T | null;
-};
-/**
- * Helper type for merging new API into existing contract during chaining
- */
-export type MergeContract<Old, Name extends string, In, Out, GuardInputs = never, Guards = never> = Old & {
-    [K in Name]: ([GuardInputs] extends [never] ? {} : {
-        guardInputs: GuardInputs;
-    }) & ([Guards] extends [never] ? {} : {
-        guards: Guards;
-    }) & {
-        input: In;
-        output: Out;
-    };
-};