lambder 7.3.1 → 8.0.2

package/dist/shared/wire/LambderApiOutcome.js

@@ -5,47 +5,65 @@
  * 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.
+ * Both hand their answer to resolveApiOutcome and act on the result; their
+ * side effects (handlers, cookie clearing, error reporting) stay with them.
+ * Pure and dependency-free, so the browser entry can include it.
  */
+import { refusalMessageOf } from "./LambderApiRefusal.js";
+/**
+ * Whether a parsed body is Lambder's envelope, which always carries
+ * apiVersion (null when the server set none). An object without it is
+ * somebody else's answer: API Gateway's own errors ({"message": ...} on a
+ * 413, a throttle, a WAF or missing-route 403, an authorizer 401, a 502 from
+ * a crashed function), a proxy's, a load balancer's.
+ */
+const isApiEnvelope = (value) => value !== null && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, "apiVersion");
 /**
  * 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.
+ * A failure read off any answer but a 422 carries the answer's Retry-After
+ * as retryAfterSeconds.
  */
 export const resolveApiOutcome = async (answer) => {
     const status = answer.status;
+    const errorMessageOf = (envelope) => envelope?.errorMessage !== undefined ? { errorMessage: refusalMessageOf(envelope.errorMessage) } : {};
+    // Retry-After (delta-seconds) rides every refusal that knows its reset
+    // time, e.g. a rate limit, and a 503 that says when to come back; absent
+    // or unreadable is undefined.
+    const retryAfterValue = Number(answer.header("retry-after") ?? NaN);
+    const retryAfter = Number.isFinite(retryAfterValue) && retryAfterValue >= 0 ? { retryAfterSeconds: retryAfterValue } : {};
     if (status >= 500) {
         // Lambder's own 500 fallback is a JSON envelope, but custom error
-        // handlers may answer text/HTML: parse defensively.
+        // handlers may answer text or HTML, and a gateway in front answers
+        // JSON of its own: parse defensively, and keep only the envelope, so
+        // a foreign body's fields never read as the app's message or crash.
         let envelope;
         try {
             const bodyText = await answer.text();
             try {
                 const parsed = JSON.parse(bodyText);
-                if (parsed !== null && typeof parsed === "object")
+                if (isApiEnvelope(parsed))
                     envelope = parsed;
             }
-            catch { /* not an envelope */ }
+            catch { /* not JSON */ }
         }
         catch { /* body unavailable */ }
         return {
             ok: false, reason: 'server', status,
-            errorMessage: envelope?.errorMessage,
+            ...errorMessageOf(envelope),
             logList: envelope?.logList,
             ...(envelope ? { response: envelope } : {}),
             error: new Error("Request failed: " + status + " - " + (answer.statusText ?? "")),
+            ...retryAfter,
         };
     }
     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.
-        // The validation body carries the call's logList as every other
-        // answer does, so it is read here rather than left on the wire.
+        // is a server failure, not a validation result. The validation body
+        // carries the call's logList like every other answer, so it is read.
         let body;
         try {
             body = await answer.json();
@@ -57,10 +75,6 @@ export const resolveApiOutcome = async (answer) => {
         }
         return { ok: false, reason: 'validation', status, zodError, logList: body?.logList };
     }
-    // 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();
@@ -69,18 +83,29 @@ export const resolveApiOutcome = async (answer) => {
     }
     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 }) };
+        return { ok: false, reason: 'server', status, error: new Error("Request failed: response is not a valid API envelope (status " + status + ")", { cause: err }), ...retryAfter };
+    }
+    // Read as envelopes, a gateway's own JSON errors would resolve as
+    // successes with no payload, so a refused save would look saved.
+    if (!isApiEnvelope(data)) {
+        const gatewayMessage = typeof data.message === "string" ? `: ${data.message}` : "";
+        return { ok: false, reason: 'server', status, error: new Error(`Request failed: ${status} - the answer is not a Lambder envelope${gatewayMessage}`), ...retryAfter };
     }
     if (data.versionExpired)
-        return { ok: false, reason: 'versionExpired', status, errorMessage: data.errorMessage, response: data, logList: data.logList, ...retryAfter };
+        return { ok: false, reason: 'versionExpired', status, ...errorMessageOf(data), response: data, logList: data.logList, ...retryAfter };
     if (data.sessionExpired)
-        return { ok: false, reason: 'sessionExpired', status, errorMessage: data.errorMessage, response: data, logList: data.logList, ...retryAfter };
+        return { ok: false, reason: 'sessionExpired', status, ...errorMessageOf(data), response: data, logList: data.logList, ...retryAfter };
     if (data.notAuthorized)
-        return { ok: false, reason: 'notAuthorized', status, errorMessage: data.errorMessage, response: data, logList: data.logList, ...retryAfter };
-    // Presence, not truthiness: the writer keeps an errorMessage an app spelled
-    // out as the empty string, so a refusal that says nothing is still a
-    // refusal. Tested for truth here, it shipped back as a success.
+        return { ok: false, reason: 'notAuthorized', status, ...errorMessageOf(data), response: data, logList: data.logList, ...retryAfter };
+    // Presence, not truthiness: the writer keeps an errorMessage an app set
+    // to the empty string, and a refusal that says nothing is still a
+    // refusal, not a success.
     if (data.errorMessage !== undefined)
-        return { ok: false, reason: 'errorMessage', status, errorMessage: data.errorMessage, response: data, logList: data.logList, ...retryAfter };
+        return { ok: false, reason: 'errorMessage', status, errorMessage: refusalMessageOf(data.errorMessage), response: data, logList: data.logList, ...retryAfter };
+    // An envelope that says nothing is wrong is still not a success when the
+    // status says otherwise.
+    if (status < 200 || status >= 300) {
+        return { ok: false, reason: 'server', status, response: data, logList: data.logList, error: new Error(`Request failed: ${status} - ${answer.statusText ?? ""}`), ...retryAfter };
+    }
     return { ok: true, payload: data.payload, response: data, logList: data.logList };
 };

package/dist/shared/wire/LambderApiRefusal.d.ts

@@ -3,9 +3,9 @@ export type LambderApiRefusalOptions = {
     /**
      * User-facing failure detail placed on the API envelope's `errorMessage`
      * field: a refusal message (`{ type: "warning", content: "..." }`, with
-     * an app's own `code`) or a plain string. Defaults to the error message
-     * string, so a bare `throw new LambderApiRefusal("...")` is still
-     * visible to the client.
+     * an app's own `code`) or a plain string, which becomes an "error"
+     * message with that content. Defaults to the error message, so a bare
+     * `throw new LambderApiRefusal("...")` is still visible to the client.
      */
     errorMessage?: LambderAppRefusalMessage | string;
     /** Sets the envelope's `notAuthorized` flag (routed to the caller's notAuthorizedHandler). */
@@ -26,18 +26,18 @@ export type LambderApiRefusalOptions = {
 /**
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
  * crashed". Throw it from anywhere in an API call's call stack (handlers,
- * hooks, or nested helpers that have no access to the per-request resolver)
- * and the render pipeline maps it onto the structured API envelope
+ * hooks, or nested helpers with no access to the per-request resolver) and
+ * the render pipeline maps it onto the structured API envelope
  * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
- * of routing it through setGlobalErrorHandler. Refusals therefore never reach
- * crash logging, and clients receive a parseable response they can surface.
+ * of routing it through setGlobalErrorHandler, so refusals never reach crash
+ * logging and clients receive a parseable response.
  *
  * Thrown outside an API call (e.g. in a route handler) it behaves like any
  * other error: global error handler, then the default 500.
  *
  * Isomorphic and dependency-free, so shared code (validators, permission
- * checks) may import and throw it from packages used by both server and
- * browser builds; in the browser it is just an Error.
+ * checks) used by both server and browser builds may throw it; in the
+ * browser it is just an Error.
  */
 export declare class LambderApiRefusal extends Error {
     /**
@@ -46,7 +46,8 @@ export declare class LambderApiRefusal extends Error {
      * across them while this marker does not. The pipeline checks the brand.
      */
     readonly isLambderApiRefusal = true;
-    readonly errorMessage?: LambderAppRefusalMessage | string;
+    /** What the envelope's errorMessage carries: always a message object, a plain string given to the options made into one. */
+    readonly errorMessage: LambderAppRefusalMessage;
     readonly notAuthorized?: boolean;
     readonly sessionExpired?: boolean;
     readonly statusCode?: LambderHttpStatusCode;
@@ -59,11 +60,11 @@ export declare const isLambderApiRefusal: (err: unknown) => err is LambderApiRef
  * The standard shape refusals carry on the envelope's errorMessage field.
  * `code` is the refusal's machine-readable identity: clients branch and
  * translate on it and never string-match `content`, which stays the
- * human-readable fallback for codes a client does not know yet. Apps keep
- * their own typed code vocabulary; the framework's own refusals carry a
- * LambderRefusalCode. The caller's errorMessageHandler receives the object
- * as-is, typed as LambderAppRefusalMessage or a plain string; an app's own
- * vocabulary goes in `code`.
+ * human-readable fallback for codes a client does not know yet. The
+ * framework's own refusals carry a LambderRefusalCode; apps put their own
+ * typed vocabulary in `code`. The caller's errorMessageHandler receives the
+ * object as-is, typed as LambderAppRefusalMessage; a server that wrote a
+ * plain string reaches it as `{ type: "error", content }` (refusalMessageOf).
  */
 export type LambderRefusalMessage<TAppCode extends string = never> = {
     type: "warning" | "error" | "info";
@@ -71,14 +72,13 @@ export type LambderRefusalMessage<TAppCode extends string = never> = {
      * Machine-readable identity of the refusal: a LambderRefusalCode, plus
      * whatever vocabulary the reader names in TAppCode.
      *
-     * Parameterized rather than widened with `string & {}`, because a union
-     * with `string` in it does not narrow: inside a `switch(message.code)`
-     * the case was not assignable and the `default: never` assertion failed,
-     * which is exactly the exhaustiveness the codes exist for. A client that
-     * reads its own vocabulary declares it
-     * (`LambderRefusalMessage<"app/not-verified" | ...>`) and gets a switch
-     * that is checked; a value an app WRITES takes LambderAppRefusalMessage,
-     * where any code is welcome.
+     * Parameterized rather than widened with `string & {}`: a union with
+     * `string` in it does not narrow, so a `switch(message.code)` could not
+     * end in a `default: never` exhaustiveness check, which is what the codes
+     * exist for. A client that reads its own vocabulary declares it
+     * (`LambderRefusalMessage<"app/not-verified" | ...>`) and gets a checked
+     * switch; a value an app WRITES takes LambderAppRefusalMessage, where any
+     * code is welcome.
      */
     code?: LambderRefusalCode | TAppCode;
     title?: string;
@@ -86,12 +86,22 @@ export type LambderRefusalMessage<TAppCode extends string = never> = {
 };
 /**
  * The refusal shape an app authors: any code, with the framework's own still
- * autocompleting. What every option that takes a message from an app is
- * typed as (a rate-limit policy's errorMessage, the mock's failure
- * injection); LambderRefusalMessage itself defaults to the framework's codes
- * alone, so a reader's switch over it is exhaustive.
+ * autocompleting. Every option that takes a message from an app is typed as
+ * this (a rate-limit policy's errorMessage, the mock's failure injection);
+ * LambderRefusalMessage itself defaults to the framework's codes alone, so a
+ * reader's switch over it is exhaustive.
  */
 export type LambderAppRefusalMessage = LambderRefusalMessage<string & {}>;
+/**
+ * An errorMessage as the one shape a reader handles: a plain string becomes
+ * an "error" message with that content, and a value that is not a message
+ * at all becomes one describing it. The envelope writer applies it, so a
+ * Lambder server only ever sends the object. A reader applies it too,
+ * because what it reads is wire input no server vouches for: a hand-built
+ * mock answer (an MSW handler, a test double) or a proxy that wrote its own
+ * body can put anything there.
+ */
+export declare const refusalMessageOf: (message: unknown) => LambderAppRefusalMessage;
 /**
  * Codes the framework stamps on the refusals it authors itself, under the
  * reserved `lambder/` prefix so app codes never collide. Compare against
@@ -103,6 +113,8 @@ export declare const LAMBDER_REFUSAL_CODES: {
     readonly rateLimited: "lambder/rate-limited";
     /** The original of an idempotent request is still processing (409). */
     readonly duplicateInFlight: "lambder/duplicate-in-flight";
+    /** The idempotencyKey was already used for a request with a different payload (409). */
+    readonly idempotencyKeyReused: "lambder/idempotency-key-reused";
     /** The idempotencyKey is malformed (400). */
     readonly invalidIdempotencyKey: "lambder/invalid-idempotency-key";
     /** No API is registered under the requested name. */

package/dist/shared/wire/LambderApiRefusal.js

@@ -1,18 +1,18 @@
 /**
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
  * crashed". Throw it from anywhere in an API call's call stack (handlers,
- * hooks, or nested helpers that have no access to the per-request resolver)
- * and the render pipeline maps it onto the structured API envelope
+ * hooks, or nested helpers with no access to the per-request resolver) and
+ * the render pipeline maps it onto the structured API envelope
  * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
- * of routing it through setGlobalErrorHandler. Refusals therefore never reach
- * crash logging, and clients receive a parseable response they can surface.
+ * of routing it through setGlobalErrorHandler, so refusals never reach crash
+ * logging and clients receive a parseable response.
  *
  * Thrown outside an API call (e.g. in a route handler) it behaves like any
  * other error: global error handler, then the default 500.
  *
  * Isomorphic and dependency-free, so shared code (validators, permission
- * checks) may import and throw it from packages used by both server and
- * browser builds; in the browser it is just an Error.
+ * checks) used by both server and browser builds may throw it; in the
+ * browser it is just an Error.
  */
 export class LambderApiRefusal extends Error {
     /**
@@ -21,6 +21,7 @@ export class LambderApiRefusal extends Error {
      * across them while this marker does not. The pipeline checks the brand.
      */
     isLambderApiRefusal = true;
+    /** What the envelope's errorMessage carries: always a message object, a plain string given to the options made into one. */
     errorMessage;
     notAuthorized;
     sessionExpired;
@@ -29,7 +30,7 @@ export class LambderApiRefusal extends Error {
     constructor(message, options = {}) {
         super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
         this.name = "LambderApiRefusal";
-        this.errorMessage = options.errorMessage ?? message;
+        this.errorMessage = refusalMessageOf(options.errorMessage ?? message);
         this.notAuthorized = options.notAuthorized;
         this.sessionExpired = options.sessionExpired;
         this.statusCode = options.statusCode;
@@ -38,6 +39,32 @@ export class LambderApiRefusal extends Error {
 }
 /** Brand-based type guard (see LambderApiRefusal.isLambderApiRefusal). */
 export const isLambderApiRefusal = (err) => err instanceof Error && err.isLambderApiRefusal === true;
+const REFUSAL_MESSAGE_TYPES = ["warning", "error", "info"];
+/**
+ * An errorMessage as the one shape a reader handles: a plain string becomes
+ * an "error" message with that content, and a value that is not a message
+ * at all becomes one describing it. The envelope writer applies it, so a
+ * Lambder server only ever sends the object. A reader applies it too,
+ * because what it reads is wire input no server vouches for: a hand-built
+ * mock answer (an MSW handler, a test double) or a proxy that wrote its own
+ * body can put anything there.
+ */
+export const refusalMessageOf = (message) => {
+    if (message !== null && typeof message === "object" && typeof message.content === "string") {
+        const candidate = message;
+        return REFUSAL_MESSAGE_TYPES.includes(candidate.type) ? candidate : { ...candidate, type: "error" };
+    }
+    if (typeof message === "string")
+        return { type: "error", content: message };
+    let content;
+    try {
+        content = JSON.stringify(message) ?? String(message);
+    }
+    catch {
+        content = String(message);
+    }
+    return { type: "error", content };
+};
 /**
  * Codes the framework stamps on the refusals it authors itself, under the
  * reserved `lambder/` prefix so app codes never collide. Compare against
@@ -49,6 +76,8 @@ export const LAMBDER_REFUSAL_CODES = {
     rateLimited: "lambder/rate-limited",
     /** The original of an idempotent request is still processing (409). */
     duplicateInFlight: "lambder/duplicate-in-flight",
+    /** The idempotencyKey was already used for a request with a different payload (409). */
+    idempotencyKeyReused: "lambder/idempotency-key-reused",
     /** The idempotencyKey is malformed (400). */
     invalidIdempotencyKey: "lambder/invalid-idempotency-key",
     /** No API is registered under the requested name. */

package/dist/shared/wire/LambderApiSignature.d.ts

@@ -6,9 +6,8 @@ import type { z } from "zod";
  * the digest of its client-facing shape (apiSignatureOf, computed on the
  * server side). A caller given the map sends the value with every call, and
  * the server answers versionExpired when it differs from the digest of what
- * it serves now. So a client built against an endpoint that has since
- * changed reloads, while one whose endpoint is unchanged keeps working
- * across deploys.
+ * it serves, so a client reloads only when an endpoint it calls has changed
+ * and otherwise keeps working across deploys.
  *
  * Keys are hashed so the map lists no endpoint names: the names a client
  * calls are in its own code already, and the rest of the surface stays out
@@ -26,14 +25,12 @@ export declare const API_SIGNATURE_HEX_LENGTH = 16;
  * name, cut to API_SIGNATURE_HEX_LENGTH hex characters. Async because
  * WebCrypto's digest is, and it is the only SHA-256 a browser has.
  *
- * Computed on the spot, every time, and nothing is kept. The digest that
- * actually describes an endpoint is the generator's, computed once at build
- * time; what is left here is one hash of a short name against a map already
- * in memory, which is nothing beside the request it belongs to. A cache of
- * it would have to be keyed by name, and on the server the name comes off
- * the wire before anything has checked that it is an endpoint at all, so it
- * would grow by an entry for every name a request cared to invent and never
- * shrink.
+ * Computed on the spot every time, with nothing kept. The digest that
+ * describes an endpoint is the generator's, computed once at build time;
+ * this is one hash of a short name, nothing beside the request it belongs
+ * to. A cache would be keyed by name, and on the server the name comes off
+ * the wire before anything checks that it is an endpoint, so the cache would
+ * gain an entry for every name a request cared to invent and never shrink.
  */
 export declare const apiNameKeyOf: (apiName: string) => Promise<string>;
 /** The map's signature for one endpoint, or null when the map holds none for it. */
@@ -59,23 +56,22 @@ export declare const EXTENSIBLE_ENUM_META_KEY = "x-lambder-extensible-enum";
  * widely returned payload (a session, a profile) then reloads only the
  * clients that send the list back, not every client that reads it.
  *
- * Where the enum is input its values still count: a value dropped from the
- * list is a request an older client may still send and the server now
- * refuses, so that endpoint's clients must reload. Everything else about the
- * schema is untouched: its type, its validation on both sides, and what it
- * is everywhere outside the digest.
+ * Where the enum is input its values still count: an older client may still
+ * send a value dropped from the list, which the server would refuse, so that
+ * endpoint's clients must reload. Everything else about the schema is
+ * untouched: its type, its validation on both sides, and what it is outside
+ * the digest.
  *
  * The mark is a promise the schema makes for its readers, and nothing checks
  * it. A client that switches over every value with no fallback, or indexes a
- * map by one, renders a value it does not know as nothing, or throws. Mark
- * only a list every reader handles that way on purpose.
+ * map by one, renders an unknown value as nothing, or throws. Mark only a
+ * list whose every reader handles an unknown value on purpose.
  *
  * It is zod metadata (`.meta()`), which zod keeps in one registry on
  * globalThis, so an enum marked in a shared package is read by the digest
- * even when the server resolves another copy of zod. A schema derived from a
- * marked enum by rebuilding it (`z.enum(marked.options)`, `.exclude()`)
- * carries no mark and counts in full, which costs a reload, never a missed
- * one.
+ * even when the server resolves another copy of zod. A schema rebuilt from a
+ * marked enum (`z.enum(marked.options)`, `.exclude()`) carries no mark and
+ * counts in full, which costs a reload, never a missed one.
  *
  * @example
  * export const RoleSchema = extensibleEnum(z.enum(["admin", "member"]));

package/dist/shared/wire/LambderApiSignature.js

@@ -12,14 +12,12 @@ const API_NAME_KEY_PREFIX = "lambder-api-name:";
  * name, cut to API_SIGNATURE_HEX_LENGTH hex characters. Async because
  * WebCrypto's digest is, and it is the only SHA-256 a browser has.
  *
- * Computed on the spot, every time, and nothing is kept. The digest that
- * actually describes an endpoint is the generator's, computed once at build
- * time; what is left here is one hash of a short name against a map already
- * in memory, which is nothing beside the request it belongs to. A cache of
- * it would have to be keyed by name, and on the server the name comes off
- * the wire before anything has checked that it is an endpoint at all, so it
- * would grow by an entry for every name a request cared to invent and never
- * shrink.
+ * Computed on the spot every time, with nothing kept. The digest that
+ * describes an endpoint is the generator's, computed once at build time;
+ * this is one hash of a short name, nothing beside the request it belongs
+ * to. A cache would be keyed by name, and on the server the name comes off
+ * the wire before anything checks that it is an endpoint, so the cache would
+ * gain an entry for every name a request cared to invent and never shrink.
  */
 export const apiNameKeyOf = async (apiName) => (await sha256HexOf(API_NAME_KEY_PREFIX + apiName)).slice(0, API_SIGNATURE_HEX_LENGTH);
 /** The map's signature for one endpoint, or null when the map holds none for it. */
@@ -57,23 +55,22 @@ export const EXTENSIBLE_ENUM_META_KEY = "x-lambder-extensible-enum";
  * widely returned payload (a session, a profile) then reloads only the
  * clients that send the list back, not every client that reads it.
  *
- * Where the enum is input its values still count: a value dropped from the
- * list is a request an older client may still send and the server now
- * refuses, so that endpoint's clients must reload. Everything else about the
- * schema is untouched: its type, its validation on both sides, and what it
- * is everywhere outside the digest.
+ * Where the enum is input its values still count: an older client may still
+ * send a value dropped from the list, which the server would refuse, so that
+ * endpoint's clients must reload. Everything else about the schema is
+ * untouched: its type, its validation on both sides, and what it is outside
+ * the digest.
  *
  * The mark is a promise the schema makes for its readers, and nothing checks
  * it. A client that switches over every value with no fallback, or indexes a
- * map by one, renders a value it does not know as nothing, or throws. Mark
- * only a list every reader handles that way on purpose.
+ * map by one, renders an unknown value as nothing, or throws. Mark only a
+ * list whose every reader handles an unknown value on purpose.
  *
  * It is zod metadata (`.meta()`), which zod keeps in one registry on
  * globalThis, so an enum marked in a shared package is read by the digest
- * even when the server resolves another copy of zod. A schema derived from a
- * marked enum by rebuilding it (`z.enum(marked.options)`, `.exclude()`)
- * carries no mark and counts in full, which costs a reload, never a missed
- * one.
+ * even when the server resolves another copy of zod. A schema rebuilt from a
+ * marked enum (`z.enum(marked.options)`, `.exclude()`) carries no mark and
+ * counts in full, which costs a reload, never a missed one.
  *
  * @example
  * export const RoleSchema = extensibleEnum(z.enum(["admin", "member"]));

package/dist/shared/wire/LambderCallOptions.d.ts

@@ -1,14 +1,14 @@
 /**
- * The per-call options both callers take, the contract-driven typing of a
- * call's arguments, 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.
+ * The per-call options, the contract-driven typing of a call's arguments, 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 cannot drift. Pure types and one dependency-free
+ * function, so the browser entry resolves it.
  */
 import type { LambderContractIdempotencyOf } from "./LambderApiContract.js";
+import type { LambderIdempotencyKeyScope } from "./LambderIdempotencyKeyScope.js";
 type IsAny<T> = 0 extends (1 & T) ? true : false;
 /**
  * The options every call takes, whichever caller sends it. Each caller adds
@@ -40,19 +40,22 @@ export type LambderSharedCallOptions = {
     /**
      * Replay-protection key for APIs declared idempotent on the server.
      * Generate once per logical operation with
-     * LambderCaller.createIdempotencyKey() and send the same key on retries:
+     * 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.
      *
-     * The typed contract makes this REQUIRED for an API whose entry declares
-     * `idempotency`, the way it does for guardInput values: a server
-     * declaration that reads as protection and silently provides none (the
-     * server runs a keyless call, which dedupes nothing) is exactly what the
-     * typed caller is for.
+     * REQUIRED by the typed contract for an API that declares `idempotency`,
+     * since the server runs a keyless call unprotected.
+     *
+     * A key scope (createIdempotencyKeyScope()) is the easier
+     * form: it rotates once an answer settles the operation, so a retry after
+     * a dropped connection reuses the key and the next attempt (a corrected
+     * form after a refusal included) gets a new one. See
+     * LambderIdempotencyKeyScope for which answers settle it.
      */
-    idempotencyKey?: string;
+    idempotencyKey?: string | LambderIdempotencyKeyScope;
 };
 /** The payload type one API of a contract takes; `any` for an untyped caller or a name the contract does not know. */
 type LambderContractInputOf<TContract, TApiName> = IsAny<TContract> extends true ? any : TApiName extends keyof TContract ? TContract[TApiName] extends {
@@ -80,12 +83,12 @@ export type LambderProvidedGuardInputs<TContract, TProvided extends string> = Is
 };
 /**
  * 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 do not require the
- * options argument. May be async; a throw fails the call as an unknown
- * error before anything is sent.
+ * 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 do not 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. */
@@ -117,11 +120,10 @@ type ContractGuardInputsField<TEntry, TProvided extends string> = [
  *
  * Read as "required unless it says false" rather than "required only when it
  * says true", so an entry whose option widened to `boolean` (declared through
- * a spread, or built in a helper) keeps the requirement instead of quietly
- * losing its compile-time half.
+ * a spread, or built in a helper) keeps the requirement at compile time.
  */
 type ContractIdempotencyKeyField<TContract, TApiName> = TApiName extends keyof TContract ? [LambderContractIdempotencyOf<TContract, TApiName>] extends [never] ? {} : [LambderContractIdempotencyOf<TContract, TApiName>] extends [false] ? {} : {
-    idempotencyKey: string;
+    idempotencyKey: string | LambderIdempotencyKeyScope;
 } : {};
 /**
  * What the contract adds to one call's options: the guardInputs field and the
@@ -131,41 +133,30 @@ type ContractCallFields<TContract, TApiName, TProvided extends string> = TApiNam
 /**
  * The options argument of one call: optional normally, REQUIRED when the
  * contract demands something of it, so forgetting a guard's value or an
- * idempotent API's key is a compile error at the call site rather than a 422
- * from the server or a replay that never happens. TOptions is the caller's own
- * per-call options type; the contract's fields are layered on top of it.
- *
- * `{} extends TFields` is the question "is every field the contract added
- * optional": an empty object is assignable to a type whose properties are all
- * optional and to nothing else.
+ * idempotent API's key is a compile error rather than a 422 or a replay that
+ * never happens. TOptions is the caller's own per-call options type.
+ * `{} extends TFields` asks "is every field the contract added optional".
  */
 type LambderCallOptionsArg<TContract, TApiName, TProvided extends string, TOptions extends {
     guardInputs?: Record<string, unknown>;
 }> = IsAny<TContract> extends true ? [options?: TOptions] : TApiName extends keyof TContract ? ContractCallFields<TContract, TApiName, TProvided> extends infer TFields ? {} extends TFields ? [options?: TOptions & TFields] : [options: TOptions & TFields] : never : [options?: TOptions];
 /**
  * Everything one call passes after the API name: the payload, then the
- * options, both decided by the contract.
- *
- * The payload is optional only when the API's input accepts undefined, so
- * `caller.api("getUser")` against `input: { id: string }` is a compile error
- * at the call site rather than a 422 from the server. Building it as one rest
- * tuple is what makes that possible: a plain optional parameter cannot be
- * made mandatory by a later type, and TypeScript has no per-argument
- * conditional otherwise.
- *
- * When the options argument is itself mandatory (an uncovered guardInput
- * guard, an idempotent API's key), the payload cannot stay optional in front
- * of it, since a tuple's required element may not follow an optional one.
- * Such a call passes its payload explicitly, `undefined` included.
+ * options, both decided by the contract. The payload is optional only when
+ * the API's input accepts undefined, so `caller.api("getUser")` against
+ * `input: { id: string }` fails to compile rather than drawing a 422. That
+ * needs one rest tuple, since TypeScript has no other per-argument
+ * conditional. When the options are mandatory, the payload cannot stay
+ * optional before them (a tuple's required element may not follow an
+ * optional one), so such a call passes it explicitly, `undefined` included.
  */
 export type LambderCallArgs<TContract, TApiName, TProvided extends string, TOptions extends {
     guardInputs?: Record<string, unknown>;
 }> = LambderCallOptionsArg<TContract, TApiName, TProvided, TOptions> extends [options: infer TRequired] ? [payload: LambderContractInputOf<TContract, TApiName>, options: TRequired] : LambderCallOptionsArg<TContract, TApiName, TProvided, TOptions> extends [options?: infer TOptional] ? undefined extends LambderContractInputOf<TContract, TApiName> ? [payload?: LambderContractInputOf<TContract, TApiName>, options?: TOptional] : [payload: LambderContractInputOf<TContract, TApiName>, options?: TOptional] : never;
 /**
  * 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.
+ * side supplied any. Synchronous 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 {};