@wtfalch/email 0.1.0

package/dist/mailbox/thread.js

@@ -0,0 +1,153 @@
+import { MailError, guard } from "./errors.js";
+import { expandTemplate } from "./uri.js";
+const MESSAGE_PROPERTIES = [
+    'id',
+    'blobId',
+    'threadId',
+    'mailboxIds',
+    'keywords',
+    'size',
+    'receivedAt',
+    'sentAt',
+    'messageId',
+    'inReplyTo',
+    'references',
+    'from',
+    'to',
+    'cc',
+    'bcc',
+    'replyTo',
+    'subject',
+    'preview',
+    'hasAttachment',
+    'textBody',
+    'htmlBody',
+    'attachments',
+    'bodyValues',
+];
+const BODY_PROPERTIES = [
+    'partId',
+    'blobId',
+    'size',
+    'name',
+    'type',
+    'charset',
+    'disposition',
+    'cid',
+];
+/** 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 const DEFAULT_MAX_BODY_BYTES = 512 * 1024;
+function joinParts(parts, values) {
+    if (!parts || parts.length === 0 || !values)
+        return { text: null, truncated: false };
+    const pieces = [];
+    let truncated = false;
+    for (const part of parts) {
+        if (part.partId === undefined)
+            continue;
+        const value = values[part.partId];
+        if (!value)
+            continue;
+        pieces.push(value.value);
+        if (value.isTruncated)
+            truncated = true;
+    }
+    if (pieces.length === 0)
+        return { text: null, truncated };
+    return { text: pieces.join('\n'), truncated };
+}
+/** Turn one `Email/get` result into a `Message`, resolving its bodies and
+ *  giving every attachment a download URL. */
+export function toMessage(raw, downloadUrlFor) {
+    const text = joinParts(raw.textBody, raw.bodyValues);
+    const html = joinParts(raw.htmlBody, raw.bodyValues);
+    const keywords = raw.keywords ?? {};
+    const attachments = (raw.attachments ?? [])
+        // A part with no blob cannot be fetched, so it is not an attachment a
+        // reader can do anything with.
+        .filter((part) => typeof part.blobId === 'string')
+        .map((part) => {
+        const name = part.name ?? 'attachment';
+        const type = part.type ?? 'application/octet-stream';
+        return {
+            blobId: part.blobId,
+            name,
+            type,
+            size: part.size ?? 0,
+            disposition: part.disposition === 'inline' ? 'inline' : 'attachment',
+            cid: part.cid ? part.cid.replace(/^<|>$/g, '') : null,
+            downloadUrl: downloadUrlFor({ blobId: part.blobId, name, type }),
+        };
+    });
+    return {
+        id: raw.id,
+        blobId: raw.blobId,
+        threadId: raw.threadId,
+        subject: raw.subject ?? '',
+        from: raw.from ?? [],
+        to: raw.to ?? [],
+        cc: raw.cc ?? [],
+        bcc: raw.bcc ?? [],
+        replyTo: raw.replyTo ?? [],
+        sentAt: raw.sentAt ?? null,
+        receivedAt: raw.receivedAt,
+        size: raw.size ?? 0,
+        preview: raw.preview ?? '',
+        messageId: raw.messageId ?? [],
+        inReplyTo: raw.inReplyTo ?? [],
+        references: raw.references ?? [],
+        text: text.text,
+        html: html.text,
+        isTruncated: text.truncated || html.truncated,
+        attachments,
+        keywords,
+        mailboxIds: Object.keys(raw.mailboxIds ?? {}),
+        isUnread: keywords.$seen !== true,
+        isFlagged: keywords.$flagged === true,
+        isDraft: keywords.$draft === true,
+    };
+}
+/** One thread, with every message's body and attachments, oldest first. */
+export async function thread(client, threadId, options = {}) {
+    const { jam, accountId, doc } = await client.connect();
+    return guard('thread', async () => {
+        const [results] = await jam.requestMany((t) => {
+            const threads = t.Thread.get({ accountId, ids: [threadId] });
+            const messages = t.Email.get({
+                accountId,
+                ids: threads.$ref('/list/*/emailIds'),
+                properties: MESSAGE_PROPERTIES,
+                bodyProperties: [...BODY_PROPERTIES],
+                fetchTextBodyValues: true,
+                fetchHTMLBodyValues: true,
+                maxBodyValueBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+            });
+            return { threads, messages };
+        });
+        const found = results.threads.list;
+        if (found.length === 0) {
+            throw new MailError(`no thread ${threadId} in this account`, {
+                type: 'notFound',
+                operation: 'thread',
+            });
+        }
+        const template = doc.downloadUrl;
+        const raw = results.messages.list;
+        const messages = raw
+            .map((message) => toMessage(message, (blob) => expandTemplate(template, {
+            accountId,
+            blobId: blob.blobId,
+            name: blob.name,
+            type: blob.type,
+        })))
+            // A thread reads oldest first, whatever order the server listed it in.
+            .sort((a, b) => (a.receivedAt < b.receivedAt ? -1 : a.receivedAt > b.receivedAt ? 1 : 0));
+        return {
+            id: threadId,
+            subject: messages.find((message) => message.subject)?.subject ?? '',
+            messages,
+        };
+    });
+}

package/dist/mailbox/threads.d.ts

@@ -0,0 +1,44 @@
+import type { MailClient } from './client.ts';
+import type { EmailAddress, MailFilter, MailSort, ThreadPage, ThreadSummary } from './types.ts';
+type SummaryEmail = {
+    id: string;
+    threadId: string;
+    mailboxIds: Record<string, boolean>;
+    keywords: Record<string, boolean>;
+    from?: EmailAddress[];
+    to?: EmailAddress[];
+    subject?: string;
+    receivedAt: string;
+    preview?: string;
+    hasAttachment?: boolean;
+};
+export type ListOptions = {
+    /** Index of the first thread to return. */
+    position?: number;
+    /** How many threads to return. Servers cap this; Stalwart's default cap is
+     *  generous but a list view should ask for what it draws. */
+    limit?: number;
+    sort?: readonly MailSort[];
+    /** Ask the server how many threads match. It is allowed to refuse, in
+     *  which case `total` comes back undefined. */
+    calculateTotal?: boolean;
+};
+/**
+ * Fold a thread's messages into one list row.
+ *
+ * `latest` is the message the query returned for the thread, which is the one
+ * the sort put first; `members` is every message in the thread, in whatever
+ * order the server listed them.
+ */
+export declare function summarise(threadId: string, latest: SummaryEmail, members: readonly SummaryEmail[]): ThreadSummary;
+/**
+ * One page of threads matching a filter.
+ *
+ * Four method calls chained by result reference, so the whole page costs one
+ * round trip: query the newest message per thread, fetch those messages,
+ * fetch their threads' member ids, fetch the members.
+ */
+export declare function queryThreads(client: MailClient, filter: MailFilter, options?: ListOptions): Promise<ThreadPage>;
+/** A page of the threads in one mailbox, newest first. */
+export declare function listThreads(client: MailClient, mailboxId: string, options?: ListOptions): Promise<ThreadPage>;
+export {};

package/dist/mailbox/threads.js

@@ -0,0 +1,156 @@
+import { guard } from "./errors.js";
+/** What a list row needs from the newest message in each thread. */
+const SUMMARY_PROPERTIES = [
+    'id',
+    'threadId',
+    'mailboxIds',
+    'keywords',
+    'from',
+    'to',
+    'subject',
+    'receivedAt',
+    'preview',
+    'hasAttachment',
+];
+/** What every other message in the thread contributes: the unread count, the
+ *  participant list, and whether anything in the thread is flagged. */
+const MEMBER_PROPERTIES = [
+    'id',
+    'threadId',
+    'mailboxIds',
+    'keywords',
+    'from',
+    'subject',
+    'receivedAt',
+    'hasAttachment',
+];
+const DEFAULT_SORT = [{ property: 'receivedAt', isAscending: false }];
+function keywords(email, keyword) {
+    return Boolean(email?.keywords?.[keyword]);
+}
+/**
+ * Fold a thread's messages into one list row.
+ *
+ * `latest` is the message the query returned for the thread, which is the one
+ * the sort put first; `members` is every message in the thread, in whatever
+ * order the server listed them.
+ */
+export function summarise(threadId, latest, members) {
+    // A thread whose members could not be fetched still has the one message the
+    // query returned, and a row drawn from it is right in every field but the
+    // counts.
+    const all = members.length > 0 ? members : [latest];
+    const chronological = [...all].sort((a, b) => (a.receivedAt < b.receivedAt ? -1 : 1));
+    const participants = [];
+    const seenAddresses = new Set();
+    for (const message of chronological) {
+        for (const address of message.from ?? []) {
+            const key = address.email.toLowerCase();
+            if (seenAddresses.has(key))
+                continue;
+            seenAddresses.add(key);
+            participants.push(address);
+        }
+    }
+    const mailboxIds = new Set();
+    for (const message of all)
+        for (const id of Object.keys(message.mailboxIds ?? {}))
+            mailboxIds.add(id);
+    // The thread's subject is the one it started with: a reply may drop or
+    // re-prefix it, and a list keyed on the newest subject reads as a new
+    // thread. `Email/get` omits `subject` entirely for a message with no
+    // Subject header, so the message the query returned is the last resort.
+    const subject = chronological.find((message) => message.subject)?.subject ?? latest.subject ?? '';
+    return {
+        id: threadId,
+        latestEmailId: latest.id,
+        subject,
+        preview: latest.preview ?? '',
+        receivedAt: latest.receivedAt,
+        participants,
+        from: latest.from?.[0] ?? null,
+        to: latest.to ?? [],
+        emailCount: all.length,
+        unreadCount: all.filter((message) => !keywords(message, '$seen')).length,
+        hasAttachment: all.some((message) => message.hasAttachment === true),
+        isFlagged: all.some((message) => keywords(message, '$flagged')),
+        isDraft: keywords(latest, '$draft'),
+        mailboxIds: [...mailboxIds],
+    };
+}
+/**
+ * One page of threads matching a filter.
+ *
+ * Four method calls chained by result reference, so the whole page costs one
+ * round trip: query the newest message per thread, fetch those messages,
+ * fetch their threads' member ids, fetch the members.
+ */
+export async function queryThreads(client, filter, options = {}) {
+    const { jam, accountId } = await client.connect();
+    const position = options.position ?? 0;
+    // `MailFilter` is deliberately readonly; the wire type is not, so the one
+    // array field is copied rather than cast away.
+    const { inMailboxOtherThan, ...conditions } = filter;
+    const condition = {
+        ...conditions,
+        ...(inMailboxOtherThan === undefined ? {} : { inMailboxOtherThan: [...inMailboxOtherThan] }),
+    };
+    return guard('threads.query', async () => {
+        const [results] = await jam.requestMany((t) => {
+            const query = t.Email.query({
+                accountId,
+                filter: condition,
+                collapseThreads: true,
+                sort: options.sort ?? DEFAULT_SORT,
+                position,
+                ...(options.limit === undefined ? {} : { limit: options.limit }),
+                calculateTotal: options.calculateTotal ?? false,
+            });
+            const latest = t.Email.get({
+                accountId,
+                ids: query.$ref('/ids'),
+                properties: SUMMARY_PROPERTIES,
+            });
+            const threads = t.Thread.get({
+                accountId,
+                ids: latest.$ref('/list/*/threadId'),
+            });
+            const members = t.Email.get({
+                accountId,
+                ids: threads.$ref('/list/*/emailIds'),
+                properties: MEMBER_PROPERTIES,
+            });
+            return { query, latest, threads, members };
+        });
+        const query = results.query;
+        const latest = results.latest;
+        const threads = results.threads;
+        const members = results.members;
+        const latestById = new Map(latest.list.map((email) => [email.id, email]));
+        const memberById = new Map(members.list.map((email) => [email.id, email]));
+        const threadById = new Map(threads.list.map((thread) => [thread.id, thread]));
+        const items = [];
+        for (const emailId of query.ids) {
+            // The query can name a message `Email/get` did not return, if it was
+            // destroyed between the two calls in the same request.
+            const email = latestById.get(emailId);
+            if (!email)
+                continue;
+            const thread = threadById.get(email.threadId);
+            const memberEmails = (thread?.emailIds ?? [])
+                .map((id) => memberById.get(id))
+                .filter((member) => member !== undefined);
+            items.push(summarise(email.threadId, email, memberEmails));
+        }
+        return {
+            items,
+            position: query.position ?? position,
+            total: query.total,
+            state: latest.state,
+        };
+    });
+}
+/** A page of the threads in one mailbox, newest first. */
+export function listThreads(client, mailboxId, options = {}) {
+    return queryThreads(client, { inMailbox: mailboxId }, options);
+}

package/dist/mailbox/types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * The package's public shapes. Nothing here comes from `jmap-jam` or
+ * `jmap-rfc-types`: those ship raw TypeScript with `.ts` import specifiers,
+ * which only compiles under `allowImportingTsExtensions`, and a consumer
+ * should not have to turn that on to use this package. The JMAP wire types
+ * stay behind the client.
+ */
+/**
+ * A mailbox address, with the display name when the message carried one.
+ *
+ * `name` may be `null` as well as absent: Stalwart sends `null` for a header
+ * field the message did not have, rather than leaving the property out, and
+ * a type that promised only `string | undefined` would be lying about what
+ * arrives.
+ */
+export type EmailAddress = {
+    name?: string | null;
+    email: string;
+};
+/** The purposes RFC 8621 §2 names, whatever a mailbox is called. */
+export type MailboxRole = 'all' | 'archive' | 'drafts' | 'flagged' | 'important' | 'inbox' | 'junk' | 'sent' | 'subscribed' | 'trash';
+/** What the session document says about the signed-in person. */
+export type MailSession = {
+    /** The login name the token resolved to. */
+    username: string;
+    /** The account this package reads and writes. */
+    accountId: string;
+    /** The account's display name. */
+    accountName: string;
+    isReadOnly: boolean;
+    /** True when the account may submit mail, so a composer can be hidden
+     *  rather than failing at send. */
+    maySubmit: boolean;
+};
+/** A mailbox with its children, as the tree the server's flat list describes. */
+export type MailboxNode = {
+    id: string;
+    name: string;
+    parentId: string | null;
+    role: MailboxRole | null;
+    sortOrder: number;
+    totalEmails: number;
+    unreadEmails: number;
+    totalThreads: number;
+    unreadThreads: number;
+    isSubscribed: boolean;
+    /** The names from the root down to and including this one, e.g.
+     *  `['Archive', '2026']`. A stable label, and a sort key. */
+    path: readonly string[];
+    children: readonly MailboxNode[];
+};
+/** One row of a thread list: what a list view draws without opening anything. */
+export type ThreadSummary = {
+    /** The thread id, which is the row's identity. */
+    id: string;
+    /** The most recent message, for opening straight to it. */
+    latestEmailId: string;
+    subject: string;
+    preview: string;
+    /** The most recent message's arrival time, which orders the list. */
+    receivedAt: string;
+    /** Everyone who wrote in the thread, oldest first, no duplicates. */
+    participants: readonly EmailAddress[];
+    /** The most recent message's sender. */
+    from: EmailAddress | null;
+    to: readonly EmailAddress[];
+    emailCount: number;
+    /** Messages in the thread without the `$seen` keyword. */
+    unreadCount: number;
+    hasAttachment: boolean;
+    isFlagged: boolean;
+    isDraft: boolean;
+    /** Every mailbox the thread's messages sit in. */
+    mailboxIds: readonly string[];
+};
+/** A page of a thread list. */
+export type ThreadPage = {
+    items: readonly ThreadSummary[];
+    /** The index of the first item within the whole result. The server may
+     *  clamp what was asked for, so this is the position actually returned. */
+    position: number;
+    /** How many threads match, when the server was asked to count. */
+    total: number | undefined;
+    /** The `Email` type's state at the time of the query. */
+    state: string;
+};
+/** An attachment, with the URL that fetches its bytes. */
+export type Attachment = {
+    blobId: string;
+    name: string;
+    type: string;
+    size: number;
+    /** `inline` for a part the body references, `attachment` otherwise. */
+    disposition: 'inline' | 'attachment';
+    /** The `Content-ID` an inline part is referenced by, without the angle
+     *  brackets, so an HTML body's `cid:` URLs can be rewritten. */
+    cid: string | null;
+    /** An absolute URL. It needs the same `Authorization` header as the API,
+     *  so a browser cannot use it as a bare `<img src>`: fetch it and make an
+     *  object URL. */
+    downloadUrl: string;
+};
+/** One message, with its body resolved. */
+export type Message = {
+    id: string;
+    blobId: string;
+    threadId: string;
+    subject: string;
+    from: readonly EmailAddress[];
+    to: readonly EmailAddress[];
+    cc: readonly EmailAddress[];
+    bcc: readonly EmailAddress[];
+    replyTo: readonly EmailAddress[];
+    sentAt: string | null;
+    receivedAt: string;
+    size: number;
+    preview: string;
+    /** The `Message-ID` header, which a reply quotes in `In-Reply-To`. */
+    messageId: readonly string[];
+    inReplyTo: readonly string[];
+    references: readonly string[];
+    /** The plain-text body, parts joined. `null` when the message has only an
+     *  HTML body. */
+    text: string | null;
+    /** The HTML body, parts joined. `null` when the message is plain text. */
+    html: string | null;
+    /** True when a body came back cut short at `maxBodyBytes`; the rest needs
+     *  another fetch. */
+    isTruncated: boolean;
+    attachments: readonly Attachment[];
+    keywords: Readonly<Record<string, boolean>>;
+    mailboxIds: readonly string[];
+    isUnread: boolean;
+    isFlagged: boolean;
+    isDraft: boolean;
+};
+/** A thread, opened. */
+export type ThreadDetail = {
+    id: string;
+    /** The subject of the first message that has one, which names the thread. */
+    subject: string;
+    /** Oldest first, as a conversation reads. */
+    messages: readonly Message[];
+};
+/** A sending identity: an address this account may send as. */
+export type MailIdentity = {
+    id: string;
+    name: string;
+    email: string;
+    replyTo: readonly EmailAddress[];
+    bcc: readonly EmailAddress[];
+    textSignature: string;
+    htmlSignature: string;
+    mayDelete: boolean;
+};
+/** A message to send. Addresses are objects and bodies are strings; the wire
+ *  shape (body parts, body values, the envelope) is this package's business. */
+export type Draft = {
+    /** The identity to send as. Its address becomes the envelope's `MAIL FROM`
+     *  and, unless `from` says otherwise, the `From` header. */
+    identityId: string;
+    from?: readonly EmailAddress[];
+    to: readonly EmailAddress[];
+    cc?: readonly EmailAddress[];
+    bcc?: readonly EmailAddress[];
+    replyTo?: readonly EmailAddress[];
+    subject: string;
+    text?: string;
+    html?: string;
+    /** `Message-ID`s this message replies to. */
+    inReplyTo?: readonly string[];
+    /** The `References` chain, oldest first. */
+    references?: readonly string[];
+    /** Blobs to attach: freshly uploaded, or carried from a message being
+     *  forwarded. */
+    attachments?: readonly DraftAttachment[];
+};
+export type DraftAttachment = {
+    blobId: string;
+    name: string;
+    type: string;
+    /** `inline` needs a `cid` the HTML body references. */
+    disposition?: 'inline' | 'attachment';
+    cid?: string;
+};
+/** What `send` reports back. */
+export type Sent = {
+    /** The submission, which `EmailSubmission/get` reports delivery for. */
+    submissionId: string;
+    /** The id the message has once it is in Sent. */
+    emailId: string;
+    threadId: string;
+};
+/** The per-type state strings a push event carries. A value that differs
+ *  from the one a previous call returned means that type changed. */
+export type ChangedState = {
+    Mailbox?: string;
+    Thread?: string;
+    Email?: string;
+    EmailSubmission?: string;
+    Identity?: string;
+    [type: string]: string | undefined;
+};
+/** The conditions a thread query filters on. Every field set is required to
+ *  match, which is what RFC 8621 §4.4 says a single filter condition means. */
+export type MailFilter = {
+    /** Only threads with a message in this mailbox. */
+    inMailbox?: string;
+    /** Exclude threads whose only messages are in these mailboxes, e.g. Trash. */
+    inMailboxOtherThan?: readonly string[];
+    /** Received strictly before this UTC timestamp. */
+    before?: string;
+    /** Received at or after this UTC timestamp. */
+    after?: string;
+    minSize?: number;
+    maxSize?: number;
+    hasKeyword?: string;
+    notKeyword?: string;
+    hasAttachment?: boolean;
+    /** Free text across the parts the server chooses to index. */
+    text?: string;
+    from?: string;
+    to?: string;
+    cc?: string;
+    bcc?: string;
+    subject?: string;
+    body?: string;
+};
+/** How to order a thread list. `receivedAt` newest-first is the default. */
+export type MailSort = {
+    property: 'receivedAt' | 'sentAt' | 'size' | 'subject' | 'from' | 'to';
+    isAscending?: boolean;
+};

package/dist/mailbox/types.js

@@ -0,0 +1,8 @@
+/**
+ * The package's public shapes. Nothing here comes from `jmap-jam` or
+ * `jmap-rfc-types`: those ship raw TypeScript with `.ts` import specifiers,
+ * which only compiles under `allowImportingTsExtensions`, and a consumer
+ * should not have to turn that on to use this package. The JMAP wire types
+ * stay behind the client.
+ */
+export {};

package/dist/mailbox/uri.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The session document's `downloadUrl`, `uploadUrl` and `eventSourceUrl` are
+ * RFC 6570 level-1 templates, and RFC 8620 §6.2 is explicit that a client
+ * must URI-encode the values it substitutes. jmap-jam's own expander does a
+ * plain `replaceAll`, so an attachment called `Q3 report (final).pdf`, or any
+ * blob id with a `/` in it, produces a broken or wrong URL.
+ *
+ * Stalwart's download template is
+ * `https://email.<apex>/jmap/download/{accountId}/{blobId}/{name}?type={type}`,
+ * where an unencoded `/` in `name` would silently change the path.
+ */
+/**
+ * Expand an RFC 6570 level-1 template, percent-encoding every value.
+ *
+ * @throws {Error} when the template names a variable `params` does not supply.
+ */
+export declare function expandTemplate(template: string, params: Record<string, string>): string;

package/dist/mailbox/uri.js

@@ -0,0 +1,26 @@
+/**
+ * The session document's `downloadUrl`, `uploadUrl` and `eventSourceUrl` are
+ * RFC 6570 level-1 templates, and RFC 8620 §6.2 is explicit that a client
+ * must URI-encode the values it substitutes. jmap-jam's own expander does a
+ * plain `replaceAll`, so an attachment called `Q3 report (final).pdf`, or any
+ * blob id with a `/` in it, produces a broken or wrong URL.
+ *
+ * Stalwart's download template is
+ * `https://email.<apex>/jmap/download/{accountId}/{blobId}/{name}?type={type}`,
+ * where an unencoded `/` in `name` would silently change the path.
+ */
+const VARIABLE = /\{([^{}]+)\}/g;
+/**
+ * Expand an RFC 6570 level-1 template, percent-encoding every value.
+ *
+ * @throws {Error} when the template names a variable `params` does not supply.
+ */
+export function expandTemplate(template, params) {
+    return template.replace(VARIABLE, (_match, name) => {
+        const value = params[name];
+        if (value === undefined) {
+            throw new Error(`the URI template needs a value for {${name}}: ${template}`);
+        }
+        return encodeURIComponent(value);
+    });
+}