@wtfalch/email 0.1.0

package/dist/mailbox/fake/index.js

@@ -0,0 +1,85 @@
+/**
+ * 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.js";
+import { FakeMailbox } from "./mailbox.js";
+import { SAMPLE } from "./sample.js";
+export { FakeMailbox };
+export { SAMPLE };
+const ORIGIN = 'https://email.example.com';
+/**
+ * The interception, and why it is here rather than a `fetch` option on
+ * `MailClient`.
+ *
+ * `jmap-jam` calls the bare global `fetch`, and takes no way to pass another
+ * one. A `fetch` option would therefore have to swap the global around each
+ * call and put it back, which is wrong under any overlap: two calls in flight
+ * save each other's replacement as "the original" and one of them restores
+ * the fake permanently.
+ *
+ * So the global is replaced once, by a function that **delegates**: anything
+ * not addressed to the fake's origin goes to the real `fetch` untouched.
+ * Nothing else in the application changes behaviour, which is the property
+ * that makes replacing a global acceptable at all. A count keeps several
+ * fakes from uninstalling each other.
+ */
+let installed = null;
+let live = 0;
+function install(route) {
+    live += 1;
+    if (installed)
+        return;
+    const original = globalThis.fetch;
+    installed = original;
+    globalThis.fetch = ((input, init) => {
+        const answered = route(input, init);
+        return answered ?? original(input, init);
+    });
+}
+function uninstall() {
+    live -= 1;
+    if (live > 0 || !installed)
+        return;
+    globalThis.fetch = installed;
+    installed = null;
+}
+/**
+ * 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 function fakeMail(options = {}) {
+    const mailbox = new FakeMailbox({ threads: SAMPLE, ...options });
+    install((input, init) => {
+        const url = String(typeof input === 'object' && input !== null && 'url' in input
+            ? input.url
+            : input);
+        if (!url.startsWith(ORIGIN))
+            return null;
+        return mailbox.fetch(url, init);
+    });
+    const client = new MailClient({
+        sessionUrl: `${ORIGIN}/.well-known/jmap`,
+        bearerToken: 'fake',
+    });
+    let disposed = false;
+    return {
+        client,
+        mailbox,
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            uninstall();
+        },
+    };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * A mailbox in memory, and the JMAP that answers questions about it.
+ *
+ * **A fake transport, not a fake API.** The obvious shortcut is to stub the
+ * exported functions -- `mailboxes()` returns three objects, `listThreads()`
+ * returns five rows -- and it is the wrong one: every story then exercises the
+ * stub, and the four-call chain, the result references, the body-value
+ * resolution and the null-handling that make up most of this package are
+ * never run. This answers JMAP instead, so a component drawn against the fake
+ * is drawn through exactly the code that will face a real server.
+ *
+ * It implements only the methods this package sends. Anything else answers
+ * `unknownMethod`, which is what a real server does and what the error path
+ * expects.
+ */
+import type { EmailAddress } from '../types.ts';
+export type SeedMessage = {
+    from: EmailAddress;
+    to?: readonly EmailAddress[];
+    subject: string;
+    text: string;
+    html?: string;
+    /** Minutes before "now". Later numbers are older. */
+    agoMinutes: number;
+    seen?: boolean;
+    flagged?: boolean;
+    attachments?: {
+        name: string;
+        type: string;
+        size: number;
+    }[];
+};
+export type SeedThread = {
+    mailbox: string;
+    messages: SeedMessage[];
+};
+export type FakeOptions = {
+    /** The signed-in person. */
+    me?: EmailAddress;
+    threads?: SeedThread[];
+    /** Fixed "now", so a story's timestamps do not move between runs. */
+    now?: Date;
+    /** Milliseconds of delay on every request, for looking at a loading state. */
+    latency?: number;
+};
+export declare class FakeMailbox {
+    #private;
+    readonly me: EmailAddress;
+    /** Everything `EmailSubmission/set` accepted, for a test that asserts a
+     *  message was actually sent rather than only composed. */
+    readonly submissions: {
+        emailId: string;
+        identityId: string;
+    }[];
+    constructor(options?: FakeOptions);
+    /** Put a thread in the mailbox. Returns its id. */
+    add(seed: SeedThread): string;
+    /** The session document, as Stalwart writes it. */
+    session(origin?: string): Record<string, unknown>;
+    /** Answer one method call. Exported for the transport, and for a test that
+     *  wants to assert on a single call's arguments. */
+    call(method: string, args: Record<string, unknown>): Record<string, unknown>;
+    /** A `fetch` that answers this mailbox. Hand it to `MailClient`. */
+    fetch: (input: unknown, init?: RequestInit) => Promise<Response>;
+}

package/dist/mailbox/fake/mailbox.js

@@ -0,0 +1,402 @@
+/**
+ * A mailbox in memory, and the JMAP that answers questions about it.
+ *
+ * **A fake transport, not a fake API.** The obvious shortcut is to stub the
+ * exported functions -- `mailboxes()` returns three objects, `listThreads()`
+ * returns five rows -- and it is the wrong one: every story then exercises the
+ * stub, and the four-call chain, the result references, the body-value
+ * resolution and the null-handling that make up most of this package are
+ * never run. This answers JMAP instead, so a component drawn against the fake
+ * is drawn through exactly the code that will face a real server.
+ *
+ * It implements only the methods this package sends. Anything else answers
+ * `unknownMethod`, which is what a real server does and what the error path
+ * expects.
+ */
+const ACCOUNT = 'fake-account';
+/** Stalwart's five, with its names and Stalwart's uniform sortOrder of 0 --
+ *  which is what makes a real tree come out alphabetical. */
+const MAILBOXES = [
+    { id: 'mb-inbox', name: 'Inbox', role: 'inbox' },
+    { id: 'mb-drafts', name: 'Drafts', role: 'drafts' },
+    { id: 'mb-sent', name: 'Sent Items', role: 'sent' },
+    { id: 'mb-junk', name: 'Junk Mail', role: 'junk' },
+    { id: 'mb-trash', name: 'Deleted Items', role: 'trash' },
+];
+export class FakeMailbox {
+    me;
+    #now;
+    #latency;
+    #emails = [];
+    #threads = new Map();
+    #counter = 0;
+    /** Everything `EmailSubmission/set` accepted, for a test that asserts a
+     *  message was actually sent rather than only composed. */
+    submissions = [];
+    constructor(options = {}) {
+        this.me = options.me ?? { name: 'Ada Lovelace', email: 'ada@example.com' };
+        this.#now = options.now ?? new Date('2026-09-07T12:00:00Z');
+        this.#latency = options.latency ?? 0;
+        for (const seed of options.threads ?? [])
+            this.add(seed);
+    }
+    /** Put a thread in the mailbox. Returns its id. */
+    add(seed) {
+        const threadId = `t${++this.#counter}`;
+        const ids = [];
+        for (const message of seed.messages) {
+            const id = `e${++this.#counter}`;
+            const at = new Date(this.#now.getTime() - seed.messages.indexOf(message) * 0);
+            const receivedAt = new Date(this.#now.getTime() - message.agoMinutes * 60_000).toISOString();
+            const attachments = (message.attachments ?? []).map((file, index) => ({
+                partId: `a${index}`,
+                blobId: `blob-${id}-${index}`,
+                size: file.size,
+                name: file.name,
+                type: file.type,
+                disposition: 'attachment',
+                cid: null,
+            }));
+            this.#emails.push({
+                id,
+                blobId: `blob-${id}`,
+                threadId,
+                mailboxIds: { [seed.mailbox]: true },
+                keywords: {
+                    ...(message.seen ? { $seen: true } : {}),
+                    ...(message.flagged ? { $flagged: true } : {}),
+                },
+                size: message.text.length + 400,
+                receivedAt,
+                sentAt: receivedAt,
+                messageId: [`${id}@example.com`],
+                inReplyTo: null,
+                references: null,
+                from: [message.from],
+                to: message.to ?? [this.me],
+                cc: null,
+                bcc: null,
+                replyTo: null,
+                subject: message.subject,
+                preview: message.text.slice(0, 80),
+                hasAttachment: attachments.length > 0,
+                textBody: [
+                    {
+                        partId: 't',
+                        blobId: `blob-${id}-t`,
+                        size: message.text.length,
+                        name: null,
+                        type: 'text/plain',
+                        charset: 'UTF-8',
+                        disposition: null,
+                        cid: null,
+                    },
+                ],
+                htmlBody: message.html
+                    ? [
+                        {
+                            partId: 'h',
+                            blobId: `blob-${id}-h`,
+                            size: message.html.length,
+                            name: null,
+                            type: 'text/html',
+                            charset: 'UTF-8',
+                            disposition: null,
+                            cid: null,
+                        },
+                    ]
+                    : [],
+                attachments,
+                bodyValues: {
+                    t: { value: message.text, isEncodingProblem: false, isTruncated: false },
+                    ...(message.html
+                        ? { h: { value: message.html, isEncodingProblem: false, isTruncated: false } }
+                        : {}),
+                },
+                _at: at,
+            });
+            ids.push(id);
+        }
+        this.#threads.set(threadId, ids);
+        return threadId;
+    }
+    #mailboxes() {
+        return MAILBOXES.map((box) => {
+            const inBox = this.#emails.filter((email) => email.mailboxIds[box.id]);
+            const unread = inBox.filter((email) => !email.keywords.$seen);
+            const threads = new Set(inBox.map((email) => email.threadId));
+            const unreadThreads = new Set(unread.map((email) => email.threadId));
+            return {
+                id: box.id,
+                name: box.name,
+                parentId: null,
+                role: box.role,
+                sortOrder: 0,
+                totalEmails: inBox.length,
+                unreadEmails: unread.length,
+                totalThreads: threads.size,
+                unreadThreads: unreadThreads.size,
+                isSubscribed: true,
+            };
+        });
+    }
+    /** The session document, as Stalwart writes it. */
+    session(origin = 'https://email.example.com') {
+        return {
+            capabilities: {
+                'urn:ietf:params:jmap:core': {},
+                'urn:ietf:params:jmap:mail': {},
+                'urn:ietf:params:jmap:submission': {},
+            },
+            accounts: {
+                [ACCOUNT]: {
+                    name: this.me.email,
+                    isPersonal: true,
+                    isReadOnly: false,
+                    accountCapabilities: {
+                        'urn:ietf:params:jmap:mail': {},
+                        'urn:ietf:params:jmap:submission': {},
+                    },
+                },
+            },
+            primaryAccounts: {
+                'urn:ietf:params:jmap:mail': ACCOUNT,
+                'urn:ietf:params:jmap:submission': ACCOUNT,
+            },
+            username: this.me.email,
+            apiUrl: `${origin}/jmap/`,
+            downloadUrl: `${origin}/jmap/download/{accountId}/{blobId}/{name}?accept={type}`,
+            uploadUrl: `${origin}/jmap/upload/{accountId}/`,
+            eventSourceUrl: `${origin}/jmap/eventsource/?types={types}&closeafter={closeafter}&ping={ping}`,
+            state: 'fake-session',
+        };
+    }
+    /** Answer one method call. Exported for the transport, and for a test that
+     *  wants to assert on a single call's arguments. */
+    call(method, args) {
+        switch (method) {
+            case 'Mailbox/get':
+                return { accountId: ACCOUNT, state: 'm1', list: this.#mailboxes(), notFound: [] };
+            case 'Identity/get':
+                return {
+                    accountId: ACCOUNT,
+                    state: 'i1',
+                    list: [
+                        {
+                            id: 'identity-1',
+                            name: this.me.name ?? '',
+                            email: this.me.email,
+                            replyTo: null,
+                            bcc: null,
+                            textSignature: '',
+                            htmlSignature: '',
+                            mayDelete: false,
+                        },
+                    ],
+                    notFound: [],
+                };
+            case 'Email/query': {
+                const filter = (args.filter ?? {});
+                let matching = this.#emails.filter((email) => this.#matches(email, filter));
+                matching.sort((a, b) => (a.receivedAt < b.receivedAt ? 1 : -1));
+                if (args.collapseThreads) {
+                    const seen = new Set();
+                    const collapsed = [];
+                    for (const email of matching) {
+                        if (seen.has(email.threadId))
+                            continue;
+                        seen.add(email.threadId);
+                        collapsed.push(email);
+                    }
+                    matching = collapsed;
+                }
+                const position = Number(args.position ?? 0);
+                const limit = args.limit === undefined ? matching.length : Number(args.limit);
+                return {
+                    accountId: ACCOUNT,
+                    queryState: 'q1',
+                    canCalculateChanges: false,
+                    position,
+                    ids: matching.slice(position, position + limit).map((email) => email.id),
+                    ...(args.calculateTotal ? { total: matching.length } : {}),
+                };
+            }
+            case 'Email/get': {
+                const ids = (args.ids ?? []);
+                const properties = args.properties;
+                const list = ids
+                    .map((id) => this.#emails.find((email) => email.id === id))
+                    .filter((email) => email !== undefined)
+                    .map((email) => this.#project(email, properties, Boolean(args.fetchTextBodyValues)));
+                return {
+                    accountId: ACCOUNT,
+                    state: 'e1',
+                    list,
+                    notFound: ids.filter((id) => !this.#emails.some((email) => email.id === id)),
+                };
+            }
+            case 'Thread/get': {
+                const ids = (args.ids ?? []);
+                return {
+                    accountId: ACCOUNT,
+                    state: 'th1',
+                    list: ids
+                        .filter((id) => this.#threads.has(id))
+                        .map((id) => ({ id, emailIds: this.#threads.get(id) ?? [] })),
+                    notFound: ids.filter((id) => !this.#threads.has(id)),
+                };
+            }
+            case 'Email/set': {
+                const create = (args.create ?? {});
+                const created = {};
+                for (const [key, draft] of Object.entries(create)) {
+                    const id = `e${++this.#counter}`;
+                    const threadId = `t${++this.#counter}`;
+                    this.#emails.push({
+                        ...draft,
+                        id,
+                        blobId: `blob-${id}`,
+                        threadId,
+                        receivedAt: this.#now.toISOString(),
+                    });
+                    this.#threads.set(threadId, [id]);
+                    created[key] = { id, blobId: `blob-${id}`, threadId, size: 512 };
+                }
+                return { accountId: ACCOUNT, oldState: '1', newState: '2', created, notCreated: null };
+            }
+            case 'EmailSubmission/set': {
+                const create = (args.create ?? {});
+                const created = {};
+                for (const [key, submission] of Object.entries(create)) {
+                    this.submissions.push(submission);
+                    created[key] = { id: `sub-${this.submissions.length}`, undoStatus: 'final' };
+                    // The move to Sent that `onSuccessUpdateEmail` asks for.
+                    const email = this.#emails.find((one) => one.id === submission.emailId);
+                    if (email) {
+                        email.mailboxIds = { 'mb-sent': true };
+                        email.keywords = { $seen: true };
+                    }
+                }
+                return { accountId: ACCOUNT, oldState: '2', newState: '3', created, notCreated: null };
+            }
+            default:
+                return {
+                    type: 'unknownMethod',
+                    description: `the fake mailbox does not implement ${method}`,
+                };
+        }
+    }
+    #matches(email, filter) {
+        const mailboxIds = email.mailboxIds;
+        if (typeof filter.inMailbox === 'string' && !mailboxIds[filter.inMailbox])
+            return false;
+        if (Array.isArray(filter.inMailboxOtherThan)) {
+            const excluded = filter.inMailboxOtherThan;
+            if (Object.keys(mailboxIds).every((id) => excluded.includes(id)))
+                return false;
+        }
+        if (typeof filter.text === 'string') {
+            const haystack = [
+                email.subject,
+                email.bodyValues?.t?.value,
+                ...(email.from ?? []).map((a) => `${a.name ?? ''} ${a.email}`),
+            ]
+                .join(' ')
+                .toLowerCase();
+            if (!haystack.includes(filter.text.toLowerCase()))
+                return false;
+        }
+        if (typeof filter.from === 'string') {
+            const from = (email.from ?? []).map((a) => a.email).join(' ');
+            if (!from.toLowerCase().includes(filter.from.toLowerCase()))
+                return false;
+        }
+        if (filter.hasAttachment === true && !email.hasAttachment)
+            return false;
+        return true;
+    }
+    /** Return only what was asked for, the way a server does -- so a component
+     *  reading a property the query never requested fails here as it would
+     *  there. */
+    #project(email, properties, bodies) {
+        const { _at, bodyValues, ...rest } = email;
+        const base = { ...rest, ...(bodies ? { bodyValues } : {}) };
+        if (!properties)
+            return base;
+        const out = { id: email.id };
+        for (const key of properties)
+            if (key in base)
+                out[key] = base[key];
+        if (bodies)
+            out.bodyValues = base.bodyValues;
+        return out;
+    }
+    /** A `fetch` that answers this mailbox. Hand it to `MailClient`. */
+    fetch = async (input, init) => {
+        if (this.#latency > 0)
+            await new Promise((resolve) => setTimeout(resolve, this.#latency));
+        const url = String(input);
+        const json = (body) => new Response(JSON.stringify(body), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+        });
+        if (!init || (init.method ?? 'GET') === 'GET') {
+            if (url.includes('/jmap/download/'))
+                return new Response('fake attachment bytes');
+            if (url.includes('/eventsource')) {
+                // An open stream that never sends: `push` stays connected and quiet.
+                return new Response(new ReadableStream(), {
+                    headers: { 'Content-Type': 'text/event-stream' },
+                });
+            }
+            return json(this.session(new URL(url).origin));
+        }
+        const body = JSON.parse(String(init.body));
+        const responses = [];
+        for (const [method, args, id] of body.methodCalls) {
+            const resolved = this.#resolveRefs(args, responses);
+            const result = this.call(method, resolved);
+            responses.push([result.type === 'unknownMethod' ? 'error' : method, result, id]);
+        }
+        return json({ methodResponses: responses, sessionState: 'fake-session' });
+    };
+    /** Replace `#ids` result references with the values they point at, which is
+     *  the whole reason a page of threads is one round trip. */
+    #resolveRefs(args, done) {
+        const out = {};
+        for (const [key, value] of Object.entries(args)) {
+            if (!key.startsWith('#')) {
+                out[key] = value;
+                continue;
+            }
+            const reference = value;
+            const source = done.find(([, , id]) => id === reference.resultOf)?.[1];
+            out[key.slice(1)] = source ? pointer(source, reference.path) : [];
+        }
+        return out;
+    }
+}
+/** RFC 8620 §3.7's pointer, with the `*` that maps over a list. */
+function pointer(value, path) {
+    let current = value;
+    for (const rawSegment of path.split('/').filter(Boolean)) {
+        const segment = rawSegment.replaceAll('~1', '/').replaceAll('~0', '~');
+        if (segment === '*') {
+            if (!Array.isArray(current))
+                return [];
+            // The rest of the path applies to every item, and a list of lists is
+            // flattened -- which is what turns `/list/*/emailIds` into every id.
+            const rest = path.slice(path.indexOf('*') + 1);
+            const mapped = current.map((item) => pointer(item, rest));
+            return mapped.flat();
+        }
+        if (Array.isArray(current))
+            current = current[Number(segment)];
+        else if (current && typeof current === 'object') {
+            current = current[segment];
+        }
+        else
+            return undefined;
+    }
+    return current;
+}

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

@@ -0,0 +1,11 @@
+import type { SeedThread } from './mailbox.ts';
+/**
+ * A plausible inbox.
+ *
+ * Chosen to put every state a list view has to draw on the screen at once:
+ * unread and read, a thread with several messages, one with an attachment,
+ * one flagged, one from a machine with no display name, and one subject long
+ * enough to need truncating. A sample that is five tidy one-line messages
+ * demonstrates a component that has never met mail.
+ */
+export declare const SAMPLE: SeedThread[];

package/dist/mailbox/fake/sample.js

@@ -0,0 +1,85 @@
+/**
+ * A plausible inbox.
+ *
+ * Chosen to put every state a list view has to draw on the screen at once:
+ * unread and read, a thread with several messages, one with an attachment,
+ * one flagged, one from a machine with no display name, and one subject long
+ * enough to need truncating. A sample that is five tidy one-line messages
+ * demonstrates a component that has never met mail.
+ */
+export const SAMPLE = [
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Charles Babbage', email: 'charles@example.com' },
+                subject: 'Engine schedule',
+                text: 'The mill is ready and the store is not. Can we push the demonstration to Thursday?',
+                agoMinutes: 12,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Luigi Menabrea', email: 'luigi@example.org' },
+                subject: 'Notes on the analytical engine, and a question about the notes',
+                text: 'I have finished the translation. The notes are now longer than the paper, which I suspect is the point.',
+                agoMinutes: 180,
+                seen: true,
+            },
+            {
+                from: { name: 'Ada Lovelace', email: 'ada@example.com' },
+                subject: 'Re: Notes on the analytical engine, and a question about the notes',
+                text: 'Good. Keep them longer than the paper.',
+                agoMinutes: 90,
+                seen: true,
+            },
+            {
+                from: { name: 'Luigi Menabrea', email: 'luigi@example.org' },
+                subject: 'Re: Notes on the analytical engine, and a question about the notes',
+                text: 'Then I will add the table of Bernoulli numbers as well.',
+                agoMinutes: 45,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { email: 'noreply@notifications.example.org' },
+                subject: 'Your monthly statement is ready',
+                text: 'Your statement for August is attached. This mailbox is not monitored.',
+                agoMinutes: 600,
+                seen: true,
+                attachments: [{ name: 'statement-august.pdf', type: 'application/pdf', size: 82_411 }],
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: "Grace O'Brien", email: 'grace@example.net' },
+                subject: 'Punch cards — reorder before Friday',
+                text: 'We are down to two boxes. I have put the order together; it needs your signature.',
+                agoMinutes: 1_500,
+                flagged: true,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-sent',
+        messages: [
+            {
+                from: { name: 'Ada Lovelace', email: 'ada@example.com' },
+                to: [{ name: 'Charles Babbage', email: 'charles@example.com' }],
+                subject: 'Thursday works',
+                text: 'Thursday works. I will bring the tables.',
+                agoMinutes: 5,
+                seen: true,
+            },
+        ],
+    },
+];

package/dist/mailbox/identities.d.ts

@@ -0,0 +1,4 @@
+import type { MailClient } from './client.ts';
+import type { MailIdentity } from './types.ts';
+/** Every address this account may send as. */
+export declare function identities(client: MailClient): Promise<readonly MailIdentity[]>;

package/dist/mailbox/identities.js

@@ -0,0 +1,18 @@
+import { guard } from "./errors.js";
+/** Every address this account may send as. */
+export async function identities(client) {
+    const { jam, accountId } = await client.connect();
+    return guard('identities', async () => {
+        const [result] = await jam.api.Identity.get({ accountId });
+        return result.list.map((identity) => ({
+            id: identity.id,
+            name: identity.name ?? '',
+            email: identity.email,
+            replyTo: identity.replyTo ?? [],
+            bcc: identity.bcc ?? [],
+            textSignature: identity.textSignature ?? '',
+            htmlSignature: identity.htmlSignature ?? '',
+            mayDelete: identity.mayDelete ?? false,
+        }));
+    });
+}