@wtfalch/email 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Tallis Falch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/mailbox/client.d.ts

@@ -0,0 +1,85 @@
+import { JamClient } from 'jmap-jam';
+import type { MailSession } from './types.ts';
+export declare const MAIL_CAPABILITY = "urn:ietf:params:jmap:mail";
+export declare const SUBMISSION_CAPABILITY = "urn:ietf:params:jmap:submission";
+/** The parts of the JMAP session document this package uses. */
+type SessionDocument = {
+    username: string;
+    apiUrl: string;
+    downloadUrl: string;
+    uploadUrl: string;
+    eventSourceUrl: string;
+    state: string;
+    accounts: Record<string, {
+        name: string;
+        isReadOnly: boolean;
+        accountCapabilities: Record<string, unknown>;
+    }>;
+    primaryAccounts: Record<string, string>;
+};
+export type MailClientOptions = {
+    /** The JMAP session URL, e.g. `https://email.example.com/.well-known/jmap`.
+     *  Stalwart redirects that to `/jmap/session`. */
+    sessionUrl: string;
+    /** The access token sent as `Authorization: Bearer`. Under an OIDC
+     *  directory this is the signed-in person's token from the issuer; for a
+     *  mail client without OAuth it is an app password's basic credential,
+     *  which is not a bearer token and needs `authorization` instead. */
+    bearerToken?: string;
+    /** A complete `Authorization` header value, when it is not a bearer token. */
+    authorization?: string;
+    /** Use a different account than the session's primary one. */
+    accountId?: string;
+};
+/**
+ * A connection to one JMAP account.
+ *
+ * Every other module in this package takes one of these. It owns the session
+ * document, the account id, and the `jmap-jam` client the wire calls go
+ * through; `jmap-jam` itself is not part of this package's public surface.
+ */
+export declare class MailClient {
+    #private;
+    constructor(options: MailClientOptions);
+    /**
+     * Use a new token from here on. An access token expires long before a mail
+     * client is closed, so the app refreshes it and calls this; the next
+     * request re-reads the session document with it.
+     */
+    setToken(bearerToken: string): void;
+    setAuthorization(authorization: string): void;
+    /** @internal The wire client and the resolved session, connecting if needed. */
+    connect(): Promise<{
+        jam: JamClient;
+        doc: SessionDocument;
+        accountId: string;
+    }>;
+    /** The signed-in person and the account being read. */
+    session(): Promise<MailSession>;
+    accountId(): Promise<string>;
+    /**
+     * The URL that fetches a blob's bytes. It carries no credential, so the
+     * request needs the same `Authorization` header as the API.
+     */
+    downloadUrl(blob: {
+        blobId: string;
+        name: string;
+        type: string;
+    }): Promise<string>;
+    /** The `Authorization` header value every request carries, for a caller
+     *  fetching a download URL itself. */
+    get authorization(): string;
+    /** Upload bytes and get back a blob id a draft can attach. */
+    upload(body: Blob | ArrayBuffer | Uint8Array | string, type?: string): Promise<{
+        blobId: string;
+        type: string;
+        size: number;
+    }>;
+    /** The event source URL for `push`, with its template expanded. */
+    eventSourceUrl(options: {
+        types: string;
+        ping: number;
+        closeAfter?: 'state' | 'no';
+    }): Promise<string>;
+}
+export {};

package/dist/mailbox/client.js

@@ -0,0 +1,201 @@
+import { JamClient } from 'jmap-jam';
+import { MailError, guard, toMailError } from "./errors.js";
+import { expandTemplate } from "./uri.js";
+export const MAIL_CAPABILITY = 'urn:ietf:params:jmap:mail';
+export const SUBMISSION_CAPABILITY = 'urn:ietf:params:jmap:submission';
+function looksLikeSession(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.apiUrl === 'string' &&
+        typeof value.accounts === 'object');
+}
+/**
+ * A connection to one JMAP account.
+ *
+ * Every other module in this package takes one of these. It owns the session
+ * document, the account id, and the `jmap-jam` client the wire calls go
+ * through; `jmap-jam` itself is not part of this package's public surface.
+ */
+export class MailClient {
+    #sessionUrl;
+    #wantedAccountId;
+    #authorization;
+    #connection;
+    constructor(options) {
+        const { sessionUrl, bearerToken, authorization, accountId } = options;
+        if (!bearerToken && !authorization) {
+            throw new MailError('a MailClient needs either a bearerToken or an authorization header');
+        }
+        this.#sessionUrl = sessionUrl;
+        this.#authorization = authorization ?? `Bearer ${bearerToken}`;
+        this.#wantedAccountId = accountId;
+    }
+    /**
+     * Use a new token from here on. An access token expires long before a mail
+     * client is closed, so the app refreshes it and calls this; the next
+     * request re-reads the session document with it.
+     */
+    setToken(bearerToken) {
+        this.setAuthorization(`Bearer ${bearerToken}`);
+    }
+    setAuthorization(authorization) {
+        if (authorization === this.#authorization)
+            return;
+        this.#authorization = authorization;
+        this.#connection = undefined;
+    }
+    /** @internal The wire client and the resolved session, connecting if needed. */
+    async connect() {
+        this.#connection ??= this.#open();
+        try {
+            return await this.#connection;
+        }
+        catch (error) {
+            // A failed connection must not be cached, or a token refresh cannot
+            // recover: the next call would replay the same rejected promise.
+            this.#connection = undefined;
+            throw error;
+        }
+    }
+    async #open() {
+        const authorization = this.#authorization;
+        const isBearer = authorization.startsWith('Bearer ');
+        // `JamClient` can only build a `Bearer` header from the string it is
+        // given, so a credential that is not a bearer token (an app password,
+        // which Stalwart takes as Basic) needs the header replaced afterwards.
+        // The constructor has already fired its own session request by then, so
+        // that path reads the session here and discards what the constructor
+        // fetched; the bearer path, which is what the product uses, costs one
+        // request as usual.
+        const jam = new JamClient({
+            sessionUrl: this.#sessionUrl,
+            bearerToken: isBearer ? authorization.slice('Bearer '.length) : '',
+        });
+        let doc;
+        if (isBearer) {
+            let loaded;
+            try {
+                loaded = await jam.session;
+            }
+            catch (cause) {
+                // `JamClient.loadSession` calls `.json()` without checking the
+                // status, so a 401 with an HTML body arrives here as a parse error.
+                throw await this.#sessionFailure(authorization, cause);
+            }
+            if (!looksLikeSession(loaded))
+                throw await this.#sessionFailure(authorization, loaded);
+            doc = loaded;
+        }
+        else {
+            jam.authHeader = authorization;
+            doc = await this.#fetchSession(authorization);
+            jam.session = Promise.resolve(doc);
+        }
+        const accountId = this.#wantedAccountId ?? doc.primaryAccounts?.[MAIL_CAPABILITY];
+        if (!accountId) {
+            throw new MailError(`the session document names no primary account for ${MAIL_CAPABILITY}; the server may not offer JMAP Mail to this login`, { operation: 'client.connect' });
+        }
+        if (!doc.accounts[accountId]) {
+            throw new MailError(`the session document has no account ${accountId}`, {
+                operation: 'client.connect',
+            });
+        }
+        return { jam, doc, accountId };
+    }
+    /** Read the session document with the status checked, so a failure says
+     *  what the server actually answered. */
+    async #fetchSession(authorization) {
+        let response;
+        try {
+            response = await fetch(this.#sessionUrl, {
+                headers: { Authorization: authorization, Accept: 'application/json' },
+                cache: 'no-cache',
+            });
+        }
+        catch (cause) {
+            throw new MailError(`could not reach ${this.#sessionUrl}`, {
+                operation: 'client.connect',
+                cause,
+            });
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new MailError(`the server rejected the credential for ${this.#sessionUrl} (${response.status})`, { status: response.status, operation: 'client.connect' });
+        }
+        const body = await response.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!looksLikeSession(parsed)) {
+            throw new MailError(`${this.#sessionUrl} did not answer with a JMAP session document (${response.status}): ${body.slice(0, 200)}`, { status: response.status, operation: 'client.connect' });
+        }
+        return parsed;
+    }
+    /** Turn a failed or unrecognisable session read into an error that says
+     *  what happened, by asking again with the status checked. */
+    async #sessionFailure(authorization, cause) {
+        try {
+            await this.#fetchSession(authorization);
+        }
+        catch (error) {
+            return toMailError(error, 'client.connect');
+        }
+        // The second read succeeded, so the first was a transient failure.
+        return toMailError(cause, 'client.connect');
+    }
+    /** The signed-in person and the account being read. */
+    async session() {
+        const { doc, accountId } = await this.connect();
+        const account = doc.accounts[accountId];
+        return {
+            username: doc.username,
+            accountId,
+            accountName: account?.name ?? '',
+            isReadOnly: account?.isReadOnly ?? false,
+            maySubmit: Boolean(account?.accountCapabilities?.[SUBMISSION_CAPABILITY]),
+        };
+    }
+    async accountId() {
+        return (await this.connect()).accountId;
+    }
+    /**
+     * The URL that fetches a blob's bytes. It carries no credential, so the
+     * request needs the same `Authorization` header as the API.
+     */
+    async downloadUrl(blob) {
+        const { doc, accountId } = await this.connect();
+        return expandTemplate(doc.downloadUrl, {
+            accountId,
+            blobId: blob.blobId,
+            name: blob.name,
+            type: blob.type,
+        });
+    }
+    /** The `Authorization` header value every request carries, for a caller
+     *  fetching a download URL itself. */
+    get authorization() {
+        return this.#authorization;
+    }
+    /** Upload bytes and get back a blob id a draft can attach. */
+    async upload(body, type = 'application/octet-stream') {
+        const { jam, accountId } = await this.connect();
+        return guard('client.upload', async () => {
+            const result = await jam.uploadBlob(accountId, body, {
+                headers: { Authorization: this.#authorization, 'Content-Type': type },
+            });
+            return { blobId: result.blobId, type: result.type, size: result.size };
+        });
+    }
+    /** The event source URL for `push`, with its template expanded. */
+    async eventSourceUrl(options) {
+        const { doc } = await this.connect();
+        return expandTemplate(doc.eventSourceUrl, {
+            types: options.types,
+            ping: String(options.ping),
+            closeafter: options.closeAfter ?? 'no',
+        });
+    }
+}

package/dist/mailbox/drafts.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Building a reply or a forward from a message is pure: no client, no
+ * network. It is also where mail clients quietly get things wrong, so it
+ * lives on its own and is tested on its own.
+ */
+import type { Draft, EmailAddress, MailIdentity, Message } from './types.ts';
+/** `Re: ` once, however many times the subject already carries it. */
+export declare function replySubject(subject: string): string;
+/** `Fwd: ` once. A forward of a reply keeps the `Re:` in the middle, which is
+ *  what the thread was actually called. */
+export declare function forwardSubject(subject: string): string;
+/** `Ada Lovelace <ada@example.com>`, or the bare address when there is no name. */
+export declare function formatAddress(address: EmailAddress): string;
+/** The attribution line above a quoted reply. */
+export declare function attribution(message: Message): string;
+/** A plain-text body quoted the way every mail client quotes: `> ` per line. */
+export declare function quoteText(message: Message): string;
+/** The block a forwarded message is introduced by. */
+export declare function forwardIntroduction(message: Message): string;
+export type ReplyOptions = {
+    /** The identity replying, so its own address is kept out of the
+     *  recipients. */
+    identity: MailIdentity;
+    /** Reply to everyone the message went to, not only its sender. */
+    all?: boolean;
+    /** Put the original above a quoted copy. On by default. */
+    quote?: boolean;
+};
+/**
+ * A reply to `message`, ready to hand to `send`.
+ *
+ * `Reply-To` wins over `From` for the recipient, per RFC 5322 §3.6.2, which
+ * is how a mailing list or a no-reply-plus-support-address arrangement
+ * expects to be answered.
+ */
+export declare function replyDraft(message: Message, options: ReplyOptions): Draft;
+export type ForwardOptions = {
+    identity: MailIdentity;
+    /** Who to forward to. Left empty, the caller fills it in before sending. */
+    to?: readonly EmailAddress[];
+    /** Carry the original's attachments. On by default: a forward that drops
+     *  them is the classic mail-client bug. */
+    attachments?: boolean;
+};
+/**
+ * A forward of `message`.
+ *
+ * A forward starts a new conversation, so it carries no `In-Reply-To` or
+ * `References`: threading it onto the original would file it under a
+ * conversation the new recipient cannot see.
+ */
+export declare function forwardDraft(message: Message, options: ForwardOptions): Draft;

package/dist/mailbox/drafts.js

@@ -0,0 +1,134 @@
+/**
+ * Building a reply or a forward from a message is pure: no client, no
+ * network. It is also where mail clients quietly get things wrong, so it
+ * lives on its own and is tested on its own.
+ */
+/**
+ * Reply prefixes, so `Re: Re: Re:` does not accumulate.
+ *
+ * A localised client writes its own: Norwegian Outlook sends `SV:`, German
+ * `AW:`, and some clients count with `Re[2]:`. Stripping a prefix this list
+ * does not know is worse than leaving it, so the list stays short and
+ * certain.
+ */
+const REPLY_PREFIX = /^\s*(?:(?:re|sv|aw|antw)(?:\[\d+\])?\s*:\s*)+/i;
+const FORWARD_PREFIX = /^\s*(?:(?:fwd?|vs|wg)(?:\[\d+\])?\s*:\s*)+/i;
+/** `Re: ` once, however many times the subject already carries it. */
+export function replySubject(subject) {
+    return `Re: ${subject.replace(REPLY_PREFIX, '').trim()}`;
+}
+/** `Fwd: ` once. A forward of a reply keeps the `Re:` in the middle, which is
+ *  what the thread was actually called. */
+export function forwardSubject(subject) {
+    return `Fwd: ${subject.replace(FORWARD_PREFIX, '').trim()}`;
+}
+/** `Ada Lovelace <ada@example.com>`, or the bare address when there is no name. */
+export function formatAddress(address) {
+    const name = address.name?.trim();
+    return name ? `${name} <${address.email}>` : address.email;
+}
+function normalise(address) {
+    return address.email.trim().toLowerCase();
+}
+/** Keep the first occurrence of each address, dropping any in `exclude`. */
+function dedupe(addresses, exclude) {
+    const seen = new Set(exclude);
+    const kept = [];
+    for (const address of addresses) {
+        const key = normalise(address);
+        if (key === '' || seen.has(key))
+            continue;
+        seen.add(key);
+        kept.push(address);
+    }
+    return kept;
+}
+/** The attribution line above a quoted reply. */
+export function attribution(message) {
+    // `2026-09-01T09:14:32.123Z` reads as `2026-09-01 at 09:14`: the date and
+    // the minute, with no timezone maths and nothing locale-dependent.
+    const when = (message.sentAt ?? message.receivedAt).slice(0, 16).replace('T', ' at ');
+    const who = message.from[0] ? formatAddress(message.from[0]) : 'someone';
+    return `On ${when}, ${who} wrote:`;
+}
+/** A plain-text body quoted the way every mail client quotes: `> ` per line. */
+export function quoteText(message) {
+    const body = message.text ?? '';
+    const quoted = body
+        .split('\n')
+        // A line that is already quoted gets one more marker and no space, which
+        // is how a quote of a quote is meant to nest.
+        .map((line) => (line.startsWith('>') ? `>${line}` : `> ${line}`))
+        .join('\n');
+    return `${attribution(message)}\n${quoted}`;
+}
+/** The block a forwarded message is introduced by. */
+export function forwardIntroduction(message) {
+    const lines = [
+        '---------- Forwarded message ----------',
+        `From: ${message.from.map(formatAddress).join(', ')}`,
+        `Date: ${message.sentAt ?? message.receivedAt}`,
+        `Subject: ${message.subject}`,
+        `To: ${message.to.map(formatAddress).join(', ')}`,
+    ];
+    if (message.cc.length > 0)
+        lines.push(`Cc: ${message.cc.map(formatAddress).join(', ')}`);
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * A reply to `message`, ready to hand to `send`.
+ *
+ * `Reply-To` wins over `From` for the recipient, per RFC 5322 §3.6.2, which
+ * is how a mailing list or a no-reply-plus-support-address arrangement
+ * expects to be answered.
+ */
+export function replyDraft(message, options) {
+    const { identity, all = false, quote = true } = options;
+    const mine = new Set([identity.email.trim().toLowerCase()]);
+    const answering = message.replyTo.length > 0 ? message.replyTo : message.from;
+    const to = dedupe(answering, mine);
+    // Replying to a message you sent yourself keeps its recipients, or the
+    // reply has nowhere to go.
+    const recipients = to.length > 0 ? to : dedupe(message.to, new Set());
+    const cc = all
+        ? dedupe([...message.to, ...message.cc], new Set([...mine, ...recipients.map(normalise)]))
+        : [];
+    // RFC 5322 §3.6.4: References is the parent's References plus its
+    // Message-ID, which is what threads the conversation for every other client.
+    const references = [...message.references, ...message.messageId];
+    return {
+        identityId: identity.id,
+        to: recipients,
+        ...(cc.length > 0 ? { cc } : {}),
+        subject: replySubject(message.subject),
+        ...(quote ? { text: `\n\n${quoteText(message)}` } : {}),
+        ...(message.messageId.length > 0 ? { inReplyTo: message.messageId } : {}),
+        ...(references.length > 0 ? { references } : {}),
+    };
+}
+/**
+ * A forward of `message`.
+ *
+ * A forward starts a new conversation, so it carries no `In-Reply-To` or
+ * `References`: threading it onto the original would file it under a
+ * conversation the new recipient cannot see.
+ */
+export function forwardDraft(message, options) {
+    const { identity, to = [], attachments = true } = options;
+    const carried = attachments
+        ? message.attachments.map((attachment) => ({
+            blobId: attachment.blobId,
+            name: attachment.name,
+            type: attachment.type,
+            disposition: attachment.disposition,
+            ...(attachment.cid ? { cid: attachment.cid } : {}),
+        }))
+        : [];
+    return {
+        identityId: identity.id,
+        to,
+        subject: forwardSubject(message.subject),
+        text: `\n\n${forwardIntroduction(message)}\n${message.text ?? ''}`,
+        ...(carried.length > 0 ? { attachments: carried } : {}),
+    };
+}

package/dist/mailbox/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * jmap-jam throws whatever the server sent: a `ProblemDetails` object for a
+ * request-level failure, a string for a non-JSON body, and an *array* of
+ * `ProblemDetails` when one call in a `requestMany` chain failed. None of
+ * those is an `Error`, so a caller that logs `err.message` gets `undefined`
+ * and a `catch` that rethrows loses the stack.
+ *
+ * Everything this package throws is a `MailError`.
+ */
+/** The shape a JMAP server returns for a failed request or method call. */
+export type ProblemDetails = {
+    type?: string;
+    status?: number;
+    title?: string;
+    detail?: string;
+    description?: string;
+    [key: string]: unknown;
+};
+export declare class MailError extends Error {
+    /** The JMAP error type, e.g. `urn:ietf:params:jmap:error:unknownCapability`
+     *  or a method-level `invalidArguments`. `unknown` when the server sent
+     *  something unparseable. */
+    readonly type: string;
+    /** The HTTP status, when the failure was request-level. */
+    readonly status: number | undefined;
+    /** The operation this package was performing, e.g. `threads.list`. */
+    readonly operation: string | undefined;
+    /** Every problem the server reported. A `requestMany` chain can fail in
+     *  more than one place; `message` names the first. */
+    readonly problems: readonly ProblemDetails[];
+    constructor(message: string, options?: {
+        type?: string;
+        status?: number;
+        operation?: string;
+        problems?: readonly ProblemDetails[];
+        cause?: unknown;
+    });
+}
+/**
+ * Turn anything jmap-jam threw into a `MailError`. A `MailError` passes
+ * through unchanged so a rethrow up a call stack does not re-wrap.
+ */
+export declare function toMailError(thrown: unknown, operation?: string): MailError;
+/** Run `fn`, and make sure anything it throws is a `MailError` naming `operation`. */
+export declare function guard<T>(operation: string, fn: () => Promise<T>): Promise<T>;

package/dist/mailbox/errors.js

@@ -0,0 +1,88 @@
+/**
+ * jmap-jam throws whatever the server sent: a `ProblemDetails` object for a
+ * request-level failure, a string for a non-JSON body, and an *array* of
+ * `ProblemDetails` when one call in a `requestMany` chain failed. None of
+ * those is an `Error`, so a caller that logs `err.message` gets `undefined`
+ * and a `catch` that rethrows loses the stack.
+ *
+ * Everything this package throws is a `MailError`.
+ */
+export class MailError extends Error {
+    /** The JMAP error type, e.g. `urn:ietf:params:jmap:error:unknownCapability`
+     *  or a method-level `invalidArguments`. `unknown` when the server sent
+     *  something unparseable. */
+    type;
+    /** The HTTP status, when the failure was request-level. */
+    status;
+    /** The operation this package was performing, e.g. `threads.list`. */
+    operation;
+    /** Every problem the server reported. A `requestMany` chain can fail in
+     *  more than one place; `message` names the first. */
+    problems;
+    constructor(message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = 'MailError';
+        this.type = options.type ?? 'unknown';
+        this.status = options.status;
+        this.operation = options.operation;
+        this.problems = options.problems ?? [];
+    }
+}
+function isProblem(value) {
+    // An `Error` is an object too, and treating one as a problem details would
+    // throw away its message and its stack.
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Error));
+}
+/** The most useful sentence a problem carries, in the order JMAP servers
+ *  actually populate the fields. */
+function describe(problem) {
+    const detail = problem.detail ?? problem.description ?? problem.title;
+    const type = typeof problem.type === 'string' ? problem.type : undefined;
+    if (typeof detail === 'string' && detail.length > 0) {
+        return type ? `${type}: ${detail}` : detail;
+    }
+    return type ?? 'the server reported an error with no description';
+}
+/**
+ * Turn anything jmap-jam threw into a `MailError`. A `MailError` passes
+ * through unchanged so a rethrow up a call stack does not re-wrap.
+ */
+export function toMailError(thrown, operation) {
+    if (thrown instanceof MailError)
+        return thrown;
+    const problems = Array.isArray(thrown)
+        ? thrown.filter(isProblem)
+        : isProblem(thrown)
+            ? [thrown]
+            : [];
+    const first = problems[0];
+    if (first) {
+        const rest = problems.length > 1 ? ` (and ${problems.length - 1} more)` : '';
+        return new MailError(`${describe(first)}${rest}`, {
+            type: typeof first.type === 'string' ? first.type : undefined,
+            status: typeof first.status === 'number' ? first.status : undefined,
+            operation,
+            problems,
+            cause: thrown,
+        });
+    }
+    if (thrown instanceof Error) {
+        return new MailError(thrown.message, { operation, cause: thrown });
+    }
+    return new MailError(typeof thrown === 'string' ? thrown : 'the request failed', {
+        operation,
+        cause: thrown,
+    });
+}
+/** Run `fn`, and make sure anything it throws is a `MailError` naming `operation`. */
+export async function guard(operation, fn) {
+    try {
+        return await fn();
+    }
+    catch (thrown) {
+        throw toMailError(thrown, operation);
+    }
+}

package/dist/mailbox/fake/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A mailbox in memory, for stories, for a development build with no server,
+ * and for tests that want to exercise this package rather than a stub.
+ *
+ * ```ts
+ * import { fakeMail } from '@wtfalch/mail/fake'
+ *
+ * const { client, mailbox, dispose } = fakeMail()
+ * const tree = await mailboxes(client)          // the real function
+ * ```
+ */
+import { MailClient } from '../client.ts';
+import { FakeMailbox, type FakeOptions, type SeedMessage, type SeedThread } from './mailbox.ts';
+import { SAMPLE } from './sample.ts';
+export { FakeMailbox };
+export type { FakeOptions, SeedMessage, SeedThread };
+export { SAMPLE };
+export type FakeMail = {
+    /** A real `MailClient`. Everything this package exports works against it
+     *  unchanged, through the real wire code. */
+    client: MailClient;
+    /** The mailbox behind it, to seed more mail or to assert on what was sent. */
+    mailbox: FakeMailbox;
+    /** Stop intercepting. Call it when a story or a test is done; leaving it
+     *  installed leaves the fake answering for the rest of the process. */
+    dispose: () => void;
+};
+/**
+ * A client and the mailbox it talks to.
+ *
+ * Seeded with `SAMPLE` unless told otherwise, because a fake with an empty
+ * inbox demonstrates the empty state and nothing else.
+ */
+export declare function fakeMail(options?: FakeOptions): FakeMail;