lambder 6.0.1 → 7.0.1

package/dist/client/LambderCaller.d.ts

@@ -1,19 +1,21 @@
-import { type LambderRequestCompressionOption } from '../shared/LambderRequestPayload.js';
-import type { ApiContractShape } from '../shared/LambderApiContract.js';
-import { type LambderApiOutcome, type LambderValidationError } from '../shared/LambderApiOutcome.js';
-import { type LambderCallOptionsArg, type LambderGuardInputsProviderOption } from '../shared/LambderCallOptions.js';
-export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError } from '../shared/LambderApiOutcome.js';
-export type { LambderProvidedGuardInputs, LambderGuardInputsProvider } from '../shared/LambderCallOptions.js';
-type VoidFunction = () => void | Promise<void>;
+import type { LambderAppRefusalMessage } from '../shared/wire/LambderApiRefusal.js';
+import { type LambderRequestCompressionOption } from '../shared/wire/LambderRequestPayload.js';
+import type { LambderApiContractShape } from '../shared/wire/LambderApiContract.js';
+import { type LambderApiOutcome, type LambderValidationError } from '../shared/wire/LambderApiOutcome.js';
+import { type LambderCallArgs, type LambderContractOutputOf, type LambderGuardInputsProviderOption, type LambderSharedCallOptions } from '../shared/wire/LambderCallOptions.js';
+import { type LambderApiTransport } from '../shared/transport/LambderApiTransport.js';
+export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError } from '../shared/wire/LambderApiOutcome.js';
+export type { LambderProvidedGuardInputs, LambderGuardInputsProvider } from '../shared/wire/LambderCallOptions.js';
+/** A handler told that something happened, with nothing to hand it. */
+type NotifyHandler = () => void | Promise<void>;
+/** One call in flight: pushed when it starts, removed when it settles, so the list is the in-flight list rather than a log of every call ever made. */
 type FetchTracker = {
     apiName: string;
-    done: boolean;
-    fetchEndCalled: boolean;
 };
 type EventHandlerFetchParams = {
     apiName: string;
     payload?: any;
-    headers?: Record<string, any>;
+    headers?: Record<string, string>;
 };
 type FetchStartEventHandler = (params: {
     fetchParams: EventHandlerFetchParams;
@@ -26,7 +28,9 @@ type FetchEndEventHandler = (params: {
 }) => void | Promise<void>;
 type ErrorHandler = (err: Error) => void | Promise<void>;
 type ValidationErrorHandler = (zodError: LambderValidationError) => (void | false) | Promise<(void | false)>;
-type MessageHandler = (message: any) => void | Promise<void>;
+type MessageHandler = (message: LambderAppRefusalMessage | string) => void | Promise<void>;
+/** The logListHandler option: an answer's logList, success or failure, when it has entries. The invoke caller's onLogList, for a browser. */
+export type LambderLogListHandler = (apiName: string, logList: unknown[]) => void | Promise<void>;
 /** One logical operation's rotating idempotency key: see LambderCaller.createIdempotencyKeyScope(). */
 export type LambderIdempotencyKeyScope = {
     /** The key for the operation currently in progress. */
@@ -34,45 +38,19 @@ export type LambderIdempotencyKeyScope = {
     /** Call after a confirmed success: the next operation is a new intent. Returns the new key. */
     rotate(): string;
 };
-/** Per-call options: request extras plus overrides for every constructor handler. */
-export type LambderCallOptions = {
-    headers?: Record<string, any>;
-    /** Abort the request after this many ms; overrides the constructor default. */
-    timeoutMs?: number;
-    /** External abort signal, combined with the timeout when both are set. */
-    signal?: AbortSignal;
-    /**
-     * Overrides the constructor's requestCompression for this call: `false`
-     * sends the payload plainly (a hot path where the CPU matters more than
-     * the bytes), `true` compresses it regardless of the size threshold.
-     * Either way a payload is only sent compressed when that is smaller.
-     */
-    compressRequest?: boolean;
-    /**
-     * Values for the API's guardInput-mode guards, keyed by guard name; sent
-     * beside the payload and consumed by the guards before validation. The
-     * typed contract makes this REQUIRED for APIs that declare such guards,
-     * except the guards a guardInputsProvider covers (these merge on top of
-     * the provider's values).
-     */
-    guardInputs?: Record<string, unknown>;
-    /**
-     * Replay-protection key for APIs declared idempotent on the server.
-     * Generate once per logical operation with createIdempotencyKey() and
-     * send the same key on retries: duplicates of an in-flight request
-     * refuse, and repeats of a completed one replay its stored response
-     * instead of re-executing. Must be UNGUESSABLE random (it scopes the
-     * replay record for logged-out clients) and at least 16 characters; the
-     * server refuses shorter keys with a 400.
-     */
-    idempotencyKey?: string;
-    versionExpiredHandler?: VoidFunction;
-    sessionExpiredHandler?: VoidFunction;
+/**
+ * Per-call options: the request extras both callers share (see
+ * LambderSharedCallOptions) plus an override for every constructor handler.
+ */
+export type LambderCallOptions = LambderSharedCallOptions & {
+    versionExpiredHandler?: NotifyHandler;
+    sessionExpiredHandler?: NotifyHandler;
     messageHandler?: MessageHandler;
     errorMessageHandler?: MessageHandler;
     apiInputValidationErrorHandler?: ValidationErrorHandler;
-    notAuthorizedHandler?: VoidFunction;
+    notAuthorizedHandler?: NotifyHandler;
     errorHandler?: ErrorHandler;
+    logListHandler?: LambderLogListHandler;
     fetchStartedHandler?: FetchStartEventHandler;
     fetchEndedHandler?: FetchEndEventHandler;
 };
@@ -82,12 +60,14 @@ type LambderCallerBaseOptions = {
     isCorsEnabled: boolean;
     /** Default per-request timeout in ms (none unless set; API Gateway caps around 29s, so ~30000 is a sensible value). Overridable per call. */
     timeoutMs?: number;
-    versionExpiredHandler?: VoidFunction;
-    sessionExpiredHandler?: VoidFunction;
+    versionExpiredHandler?: NotifyHandler;
+    sessionExpiredHandler?: NotifyHandler;
     messageHandler?: MessageHandler;
     errorMessageHandler?: MessageHandler;
-    notAuthorizedHandler?: VoidFunction;
+    notAuthorizedHandler?: NotifyHandler;
     errorHandler?: ErrorHandler;
+    /** Receives each answer's logList, with the API name. Default: console.log with a `[lambder]` prefix, one line per entry. */
+    logListHandler?: LambderLogListHandler;
     fetchStartedHandler?: FetchStartEventHandler;
     fetchEndedHandler?: FetchEndEventHandler;
     apiInputValidationErrorHandler?: ValidationErrorHandler;
@@ -103,6 +83,13 @@ type LambderCallerBaseOptions = {
      * Lambda's ~6MB invoke cap, which applies to the compressed bytes.
      */
     requestCompression?: LambderRequestCompressionOption;
+    /**
+     * How a call reaches the server. Default: fetch to apiPath
+     * (lambderFetchTransport, with CORS per isCorsEnabled). A mock runtime,
+     * an in-process Lambder handler, or a cookie-jar decorator over either
+     * are the other transports that ship; see LambderApiTransport.
+     */
+    transport?: LambderApiTransport;
 };
 /** Constructor options: the base options plus guardInputsProvider, mandatory once TProvided names guards. */
 export type LambderCallerOptions<TContract, TProvided extends string = never> = LambderCallerBaseOptions & LambderGuardInputsProviderOption<TContract, TProvided>;
@@ -110,13 +97,15 @@ export type LambderCallerOptions<TContract, TProvided extends string = never> =
  * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
  * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
  */
-export default class LambderCaller<TContract extends ApiContractShape = any, TProvidedGuards extends string = never> {
+export default class LambderCaller<TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never> {
     private isCorsEnabled;
     private apiPath;
     private apiVersion?;
     private timeoutMs?;
+    /** The calls currently in flight, in the order they started. */
     fetchTrackerList: FetchTracker[];
-    isLoading: boolean;
+    /** Whether any call is in flight. Derived, so it cannot drift from the list the way a separate flag did. */
+    get isLoading(): boolean;
     private versionExpiredHandler?;
     private sessionExpiredHandler?;
     private messageHandler?;
@@ -124,6 +113,7 @@ export default class LambderCaller<TContract extends ApiContractShape = any, TPr
     private notAuthorizedHandler?;
     private errorHandler?;
     private apiInputValidationErrorHandler?;
+    private logListHandler?;
     private fetchStartedHandler?;
     private fetchEndedHandler?;
     private guardInputsProvider?;
@@ -131,8 +121,11 @@ export default class LambderCaller<TContract extends ApiContractShape = any, TPr
     private sessionCsrfCookieKey;
     private sessionCookieDomain?;
     private requestCompression;
+    private transport;
     constructor(options: LambderCallerOptions<TContract, TProvidedGuards>);
     setSessionCookieKey(sessionTokenCookieKey: string, sessionCsrfCookieKey: string): void;
+    /** Replaces how calls reach the server: a mock runtime, an in-process handler, a decorated transport. */
+    setTransport(transport: LambderApiTransport): this;
     /**
      * A self-rotating idempotency key for a component or form that performs
      * the same logical operation repeatedly. `current` is the key for the
@@ -155,6 +148,11 @@ export default class LambderCaller<TContract extends ApiContractShape = any, TPr
      * confirmed success. Uses crypto.randomUUID when available and falls back
      * to a v4 UUID from getRandomValues, because randomUUID only exists in
      * secure contexts (plain-http LAN device testing lacks it).
+     *
+     * A runtime with neither throws rather than reaching for Math.random: the
+     * key must be UNGUESSABLE, since it is what scopes the replay record for a
+     * logged-out client, and a guessable one hands that client's stored
+     * response to whoever guesses it.
      */
     static createIdempotencyKey(): string;
     private clearSessionCookies;
@@ -162,9 +160,18 @@ export default class LambderCaller<TContract extends ApiContractShape = any, TPr
     private dispatch;
     /**
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
-     * instead of collapsing every failure to null. Never throws.
+     * instead of collapsing every failure to undefined. Never throws.
+     *
+     * The output is computed from the contract in the return type rather than
+     * taken as a type parameter, so a call site cannot replace it by
+     * annotating what it assigns to.
+     */
+    apiOutcome<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderCallOptions>): Promise<LambderApiOutcome<LambderContractOutputOf<TContract, TApiName>>>;
+    /**
+     * The payload on success, `undefined` on every failure except a
+     * structured refusal, which hands back whatever payload the envelope
+     * carried (usually null). Neither is distinguishable from a legitimately
+     * null or undefined payload: use apiOutcome() when that matters.
      */
-    apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: LambderCallOptionsArg<TContract, TApiName, TProvidedGuards, LambderCallOptions>): Promise<LambderApiOutcome<TOutput>>;
-    /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
-    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: LambderCallOptionsArg<TContract, TApiName, TProvidedGuards, LambderCallOptions>): Promise<TOutput | null | undefined>;
+    api<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderCallOptions>): Promise<LambderContractOutputOf<TContract, TApiName> | null | undefined>;
 }

package/dist/client/LambderCaller.js

@@ -1,8 +1,13 @@
 import Cookies from 'js-cookie';
-import { compressPayloadGzip, isRequestCompressionAvailable, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from '../shared/LambderRequestPayload.js';
-import { resolveCompressionOption } from '../shared/LambderCompressionOption.js';
-import { resolveApiOutcome } from '../shared/LambderApiOutcome.js';
-import { mergeGuardInputs, } from '../shared/LambderCallOptions.js';
+import { compressPayloadGzip, isRequestCompressionAvailable, resolveRequestCompressionMinBytes, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from '../shared/wire/LambderRequestPayload.js';
+import { resolveCompressionOption } from '../shared/wire/LambderCompressionOption.js';
+import { resolveApiOutcome } from '../shared/wire/LambderApiOutcome.js';
+import { mergeGuardInputs, } from '../shared/wire/LambderCallOptions.js';
+import { createCallAbort } from '../shared/util/LambderCallAbort.js';
+import { coerceToError } from '../shared/wire/LambderCrashDetail.js';
+import { isLambderTransportFailure } from '../shared/transport/LambderApiTransport.js';
+import { DEFAULT_SESSION_TOKEN_COOKIE_KEY, DEFAULT_SESSION_CSRF_COOKIE_KEY } from '../shared/wire/LambderSessionCookieNames.js';
+import { lambderFetchTransport } from './lambderFetchTransport.js';
 /**
  * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
  * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
@@ -12,8 +17,10 @@ export default class LambderCaller {
     apiPath;
     apiVersion;
     timeoutMs;
+    /** The calls currently in flight, in the order they started. */
     fetchTrackerList = [];
-    isLoading = false;
+    /** Whether any call is in flight. Derived, so it cannot drift from the list the way a separate flag did. */
+    get isLoading() { return this.fetchTrackerList.length > 0; }
     versionExpiredHandler;
     sessionExpiredHandler;
     messageHandler;
@@ -21,24 +28,27 @@ export default class LambderCaller {
     notAuthorizedHandler;
     errorHandler;
     apiInputValidationErrorHandler;
+    logListHandler;
     fetchStartedHandler;
     fetchEndedHandler;
     guardInputsProvider;
-    sessionTokenCookieKey = "LMDRSESSIONTKID";
-    sessionCsrfCookieKey = "LMDRSESSIONCSTK";
+    sessionTokenCookieKey = DEFAULT_SESSION_TOKEN_COOKIE_KEY;
+    sessionCsrfCookieKey = DEFAULT_SESSION_CSRF_COOKIE_KEY;
     sessionCookieDomain;
     requestCompression;
+    transport;
     constructor(options) {
         // The conditional provider option is resolved per instantiation;
         // inside the class it is read through the plain shape.
-        const { apiPath, apiVersion, isCorsEnabled = false, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, requestCompression, guardInputsProvider, } = options;
-        this.apiPath = apiPath ?? "/api";
+        const { apiPath, apiVersion, isCorsEnabled, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, logListHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, requestCompression, guardInputsProvider, transport, } = options;
+        this.apiPath = apiPath;
         this.apiVersion = apiVersion;
         this.isCorsEnabled = isCorsEnabled;
         this.timeoutMs = timeoutMs;
         this.sessionCookieDomain = sessionCookieDomain;
         // `?? false`: unlike the at-rest stores, this one is off unless asked for.
         this.requestCompression = resolveCompressionOption(requestCompression ?? false, DEFAULT_REQUEST_COMPRESSION_SETTINGS);
+        this.transport = transport ?? lambderFetchTransport({ cors: this.isCorsEnabled });
         this.versionExpiredHandler = versionExpiredHandler;
         this.sessionExpiredHandler = sessionExpiredHandler;
         this.messageHandler = messageHandler;
@@ -46,6 +56,7 @@ export default class LambderCaller {
         this.notAuthorizedHandler = notAuthorizedHandler;
         this.errorHandler = errorHandler;
         this.apiInputValidationErrorHandler = apiInputValidationErrorHandler;
+        this.logListHandler = logListHandler;
         this.fetchStartedHandler = fetchStartedHandler;
         this.fetchEndedHandler = fetchEndedHandler;
         this.guardInputsProvider = guardInputsProvider;
@@ -55,6 +66,11 @@ export default class LambderCaller {
         this.sessionTokenCookieKey = sessionTokenCookieKey;
         this.sessionCsrfCookieKey = sessionCsrfCookieKey;
     }
+    /** Replaces how calls reach the server: a mock runtime, an in-process handler, a decorated transport. */
+    setTransport(transport) {
+        this.transport = transport;
+        return this;
+    }
     /**
      * A self-rotating idempotency key for a component or form that performs
      * the same logical operation repeatedly. `current` is the key for the
@@ -83,20 +99,20 @@ export default class LambderCaller {
      * confirmed success. Uses crypto.randomUUID when available and falls back
      * to a v4 UUID from getRandomValues, because randomUUID only exists in
      * secure contexts (plain-http LAN device testing lacks it).
+     *
+     * A runtime with neither throws rather than reaching for Math.random: the
+     * key must be UNGUESSABLE, since it is what scopes the replay record for a
+     * logged-out client, and a guessable one hands that client's stored
+     * response to whoever guesses it.
      */
     static createIdempotencyKey() {
         const cryptoObj = globalThis.crypto;
         if (cryptoObj?.randomUUID)
             return cryptoObj.randomUUID();
+        if (!cryptoObj?.getRandomValues)
+            throw new Error("LambderCaller.createIdempotencyKey needs crypto.getRandomValues: an idempotency key must be unguessable, and this runtime offers no random source that is.");
         const bytes = new Uint8Array(16);
-        if (cryptoObj?.getRandomValues) {
-            cryptoObj.getRandomValues(bytes);
-        }
-        else {
-            for (let i = 0; i < 16; i += 1) {
-                bytes[i] = Math.floor(Math.random() * 256);
-            }
-        }
+        cryptoObj.getRandomValues(bytes);
         bytes[6] = (bytes[6] & 0x0f) | 0x40;
         bytes[8] = (bytes[8] & 0x3f) | 0x80;
         const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -104,7 +120,7 @@ export default class LambderCaller {
     }
     clearSessionCookies() {
         const domainOption = this.sessionCookieDomain;
-        const hostname = typeof window !== "undefined" ? window.location.hostname : "";
+        const hostname = globalThis.location?.hostname ?? "";
         const resolvedDomain = typeof domainOption === "function" ? domainOption(hostname) : domainOption;
         for (const key of [this.sessionTokenCookieKey, this.sessionCsrfCookieKey]) {
             // Host-only and domain-scoped cookies are distinct entries; clear both.
@@ -126,19 +142,31 @@ export default class LambderCaller {
         const notAuthorizedHandler = options?.notAuthorizedHandler ?? this.notAuthorizedHandler;
         const errorHandler = options?.errorHandler ?? this.errorHandler;
         const apiInputValidationErrorHandler = options?.apiInputValidationErrorHandler ?? this.apiInputValidationErrorHandler;
+        const logListHandler = options?.logListHandler ?? this.logListHandler;
         const fetchStartedHandler = options?.fetchStartedHandler ?? this.fetchStartedHandler;
         const fetchEndedHandler = options?.fetchEndedHandler ?? this.fetchEndedHandler;
         const headers = options?.headers;
-        const fetchTracker = { apiName, done: false, fetchEndCalled: false };
+        const fetchTracker = { apiName };
+        // Dropped the moment the call settles, and idempotently, since the
+        // finally block below runs for the paths fetchEnded never reaches.
+        // Left in, the list grew by one per call forever, and every handler
+        // call scanned all of it: a long-lived page paid more per call the
+        // longer it had been open.
+        const dropFetchTracker = () => {
+            const at = this.fetchTrackerList.indexOf(fetchTracker);
+            if (at !== -1)
+                this.fetchTrackerList.splice(at, 1);
+        };
+        let fetchEndCalled = false;
         const fetchEnded = async (fetchResult) => {
-            fetchTracker.done = true;
-            if (fetchTracker.fetchEndCalled || !fetchEndedHandler)
+            dropFetchTracker();
+            if (fetchEndCalled || !fetchEndedHandler)
                 return;
-            fetchTracker.fetchEndCalled = true;
+            fetchEndCalled = true;
             await fetchEndedHandler({
                 fetchParams: { apiName, payload, headers },
                 fetchResult,
-                activeFetchList: this.fetchTrackerList.filter(v => !v.done),
+                activeFetchList: [...this.fetchTrackerList],
             });
         };
         let errorHandlerCalled = false;
@@ -148,36 +176,33 @@ export default class LambderCaller {
             errorHandlerCalled = true;
             await errorHandler(err);
         };
-        // Timeout / abort wiring: the timeout gets its own controller chained
-        // to any external signal, so either source aborts the fetch.
-        const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
-        const externalSignal = options?.signal;
-        let timedOut = false;
-        let signal = externalSignal;
-        let timeoutId;
-        if (timeoutMs !== undefined) {
-            const controller = new AbortController();
-            if (externalSignal) {
-                if (externalSignal.aborted) {
-                    controller.abort(externalSignal.reason);
-                }
-                else {
-                    externalSignal.addEventListener("abort", () => controller.abort(externalSignal.reason), { once: true });
-                }
-            }
-            timeoutId = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
-            signal = controller.signal;
-        }
+        // Timeout and abort wiring, shared with LambderInvokeCaller so the two
+        // cannot drift on what a late or abandoned call means.
+        const abort = createCallAbort({ timeoutMs: options?.timeoutMs ?? this.timeoutMs, signal: options?.signal });
+        const signal = abort.signal;
+        /** Reports a call that was given up on, or null while it still stands. */
+        const abandonedOutcome = async (stage) => {
+            const failure = abort.abortFailure(stage);
+            if (!failure)
+                return null;
+            await fetchEnded(failure.error);
+            await reportError(failure.error);
+            const outcome = { ok: false, reason: failure.reason, error: failure.error };
+            return outcome;
+        };
         try {
             this.fetchTrackerList.push(fetchTracker);
             if (fetchStartedHandler)
                 await fetchStartedHandler({
                     fetchParams: { apiName, payload, headers, },
-                    activeFetchList: this.fetchTrackerList.filter(v => !v.done)
+                    activeFetchList: [...this.fetchTrackerList],
                 });
             const version = this.apiVersion;
+            // js-cookie reads nothing without a document, and there is no
+            // location outside a page: both are "" then, and a transport that
+            // carries a cookie jar fills the token in from it.
             const token = Cookies.get(this.sessionCsrfCookieKey) || "";
-            const siteHost = window.location.hostname;
+            const siteHost = globalThis.location?.hostname ?? "";
             // Provider values underneath, per-call values on top.
             const providedGuardInputs = this.guardInputsProvider
                 ? await this.guardInputsProvider(apiName)
@@ -188,45 +213,65 @@ export default class LambderCaller {
             // without CompressionStream always sends the payload plainly.
             // Nothing here runs (the extra stringify included) unless
             // compression is actually a possibility for this call.
-            const compressionMinBytes = options?.compressRequest === true ? 0
-                : options?.compressRequest === false ? null
-                    : this.requestCompression?.minBytes ?? null;
+            const compressionMinBytes = resolveRequestCompressionMinBytes(options?.compressRequest, this.requestCompression);
             const compressedPayload = compressionMinBytes !== null && payload !== undefined && isRequestCompressionAvailable()
                 ? await compressPayloadGzip(JSON.stringify(payload), compressionMinBytes)
                 : null;
-            let res;
+            // A call the site has already given up on does not reach the
+            // transport at all: honouring request.signal is the transport's
+            // obligation, and not every transport does.
+            const refused = await abandonedOutcome("beforeSending");
+            if (refused)
+                return refused;
+            let answer;
             try {
-                res = await fetch(this.apiPath, {
-                    method: 'POST', cache: 'no-cache',
-                    // Cross-origin API hosts need CORS mode and included credentials.
-                    mode: this.isCorsEnabled ? 'cors' : 'same-origin',
-                    credentials: this.isCorsEnabled ? 'include' : 'same-origin',
-                    redirect: 'follow', referrerPolicy: 'origin',
-                    headers: { 'Content-Type': 'application/json', ...(headers || {}) },
-                    body: JSON.stringify({
-                        apiName, version, token, siteHost,
-                        ...(compressedPayload ?? { payload }),
-                        ...(guardInputs !== undefined ? { guardInputs } : {}),
-                        ...(options?.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
-                    }),
+                answer = await this.transport({
+                    apiPath: this.apiPath,
+                    apiName, version, token, siteHost,
+                    csrfCookieKey: this.sessionCsrfCookieKey,
+                    ...(compressedPayload ? { compressed: compressedPayload } : { payload }),
+                    ...(guardInputs !== undefined ? { guardInputs } : {}),
+                    ...(options?.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
+                    ...(headers ? { headers } : {}),
                     ...(signal ? { signal } : {}),
                 });
             }
             catch (err) {
-                const wrappedError = err instanceof Error ? err : new Error("Request failed", { cause: err });
+                const wrappedError = coerceToError(err, "Request failed");
                 await fetchEnded(wrappedError);
                 await reportError(wrappedError);
-                return { ok: false, reason: timedOut ? 'timeout' : 'network', error: wrappedError };
+                // The caller's own abort wins, since only it knows about that.
+                // Otherwise a transport that named its reason is believed:
+                // "protocol" means something came back and was not an answer,
+                // which is what this caller already calls `server`.
+                const reason = abort.timedOut() ? 'timeout'
+                    : isLambderTransportFailure(err) && err.reason === 'protocol' ? 'server'
+                        : 'network';
+                return { ok: false, reason, error: wrappedError };
             }
+            // An answer that arrives after the call was given up on is not a
+            // success. A transport that ignores request.signal resolves late,
+            // and believing it would report ok on a 20ms timeoutMs 300ms in,
+            // handing the call site data it had already abandoned.
+            const late = await abandonedOutcome("afterAnswering");
+            if (late)
+                return late;
             // The reading of the answer is shared with LambderInvokeCaller;
             // only what to do about each outcome is this caller's.
-            const outcome = await resolveApiOutcome({
-                status: res.status,
-                statusText: res.statusText,
-                header: (name) => res.headers?.get?.(name) ?? null,
-                json: () => res.json(),
-                text: () => res.text(),
-            });
+            const outcome = await resolveApiOutcome(answer);
+            // Every answer's logs, surfaced once and before any branch that
+            // returns: the 500 whose global error handler attached a crash and
+            // a logList is the answer whose log trail is worth the most, and
+            // surfacing them under the envelope reads meant it was the one
+            // answer that never reached logListHandler at all.
+            const logList = outcome.logList;
+            if (logList?.length) {
+                if (logListHandler)
+                    await logListHandler(apiName, logList);
+                else
+                    for (const record of logList)
+                        console.log("[lambder]", record);
+            }
             if (!outcome.ok && outcome.reason === 'server') {
                 await fetchEnded(outcome.error);
                 await reportError(outcome.error);
@@ -242,13 +287,10 @@ export default class LambderCaller {
                 }
                 return outcome;
             }
+            // Whatever is left carries the envelope: a success or one of the
+            // envelope's own refusals, which is why no assertion is needed.
             const data = outcome.response;
             await fetchEnded(data);
-            if (data.logList?.length) {
-                for (const record of data.logList) {
-                    console.log("[lambder]", record);
-                }
-            }
             if (!outcome.ok && outcome.reason === 'versionExpired') {
                 if (versionExpiredHandler) {
                     await versionExpiredHandler();
@@ -277,11 +319,13 @@ export default class LambderCaller {
                 }
                 return outcome;
             }
-            if (data.message && messageHandler) {
+            // Presence, not truthiness: the envelope keeps a message an app
+            // spelled out as the empty string, so the handler runs for it.
+            if (data.message !== undefined && messageHandler) {
                 await messageHandler(data.message);
             }
             if (!outcome.ok && outcome.reason === 'errorMessage') {
-                if (errorMessageHandler) {
+                if (errorMessageHandler && data.errorMessage !== undefined) {
                     await errorMessageHandler(data.errorMessage);
                 }
                 return outcome;
@@ -291,7 +335,7 @@ export default class LambderCaller {
         catch (err) {
             // Escape hatch for anything above (typically an app handler throwing):
             // dispatch never throws, so api()/apiOutcome() call sites never do.
-            const wrappedError = err instanceof Error ? err : new Error("Error: ", { cause: err });
+            const wrappedError = coerceToError(err, "The call failed before it produced an outcome");
             try {
                 await fetchEnded(wrappedError);
                 await reportError(wrappedError);
@@ -300,25 +344,38 @@ export default class LambderCaller {
             return { ok: false, reason: 'unknown', error: wrappedError };
         }
         finally {
-            fetchTracker.done = true;
-            if (timeoutId !== undefined)
-                clearTimeout(timeoutId);
+            dropFetchTracker();
+            abort.detach();
         }
     }
     ;
     /**
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
-     * instead of collapsing every failure to null. Never throws.
+     * instead of collapsing every failure to undefined. Never throws.
+     *
+     * The output is computed from the contract in the return type rather than
+     * taken as a type parameter, so a call site cannot replace it by
+     * annotating what it assigns to.
      */
-    async apiOutcome(apiName, payload, ...rest) {
-        return await this.dispatch(apiName, payload, rest[0]);
+    async apiOutcome(apiName, ...rest) {
+        // The tuple is a conditional type on an unresolved TApiName, so its
+        // elements read as unknown from inside; the contract shaped them on
+        // the way in, which is where the guarantee belongs.
+        const [payload, options] = rest;
+        return await this.dispatch(apiName, payload, options);
     }
     ;
-    /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
-    async api(apiName, payload, ...rest) {
-        const outcome = await this.dispatch(apiName, payload, rest[0]);
+    /**
+     * The payload on success, `undefined` on every failure except a
+     * structured refusal, which hands back whatever payload the envelope
+     * carried (usually null). Neither is distinguishable from a legitimately
+     * null or undefined payload: use apiOutcome() when that matters.
+     */
+    async api(apiName, ...rest) {
+        const [payload, options] = rest;
+        const outcome = await this.dispatch(apiName, payload, options);
         if (outcome.ok)
-            return outcome.response?.payload;
-        return outcome.reason === 'errorMessage' ? outcome.response?.payload : undefined;
+            return outcome.payload;
+        return outcome.reason === 'errorMessage' ? outcome.response.payload : undefined;
     }
 }

package/dist/client/lambderFetchTransport.d.ts

@@ -0,0 +1,9 @@
+import type { LambderApiTransport } from "../shared/transport/LambderApiTransport.js";
+/**
+ * The production transport: one POST of the envelope to the API path over
+ * fetch, with the cookie and CORS behaviour a browser call needs. The
+ * caller's default, built from its isCorsEnabled option.
+ */
+export declare const lambderFetchTransport: (options?: {
+    cors?: boolean;
+}) => LambderApiTransport;