@wtfalch/email 0.1.0

package/dist/mailbox/react/ThreadView.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, Empty, Icon, Identity, Menu, ScrollArea } from '@wtfalch/design';
+import { useState } from 'react';
+export function ThreadView({ thread, loading = false, onReply, onForward, onDownload, className, }) {
+    if (loading && !thread)
+        return _jsx("p", { className: "message-quiet", children: "Loading\u2026" });
+    if (!thread || thread.messages.length === 0) {
+        return (_jsx("div", { className: `thread${className ? ` ${className}` : ''}`, children: _jsx(Empty, { icon: "chat", children: "Pick a conversation to read it." }) }));
+    }
+    const last = thread.messages.length - 1;
+    return (_jsxs("div", { className: `thread${className ? ` ${className}` : ''}`, children: [_jsxs("header", { className: "thread-head", children: [_jsx("h2", { className: "thread-title", children: thread.subject || '(no subject)' }), _jsx("p", { className: "thread-meta", children: thread.messages.length === 1 ? '1 message' : `${thread.messages.length} messages` })] }), _jsx(ScrollArea, { className: "thread-body", label: "Messages in this conversation", children: _jsx("ol", { className: "messages", children: thread.messages.map((message, index) => (_jsx("li", { children: _jsx(MessageCard, { message: message, defaultOpen: index === last, onReply: onReply, onForward: onForward, onDownload: onDownload }) }, message.id))) }) })] }));
+}
+function MessageCard({ message, defaultOpen, onReply, onForward, onDownload, }) {
+    const [open, setOpen] = useState(defaultOpen);
+    const sender = message.from[0];
+    const when = new Date(message.sentAt ?? message.receivedAt);
+    return (_jsxs("article", { className: `message${open ? ' open' : ''}`, children: [_jsxs("header", { className: "message-head", children: [_jsxs("button", { type: "button", className: "message-toggle", onClick: () => setOpen((was) => !was), "aria-expanded": open, children: [sender ? (_jsx(Identity, { name: sender.name, address: sender.email, kind: open ? 'full' : 'line' })) : (_jsx("span", { className: "message-nobody", children: "Unknown sender" })), _jsx("time", { className: "message-when", dateTime: when.toISOString(), children: when.toLocaleString('en-GB', {
+                                    day: 'numeric',
+                                    month: 'short',
+                                    hour: '2-digit',
+                                    minute: '2-digit',
+                                }) })] }), open && (onReply || onForward) && (_jsx(Menu, { label: "Message actions", trigger: _jsx(Button, { kind: "ghost", "aria-label": "Message actions", children: _jsx(Icon, { name: "settings" }) }), items: [
+                            ...(onReply
+                                ? [
+                                    {
+                                        id: 'reply',
+                                        label: 'Reply',
+                                        shortcut: 'R',
+                                        onAction: () => onReply(message, false),
+                                    },
+                                    {
+                                        id: 'reply-all',
+                                        label: 'Reply all',
+                                        shortcut: '⇧R',
+                                        onAction: () => onReply(message, true),
+                                    },
+                                ]
+                                : []),
+                            ...(onForward
+                                ? [
+                                    {
+                                        id: 'forward',
+                                        label: 'Forward',
+                                        shortcut: 'F',
+                                        onAction: () => onForward(message),
+                                    },
+                                ]
+                                : []),
+                        ] }))] }), open && (_jsxs("div", { className: "message-body", children: [_jsx(Recipients, { message: message }), message.text !== null ? (
+                    /* `pre-wrap`, not a paragraph split: plain-text mail is laid out
+                       with its own line breaks and its own quote markers, and
+                       reflowing it destroys both. */
+                    _jsx("pre", { className: "message-text", children: message.text })) : message.html !== null ? (_jsx(HtmlNotice, { html: message.html })) : (_jsx("p", { className: "message-quiet", children: "This message has no body." })), message.isTruncated && (_jsx("p", { className: "message-quiet", children: "This message was cut short at half a megabyte. The rest has not been fetched." })), message.attachments.length > 0 && (_jsx("ul", { className: "attachments", children: message.attachments
+                            .filter((file) => file.disposition !== 'inline')
+                            .map((file) => (_jsx("li", { children: _jsxs("button", { type: "button", className: "attachment", onClick: () => onDownload?.(file), disabled: !onDownload, children: [_jsx(Icon, { name: "file", className: "attachment-icon" }), _jsx("span", { className: "attachment-name", children: file.name }), _jsx("span", { className: "attachment-size", children: bytes(file.size) })] }) }, file.blobId))) }))] }))] }));
+}
+function Recipients({ message }) {
+    const line = (label, people) => people.length === 0 ? null : (_jsxs("p", { className: "message-line", children: [_jsx("span", { className: "message-line-label", children: label }), _jsx("span", { children: people.map((p) => p.name?.trim() || p.email).join(', ') })] }));
+    return (_jsxs("div", { className: "message-lines", children: [line('To', message.to), line('Cc', message.cc)] }));
+}
+/**
+ * A message with only an HTML body.
+ *
+ * Not rendered, and the reason is said out loud rather than left as a blank
+ * pane: injecting a stranger's markup into the client's own document is the
+ * bug this refuses to ship. The source is offered because a person who wants
+ * it should not have to leave to get it.
+ */
+function HtmlNotice({ html }) {
+    const [shown, setShown] = useState(false);
+    return (_jsxs("div", { className: "message-html", children: [_jsx("p", { className: "message-quiet", children: "This message has an HTML body and no plain-text one. It is not rendered here: a mail client that puts a stranger's markup into its own page is one script tag from being read by them." }), _jsx(Button, { kind: "ghost", onClick: () => setShown((was) => !was), children: shown ? 'Hide the source' : 'Show the source' }), shown && _jsx("pre", { className: "message-source", children: html })] }));
+}
+/** Bytes, the way a mail client says them. */
+export function bytes(size) {
+    if (size < 1024)
+        return `${size} B`;
+    if (size < 1024 * 1024)
+        return `${Math.round(size / 1024)} kB`;
+    return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}

package/dist/mailbox/react/context.d.ts

@@ -0,0 +1,11 @@
+import type { MailClient } from '../client.ts';
+export declare function MailProvider({ client, children, }: {
+    client: MailClient;
+    children: React.ReactNode;
+}): import("react").JSX.Element;
+/** The client from the nearest provider, or `null` when there is none --
+ *  which is a legitimate arrangement: every hook also takes a client as an
+ *  argument, so a component tree may skip the provider entirely. */
+export declare function useOptionalMailClient(): MailClient | null;
+/** The client from the nearest provider. Throws when there is none. */
+export declare function useMailClient(): MailClient;

package/dist/mailbox/react/context.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+/**
+ * The client, so a tree of components does not thread it through every prop.
+ *
+ * Only the hooks read this. The view components take their data as props and
+ * know nothing about a client at all, which is what lets them be drawn in a
+ * gallery, in a test, and against the fake without any of those having to
+ * stand up a context first.
+ */
+const Mail = createContext(null);
+export function MailProvider({ client, children, }) {
+    return _jsx(Mail.Provider, { value: client, children: children });
+}
+/** The client from the nearest provider, or `null` when there is none --
+ *  which is a legitimate arrangement: every hook also takes a client as an
+ *  argument, so a component tree may skip the provider entirely. */
+export function useOptionalMailClient() {
+    return useContext(Mail);
+}
+/** The client from the nearest provider. Throws when there is none. */
+export function useMailClient() {
+    const client = useContext(Mail);
+    if (!client) {
+        throw new Error('useMailClient must be used inside a <MailProvider client={…}>');
+    }
+    return client;
+}

package/dist/mailbox/react/hooks.d.ts

@@ -0,0 +1,46 @@
+import type { MailClient } from '../client.ts';
+import { type MailError } from '../errors.ts';
+import { type ListOptions } from '../threads.ts';
+import type { ChangedState, MailIdentity, MailboxNode, ThreadDetail, ThreadPage } from '../types.ts';
+/**
+ * What a view needs to know about something being fetched.
+ *
+ * `data` survives a reload rather than blanking to `undefined` -- a list that
+ * empties itself every time it refreshes flashes, and under push-driven
+ * refresh it would flash constantly. `refreshing` is how a view says "this is
+ * a moment old" without taking the content away.
+ */
+export type Resource<T> = {
+    data: T | undefined;
+    error: MailError | undefined;
+    /** The first load, when there is nothing to show yet. */
+    loading: boolean;
+    /** A later load, with the previous answer still on screen. */
+    refreshing: boolean;
+    reload: () => void;
+};
+/** Every mailbox, as a tree. */
+export declare function useMailboxes(client?: MailClient): Resource<readonly MailboxNode[]>;
+export type ThreadsQuery = ListOptions & {
+    /** The mailbox to list. Ignored when `text` is set, unless both are given,
+     *  in which case the search is scoped to it. */
+    mailboxId?: string;
+    /** Free text. Present, this searches instead of listing. */
+    text?: string;
+};
+/** A page of threads: a mailbox, a search, or a search within a mailbox. */
+export declare function useThreads(query: ThreadsQuery, client?: MailClient): Resource<ThreadPage>;
+/** One thread, with bodies and attachments. `null` fetches nothing. */
+export declare function useThread(threadId: string | null, client?: MailClient): Resource<ThreadDetail>;
+/** The addresses this account may send as. */
+export declare function useIdentities(client?: MailClient): Resource<readonly MailIdentity[]>;
+/**
+ * Refetch when the server says something changed.
+ *
+ * `onChange` is held in a ref rather than being a dependency, so a caller
+ * writing it inline does not tear the connection down and build it up again
+ * on every render -- which, for a stream, means never staying connected.
+ */
+export declare function usePush(onChange: (changed: ChangedState) => void, client?: MailClient): {
+    connected: boolean;
+};

package/dist/mailbox/react/hooks.js

@@ -0,0 +1,127 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { toMailError } from "../errors.js";
+import { identities as fetchIdentities } from "../identities.js";
+import { mailboxes as fetchMailboxes } from "../mailboxes.js";
+import { push } from "../push.js";
+import { search as runSearch } from "../search.js";
+import { thread as fetchThread } from "../thread.js";
+import { listThreads } from "../threads.js";
+import { useOptionalMailClient } from "./context.js";
+/**
+ * Fetch on mount and whenever the key changes.
+ *
+ * The key rather than the function is the dependency, because every call site
+ * builds its function inline and a function identity changes on every render
+ * -- which is the standard way to write a fetch loop that never stops
+ * fetching.
+ */
+function useResource(key, run) {
+    const [state, setState] = useState({});
+    const [pending, setPending] = useState(true);
+    const [nonce, setNonce] = useState(0);
+    const latest = useRef(run);
+    latest.current = run;
+    /* The key and the nonce are the triggers, not values the body reads: the
+       caller's function lives in a ref because every call site builds it inline,
+       and depending on it is how a fetch loop that never stops fetching gets
+       written. */
+    // biome-ignore lint/correctness/useExhaustiveDependencies: the key and the nonce are the triggers; the function they run is held in a ref on purpose.
+    useEffect(() => {
+        let live = true;
+        setPending(true);
+        latest
+            .current()
+            .then((data) => {
+            if (live)
+                setState({ data });
+        }, (error) => {
+            if (live)
+                setState((previous) => ({ data: previous.data, error: toMailError(error) }));
+        })
+            .finally(() => {
+            if (live)
+                setPending(false);
+        });
+        return () => {
+            // A key that changed while a request was out must not have its answer
+            // written over the new one's.
+            live = false;
+        };
+    }, [key, nonce]);
+    const reload = useCallback(() => setNonce((n) => n + 1), []);
+    return {
+        data: state.data,
+        error: state.error,
+        loading: pending && state.data === undefined,
+        refreshing: pending && state.data !== undefined,
+        reload,
+    };
+}
+/** Every mailbox, as a tree. */
+export function useMailboxes(client) {
+    const fromContext = useOptionalClient(client);
+    return useResource('mailboxes', () => fetchMailboxes(fromContext));
+}
+/** A page of threads: a mailbox, a search, or a search within a mailbox. */
+export function useThreads(query, client) {
+    const fromContext = useOptionalClient(client);
+    const { mailboxId, text, position = 0, limit, calculateTotal, sort } = query;
+    const key = JSON.stringify([mailboxId, text, position, limit, calculateTotal, sort]);
+    const options = useMemo(() => ({ position, limit, calculateTotal, sort }), [position, limit, calculateTotal, sort]);
+    return useResource(key, () => {
+        if (text !== undefined && text.trim() !== '') {
+            return runSearch(fromContext, text, {
+                ...options,
+                ...(mailboxId ? { inMailbox: mailboxId } : {}),
+            });
+        }
+        if (!mailboxId)
+            return Promise.resolve({ items: [], position: 0, total: 0, state: '' });
+        return listThreads(fromContext, mailboxId, options);
+    });
+}
+/** One thread, with bodies and attachments. `null` fetches nothing. */
+export function useThread(threadId, client) {
+    const fromContext = useOptionalClient(client);
+    return useResource(threadId ?? '', () => {
+        if (!threadId) {
+            return Promise.resolve({ id: '', subject: '', messages: [] });
+        }
+        return fetchThread(fromContext, threadId);
+    });
+}
+/** The addresses this account may send as. */
+export function useIdentities(client) {
+    const fromContext = useOptionalClient(client);
+    return useResource('identities', () => fetchIdentities(fromContext));
+}
+/**
+ * Refetch when the server says something changed.
+ *
+ * `onChange` is held in a ref rather than being a dependency, so a caller
+ * writing it inline does not tear the connection down and build it up again
+ * on every render -- which, for a stream, means never staying connected.
+ */
+export function usePush(onChange, client) {
+    const fromContext = useOptionalClient(client);
+    const [connected, setConnected] = useState(false);
+    const handler = useRef(onChange);
+    handler.current = onChange;
+    useEffect(() => {
+        const handle = push(fromContext, (changed) => handler.current(changed), {
+            onConnectionChange: setConnected,
+        });
+        return () => handle.close();
+    }, [fromContext]);
+    return { connected };
+}
+/** The client passed in, or the one from the provider. A prop wins, so a
+ *  single component can be pointed at the fake without a provider anywhere. */
+function useOptionalClient(client) {
+    const context = useOptionalMailClient();
+    const resolved = client ?? context;
+    if (!resolved) {
+        throw new Error('a mail hook needs a client, from its argument or a <MailProvider>');
+    }
+    return resolved;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * `@wtfalch/mail/react` — the components that draw a mailbox.
+ *
+ * Everything but `Mail` is pure: props in, markup out, no client and no
+ * fetching. That is what lets each be drawn in a gallery, rendered in a test,
+ * and reused by an application with its own layout. `Mail` is the one piece
+ * that holds state and calls the hooks.
+ *
+ * On `@wtfalch/design` 0.4.0 and `@wtfalch/mail`. Import `@wtfalch/mail/mail.css`
+ * after the design stylesheet.
+ */
+export { MailProvider, useMailClient, useOptionalMailClient } from './context.tsx';
+export { useIdentities, useMailboxes, usePush, useThread, useThreads, } from './hooks.ts';
+export type { Resource, ThreadsQuery } from './hooks.ts';
+export { MailboxTree, flatMailboxes, orderForReading } from './MailboxTree.tsx';
+export type { MailboxTreeProps } from './MailboxTree.tsx';
+export { ThreadList, shortTime } from './ThreadList.tsx';
+export type { ThreadListProps } from './ThreadList.tsx';
+export { ThreadView, bytes } from './ThreadView.tsx';
+export type { ThreadViewProps } from './ThreadView.tsx';
+export { Composer, parseAddresses } from './Composer.tsx';
+export type { ComposerProps } from './Composer.tsx';
+export { Mail } from './Mail.tsx';
+export type { MailProps } from './Mail.tsx';

package/dist/mailbox/react/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@wtfalch/mail/react` — the components that draw a mailbox.
+ *
+ * Everything but `Mail` is pure: props in, markup out, no client and no
+ * fetching. That is what lets each be drawn in a gallery, rendered in a test,
+ * and reused by an application with its own layout. `Mail` is the one piece
+ * that holds state and calls the hooks.
+ *
+ * On `@wtfalch/design` 0.4.0 and `@wtfalch/mail`. Import `@wtfalch/mail/mail.css`
+ * after the design stylesheet.
+ */
+export { MailProvider, useMailClient, useOptionalMailClient } from "./context.js";
+export { useIdentities, useMailboxes, usePush, useThread, useThreads, } from "./hooks.js";
+export { MailboxTree, flatMailboxes, orderForReading } from "./MailboxTree.js";
+export { ThreadList, shortTime } from "./ThreadList.js";
+export { ThreadView, bytes } from "./ThreadView.js";
+export { Composer, parseAddresses } from "./Composer.js";
+export { Mail } from "./Mail.js";

package/dist/mailbox/search.d.ts

@@ -0,0 +1,20 @@
+import type { MailClient } from './client.ts';
+import type { ListOptions } from './threads.ts';
+import type { MailFilter, ThreadPage } from './types.ts';
+export type SearchOptions = ListOptions & {
+    /** Narrow the search to one mailbox. Without it the whole account is
+     *  searched, Trash and Junk included; pass `inMailboxOtherThan` to leave
+     *  those out. */
+    inMailbox?: string;
+    inMailboxOtherThan?: readonly string[];
+    /** Further conditions, ANDed with the text. */
+    filter?: MailFilter;
+};
+/**
+ * Threads matching free text, in the same shape a list returns.
+ *
+ * What `text` searches is the server's choice; RFC 8621 §4.4.1 lets it cover
+ * the headers, the body, and attachment contents it has indexed. A structured
+ * search (`from`, `subject`, a date range) goes in `filter`.
+ */
+export declare function search(client: MailClient, text: string, options?: SearchOptions): Promise<ThreadPage>;

package/dist/mailbox/search.js

@@ -0,0 +1,18 @@
+import { queryThreads } from "./threads.js";
+/**
+ * Threads matching free text, in the same shape a list returns.
+ *
+ * What `text` searches is the server's choice; RFC 8621 §4.4.1 lets it cover
+ * the headers, the body, and attachment contents it has indexed. A structured
+ * search (`from`, `subject`, a date range) goes in `filter`.
+ */
+export function search(client, text, options = {}) {
+    const { inMailbox, inMailboxOtherThan, filter, ...list } = options;
+    const trimmed = text.trim();
+    return queryThreads(client, {
+        ...filter,
+        ...(trimmed === '' ? {} : { text: trimmed }),
+        ...(inMailbox === undefined ? {} : { inMailbox }),
+        ...(inMailboxOtherThan === undefined ? {} : { inMailboxOtherThan }),
+    }, list);
+}

package/dist/mailbox/submit.d.ts

@@ -0,0 +1,35 @@
+import type { MailClient } from './client.ts';
+import type { Draft, EmailAddress, MailIdentity, MailboxNode, Sent } from './types.ts';
+/** The JMAP `Email` object a draft becomes. Exported so the shape can be
+ *  asserted without a server. */
+export declare function draftToEmail(draft: Draft, from: readonly EmailAddress[], draftsMailboxId: string): Record<string, unknown>;
+/** The patch that files a sent message: out of Drafts, into Sent, no longer a
+ *  draft. */
+export declare function sentPatch(draftsMailboxId: string, sentMailboxId: string): {
+    [x: string]: boolean | null;
+    'keywords/$draft': null;
+    'keywords/$seen': boolean;
+};
+export type SendOptions = {
+    /** The identity to send as, when the caller already has it. Saves an
+     *  `Identity/get`. */
+    identity?: MailIdentity;
+    /** The mailbox tree, when the caller already has it. Saves a
+     *  `Mailbox/get`. */
+    mailboxes?: readonly MailboxNode[];
+};
+/**
+ * Send a draft.
+ *
+ * Two requests, not one, and the reason is a sharp edge in RFC 8621 §7.5:
+ * `onSuccessUpdateEmail` makes the server run an implicit `Email/set` and
+ * return it *under the same method call id* as the `EmailSubmission/set`.
+ * A client that reads a multi-call response into a map by id therefore loses
+ * the submission's own result to the implicit one. `jmap-jam`'s `requestMany`
+ * does exactly that, so the submission goes through the single-call path,
+ * which reads the first response and is unaffected.
+ *
+ * The draft is created first and separately, which also means a failed
+ * submission leaves the message in Drafts rather than losing it.
+ */
+export declare function send(client: MailClient, draft: Draft, options?: SendOptions): Promise<Sent>;

package/dist/mailbox/submit.js

@@ -0,0 +1,150 @@
+import { MailError, guard } from "./errors.js";
+import { identities } from "./identities.js";
+import { findRole, mailboxes } from "./mailboxes.js";
+/** RFC 6901 §3: `~` and `/` inside a pointer segment are escaped. Mailbox ids
+ *  are the server's to choose, so a patch key built from one must escape. */
+function pointer(segment) {
+    return segment.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+function failed(operation, notCreated) {
+    const first = notCreated ? Object.values(notCreated)[0] : undefined;
+    throw new MailError(first?.description ?? `the server refused to create the ${operation}`, {
+        type: first?.type ?? 'unknown',
+        operation,
+    });
+}
+/** The JMAP `Email` object a draft becomes. Exported so the shape can be
+ *  asserted without a server. */
+export function draftToEmail(draft, from, draftsMailboxId) {
+    const bodyValues = {};
+    const textBody = [];
+    const htmlBody = [];
+    if (draft.text !== undefined) {
+        bodyValues.text = { value: draft.text };
+        textBody.push({ partId: 'text', type: 'text/plain' });
+    }
+    if (draft.html !== undefined) {
+        bodyValues.html = { value: draft.html };
+        htmlBody.push({ partId: 'html', type: 'text/html' });
+    }
+    // A message with no body at all is legal but confuses some servers'
+    // structure building; an empty text part is the harmless equivalent.
+    if (textBody.length === 0 && htmlBody.length === 0) {
+        bodyValues.text = { value: '' };
+        textBody.push({ partId: 'text', type: 'text/plain' });
+    }
+    return {
+        mailboxIds: { [draftsMailboxId]: true },
+        keywords: { $draft: true, $seen: true },
+        from,
+        to: draft.to,
+        ...(draft.cc?.length ? { cc: draft.cc } : {}),
+        ...(draft.bcc?.length ? { bcc: draft.bcc } : {}),
+        ...(draft.replyTo?.length ? { replyTo: draft.replyTo } : {}),
+        subject: draft.subject,
+        ...(draft.inReplyTo?.length ? { inReplyTo: draft.inReplyTo } : {}),
+        ...(draft.references?.length ? { references: draft.references } : {}),
+        bodyValues,
+        ...(textBody.length ? { textBody } : {}),
+        ...(htmlBody.length ? { htmlBody } : {}),
+        ...(draft.attachments?.length
+            ? {
+                attachments: draft.attachments.map((attachment) => ({
+                    blobId: attachment.blobId,
+                    type: attachment.type,
+                    name: attachment.name,
+                    disposition: attachment.disposition ?? 'attachment',
+                    ...(attachment.cid ? { cid: attachment.cid } : {}),
+                })),
+            }
+            : {}),
+    };
+}
+/** The patch that files a sent message: out of Drafts, into Sent, no longer a
+ *  draft. */
+export function sentPatch(draftsMailboxId, sentMailboxId) {
+    return {
+        [`mailboxIds/${pointer(draftsMailboxId)}`]: null,
+        [`mailboxIds/${pointer(sentMailboxId)}`]: true,
+        'keywords/$draft': null,
+        'keywords/$seen': true,
+    };
+}
+/**
+ * Send a draft.
+ *
+ * Two requests, not one, and the reason is a sharp edge in RFC 8621 §7.5:
+ * `onSuccessUpdateEmail` makes the server run an implicit `Email/set` and
+ * return it *under the same method call id* as the `EmailSubmission/set`.
+ * A client that reads a multi-call response into a map by id therefore loses
+ * the submission's own result to the implicit one. `jmap-jam`'s `requestMany`
+ * does exactly that, so the submission goes through the single-call path,
+ * which reads the first response and is unaffected.
+ *
+ * The draft is created first and separately, which also means a failed
+ * submission leaves the message in Drafts rather than losing it.
+ */
+export async function send(client, draft, options = {}) {
+    const { jam, accountId } = await client.connect();
+    const tree = options.mailboxes ?? (await mailboxes(client));
+    const drafts = findRole(tree, 'drafts');
+    const sent = findRole(tree, 'sent');
+    if (!drafts) {
+        throw new MailError('the account has no Drafts mailbox to compose in', {
+            type: 'notFound',
+            operation: 'send',
+        });
+    }
+    if (!sent) {
+        throw new MailError('the account has no Sent mailbox to file the message in', {
+            type: 'notFound',
+            operation: 'send',
+        });
+    }
+    let from = draft.from;
+    if (!from || from.length === 0) {
+        const identity = options.identity ?? (await identities(client)).find((one) => one.id === draft.identityId);
+        if (!identity) {
+            throw new MailError(`no identity ${draft.identityId} on this account`, {
+                type: 'notFound',
+                operation: 'send',
+            });
+        }
+        // RFC 8621 §7.1: a server may refuse a submission whose From header does
+        // not match the identity, so the header is filled from the identity
+        // rather than left to the server to guess.
+        from = [{ name: identity.name, email: identity.email }];
+    }
+    return guard('send', async () => {
+        const [created] = await jam.api.Email.set({
+            accountId,
+            create: { draft: draftToEmail(draft, from, drafts.id) },
+        });
+        const email = created.created?.draft;
+        if (!email)
+            failed('draft', created.notCreated);
+        const [submitted] = await jam.api.EmailSubmission.set({
+            accountId,
+            create: {
+                submission: {
+                    identityId: draft.identityId,
+                    emailId: email.id,
+                },
+            },
+            onSuccessUpdateEmail: { '#submission': sentPatch(drafts.id, sent.id) },
+        }, 
+        // `onSuccessUpdateEmail` runs an Email/set, so the request has to
+        // declare the mail capability as well as submission. jmap-jam derives
+        // capabilities from the method names alone and would send only
+        // submission and core.
+        { using: ['urn:ietf:params:jmap:mail'] });
+        const submission = submitted.created?.submission;
+        if (!submission)
+            failed('submission', submitted.notCreated);
+        return {
+            submissionId: submission.id,
+            emailId: email.id,
+            threadId: email.threadId,
+        };
+    });
+}

package/dist/mailbox/thread.d.ts

@@ -0,0 +1,61 @@
+import type { MailClient } from './client.ts';
+import type { EmailAddress, Message, ThreadDetail } from './types.ts';
+/** A body part as `Email/get` returns it. */
+type BodyPart = {
+    partId?: string;
+    blobId?: string;
+    size?: number;
+    name?: string;
+    type?: string;
+    charset?: string;
+    disposition?: string;
+    cid?: string;
+};
+type BodyValue = {
+    value: string;
+    isEncodingProblem?: boolean;
+    isTruncated?: boolean;
+};
+export type RawMessage = {
+    id: string;
+    blobId: string;
+    threadId: string;
+    mailboxIds?: Record<string, boolean>;
+    keywords?: Record<string, boolean>;
+    size?: number;
+    receivedAt: string;
+    sentAt?: string;
+    messageId?: string[];
+    inReplyTo?: string[];
+    references?: string[];
+    from?: EmailAddress[];
+    to?: EmailAddress[];
+    cc?: EmailAddress[];
+    bcc?: EmailAddress[];
+    replyTo?: EmailAddress[];
+    subject?: string;
+    preview?: string;
+    hasAttachment?: boolean;
+    textBody?: BodyPart[];
+    htmlBody?: BodyPart[];
+    attachments?: BodyPart[];
+    bodyValues?: Record<string, BodyValue>;
+};
+/** How many bytes of each body part to fetch. A message with a megabyte of
+ *  quoted history should not stall a thread view; anything cut short is
+ *  reported as `isTruncated`. */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+/** Turn one `Email/get` result into a `Message`, resolving its bodies and
+ *  giving every attachment a download URL. */
+export declare function toMessage(raw: RawMessage, downloadUrlFor: (blob: {
+    blobId: string;
+    name: string;
+    type: string;
+}) => string): Message;
+export type ThreadOptions = {
+    /** Bytes of each body part to fetch. */
+    maxBodyBytes?: number;
+};
+/** One thread, with every message's body and attachments, oldest first. */
+export declare function thread(client: MailClient, threadId: string, options?: ThreadOptions): Promise<ThreadDetail>;
+export {};