lambder 8.0.2 → 8.1.1

package/dist/build.d.ts

@@ -1,9 +1,14 @@
 /**
  * Build entry point (`import ... from "lambder/build"`).
  *
- * What a generator script runs at build time over the app's own instance to
- * write the signature file both sides ship. Node-only and imported by nothing
- * else in the package, so no deployment or bundle carries it.
+ * What a generator script runs at build time to write the files a deployment
+ * ships: the signature file both sides read, from the app's own instance, and
+ * the contract a client compiles against, from the server's sources. Node-only
+ * and imported by nothing else in the package, so no deployment or bundle
+ * carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
 export type { LambderApiSignatureSource, LambderApiSignatureFileOptions, LambderApiSignatureFileResult, } from "./build/writeApiSignatures.js";
+export { writeApiContract } from "./build/writeApiContract.js";
+export type { LambderApiContractFileOptions, LambderApiContractFileResult, } from "./build/writeApiContract.js";
+export type { LambderModuleLocation } from "./build/moduleLocation.js";

package/dist/build.js

@@ -1,8 +1,11 @@
 /**
  * Build entry point (`import ... from "lambder/build"`).
  *
- * What a generator script runs at build time over the app's own instance to
- * write the signature file both sides ship. Node-only and imported by nothing
- * else in the package, so no deployment or bundle carries it.
+ * What a generator script runs at build time to write the files a deployment
+ * ships: the signature file both sides read, from the app's own instance, and
+ * the contract a client compiles against, from the server's sources. Node-only
+ * and imported by nothing else in the package, so no deployment or bundle
+ * carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
+export { writeApiContract } from "./build/writeApiContract.js";

package/dist/client/LambderUploadRunner.d.ts

@@ -0,0 +1,96 @@
+import { type LambderUploadFileFacts, type LambderUploadRule, type LambderUploadRuleVerdict, type LambderUploadTicket } from "../shared/contracts/LambderUploadBucket.js";
+/** Where an upload is, in order. `sentBytes` only moves during `uploading`. */
+export type LambderUploadPhase = "hashing" | "requesting" | "uploading" | "confirming";
+export type LambderUploadProgress = {
+    phase: LambderUploadPhase;
+    sentBytes: number;
+    totalBytes: number;
+};
+export type LambderUploadFailureReason = LambderUploadRuleVerdict
+/** The browser could not read the file (moved, deleted, or a cloud placeholder that never downloaded). */
+ | "fileUnreadable"
+/** The app's ticket endpoint would not issue a ticket. */
+ | "ticketRefused"
+/** Storage answered and said no, for a reason a retry cannot cure. */
+ | "storageRejected"
+/** Storage could not be reached, or kept stalling, through every attempt. */
+ | "networkFailed"
+/** The bytes are stored, and the app's confirm endpoint would not confirm them. */
+ | "confirmRefused" | "cancelled";
+/** How an upload failed: `reason` for a screen to word, the underlying error as `cause`. */
+export declare class LambderUploadError extends Error {
+    readonly reason: LambderUploadFailureReason;
+    constructor(reason: LambderUploadFailureReason, options?: {
+        cause?: unknown;
+        detail?: string;
+    });
+}
+export type LambderUploadRunnerOptions<Reference, Receipt> = {
+    uploadRule: LambderUploadRule;
+    /**
+     * The app's ticket endpoint. `reference` is whatever its confirm endpoint
+     * needs to find this upload again (the id of the record it made), and
+     * means nothing to the runner. `signal` is the upload's own, for the call
+     * to pass on so a cancel stops it too.
+     */
+    requestTicket: (fileFacts: LambderUploadFileFacts, call: {
+        signal: AbortSignal | undefined;
+    }) => Promise<{
+        ticket: LambderUploadTicket;
+        reference: Reference;
+    }>;
+    /** The app's confirm endpoint: the server checks the stored object and answers its record of it. */
+    confirmUpload: (reference: Reference, call: {
+        signal: AbortSignal | undefined;
+    }) => Promise<Receipt>;
+    /** The app's way of forgetting a confirmed upload the person removed again. Without one, discard() does nothing. */
+    discardUpload?: (receipt: Receipt) => Promise<void>;
+    /**
+     * How storage is tried again when it cannot be reached, stalls, or answers
+     * a failure a retry can cure (a 5xx, RequestTimeout, SlowDown). Each wait
+     * is a random time between `baseDelayMs` and a ceiling that doubles with
+     * every failed attempt, never past `maxDelayMs`, so many browsers dropped
+     * together do not come back in step. Default: 4 attempts, waits from one
+     * second to 15.
+     */
+    storageRetry?: {
+        attempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
+    /**
+     * How long a post may be open and move nothing before it counts as
+     * dropped. Default: 60 seconds. Watched where XMLHttpRequest exists,
+     * which reports a body's progress; a runtime with only fetch posts
+     * unwatched.
+     */
+    stallTimeoutMs?: number;
+};
+export declare class LambderUploadRunner<Reference, Receipt> {
+    private readonly options;
+    private readonly attempts;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly stallTimeoutMs;
+    constructor(options: LambderUploadRunnerOptions<Reference, Receipt>);
+    /** For a file input's `accept`, so the picker only offers what the rule takes. */
+    get acceptedTypes(): string;
+    get maxBytes(): number;
+    /** The rule's verdict on a file, or null when it may be uploaded. Costs nothing, so a screen can ask on drop. */
+    checkFile(file: Blob): LambderUploadRuleVerdict | null;
+    /**
+     * Uploads one file and answers the app's receipt, or throws a
+     * LambderUploadError. Aborting `signal` stops it wherever it is: the
+     * runner's own steps at once, and the app's calls as far as they pass
+     * the signal on.
+     */
+    upload(file: File, { onProgress, signal }?: {
+        onProgress?: (progress: LambderUploadProgress) => void;
+        signal?: AbortSignal;
+    }): Promise<Receipt>;
+    /** Forgets a confirmed upload through the app's endpoint, when it declared one. */
+    discard(receipt: Receipt): Promise<void>;
+    private waitBeforeRetry;
+    /** One post of the file to storage. Never throws: every ending is an outcome. */
+    private post;
+}

package/dist/client/LambderUploadRunner.js

@@ -0,0 +1,234 @@
+import { checkUploadRule, } from "../shared/contracts/LambderUploadBucket.js";
+import { sha256Base64Of } from "../shared/util/LambderTextDigest.js";
+/** How an upload failed: `reason` for a screen to word, the underlying error as `cause`. */
+export class LambderUploadError extends Error {
+    reason;
+    constructor(reason, options = {}) {
+        super(options.detail ? `${reason}: ${options.detail}` : reason, { cause: options.cause });
+        this.name = "LambderUploadError";
+        this.reason = reason;
+    }
+}
+/**
+ * How many times one upload asks for a new ticket because storage called the
+ * last one expired. A new ticket is asked for at once and spends no attempt
+ * at storage; the bound is for a clock so far off that every ticket arrives
+ * expired.
+ */
+const TICKET_RENEWAL_LIMIT = 2;
+/** S3's refusals that are the connection's or the service's fault rather than the file's, which its own SDK retries too. */
+const TRANSIENT_STORAGE_CODES = new Set(["RequestTimeout", "SlowDown", "InternalError", "ServiceUnavailable"]);
+export class LambderUploadRunner {
+    options;
+    attempts;
+    baseDelayMs;
+    maxDelayMs;
+    stallTimeoutMs;
+    constructor(options) {
+        this.options = options;
+        this.attempts = Math.max(1, options.storageRetry?.attempts ?? 4);
+        this.baseDelayMs = options.storageRetry?.baseDelayMs ?? 1_000;
+        this.maxDelayMs = options.storageRetry?.maxDelayMs ?? 15_000;
+        this.stallTimeoutMs = options.stallTimeoutMs ?? 60_000;
+    }
+    /** For a file input's `accept`, so the picker only offers what the rule takes. */
+    get acceptedTypes() {
+        return this.options.uploadRule.mimeTypes.join(",");
+    }
+    get maxBytes() {
+        return this.options.uploadRule.maxBytes;
+    }
+    /** The rule's verdict on a file, or null when it may be uploaded. Costs nothing, so a screen can ask on drop. */
+    checkFile(file) {
+        return checkUploadRule(this.options.uploadRule, { mimeType: file.type, byteSize: file.size });
+    }
+    /**
+     * Uploads one file and answers the app's receipt, or throws a
+     * LambderUploadError. Aborting `signal` stops it wherever it is: the
+     * runner's own steps at once, and the app's calls as far as they pass
+     * the signal on.
+     */
+    async upload(file, { onProgress, signal } = {}) {
+        const rejection = this.checkFile(file);
+        if (rejection)
+            throw new LambderUploadError(rejection);
+        const report = (phase, sentBytes = 0) => onProgress?.({ phase, sentBytes, totalBytes: file.size });
+        const stopIfCancelled = () => {
+            if (signal?.aborted)
+                throw new LambderUploadError("cancelled");
+        };
+        stopIfCancelled();
+        report("hashing");
+        let bytes;
+        try {
+            bytes = new Uint8Array(await file.arrayBuffer());
+        }
+        catch (cause) {
+            throw new LambderUploadError("fileUnreadable", { cause });
+        }
+        const fileFacts = {
+            fileName: file.name,
+            mimeType: file.type,
+            byteSize: file.size,
+            sha256Base64: await sha256Base64Of(bytes),
+        };
+        stopIfCancelled();
+        const requestTicket = async () => {
+            report("requesting");
+            try {
+                return await this.options.requestTicket(fileFacts, { signal });
+            }
+            catch (cause) {
+                throw new LambderUploadError(signal?.aborted ? "cancelled" : "ticketRefused", { cause });
+            }
+        };
+        let issued = await requestTicket();
+        let failedAttempts = 0;
+        let ticketRenewals = 0;
+        for (;;) {
+            stopIfCancelled();
+            report("uploading");
+            const outcome = await this.post(issued.ticket, file, signal, (sentBytes) => report("uploading", sentBytes));
+            if (outcome.kind === "stored")
+                break;
+            if (outcome.kind === "cancelled")
+                throw new LambderUploadError("cancelled");
+            if (outcome.kind === "rejected") {
+                // An expired ticket needs no wait and costs no attempt, only a
+                // new ticket; any other refusal is the file's, and final.
+                if (!outcome.ticketExpired || ++ticketRenewals > TICKET_RENEWAL_LIMIT)
+                    throw new LambderUploadError("storageRejected", { detail: outcome.detail });
+                issued = await requestTicket();
+                continue;
+            }
+            // The ticket is kept through a network retry, so a flaky
+            // connection does not leave the app a record per attempt.
+            if (++failedAttempts >= this.attempts)
+                throw new LambderUploadError("networkFailed");
+            await this.waitBeforeRetry(failedAttempts, signal);
+        }
+        report("confirming", file.size);
+        try {
+            return await this.options.confirmUpload(issued.reference, { signal });
+        }
+        catch (cause) {
+            throw new LambderUploadError(signal?.aborted ? "cancelled" : "confirmRefused", { cause });
+        }
+    }
+    /** Forgets a confirmed upload through the app's endpoint, when it declared one. */
+    async discard(receipt) {
+        await this.options.discardUpload?.(receipt);
+    }
+    waitBeforeRetry(failedAttempts, signal) {
+        const ceiling = Math.max(this.baseDelayMs, Math.min(this.baseDelayMs * 2 ** (failedAttempts - 1), this.maxDelayMs));
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted)
+                return reject(new LambderUploadError("cancelled"));
+            const cancel = () => {
+                clearTimeout(timer);
+                reject(new LambderUploadError("cancelled"));
+            };
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", cancel);
+                resolve();
+            }, this.baseDelayMs + Math.random() * (ceiling - this.baseDelayMs));
+            signal?.addEventListener("abort", cancel, { once: true });
+        });
+    }
+    /** One post of the file to storage. Never throws: every ending is an outcome. */
+    post(ticket, file, signal, onSent) {
+        if (signal?.aborted)
+            return Promise.resolve({ kind: "cancelled" });
+        const form = new FormData();
+        for (const [name, value] of Object.entries(ticket.formFields))
+            form.append(name, value);
+        // Storage ignores every field that comes after the file.
+        form.append("file", file);
+        return typeof XMLHttpRequest === "function"
+            ? postWithXhr(ticket.uploadUrl, form, file.size, this.stallTimeoutMs, signal, onSent)
+            : postWithFetch(ticket.uploadUrl, form, file.size, signal, onSent);
+    }
+}
+/** XMLHttpRequest rather than fetch where it exists: fetch cannot report how much of a request body has been sent. */
+const postWithXhr = (url, form, fileBytes, stallTimeoutMs, signal, onSent) => new Promise((resolve) => {
+    const request = new XMLHttpRequest();
+    let stalled = false;
+    let stallTimer;
+    const watchForStall = () => {
+        clearTimeout(stallTimer);
+        stallTimer = setTimeout(() => {
+            stalled = true;
+            request.abort();
+        }, stallTimeoutMs);
+    };
+    const cancel = () => request.abort();
+    const settle = (outcome) => {
+        clearTimeout(stallTimer);
+        signal?.removeEventListener("abort", cancel);
+        resolve(outcome);
+    };
+    request.upload.onprogress = (event) => {
+        watchForStall();
+        // `loaded` counts the form's own framing too, a little over the file.
+        onSent(Math.min(event.loaded, fileBytes));
+    };
+    request.onload = () => {
+        if (request.status >= 200 && request.status < 300)
+            return settle({ kind: "stored" });
+        if (request.status >= 500)
+            return settle({ kind: "unreachable" });
+        settle(rejectedOutcome(request.status, request.responseText));
+    };
+    request.onerror = () => settle({ kind: "unreachable" });
+    request.onabort = () => settle(stalled ? { kind: "unreachable" } : { kind: "cancelled" });
+    signal?.addEventListener("abort", cancel, { once: true });
+    watchForStall();
+    try {
+        request.open("POST", url);
+        request.send(form);
+    }
+    catch {
+        // A URL the browser will not open, or a request it will not send, answers nothing.
+        settle({ kind: "unreachable" });
+    }
+});
+const postWithFetch = async (url, form, fileBytes, signal, onSent) => {
+    let response;
+    try {
+        response = await fetch(url, { method: "POST", body: form, signal });
+    }
+    catch {
+        return signal?.aborted ? { kind: "cancelled" } : { kind: "unreachable" };
+    }
+    if (response.ok) {
+        onSent(fileBytes);
+        return { kind: "stored" };
+    }
+    if (response.status >= 500)
+        return { kind: "unreachable" };
+    return rejectedOutcome(response.status, await response.text().catch(() => ""));
+};
+const XML_ENTITIES = { amp: "&", lt: "<", gt: ">", quot: "\"", apos: "'" };
+const xmlText = (text) => text.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (entity, name) => {
+    if (name[0] !== "#")
+        return XML_ENTITIES[name] ?? entity;
+    const codePoint = Number(name[1]?.toLowerCase() === "x" ? `0${name.slice(1)}` : name.slice(1));
+    return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : entity;
+});
+/**
+ * Storage explains a refusal in XML, `<Error><Code/><Message/></Error>`,
+ * read here without a DOM so the runner works wherever fetch does. A
+ * transient code is tried again like a dropped connection, and an expired
+ * ticket is the one refusal a new ticket cures.
+ */
+const rejectedOutcome = (status, body) => {
+    const code = xmlText(/<Code>([^<]*)<\/Code>/.exec(body)?.[1] ?? "") || `HTTP ${status}`;
+    const message = xmlText(/<Message>([^<]*)<\/Message>/.exec(body)?.[1] ?? "");
+    if (TRANSIENT_STORAGE_CODES.has(code))
+        return { kind: "unreachable" };
+    return {
+        kind: "rejected",
+        ticketExpired: code === "AccessDenied" && /expired/i.test(message),
+        detail: message ? `${code}: ${message}` : code,
+    };
+};

package/dist/client.d.ts

@@ -36,3 +36,7 @@ export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtm
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
 export type { LambderHttpStatusCode } from "./shared/wire/LambderHttpStatus.js";
+export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";
+export type { LambderUploadRunnerOptions, LambderUploadProgress, LambderUploadPhase, LambderUploadFailureReason } from "./client/LambderUploadRunner.js";
+export { checkUploadRule } from "./shared/contracts/LambderUploadBucket.js";
+export type { LambderUploadRule, LambderUploadFileFacts, LambderUploadTicket, LambderUploadRuleVerdict } from "./shared/contracts/LambderUploadBucket.js";

package/dist/client.js

@@ -33,3 +33,7 @@ export { resolveCompressionOption } from "./shared/wire/LambderCompressionOption
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
 // Typed translations (standalone, isomorphic)
 export { createLambderI18n } from "./shared/LambderI18n.js";
+// Direct uploads: the runner that takes a file from the browser straight to
+// storage, and the vocabulary it shares with the server's bucket.
+export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";
+export { checkUploadRule } from "./shared/contracts/LambderUploadBucket.js";

package/dist/core/Lambder.d.ts

@@ -68,20 +68,19 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     /** The instance's file reader (source + caches), or null without the files option. */
     files: LambderFiles | null;
     /**
-     * Type property for extracting the API contract, to export your API
-     * types to the frontend.
+     * Type property for extracting the API contract: every registered API's
+     * input, output, mode and declared options, as a client calls it.
      *
-     * Export it as an interface extending LambderFlattenContract, not as a
-     * type alias. Chaining builds the contract as an intersection one member
-     * deep per endpoint; an interface collapses that into one declared set of
-     * members, which every generic read of the contract (a mock registry, a
-     * needs map, the typed caller) checks far more cheaply. See
-     * LambderFlattenContract for the measurements.
+     * A small app's client imports it as it is. It is an intersection one
+     * member deep per endpoint, so reading it generically costs a large app's
+     * client most of its type check; writeApiContract (lambder/build) reads
+     * this property off the exported instance and writes the contract out as
+     * plain types for such a client to import instead.
      *
      * @example
      * ```typescript
-     * const lambder = new Lambder().addApi(...).addApi(...);
-     * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
+     * export const lambder = initLambder().create({ ... }).addApi(...).addApi(...);
+     * export type ApiContractType = typeof lambder.ApiContract;
      * ```
      */
     readonly ApiContract: _TContract;

package/dist/core/Lambder.js

@@ -57,20 +57,19 @@ export default class Lambder {
     /** The instance's file reader (source + caches), or null without the files option. */
     files;
     /**
-     * Type property for extracting the API contract, to export your API
-     * types to the frontend.
+     * Type property for extracting the API contract: every registered API's
+     * input, output, mode and declared options, as a client calls it.
      *
-     * Export it as an interface extending LambderFlattenContract, not as a
-     * type alias. Chaining builds the contract as an intersection one member
-     * deep per endpoint; an interface collapses that into one declared set of
-     * members, which every generic read of the contract (a mock registry, a
-     * needs map, the typed caller) checks far more cheaply. See
-     * LambderFlattenContract for the measurements.
+     * A small app's client imports it as it is. It is an intersection one
+     * member deep per endpoint, so reading it generically costs a large app's
+     * client most of its type check; writeApiContract (lambder/build) reads
+     * this property off the exported instance and writes the contract out as
+     * plain types for such a client to import instead.
      *
      * @example
      * ```typescript
-     * const lambder = new Lambder().addApi(...).addApi(...);
-     * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
+     * export const lambder = initLambder().create({ ... }).addApi(...).addApi(...);
+     * export type ApiContractType = typeof lambder.ApiContract;
      * ```
      */
     ApiContract;

package/dist/index.d.ts

@@ -78,6 +78,16 @@ export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
 export type { LambderS3FileSourceOptions } from "./stores/LambderS3FileSource.js";
 export { LambderHttpFileSource } from "./stores/LambderHttpFileSource.js";
 export type { LambderHttpFileSourceOptions } from "./stores/LambderHttpFileSource.js";
+export { LambderS3UploadBucket } from "./stores/LambderS3UploadBucket.js";
+export type { LambderS3UploadBucketOptions } from "./stores/LambderS3UploadBucket.js";
+export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js";
+export type { LambderMemoryUploadBucketOptions, LambderMemoryUploadObject } from "./stores/LambderMemoryUploadBucket.js";
+export { checkUploadRule } from "./shared/contracts/LambderUploadBucket.js";
+export type { LambderUploadBucket, LambderUploadRule, LambderUploadFileFacts, LambderUploadTicket, LambderUploadVerdict, LambderUploadRuleVerdict, LambderUploadObjectOptions, LambderUploadContentDisposition, } from "./shared/contracts/LambderUploadBucket.js";
+export { LambderUploadFileFactsSchema, LambderUploadTicketSchema } from "./shared/wire/LambderUploadSchemas.js";
+export { refuseUnacceptedUpload } from "./shared/wire/LambderUploadRefusal.js";
+export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";
+export type { LambderUploadRunnerOptions, LambderUploadProgress, LambderUploadPhase, LambderUploadFailureReason } from "./client/LambderUploadRunner.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
 export type { LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
 export { resolveCompressionOption, LAMBDER_ENCODINGS } from "./shared/wire/LambderCompressionOption.js";
@@ -110,7 +120,7 @@ export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js
 export type { LambderGuardsOptionValue, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderFlattenContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderHttpEventFormat } from "./core/LambderContext.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";

package/dist/index.js

@@ -50,6 +50,14 @@ export { LambderFiles } from "./core/LambderFiles.js";
 export { LambderLocalFileSource } from "./stores/LambderLocalFileSource.js";
 export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
 export { LambderHttpFileSource } from "./stores/LambderHttpFileSource.js";
+// Direct uploads: storage a browser posts a file to with a ticket the server
+// signed, the schemas an app's ticket endpoint declares, and the browser runner.
+export { LambderS3UploadBucket } from "./stores/LambderS3UploadBucket.js";
+export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js";
+export { checkUploadRule } from "./shared/contracts/LambderUploadBucket.js";
+export { LambderUploadFileFactsSchema, LambderUploadTicketSchema } from "./shared/wire/LambderUploadSchemas.js";
+export { refuseUnacceptedUpload } from "./shared/wire/LambderUploadRefusal.js";
+export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";
 // Compression: the option every site shares, and the one codec behind them all.
 export { resolveCompressionOption, LAMBDER_ENCODINGS } from "./shared/wire/LambderCompressionOption.js";
 // Brotli/gzip plus the bounded, length-verified restore every compressed

package/dist/mock/lambderMockMswHandler.d.ts

@@ -1,8 +1,14 @@
 import { type LambderApiRequest } from "../api/LambderApiRequest.js";
 import type { LambderApiAnswer } from "../api/LambderApiAnswer.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
+/** What a resolver of Lambder's adapters is: msw's, answering a Response, or `undefined` to hand the request on. */
+type LambderMswResolver = (info: {
+    request: Request;
+}) => Promise<Response | undefined>;
 /**
- * The parts of the msw module the adapter uses: `import * as msw from "msw"`.
+ * The parts of the msw module Lambder's adapters use, `import * as msw from
+ * "msw"`: `http.post` for the API (lambderMockMswHandler) and `http.all` for
+ * an upload bucket's storage (lambderMockUploadMswHandler).
  *
  * Written so the real package satisfies it. msw's resolver answers a
  * Response, or `undefined` to hand the request back (its
@@ -12,9 +18,8 @@ import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
  */
 export type LambderMswModule = {
     http: {
-        post: (path: string, resolver: (info: {
-            request: Request;
-        }) => Promise<Response | undefined>) => unknown;
+        post: (path: string, resolver: LambderMswResolver) => unknown;
+        all: (path: string, resolver: LambderMswResolver) => unknown;
     };
     HttpResponse: {
         new (body?: BodyInit | null, init?: ResponseInit): Response;
@@ -101,3 +106,4 @@ export declare const lambderMockMswHandler: <M extends LambderMswModule>(mockApp
     /** The client IP its calls are read as arriving from. Default: the runtime's own defaultClientIp. */
     clientIp?: string;
 }) => ReturnType<M["http"]["post"]>;
+export {};

package/dist/mock/lambderMockUploadMswHandler.d.ts

@@ -0,0 +1,26 @@
+import type { LambderMemoryUploadBucket } from "../stores/LambderMemoryUploadBucket.js";
+import type { LambderMswModule } from "./lambderMockMswHandler.js";
+/**
+ * The MSW handler that makes a LambderMemoryUploadBucket the storage a mock
+ * app's browser uploads to: every request under the bucket's baseUrl (a
+ * LambderUploadRunner's post, a download link's GET) is answered by the
+ * bucket, the way S3 would answer it. Register it beside the API handler:
+ *
+ * ```ts
+ * const documents = new LambderMemoryUploadBucket();
+ * setupWorker(
+ *     lambderMockMswHandler(mockApp, { apiPath: "/api", msw }),
+ *     lambderMockUploadMswHandler(documents, { msw }),
+ * );
+ * ```
+ *
+ * The mock's ticket and confirm handlers then call `documents` as the
+ * server's call the real bucket, so the runner's whole conversation runs, the
+ * checks storage makes on a post included.
+ *
+ * Lambder never depends on msw: the app installs it and passes the module
+ * in. Generic over the module so the handler keeps msw's own handler type.
+ */
+export declare const lambderMockUploadMswHandler: <M extends LambderMswModule>(bucket: LambderMemoryUploadBucket, options: {
+    msw: M;
+}) => ReturnType<M["http"]["all"]>;

package/dist/mock/lambderMockUploadMswHandler.js

@@ -0,0 +1,28 @@
+/**
+ * The MSW handler that makes a LambderMemoryUploadBucket the storage a mock
+ * app's browser uploads to: every request under the bucket's baseUrl (a
+ * LambderUploadRunner's post, a download link's GET) is answered by the
+ * bucket, the way S3 would answer it. Register it beside the API handler:
+ *
+ * ```ts
+ * const documents = new LambderMemoryUploadBucket();
+ * setupWorker(
+ *     lambderMockMswHandler(mockApp, { apiPath: "/api", msw }),
+ *     lambderMockUploadMswHandler(documents, { msw }),
+ * );
+ * ```
+ *
+ * The mock's ticket and confirm handlers then call `documents` as the
+ * server's call the real bucket, so the runner's whole conversation runs, the
+ * checks storage makes on a post included.
+ *
+ * Lambder never depends on msw: the app installs it and passes the module
+ * in. Generic over the module so the handler keeps msw's own handler type.
+ */
+export const lambderMockUploadMswHandler = (bucket, options) => {
+    const { msw } = options;
+    if (!msw?.http?.all) {
+        throw new Error('lambderMockUploadMswHandler requires the msw module: lambderMockUploadMswHandler(bucket, { msw: await import("msw") }). Install it with: npm install msw --save-dev');
+    }
+    return msw.http.all(`${bucket.baseUrl}*`, async ({ request }) => (await bucket.handleStorageRequest(request)) ?? undefined);
+};

package/dist/mock.d.ts

@@ -14,6 +14,9 @@ export { lambderMockConsoleLogger } from "./mock/lambderMockConsoleLogger.js";
 export type { LambderMockConsoleLoggerOptions } from "./mock/lambderMockConsoleLogger.js";
 export { lambderMockMswHandler } from "./mock/lambderMockMswHandler.js";
 export type { LambderMswModule, LambderMockMswTarget } from "./mock/lambderMockMswHandler.js";
+export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js";
+export type { LambderMemoryUploadBucketOptions, LambderMemoryUploadObject } from "./stores/LambderMemoryUploadBucket.js";
+export { lambderMockUploadMswHandler } from "./mock/lambderMockUploadMswHandler.js";
 export { lambderMockInvokeTransport } from "./mock/lambderMockInvokeTransport.js";
 export type { LambderMockInvokeEvent, LambderMockInvokeResult } from "./mock/lambderMockInvokeTransport.js";
 export { LambderCookieJar } from "./shared/transport/LambderCookieJar.js";

package/dist/mock.js

@@ -14,6 +14,10 @@ export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
 export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
 export { lambderMockConsoleLogger } from "./mock/lambderMockConsoleLogger.js";
 export { lambderMockMswHandler } from "./mock/lambderMockMswHandler.js";
+// The storage a mock app's uploads go to: a memory bucket the mock's ticket and
+// confirm handlers call, and the MSW handler that answers its storage requests.
+export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js";
+export { lambderMockUploadMswHandler } from "./mock/lambderMockUploadMswHandler.js";
 export { lambderMockInvokeTransport } from "./mock/lambderMockInvokeTransport.js";
 // What a mock setup reaches for beside the app: the stores it runs on, the
 // jar its transport carries, and the refusal a handler says no with.