lambder 5.1.2 → 6.0.1

package/dist/policies/LambderApiGuards.d.ts

@@ -36,7 +36,7 @@ import type { LambderResponse } from "../core/LambderResponse.js";
  * and the handler refuses by throwing (typically refuse()/LambderApiError).
  * Build with lambderGuard() so the handler's payload/ctx/param types line up.
  */
-export type LambderApiGuard<TInput extends z.ZodTypeAny = z.ZodTypeAny, TParam = any, TOutput = any> = {
+export type LambderApiGuard<TInput extends z.ZodType = z.ZodType, TParam = any, TOutput = any> = {
     apiInput: TInput;
     guardInput?: undefined;
     session?: boolean;
@@ -61,7 +61,7 @@ type GuardSessionCtx = LambderSessionRenderContext<any, any>;
  * inferred from the handler's 4th argument annotation; the output from its
  * return type.
  */
-export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+export declare function lambderGuard<TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
     apiInput: TInput;
     session: true;
     handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
@@ -71,7 +71,7 @@ export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undef
     session: true;
     handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
 };
-export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+export declare function lambderGuard<TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
     apiInput: TInput;
     handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
 }): {
@@ -80,7 +80,7 @@ export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undef
     session?: undefined;
     handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
 };
-export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+export declare function lambderGuard<TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
     guardInput: TInput;
     session: true;
     handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
@@ -90,7 +90,7 @@ export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undef
     session: true;
     handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
 };
-export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+export declare function lambderGuard<TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
     guardInput: TInput;
     handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
 }): {
@@ -126,11 +126,11 @@ type LambderGuardOutputOf<G> = G extends {
 } ? Awaited<R> : never;
 /** Per-guard metadata carried on the Lambder instance: input mode, session requirement, param type, output type. */
 export type LambderGuardMeta<G> = (G extends {
-    apiInput: infer S extends z.ZodTypeAny;
+    apiInput: infer S extends z.ZodType;
 } ? {
     apiInput: z.output<S>;
 } : G extends {
-    guardInput: infer S extends z.ZodTypeAny;
+    guardInput: infer S extends z.ZodType;
 } ? {
     guardInput: z.output<S>;
 } : {}) & (G extends {
@@ -237,7 +237,7 @@ export type LambderInputValidationRefusal = (ctx: LambderRenderContext, resolver
  * same one regular input validation answers. Shared with the rate-limit
  * engine's apiInput-keyed policies.
  */
-export declare const parsePreflightSlice: (input: z.ZodTypeAny, value: unknown, ctx: LambderRenderContext, resolver: LambderResolver, onInvalid: LambderInputValidationRefusal) => Promise<unknown>;
+export declare const parsePreflightSlice: (input: z.ZodType, value: unknown, ctx: LambderRenderContext, resolver: LambderResolver, onInvalid: LambderInputValidationRefusal) => Promise<unknown>;
 /**
  * Runtime side of the guards subsystem: holds the defined guards, asserts
  * API registrations against them at startup, and executes an API's declared

package/dist/policies/LambderApiRateLimits.d.ts

@@ -14,7 +14,7 @@ import { type LambderInputValidationRefusal } from "./LambderApiGuards.js";
  * stays the single owner of the field. Build with lambderRateLimitKey() so
  * the handler's payload type follows `apiInput`.
  */
-export type LambderRateLimitKeyFn<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
+export type LambderRateLimitKeyFn<TInput extends z.ZodType = z.ZodType> = {
     apiInput: TInput;
     handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
 } | {
@@ -26,7 +26,7 @@ export type LambderRateLimitKeyFn<TInput extends z.ZodTypeAny = z.ZodTypeAny> =
  * inside one literal. Returns the exact union member so type extraction can
  * see the schema.
  */
-export declare function lambderRateLimitKey<TInput extends z.ZodTypeAny>(key: {
+export declare function lambderRateLimitKey<TInput extends z.ZodType>(key: {
     apiInput: TInput;
     handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
 }): {
@@ -78,7 +78,7 @@ export type LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession exten
         per: "session";
     } ? (TIncludeSession extends true ? K : never) : TPolicies[K] extends {
         per: {
-            apiInput: infer S extends z.ZodTypeAny;
+            apiInput: infer S extends z.ZodType;
         };
     } ? (TPayload extends z.output<S> ? K : never) : K;
 }[keyof TPolicies] & string;

package/dist/session/LambderSessionManager.d.ts

@@ -78,7 +78,9 @@ export default class LambderSessionManager {
     private sessionSalt;
     private partitionKey;
     private sortKey;
-    private ddbDocumentClient;
+    private tableRegion;
+    /** The document client and the SDK it came from, created the first time the table is touched. */
+    private readyPromise;
     private enableSlidingExpiration;
     private slidingWriteIntervalSeconds;
     private dataRefresh;
@@ -94,6 +96,8 @@ export default class LambderSessionManager {
         dataRefresh?: LambderSessionDataRefreshConfig;
         compression?: LambderCompressionOption;
     });
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    private ready;
     private sessionUserKeyHasher;
     /**
      * At-rest hash for the bearer secrets (session sort-key secret, CSRF

package/dist/session/LambderSessionManager.js

@@ -1,7 +1,6 @@
 import crypto from "crypto";
-import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { DynamoDBDocumentClient, QueryCommand, DeleteCommand, PutCommand, GetCommand, UpdateCommand } from "@aws-sdk/lib-dynamodb";
-import { compressText, restoreBoundedText } from "../shared/LambderCompressionCodec.js";
+import { loadDynamoClientSdk, loadDynamoDocumentSdk } from "../stores/LambderDdbSdk.js";
+import { compressText, restoreText } from "../shared/LambderCompressionCodec.js";
 import { resolveCompressionOption, } from "../shared/LambderCompressionOption.js";
 /**
  * Session compression defaults: every record compressed (see
@@ -42,7 +41,9 @@ export default class LambderSessionManager {
     sessionSalt;
     partitionKey;
     sortKey;
-    ddbDocumentClient;
+    tableRegion;
+    /** The document client and the SDK it came from, created the first time the table is touched. */
+    readyPromise;
     enableSlidingExpiration;
     slidingWriteIntervalSeconds;
     dataRefresh;
@@ -56,8 +57,14 @@ export default class LambderSessionManager {
         this.slidingWriteIntervalSeconds = slidingWriteIntervalSeconds ?? null;
         this.dataRefresh = dataRefresh ?? null;
         this.compression = resolveCompressionOption(compression, SESSION_COMPRESSION_DEFAULTS);
-        const ddbClient = new DynamoDBClient({ region: tableRegion });
-        this.ddbDocumentClient = DynamoDBDocumentClient.from(ddbClient);
+        this.tableRegion = tableRegion;
+    }
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    ready() {
+        this.readyPromise ??= Promise.all([loadDynamoClientSdk("LambderSessionManager"), loadDynamoDocumentSdk("LambderSessionManager")])
+            .then(([clientSdk, sdk]) => ({ sdk, client: sdk.DynamoDBDocumentClient.from(new clientSdk.DynamoDBClient({ region: this.tableRegion })) }))
+            .catch((error) => { this.readyPromise = undefined; throw error; });
+        return this.readyPromise;
     }
     sessionUserKeyHasher(password) {
         return crypto.createHash("sha256")
@@ -81,7 +88,8 @@ export default class LambderSessionManager {
         return crypto.timingSafeEqual(new Uint8Array(bufferA), new Uint8Array(bufferB));
     }
     async ddbGetItem(key) {
-        const response = await this.ddbDocumentClient.send(new GetCommand({ TableName: this.tableName, Key: key, ConsistentRead: true }));
+        const { client, sdk } = await this.ready();
+        const response = await client.send(new sdk.GetCommand({ TableName: this.tableName, Key: key, ConsistentRead: true }));
         if (response.Item)
             return response.Item;
         return null;
@@ -102,11 +110,13 @@ export default class LambderSessionManager {
         else {
             item.data = data;
         }
-        return await this.ddbDocumentClient.send(new PutCommand({ TableName: this.tableName, Item: item, }));
+        const { client, sdk } = await this.ready();
+        return await client.send(new sdk.PutCommand({ TableName: this.tableName, Item: item, }));
     }
     ;
     async ddbDeleteItem(key) {
-        return await this.ddbDocumentClient.send(new DeleteCommand({ TableName: this.tableName, Key: key, }));
+        const { client, sdk } = await this.ready();
+        return await client.send(new sdk.DeleteCommand({ TableName: this.tableName, Key: key, }));
     }
     ;
     /** Sort keys of every session under a partition (the callers only need the keys). */
@@ -120,7 +130,8 @@ export default class LambderSessionManager {
         };
         const queryResults = [];
         do {
-            const { Items, LastEvaluatedKey } = await this.ddbDocumentClient.send(new QueryCommand(params));
+            const { client, sdk } = await this.ready();
+            const { Items, LastEvaluatedKey } = await client.send(new sdk.QueryCommand(params));
             if (Items)
                 queryResults.push(...Items);
             params.ExclusiveStartKey = LastEvaluatedKey;
@@ -133,7 +144,8 @@ export default class LambderSessionManager {
     async ddbDeleteAllByPartitionKey(partitionValue) {
         const queryResults = await this.ddbQueryAllByPartitionKey(partitionValue);
         for (const item of queryResults) {
-            await this.ddbDocumentClient.send(new DeleteCommand({
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.DeleteCommand({
                 TableName: this.tableName,
                 Key: { [this.partitionKey]: partitionValue, [this.sortKey]: item[this.sortKey] }
             }));
@@ -202,7 +214,7 @@ export default class LambderSessionManager {
         // that fails to decode throws, which the controller treats like any
         // malformed record: no session.
         if (session.dataBr) {
-            session.data = JSON.parse(await restoreBoundedText(session.dataBr, session.dataBytes, "br"));
+            session.data = JSON.parse(await restoreText(session.dataBr, "br", { declaredBytes: session.dataBytes }));
             delete session.dataBr;
             delete session.dataBytes;
         }
@@ -360,7 +372,8 @@ export default class LambderSessionManager {
         const now = Math.floor(Date.now() / 1000);
         for (const item of await this.ddbQueryAllByPartitionKey(partitionValue)) {
             try {
-                await this.ddbDocumentClient.send(new UpdateCommand({
+                const { client, sdk } = await this.ready();
+                await client.send(new sdk.UpdateCommand({
                     TableName: this.tableName,
                     Key: { [this.partitionKey]: partitionValue, [this.sortKey]: item[this.sortKey] },
                     UpdateExpression: "SET #dataExpiresAt = :now",

package/dist/shared/LambderApiContract.d.ts

@@ -19,6 +19,7 @@ export type ApiContractShape = Record<string, {
      */
     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;
@@ -27,6 +28,14 @@ export type LambderApiResponseConfig = {
     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 & {

package/dist/shared/LambderApiOutcome.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The one mapping from an HTTP answer to an API outcome.
+ *
+ * LambderCaller (a browser, over fetch) and LambderInvokeCaller (a server,
+ * over a direct Lambda invoke) receive the same envelope and must read it
+ * the same way: which status is a crash, which is a rejected input, in what
+ * order the envelope flags are honoured, what a non-envelope body means.
+ * Both hand their answer to resolveApiOutcome and act on the result; the
+ * side effects each has (handlers, cookie clearing, error reporting) stay
+ * with the caller that owns them. Pure and dependency-free, so the browser
+ * entry resolves it.
+ */
+import type { z } from "zod";
+import type { LambderApiResponse } from "./LambderApiContract.js";
+/**
+ * The 422 body's `zodError` as it survives JSON: a ZodError's name and
+ * message, and its issues spelled out. Not a ZodError instance (it has no
+ * methods on this side of the wire), which is why it is not typed as one.
+ */
+export type LambderValidationError = {
+    name: string;
+    message: string;
+    issues: z.core.$ZodIssue[];
+};
+export type LambderApiFailureReason = 'network' | 'timeout' | 'server' | 'validation' | 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'errorMessage' | 'unknown';
+/**
+ * Discriminated result of an API call: `ok: true` carries the payload, every
+ * failure carries a machine-readable reason, so "the server returned null"
+ * and "the request failed" are never conflated.
+ */
+export type LambderApiOutcome<T> = {
+    ok: true;
+    payload: T | null | undefined;
+    response: LambderApiResponse<T>;
+} | {
+    ok: false;
+    reason: LambderApiFailureReason;
+    /** HTTP status, when a response was received. */
+    status?: number;
+    /** Envelope errorMessage, when the server provided one. */
+    errorMessage?: any;
+    /** Seconds to wait before retrying, from the response's Retry-After header (rate-limit refusals send it). */
+    retryAfterSeconds?: number;
+    /** Underlying Error for network/timeout/server/unknown failures. */
+    error?: Error;
+    /** The issues for 'validation'. */
+    zodError?: LambderValidationError;
+    /** The parsed envelope, when one was received (protocol-level failures, and a 5xx that answered with Lambder's own envelope). */
+    response?: LambderApiResponse<T>;
+};
+/** What the mapping needs from an HTTP answer, whichever transport produced it. */
+export type LambderApiHttpAnswer = {
+    status: number;
+    statusText?: string;
+    /** Case-insensitive header lookup; null or undefined when absent. */
+    header: (name: string) => string | null | undefined;
+    /** The body parsed as JSON; rejects when it is not JSON. */
+    json: () => Promise<unknown>;
+    /** The body as text. */
+    text: () => Promise<string>;
+};
+/**
+ * Reads one HTTP answer into an outcome. A 5xx is a server failure that keeps
+ * the envelope when the server sent one (Lambder's own 500 body carries
+ * errorMessage, and a global error handler may add crash and logList); a
+ * 422 is a validation failure only with Lambder's validation body; anything
+ * else must be a JSON envelope, whose flags are honoured in a fixed order.
+ */
+export declare const resolveApiOutcome: <T>(answer: LambderApiHttpAnswer) => Promise<LambderApiOutcome<T>>;

package/dist/shared/LambderApiOutcome.js

@@ -0,0 +1,79 @@
+/**
+ * The one mapping from an HTTP answer to an API outcome.
+ *
+ * LambderCaller (a browser, over fetch) and LambderInvokeCaller (a server,
+ * over a direct Lambda invoke) receive the same envelope and must read it
+ * the same way: which status is a crash, which is a rejected input, in what
+ * order the envelope flags are honoured, what a non-envelope body means.
+ * Both hand their answer to resolveApiOutcome and act on the result; the
+ * side effects each has (handlers, cookie clearing, error reporting) stay
+ * with the caller that owns them. Pure and dependency-free, so the browser
+ * entry resolves it.
+ */
+/**
+ * Reads one HTTP answer into an outcome. A 5xx is a server failure that keeps
+ * the envelope when the server sent one (Lambder's own 500 body carries
+ * errorMessage, and a global error handler may add crash and logList); a
+ * 422 is a validation failure only with Lambder's validation body; anything
+ * else must be a JSON envelope, whose flags are honoured in a fixed order.
+ */
+export const resolveApiOutcome = async (answer) => {
+    const status = answer.status;
+    if (status >= 500) {
+        // Lambder's own 500 fallback is a JSON envelope, but custom error
+        // handlers may answer text/HTML: parse defensively.
+        let envelope;
+        try {
+            const bodyText = await answer.text();
+            try {
+                const parsed = JSON.parse(bodyText);
+                if (parsed !== null && typeof parsed === "object")
+                    envelope = parsed;
+            }
+            catch { /* not an envelope */ }
+        }
+        catch { /* body unavailable */ }
+        return {
+            ok: false, reason: 'server', status,
+            errorMessage: envelope?.errorMessage,
+            ...(envelope ? { response: envelope } : {}),
+            error: new Error("Request failed: " + status + " - " + (answer.statusText ?? "")),
+        };
+    }
+    if (status === 422) {
+        // A 422 without Lambder's validation body (e.g. a proxy's error page)
+        // is a server failure, not a validation result.
+        let zodError;
+        try {
+            zodError = (await answer.json())?.zodError;
+        }
+        catch { /* not JSON */ }
+        if (zodError === undefined) {
+            return { ok: false, reason: 'server', status, error: new Error("Request failed: 422 without a validation body") };
+        }
+        return { ok: false, reason: 'validation', status, zodError };
+    }
+    // Retry-After (delta-seconds) rides every refusal that knows its reset
+    // time, e.g. a rate limit; absent or unreadable is undefined.
+    const retryAfterValue = Number(answer.header("retry-after") ?? NaN);
+    const retryAfter = Number.isFinite(retryAfterValue) && retryAfterValue >= 0 ? { retryAfterSeconds: retryAfterValue } : {};
+    let data;
+    try {
+        data = await answer.json();
+        if (data === null || typeof data !== "object")
+            throw new Error("Response is not an object");
+    }
+    catch (err) {
+        // A non-envelope body (e.g. an HTML error page) is a server failure.
+        return { ok: false, reason: 'server', status, error: new Error("Request failed: response is not a valid API envelope (status " + status + ")", { cause: err }) };
+    }
+    if (data.versionExpired)
+        return { ok: false, reason: 'versionExpired', status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+    if (data.sessionExpired)
+        return { ok: false, reason: 'sessionExpired', status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+    if (data.notAuthorized)
+        return { ok: false, reason: 'notAuthorized', status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+    if (data.errorMessage)
+        return { ok: false, reason: 'errorMessage', status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+    return { ok: true, payload: data.payload, response: data };
+};

package/dist/shared/LambderCallOptions.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The contract-driven typing of a call's options argument, and the runtime
+ * merge of guard inputs, shared by the browser caller (LambderCaller) and the
+ * server-side invoke caller (LambderInvokeCaller). Both speak the same
+ * envelope to the same kind of contract, so what an API demands of its caller
+ * (a guardInput-mode guard's value, say) is decided here once and the two
+ * callers cannot drift on it. Pure types and one dependency-free function,
+ * so the browser entry resolves it.
+ */
+export type IsAny<T> = 0 extends (1 & T) ? true : false;
+export type GuardInputsOf<TEntry> = TEntry extends {
+    guardInputs: infer G;
+} ? G : never;
+/** Input type of guard G on one contract entry; never when that API does not declare it. */
+type GuardInputOf<TEntry, G extends string> = GuardInputsOf<TEntry> extends infer I ? (G extends keyof I ? I[G] : never) : never;
+/**
+ * What guardInputsProvider returns: for every provided guard name, the value
+ * the contract's APIs expect for it (a union across APIs when they differ).
+ * Naming a guard no API declares in guardInput mode resolves to never, so a
+ * typo fails the provider's return type instead of going missing at runtime.
+ */
+export type LambderProvidedGuardInputs<TContract, TProvided extends string> = IsAny<TContract> extends true ? Record<TProvided, unknown> : {
+    [G in TProvided]: {
+        [K in keyof TContract]: GuardInputOf<TContract[K], G>;
+    }[keyof TContract];
+};
+/**
+ * Supplies guardInputs for every call from one place (the organization the
+ * UI is on, a device token), keyed by guard name; per-call guardInputs
+ * merge on top. Name the guards it covers in the caller's second type
+ * parameter, `new LambderCaller<Contract, "orgPermission">`, and calls to
+ * APIs whose guardInput guards are all covered no longer require the
+ * options argument. May be async; a throw fails the call as an unknown
+ * error before anything is sent.
+ */
+export type LambderGuardInputsProvider<TContract, TProvided extends string> = (apiName: keyof TContract & string) => LambderProvidedGuardInputs<TContract, TProvided> | Promise<LambderProvidedGuardInputs<TContract, TProvided>>;
+/** Optional until the caller names provided guards: naming them without a provider would send nothing. */
+export type LambderGuardInputsProviderOption<TContract, TProvided extends string> = [
+    TProvided
+] extends [never] ? {
+    guardInputsProvider?: LambderGuardInputsProvider<TContract, TProvided>;
+} : {
+    guardInputsProvider: LambderGuardInputsProvider<TContract, TProvided>;
+};
+/** An API's guardInput guards the provider does not cover: those the call must still pass. */
+type RemainingGuardInputs<TEntry, TProvided extends string> = Omit<GuardInputsOf<TEntry>, TProvided>;
+/**
+ * The options argument of one call: optional normally, REQUIRED (with
+ * guardInputs) when the API's contract declares guardInput-mode guards the
+ * provider does not cover, so forgetting to send a guard's value is a
+ * compile error at the call site. Provided guards may still be overridden
+ * per call. TOptions is the caller's own per-call options type; the
+ * guardInputs requirement is layered on top of it.
+ */
+export type LambderCallOptionsArg<TContract, TApiName, TProvided extends string, TOptions extends {
+    guardInputs?: Record<string, unknown>;
+}> = IsAny<TContract> extends true ? [options?: TOptions] : TApiName extends keyof TContract ? [GuardInputsOf<TContract[TApiName]>] extends [never] ? [options?: TOptions] : [keyof RemainingGuardInputs<TContract[TApiName], TProvided>] extends [never] ? [options?: TOptions & {
+    guardInputs?: Partial<GuardInputsOf<TContract[TApiName]>>;
+}] : [
+    options: TOptions & {
+        guardInputs: RemainingGuardInputs<TContract[TApiName], TProvided> & Partial<GuardInputsOf<TContract[TApiName]>>;
+    }
+] : [options?: TOptions];
+/**
+ * Provider values underneath, per-call values on top; undefined when neither
+ * side supplied any. Synchronous on purpose: a caller awaits its provider
+ * only when it has one, so a call without a provider still issues its
+ * request in the same tick it was made.
+ */
+export declare const mergeGuardInputs: (provided: Record<string, unknown> | undefined, perCall: Record<string, unknown> | undefined) => Record<string, unknown> | undefined;
+export {};

package/dist/shared/LambderCallOptions.js

@@ -0,0 +1,16 @@
+/**
+ * The contract-driven typing of a call's options argument, and the runtime
+ * merge of guard inputs, shared by the browser caller (LambderCaller) and the
+ * server-side invoke caller (LambderInvokeCaller). Both speak the same
+ * envelope to the same kind of contract, so what an API demands of its caller
+ * (a guardInput-mode guard's value, say) is decided here once and the two
+ * callers cannot drift on it. Pure types and one dependency-free function,
+ * so the browser entry resolves it.
+ */
+/**
+ * Provider values underneath, per-call values on top; undefined when neither
+ * side supplied any. Synchronous on purpose: a caller awaits its provider
+ * only when it has one, so a call without a provider still issues its
+ * request in the same tick it was made.
+ */
+export const mergeGuardInputs = (provided, perCall) => provided !== undefined || perCall !== undefined ? { ...provided, ...perCall } : undefined;

package/dist/shared/LambderCompressionCodec.d.ts

@@ -3,10 +3,15 @@
  *
  * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotency
  * (Brotli at rest in DynamoDB), HTTP responses (Brotli or gzip, negotiated)
- * and request payloads (gzip, because the browser's CompressionStream
- * offers nothing else). They all compress text, so TEXT mode throughout,
- * and they all restore it the same way: the compressed bytes beside the
- * text's original UTF-8 byte length.
+ * and request payloads (gzip from a browser, whose CompressionStream offers
+ * nothing else; Brotli from a Node caller). They all compress text, so TEXT
+ * mode throughout, and they all restore it the same way: the compressed
+ * bytes beside the text's original UTF-8 byte length. The one restore
+ * without a declared length is a compressed HTTP answer read by
+ * LambderInvokeCaller, which passes a ceiling instead; both restores take
+ * either bound. That answer is also the one restore whose bytes may not be
+ * text at all, so the restore comes in two: restoreBytes returns the buffer
+ * and restoreText decodes it.
  *
  * That length is the safety mechanism, not bookkeeping. It bounds the
  * decompression, so a body that would expand without limit is cut off
@@ -48,8 +53,40 @@ export declare class LambderCompressionError extends Error {
  */
 export declare const compressText: (input: Buffer, encoding: LambderEncoding, quality: number) => Promise<Buffer>;
 /**
- * Restores text from compressed bytes beside the declared UTF-8 byte length
- * of the original, bounded and verified by that length. Throws
- * LambderCompressionError on anything it cannot vouch for.
+ * What bounds a restore: the text's declared UTF-8 byte length, stored
+ * beside the bytes (the decompression stops there and the result must match
+ * it exactly), or a ceiling alone, for bytes whose sender recorded no length
+ * (a compressed HTTP answer): the decompression stops there and nothing is
+ * verified.
  */
-export declare const restoreBoundedText: (compressed: Uint8Array, declaredBytes: number, encoding: LambderEncoding) => Promise<string>;
+export type LambderRestoreBound = {
+    declaredBytes: number;
+} | {
+    maxBytes: number;
+};
+/**
+ * Restores the original bytes from compressed bytes under a bound. With
+ * `declaredBytes` (records at rest, request payloads) the length both bounds
+ * the decompression and verifies it, so a body that would expand without
+ * limit is cut off rather than allocated, and a truncated or tampered input
+ * fails instead of decoding to something merely plausible. With `maxBytes`
+ * only the ceiling holds; truncation and corruption are what zlib's
+ * stream-end check and gzip's CRC catch. Throws LambderCompressionError on
+ * anything it cannot vouch for. A nonsense ceiling is the caller's
+ * configuration error and throws a plain Error.
+ *
+ * This is the restore for bytes that are not text: a compressed binary
+ * answer (a wasm module, an image a route forced compression on) read by
+ * LambderInvokeCaller. Text callers use restoreText, which is this plus the
+ * UTF-8 decode; going through a string would replace every byte that is not
+ * valid UTF-8 and hand back a body that is silently not what was sent.
+ */
+export declare const restoreBytes: (compressed: Uint8Array, encoding: LambderEncoding, bound: LambderRestoreBound) => Promise<Buffer>;
+/**
+ * Restores text: restoreBytes plus the UTF-8 decode. What every text caller
+ * uses (sessions, the DynamoDB stores, request payloads). The declared byte
+ * length a `declaredBytes` bound carries is the text's UTF-8 byte length,
+ * which is the restored buffer's length, so the verification is the same one
+ * either way.
+ */
+export declare const restoreText: (compressed: Uint8Array, encoding: LambderEncoding, bound: LambderRestoreBound) => Promise<string>;

package/dist/shared/LambderCompressionCodec.js

@@ -3,10 +3,15 @@
  *
  * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotency
  * (Brotli at rest in DynamoDB), HTTP responses (Brotli or gzip, negotiated)
- * and request payloads (gzip, because the browser's CompressionStream
- * offers nothing else). They all compress text, so TEXT mode throughout,
- * and they all restore it the same way: the compressed bytes beside the
- * text's original UTF-8 byte length.
+ * and request payloads (gzip from a browser, whose CompressionStream offers
+ * nothing else; Brotli from a Node caller). They all compress text, so TEXT
+ * mode throughout, and they all restore it the same way: the compressed
+ * bytes beside the text's original UTF-8 byte length. The one restore
+ * without a declared length is a compressed HTTP answer read by
+ * LambderInvokeCaller, which passes a ceiling instead; both restores take
+ * either bound. That answer is also the one restore whose bytes may not be
+ * text at all, so the restore comes in two: restoreBytes returns the buffer
+ * and restoreText decodes it.
  *
  * That length is the safety mechanism, not bookkeeping. It bounds the
  * decompression, so a body that would expand without limit is cut off
@@ -79,13 +84,30 @@ export const compressText = async (input, encoding, quality) => {
     });
 };
 /**
- * Restores text from compressed bytes beside the declared UTF-8 byte length
- * of the original, bounded and verified by that length. Throws
- * LambderCompressionError on anything it cannot vouch for.
+ * Restores the original bytes from compressed bytes under a bound. With
+ * `declaredBytes` (records at rest, request payloads) the length both bounds
+ * the decompression and verifies it, so a body that would expand without
+ * limit is cut off rather than allocated, and a truncated or tampered input
+ * fails instead of decoding to something merely plausible. With `maxBytes`
+ * only the ceiling holds; truncation and corruption are what zlib's
+ * stream-end check and gzip's CRC catch. Throws LambderCompressionError on
+ * anything it cannot vouch for. A nonsense ceiling is the caller's
+ * configuration error and throws a plain Error.
+ *
+ * This is the restore for bytes that are not text: a compressed binary
+ * answer (a wasm module, an image a route forced compression on) read by
+ * LambderInvokeCaller. Text callers use restoreText, which is this plus the
+ * UTF-8 decode; going through a string would replace every byte that is not
+ * valid UTF-8 and hand back a body that is silently not what was sent.
  */
-export const restoreBoundedText = async (compressed, declaredBytes, encoding) => {
-    if (!Number.isSafeInteger(declaredBytes) || declaredBytes <= 0) {
-        throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.missingLength, "compressed value is missing its byte length");
+export const restoreBytes = async (compressed, encoding, bound) => {
+    const verified = "declaredBytes" in bound;
+    const limit = verified ? bound.declaredBytes : bound.maxBytes;
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+        if (verified) {
+            throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.missingLength, "compressed value is missing its byte length");
+        }
+        throw new Error("restoreBytes: maxBytes must be a positive integer");
     }
     const zlib = await requireZlib();
     let output;
@@ -98,16 +120,24 @@ export const restoreBoundedText = async (compressed, declaredBytes, encoding) =>
                 resolve(result); };
             // maxOutputLength is the bound: zlib stops rather than allocating past it.
             if (encoding === "br")
-                zlib.brotliDecompress(compressed, { maxOutputLength: declaredBytes }, done);
+                zlib.brotliDecompress(compressed, { maxOutputLength: limit }, done);
             else
-                zlib.gunzip(compressed, { maxOutputLength: declaredBytes }, done);
+                zlib.gunzip(compressed, { maxOutputLength: limit }, done);
         });
     }
     catch (err) {
         throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.undecodable, "compressed value could not be decompressed", { cause: err });
     }
-    if (output.length !== declaredBytes) {
+    if (verified && output.length !== limit) {
         throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.lengthMismatch, "decompressed length does not match the declared length");
     }
-    return output.toString("utf8");
+    return output;
 };
+/**
+ * Restores text: restoreBytes plus the UTF-8 decode. What every text caller
+ * uses (sessions, the DynamoDB stores, request payloads). The declared byte
+ * length a `declaredBytes` bound carries is the text's UTF-8 byte length,
+ * which is the restored buffer's length, so the verification is the same one
+ * either way.
+ */
+export const restoreText = async (compressed, encoding, bound) => (await restoreBytes(compressed, encoding, bound)).toString("utf8");