@wtfalch/email 0.4.1 → 0.6.0

package/dist/mailbox/download.d.ts

@@ -0,0 +1,43 @@
+import type { MailClient } from './client.ts';
+import type { Attachment } from './types.ts';
+/**
+ * Fetching an attachment's bytes.
+ *
+ * **This module exists because a download URL is not a link.** JMAP's
+ * `downloadUrl` carries no credential of its own — RFC 8620 §6.2 expects the
+ * same authentication the API uses — so `<a href={downloadUrl} download>` and
+ * `<img src={cid}>` both fetch it without an `Authorization` header and get a
+ * 401. The bytes have to be fetched by code that holds the token, and the
+ * result handed to the browser as a blob it already has.
+ *
+ * That is the whole reason attachments were unreachable: `ThreadView` has
+ * taken an `onDownload` since it was written, and nothing could supply one
+ * without this.
+ *
+ * **`credentials: 'omit'`, for the reason `client.ts` gives at length.** A
+ * refused request makes Stalwart answer with `WWW-Authenticate: Basic` as
+ * well as `Bearer`, and a browser allowed to use credentials honours the
+ * second by opening its native password prompt — a modal that hides whatever
+ * the application was about to say. Declining that here keeps a 401 an
+ * ordinary response.
+ */
+/** How much of a message this will pull into memory before refusing. A mail
+ *  server will happily serve a 2GB blob and a browser tab will not survive
+ *  holding one; Stalwart's own default message size limit is well under this.
+ *  A caller that genuinely wants more passes its own `maxBytes`. */
+export declare const DEFAULT_MAX_DOWNLOAD_BYTES: number;
+export type DownloadOptions = {
+    /** Refuse a blob larger than this, rather than exhausting the tab. */
+    maxBytes?: number;
+    /** Abort the fetch — a person navigating away from a slow attachment. */
+    signal?: AbortSignal;
+};
+/**
+ * An attachment's bytes, as a `Blob`.
+ *
+ * The type comes from the message rather than from the response: a server
+ * that sends `application/octet-stream` for everything would otherwise turn
+ * every PDF into a file the operating system cannot open, and the part's
+ * declared type is the one the sender chose.
+ */
+export declare function downloadAttachment(client: MailClient, attachment: Pick<Attachment, 'blobId' | 'name' | 'type' | 'size' | 'downloadUrl'>, options?: DownloadOptions): Promise<Blob>;

package/dist/mailbox/download.js

@@ -0,0 +1,68 @@
+import { MailError, guard } from "./errors.js";
+/**
+ * Fetching an attachment's bytes.
+ *
+ * **This module exists because a download URL is not a link.** JMAP's
+ * `downloadUrl` carries no credential of its own — RFC 8620 §6.2 expects the
+ * same authentication the API uses — so `<a href={downloadUrl} download>` and
+ * `<img src={cid}>` both fetch it without an `Authorization` header and get a
+ * 401. The bytes have to be fetched by code that holds the token, and the
+ * result handed to the browser as a blob it already has.
+ *
+ * That is the whole reason attachments were unreachable: `ThreadView` has
+ * taken an `onDownload` since it was written, and nothing could supply one
+ * without this.
+ *
+ * **`credentials: 'omit'`, for the reason `client.ts` gives at length.** A
+ * refused request makes Stalwart answer with `WWW-Authenticate: Basic` as
+ * well as `Bearer`, and a browser allowed to use credentials honours the
+ * second by opening its native password prompt — a modal that hides whatever
+ * the application was about to say. Declining that here keeps a 401 an
+ * ordinary response.
+ */
+/** How much of a message this will pull into memory before refusing. A mail
+ *  server will happily serve a 2GB blob and a browser tab will not survive
+ *  holding one; Stalwart's own default message size limit is well under this.
+ *  A caller that genuinely wants more passes its own `maxBytes`. */
+export const DEFAULT_MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
+/**
+ * An attachment's bytes, as a `Blob`.
+ *
+ * The type comes from the message rather than from the response: a server
+ * that sends `application/octet-stream` for everything would otherwise turn
+ * every PDF into a file the operating system cannot open, and the part's
+ * declared type is the one the sender chose.
+ */
+export async function downloadAttachment(client, attachment, options = {}) {
+    const max = options.maxBytes ?? DEFAULT_MAX_DOWNLOAD_BYTES;
+    /* Checked before the request as well as after. The message says how big
+       the part is, and refusing on that alone saves pulling a gigabyte over
+       the wire to then refuse it. */
+    if (attachment.size > max) {
+        throw new MailError(`${attachment.name} is ${attachment.size} bytes, over the ${max}-byte limit for a download`, { type: 'tooLarge', operation: 'download' });
+    }
+    /* The URL on the attachment was expanded when the message was read. A
+       caller that built an `Attachment` by hand may not have one, so it is
+       recomputed rather than assumed. */
+    const url = attachment.downloadUrl || (await client.downloadUrl(attachment));
+    return guard('download', async () => {
+        const response = await fetch(url, {
+            headers: { Authorization: client.authorization },
+            credentials: 'omit',
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (!response.ok) {
+            throw new MailError(`the server refused to send ${attachment.name}`, {
+                status: response.status,
+                operation: 'download',
+            });
+        }
+        const bytes = await response.arrayBuffer();
+        /* A server is not obliged to send `Content-Length`, and a chunked
+           response can be any size whatever the message claimed. */
+        if (bytes.byteLength > max) {
+            throw new MailError(`${attachment.name} arrived at ${bytes.byteLength} bytes, over the ${max}-byte limit`, { type: 'tooLarge', operation: 'download' });
+        }
+        return new Blob([bytes], { type: attachment.type || 'application/octet-stream' });
+    });
+}

package/dist/mailbox/fake/mailbox.js

@@ -262,7 +262,62 @@ export class FakeMailbox {
                     this.#threads.set(threadId, [id]);
                     created[key] = { id, blobId: `blob-${id}`, threadId, size: 512 };
                 }
-                return { accountId: ACCOUNT, oldState: '1', newState: '2', created, notCreated: null };
+                /* The patch language, enough of it for what `mutate.ts` sends:
+                   `keywords/$seen`, a whole `mailboxIds` replacement, and
+                   `mailboxIds/<id>` removal. A `null` value deletes rather than sets
+                   false, which is RFC 8620 §5.3's rule and the one a fake gets wrong
+                   by treating the patch as a merge -- `keywords: { $seen: false }`
+                   reads as unread everywhere in this package, so a fake that stores
+                   the false would pass a test the real server fails. */
+                const update = (args.update ?? {});
+                const updated = {};
+                const notUpdated = {};
+                for (const [id, patch] of Object.entries(update)) {
+                    const email = this.#emails.find((one) => one.id === id);
+                    if (!email) {
+                        notUpdated[id] = { type: 'notFound' };
+                        continue;
+                    }
+                    for (const [path, value] of Object.entries(patch)) {
+                        if (path === 'mailboxIds') {
+                            email.mailboxIds = { ...value };
+                        }
+                        else if (path.startsWith('mailboxIds/')) {
+                            const boxId = unpointer(path.slice('mailboxIds/'.length));
+                            const next = { ...email.mailboxIds };
+                            if (value === null)
+                                delete next[boxId];
+                            else
+                                next[boxId] = true;
+                            email.mailboxIds = next;
+                        }
+                        else if (path.startsWith('keywords/')) {
+                            const keyword = unpointer(path.slice('keywords/'.length));
+                            const next = { ...email.keywords };
+                            if (value === null)
+                                delete next[keyword];
+                            else
+                                next[keyword] = true;
+                            email.keywords = next;
+                        }
+                        else if (path === 'keywords') {
+                            email.keywords = { ...value };
+                        }
+                        else {
+                            notUpdated[id] = { type: 'invalidPatch', description: `cannot patch ${path}` };
+                        }
+                    }
+                    updated[id] = null;
+                }
+                return {
+                    accountId: ACCOUNT,
+                    oldState: '1',
+                    newState: '2',
+                    created,
+                    notCreated: null,
+                    updated,
+                    notUpdated: Object.keys(notUpdated).length > 0 ? notUpdated : null,
+                };
             }
             case 'EmailSubmission/set': {
                 const create = (args.create ?? {});
@@ -376,6 +431,11 @@ export class FakeMailbox {
         return out;
     }
 }
+/** RFC 6901 §3 in reverse: one patch-key segment, unescaped. A mailbox id is
+ *  the server's to choose, so a key built from one may carry `~0` or `~1`. */
+function unpointer(segment) {
+    return segment.replaceAll('~1', '/').replaceAll('~0', '~');
+}
 /** RFC 8620 §3.7's pointer, with the `*` that maps over a list. */
 function pointer(value, path) {
     let current = value;

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

@@ -1,11 +1,2 @@
 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

@@ -2,11 +2,26 @@
  * 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.
+ * unread and read, a thread with several messages, one with several *unread*
+ * messages, one with an attachment, several with attachments of different
+ * kinds, one flagged, one from a machine with no display name, one with no
+ * subject at all, one whose sender has no display name, one subject long
+ * enough to need truncating and one preview that is a single word. A sample
+ * that is five tidy one-line messages demonstrates a component that has never
+ * met mail.
+ *
+ * **It is long on purpose.** A list of four rows cannot show whether a row is
+ * the right height, whether the date groups earn their space, whether the
+ * scroll region behaves or whether the pager is reachable. Sixteen
+ * conversations spread over a fortnight can, and that is the shortest sample
+ * that can: relative time collapses at an hour, a day, a week and a year, and
+ * a fixture with nothing older than yesterday exercises one of the four.
+ *
+ * Times are minutes before the fake's fixed "now", so every screenshot of
+ * this is the same screenshot.
  */
+const HOUR = 60;
+const DAY = 24 * HOUR;
 export const SAMPLE = [
     {
         mailbox: 'mb-inbox',
@@ -69,6 +84,187 @@ export const SAMPLE = [
             },
         ],
     },
+    /* Two people going back and forth, none of it read: the case where the row
+       has to say "4" and the mailbox count has to say one, not four. */
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Mary Somerville', email: 'mary@example.org' },
+                subject: 'The Difference Engine chapter',
+                text: 'I have marked up the proofs. Three passages need a decision from you before Friday.',
+                agoMinutes: 5 * HOUR,
+            },
+            {
+                from: { name: 'Mary Somerville', email: 'mary@example.org' },
+                subject: 'Re: The Difference Engine chapter',
+                text: 'Ignore the second passage — I have resolved it myself.',
+                agoMinutes: 4 * HOUR,
+            },
+            {
+                from: { name: 'Charles Babbage', email: 'charles@example.com' },
+                subject: 'Re: The Difference Engine chapter',
+                text: 'The third passage is the one that matters. I would rather we said nothing than said it vaguely.',
+                agoMinutes: 3 * HOUR,
+            },
+            {
+                from: { name: 'Mary Somerville', email: 'mary@example.org' },
+                subject: 'Re: The Difference Engine chapter',
+                text: 'Agreed. Ada, you have the casting vote.',
+                agoMinutes: 2 * HOUR,
+            },
+        ],
+    },
+    /* A message with no subject, which is a real thing that arrives and a real
+       way to make a list view draw an empty line. */
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Sophie Germain', email: 'sophie@example.fr' },
+                subject: '',
+                text: 'Yes.',
+                agoMinutes: 7 * HOUR,
+                seen: true,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'The Royal Society', email: 'events@royalsociety.example.org' },
+                subject: 'Invitation: demonstration of the analytical engine, 14 October',
+                text: 'You are invited to a demonstration. Papers are attached. Please reply with numbers by the end of the month.',
+                agoMinutes: 9 * HOUR,
+                attachments: [
+                    { name: 'programme.pdf', type: 'application/pdf', size: 214_882 },
+                    { name: 'directions.png', type: 'image/png', size: 48_120 },
+                ],
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Augustus De Morgan', email: 'augustus@example.ac.uk' },
+                subject: 'A correction, and an apology for the correction',
+                text: 'The recurrence in your note 7 is right and my objection was not. I have written to the editor withdrawing it.',
+                agoMinutes: 26 * HOUR,
+                seen: true,
+            },
+            {
+                from: { name: 'Ada Lovelace', email: 'ada@example.com' },
+                subject: 'Re: A correction, and an apology for the correction',
+                text: 'No apology needed. The objection made the note better.',
+                agoMinutes: 25 * HOUR,
+                seen: true,
+            },
+        ],
+    },
+    /* Only an HTML body, which the reading pane refuses to render and says so.
+       Its own row so the state is reachable from the list rather than only
+       from a unit test. */
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { email: 'campaigns@marketing.example.com' },
+                subject: 'Your weekly digest, beautifully formatted',
+                text: '',
+                html: '<html><body><h1>This week</h1><p>Rendered nowhere, on purpose.</p></body></html>',
+                agoMinutes: 30 * HOUR,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'William King', email: 'william@example.com' },
+                subject: 'Ockham Park, the weekend',
+                text: 'The house is free from Friday. Bring the tables if you must, but not the mill.',
+                agoMinutes: 2 * DAY,
+                seen: true,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Michael Faraday', email: 'michael@example.org' },
+                subject: 'Re: your question about the coil',
+                text: 'It is the rate of change, not the field. I have drawn it out, which is quicker than the sentence.',
+                agoMinutes: 3 * DAY,
+                seen: true,
+                attachments: [{ name: 'coil.svg', type: 'image/svg+xml', size: 4_902 }],
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { email: 'security-noreply@accounts.example.net' },
+                subject: 'New sign-in from an unrecognised device',
+                text: 'A new sign-in was recorded. If this was you, no action is needed.',
+                agoMinutes: 4 * DAY,
+                seen: true,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Anne Isabella Byron', email: 'annabella@example.com' },
+                subject: 'Sunday',
+                text: 'Come at four. There is nothing to discuss and I would like to discuss it at length.',
+                agoMinutes: 6 * DAY,
+                seen: true,
+                flagged: true,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Joseph-Marie Jacquard', email: 'joseph@example.fr' },
+                subject: 'On the punched card mechanism, its failure modes in humid weather, and what I propose to do about the third of them before the demonstration',
+                text: 'The cards swell. Everything else in the list follows from the cards swelling, so I have started there.',
+                agoMinutes: 9 * DAY,
+                seen: true,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Charles Wheatstone', email: 'charles.w@example.org' },
+                subject: 'Telegraph trial — results',
+                text: 'Twelve miles, no repeater, legible throughout. The full log is attached.',
+                agoMinutes: 14 * DAY,
+                seen: true,
+                attachments: [{ name: 'trial-log.csv', type: 'text/csv', size: 11_204 }],
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-inbox',
+        messages: [
+            {
+                from: { name: 'Ada Lovelace', email: 'ada@example.com' },
+                subject: 'Notes to myself: the Bernoulli table',
+                text: 'Start from the recurrence, not the closed form. The closed form is where the last three attempts went wrong.',
+                agoMinutes: 400 * DAY,
+                seen: true,
+            },
+        ],
+    },
     {
         mailbox: 'mb-sent',
         messages: [
@@ -82,4 +278,28 @@ export const SAMPLE = [
             },
         ],
     },
+    {
+        mailbox: 'mb-sent',
+        messages: [
+            {
+                from: { name: 'Ada Lovelace', email: 'ada@example.com' },
+                to: [{ name: 'Mary Somerville', email: 'mary@example.org' }],
+                subject: 'Re: The Difference Engine chapter',
+                text: 'Give me until tomorrow on the third passage.',
+                agoMinutes: 90,
+                seen: true,
+            },
+        ],
+    },
+    {
+        mailbox: 'mb-junk',
+        messages: [
+            {
+                from: { email: 'winner@lottery.example' },
+                subject: 'YOU HAVE BEEN SELECTED',
+                text: 'Reply with your bank details to claim your prize.',
+                agoMinutes: 8 * HOUR,
+            },
+        ],
+    },
 ];

package/dist/mailbox/index.d.ts

@@ -21,6 +21,10 @@ export { attribution, formatAddress, forwardDraft, forwardIntroduction, forwardS
 export type { ForwardOptions, ReplyOptions } from './drafts.ts';
 export { draftToEmail, send, sentPatch } from './submit.ts';
 export type { SendOptions } from './submit.ts';
+export { moveThread, moveToRole, removeFromMailbox, setFlagged, setRead, } from './mutate.ts';
+export type { MoveOptions } from './mutate.ts';
+export { DEFAULT_MAX_DOWNLOAD_BYTES, downloadAttachment } from './download.ts';
+export type { DownloadOptions } from './download.ts';
 export { push } from './push.ts';
 export type { PushHandle, PushOptions } from './push.ts';
 export { expandTemplate } from './uri.ts';

package/dist/mailbox/index.js

@@ -13,5 +13,7 @@ export { search } from "./search.js";
 export { identities } from "./identities.js";
 export { attribution, formatAddress, forwardDraft, forwardIntroduction, forwardSubject, quoteText, replyDraft, replySubject, } from "./drafts.js";
 export { draftToEmail, send, sentPatch } from "./submit.js";
+export { moveThread, moveToRole, removeFromMailbox, setFlagged, setRead, } from "./mutate.js";
+export { DEFAULT_MAX_DOWNLOAD_BYTES, downloadAttachment } from "./download.js";
 export { push } from "./push.js";
 export { expandTemplate } from "./uri.js";