@framers/agentos-ext-channel-email 0.4.4 → 0.5.0

package/dist/EmailService.js

@@ -5,6 +5,10 @@
  *
  * Sends through nodemailer (SMTP) or Resend's HTTPS API, and reads,
  * searches, and fetches the messages it replies to through imapflow (IMAP).
+ * A read gives each message's recipients, threading and authentication
+ * headers, its text and HTML parts under a bound, and its attachments, whose
+ * bytes are fetched only when asked; one message is moved, labelled, flagged
+ * or deleted by its UID.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -40,13 +44,31 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EmailService = void 0;
+exports.EmailService = exports.EmailMailboxError = void 0;
 const nodemailer = __importStar(require("nodemailer"));
 const imapflow_1 = require("imapflow");
 const ResendTransport_js_1 = require("./ResendTransport.js");
 const messageHeaders_js_1 = require("./messageHeaders.js");
 const messageText_js_1 = require("./messageText.js");
 const reads_js_1 = require("./reads.js");
+const headers_js_1 = require("./headers.js");
+const attachments_js_1 = require("./attachments.js");
+/**
+ * A change to one message, or a read of an attachment, that failed: `gone` when the folder holds no message with the UID
+ * named, which a caller that wants the message gone counts as done; `refused` when the server refused the command or
+ * would not open the folder; `unsupported` when the server lacks the extension the change needs; `too_large` when an
+ * attachment passes the bound a read named. Its message never holds a UID, a folder's name or an address, and it
+ * carries nothing the server said.
+ */
+class EmailMailboxError extends Error {
+    constructor(code, message) {
+        super(message);
+        /** The type's own name. */
+        this.name = 'EmailMailboxError';
+        this.code = code;
+    }
+}
+exports.EmailMailboxError = EmailMailboxError;
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -65,21 +87,244 @@ function smtpField(key, value) {
 function firstAddress(list) {
     return list?.find((entry) => typeof entry?.address === 'string' && entry.address !== '')?.address;
 }
+/** The most bytes of a message's text part, and of its HTML part, a read gives when it names no bound: 256 KiB. */
+const DEFAULT_PART_BYTES = 262144;
+/** The most bytes of an attachment `read()` gives when it names no bound: 25 MiB. */
+const DEFAULT_ATTACHMENT_BYTES = 26214400;
+/**
+ * The largest bound a read takes: 256 MiB, so that the bytes a fetch asks for, at most four times the bound, stay a
+ * 32-bit number, as IMAP's partial fetch writes them (RFC 3501 section 9, `number`).
+ */
+const MOST_BYTES = 268435456;
+/** The largest UID, a 32-bit number (RFC 3501 section 9, `nz-number`). */
+const LARGEST_UID = 4294967295;
+/** The header fields a read fetches beside the envelope (`BODY.PEEK[HEADER.FIELDS (...)]`), which marks nothing seen. */
+const READ_FIELDS = [
+    'delivered-to',
+    'in-reply-to',
+    'references',
+    'authentication-results',
+    'auto-submitted',
+    'precedence',
+    'x-autoreply',
+    'x-auto-response-suppress',
+];
+/** What a read's first fetch asks for of each message; the text and HTML parts follow by UID, under the bound. */
+const READ_QUERY = { uid: true, envelope: true, flags: true, bodyStructure: true, headers: READ_FIELDS };
+/** A control character, which no folder, label or flag name holds. */
+const CONTROL = /[\x00-\x1f\x7f]/;
+/** A flag a STORE may carry: an atom (RFC 3501 section 9, `flag-keyword`), or a system flag with its backslash. */
+const FLAG = /^\\?[^\s()\{\}%*"\\\]\x00-\x1f\x7f-\uffff]+$/;
+/** `folder` when it names a mailbox, INBOX when it is `undefined` or `null`; anything else throws an `Error`. */
+function requireFolder(folder, field = 'folder') {
+    if (folder === undefined || folder === null)
+        return 'INBOX';
+    return requireName(folder, field);
+}
+/** `name` when it is text with no control character, which a folder, a label or a flag name is; anything else throws. */
+function requireName(name, field) {
+    if (typeof name === 'string' && name !== '' && !CONTROL.test(name))
+        return name;
+    throw new Error(`The ${field} was refused: give it as a name of text with no control character`);
+}
+/** The UID a read follows, or `undefined` when none is given; anything but a whole number from 0 throws. */
+function requireAfterUid(afterUid) {
+    if (afterUid === undefined || afterUid === null)
+        return undefined;
+    if (typeof afterUid === 'number' && Number.isSafeInteger(afterUid) && afterUid >= 0)
+        return afterUid;
+    throw new Error('The afterUid was refused: give it as a whole number of at least 0');
+}
+/** A bound in bytes: `fallback` when it is `undefined` or `null`; anything but a whole number from 1 to 256 MiB throws. */
+function requireBytes(maxBytes, fallback) {
+    if (maxBytes === undefined || maxBytes === null)
+        return fallback;
+    if (typeof maxBytes === 'number' && Number.isSafeInteger(maxBytes) && maxBytes >= 1 && maxBytes <= MOST_BYTES)
+        return maxBytes;
+    throw new Error(`The maxBytes was refused: give it as a whole number from 1 to ${MOST_BYTES}`);
+}
+/**
+ * The receiving host's authserv-id in lowercase, or `undefined` when none is given; a value that is not text, or that is
+ * white space alone, which would let the first field of any host count, throws.
+ */
+function requireAuthServId(authServId) {
+    if (authServId === undefined || authServId === null || authServId === '')
+        return undefined;
+    if (typeof authServId === 'string' && !CONTROL.test(authServId) && authServId.trim() !== '')
+        return authServId.trim().toLowerCase();
+    throw new Error('The authServId was refused: give it as the name of the host that received the mail');
+}
+/**
+ * The UIDVALIDITY a read's `afterUid` was read under, in decimal, or `undefined` when none is given; anything but a whole
+ * number from 1 to the largest UIDVALIDITY, or its digits with no leading zero, throws.
+ */
+function requireUidValidity(uidValidity) {
+    if (uidValidity === undefined || uidValidity === null || uidValidity === '')
+        return undefined;
+    const digits = typeof uidValidity === 'number' && Number.isSafeInteger(uidValidity) ? String(uidValidity) : uidValidity;
+    if (typeof digits === 'string' && /^[1-9][0-9]{0,9}$/.test(digits) && Number(digits) <= LARGEST_UID)
+        return digits;
+    throw new Error(`The uidValidity was refused: give it as the folder's UIDVALIDITY, a whole number from 1 to ${LARGEST_UID}`);
+}
+/** A message's UID; anything but a whole number from 1 to the largest UID throws. */
+function requireUid(uid) {
+    if (typeof uid === 'number' && Number.isSafeInteger(uid) && uid >= 1 && uid <= LARGEST_UID)
+        return uid;
+    throw new Error(`The uid was refused: give it as a whole number from 1 to ${LARGEST_UID}`);
+}
+/** The flags a STORE sets: a list of flag names, `\Recent` not among them, which the server alone sets; else throws. */
+function requireFlags(flags) {
+    if (!Array.isArray(flags) || !flags.every((flag) => typeof flag === 'string' && FLAG.test(flag))) {
+        throw new Error('The flags were refused: give them as a list of flag names, such as \\Seen or $Handled');
+    }
+    if (flags.some((flag) => flag.toLowerCase() === '\\recent'))
+        throw new Error('The flags were refused: the server alone sets \\Recent');
+    return [...flags];
+}
+/** A read's bounds, checked. */
+function readPlanOf(options) {
+    return { maxBytes: requireBytes(options.maxBytes, DEFAULT_PART_BYTES), authServId: requireAuthServId(options.authServId) };
+}
+/** A flag as imapflow 1.2.9 writes it into a STORE (`formatFlag` in `lib/tools.js`): a system flag in its own case. */
+function storedFlag(flag) {
+    const lowercase = flag.toLowerCase();
+    return ['\\seen', '\\answered', '\\flagged', '\\deleted', '\\draft'].includes(lowercase) ? lowercase.replace(/^\\./, (start) => start.toUpperCase()) : flag;
+}
+/**
+ * The flags a STORE gives imapflow so that it keeps every one named, or `undefined` when the folder's PERMANENTFLAGS
+ * keep one of them in no spelling. imapflow 1.2.9 keeps a flag only in the spelling PERMANENTFLAGS gives it, unless they
+ * hold `\*` (`canUseFlag` in `lib/tools.js`), and IMAP reads a flag's name ignoring case (RFC 3501 section 9, note 1),
+ * so a keyword is given in the spelling the folder keeps; a system flag goes as imapflow writes it. With no
+ * PERMANENTFLAGS imapflow keeps every flag.
+ */
+function keptFlags(wanted, permanent) {
+    if (!(permanent instanceof Set))
+        return wanted;
+    const kept = [];
+    for (const flag of wanted) {
+        let spelled;
+        if (flag.startsWith('\\')) {
+            spelled = permanent.has('\\*') || permanent.has(storedFlag(flag)) ? flag : undefined;
+        }
+        else {
+            const lowercase = flag.toLowerCase();
+            spelled = [...permanent].find((known) => typeof known === 'string' && known.toLowerCase() === lowercase) ?? (permanent.has('\\*') ? flag : undefined);
+        }
+        if (spelled === undefined)
+            return undefined;
+        if (!kept.includes(spelled))
+            kept.push(spelled);
+    }
+    return kept;
+}
+/** The rejection of a change or a read whose message the folder no longer holds. */
+function gone() {
+    return new EmailMailboxError('gone', 'The message is gone: the folder holds no message with that UID');
+}
+/** Whether the server announced `capability`; imapflow keeps the names in uppercase. */
+function offers(client, capability) {
+    return client?.capabilities instanceof Map && client.capabilities.has(capability);
+}
+/**
+ * Whether the selected folder holds a message with `uid`, by `UID SEARCH`; a server that refuses the search rejects with
+ * `EmailMailboxError` `refused`.
+ */
+async function holds(client, uid) {
+    const found = await client.search({ uid: String(uid) }, { uid: true });
+    if (!Array.isArray(found))
+        throw new EmailMailboxError('refused', 'The change was refused: the server refused the search');
+    return found.includes(uid);
+}
 /**
- * A fetched message as `readInbox` and `searchEmails` give it. A Date field that does not read as a date gives an empty
- * `date`: imapflow gives the field's text in place of a `Date` then, so one such message cannot fail the whole read.
+ * Opens `folder` and holds it, as imapflow's `getMailboxLock` does. A server that refuses the SELECT, as it refuses a
+ * folder that does not exist, rejects with `EmailMailboxError` `refused` and `refusal` as its message: imapflow's own
+ * error carries the server's text and the command it sent (imapflow 1.2.9 `lib/imap-flow.js`), which name the folder.
+ * Any other failure, such as a lost connection, rejects as imapflow rejected.
  */
-function emailMessageOf(msg, body) {
+async function lockOf(client, folder, refusal) {
+    try {
+        return await client.getMailboxLock(folder);
+    }
+    catch (error) {
+        const status = typeof error === 'object' && error !== null ? error.responseStatus : undefined;
+        if (status === 'NO' || status === 'BAD')
+            throw new EmailMailboxError('refused', refusal);
+        throw error;
+    }
+}
+/**
+ * Whether a COPY or MOVE copied the message whose UID is `uid`, by the COPYUID a server with UIDPLUS sends when it
+ * copied a message (RFC 4315 section 3), which imapflow gives as `uidMap`; `undefined` when the server sent none.
+ */
+function copiedBy(answer, uid) {
+    return answer?.uidMap instanceof Map ? answer.uidMap.has(uid) : undefined;
+}
+/**
+ * Every address of an envelope's To and Cc and of the Delivered-To fields, in lowercase, each once, a local part that
+ * needs quotes in them. A group's name comes through imapflow as an address with nothing after its `@`, and is none.
+ */
+function recipientsOf(envelope, deliveredTo) {
+    const listed = [...(Array.isArray(envelope?.to) ? envelope.to : []), ...(Array.isArray(envelope?.cc) ? envelope.cc : [])].map((entry) => entry?.address);
+    const recipients = [];
+    for (const address of [...listed, ...deliveredTo]) {
+        if (typeof address !== 'string')
+            continue;
+        const form = (0, headers_js_1.addressOf)(address);
+        if (form === undefined || recipients.includes(form))
+            continue;
+        recipients.push(form);
+    }
+    return recipients;
+}
+/**
+ * A fetched message as `readInbox` and `searchEmails` give it, from its first fetch, the parts its body structure
+ * names, and the text and HTML bytes the second fetch gave under each part's window. A Date field that does not read as
+ * a date gives an empty `date`: imapflow gives the field's text in place of a `Date` then, so one such message cannot
+ * fail the whole read.
+ */
+function emailMessageOf(planned, bodies, context) {
+    const { msg, parts } = planned;
     const envelope = msg.envelope;
+    const from = envelope?.from?.[0]?.address ?? '';
+    const header = Buffer.isBuffer(msg.headers) ? msg.headers.toString('utf8') : '';
+    const fields = (0, headers_js_1.readHeaderFields)(header, { from, authServId: context.authServId });
+    const bytesOf = (info) => bodies?.get(info.part);
+    const text = (0, attachments_js_1.joinedTextOf)(parts.texts, planned.textWindows, parts.texts.map(bytesOf), context.maxBytes);
+    const html = (0, attachments_js_1.joinedTextOf)(parts.htmls, planned.htmlWindows, parts.htmls.map(bytesOf), context.maxBytes);
+    const messageId = (0, messageHeaders_js_1.messageIdIn)(envelope?.messageId);
+    const key = context.serverIds && typeof msg.emailId === 'string' && msg.emailId !== ''
+        ? msg.emailId
+        : messageId !== undefined
+            ? `${context.folder} ${messageId}`
+            : `${context.folder} ${context.uidValidity}:${msg.uid}`;
     return {
         messageId: envelope?.messageId ?? '',
-        from: envelope?.from?.[0]?.address ?? '',
+        from,
         to: envelope?.to?.[0]?.address ?? '',
         subject: envelope?.subject ?? '',
         date: (0, reads_js_1.isoDateOf)(envelope?.date),
-        body,
+        body: parts.texts.length > 0 ? text.text : (0, reads_js_1.withoutTags)(html.text).replace(/\s+/g, ' ').trim(),
+        html: html.text,
         flags: Array.from(msg.flags ?? []),
         uid: msg.uid,
+        uidValidity: context.uidValidity,
+        key,
+        recipients: recipientsOf(envelope, fields.deliveredTo),
+        inReplyTo: fields.inReplyTo,
+        references: fields.references,
+        autoSubmitted: fields.autoSubmitted,
+        precedence: fields.precedence,
+        autoreply: fields.autoreply,
+        isReport: parts.isReport,
+        authentication: fields.authentication,
+        text: text.text,
+        truncated: text.truncated || html.truncated,
+        attachments: parts.attachments.map((info) => ({
+            name: info.name,
+            type: info.type,
+            bytes: info.size,
+            read: (maxBytes) => context.readPart(msg.uid, info, maxBytes),
+        })),
     };
 }
 // ---------------------------------------------------------------------------
@@ -218,37 +463,71 @@ class EmailService {
     }
     // ── Read Inbox ──
     /**
-     * The last `limit` messages of `folder`, newest first: INBOX and 20 when they are not given, and 20 when `limit` is
-     * `null`. `limit` must be a whole number of at least 1: any other value throws an `Error` before any mail is read,
-     * where the fetch would name a message past the last one, which a server answers BAD. A message whose Date field does
-     * not read as a date is given with an empty `date`.
+     * Reads `folder`'s messages. Given a folder and a limit, or neither, it gives the last `limit` messages of `folder`,
+     * newest first: INBOX and 20 when they are not given, and 20 when `limit` is `null`. Given one object
+     * (`ReadInboxOptions`), it reads the same way, or, with `afterUid`, gives the first `limit` messages whose UID is
+     * greater, oldest first, whatever their flags: it searches `UID <afterUid + 1>:*` and keeps only the greater UIDs,
+     * since a range ending in `*` names the last message even when its UID is not greater (RFC 3501 section 9). Given
+     * `uidValidity` with `afterUid`, a folder whose UIDVALIDITY is another is read from its first message, since its UIDs
+     * were given anew and `afterUid` names nothing of it.
+     *
+     * `limit` must be a whole number of at least 1, `afterUid` a whole number from 0, `uidValidity` a UIDVALIDITY,
+     * `maxBytes` a whole number from 1 to 268,435,456, `folder` a name with no control character and `authServId` text that
+     * is not white space alone: any other value throws an `Error` before any mail is read, where the fetch would name a
+     * message past the last one, which a server answers BAD. A server that refuses the search after a UID rejects the read
+     * with `EmailMailboxError` `refused`. A message whose Date field does not read as a date is given with an empty `date`.
+     *
+     * Each message is fetched with its envelope, flags, body structure and the header fields its recipients, threading
+     * and authentication come from, then its text and HTML parts by UID, each up to the bytes that can decode to what
+     * `maxBytes` leaves, in one fetch for the messages whose parts share their sections and windows. No fetch marks a
+     * message seen, and no attachment's bytes are fetched until its `read()` is called. A FETCH response the server sends
+     * unasked during a fetch, such as the flags another session changed, is no message of the read.
      */
-    async readInbox(folder = 'INBOX', limit) {
+    async readInbox(folder, limit) {
         this.requireRunning();
-        const count = (0, reads_js_1.requireLimit)(limit, 20);
+        const given = typeof folder === 'object' && folder !== null ? folder : { folder, limit };
+        const path = requireFolder(given.folder);
+        const count = (0, reads_js_1.requireLimit)(given.limit, 20);
+        const afterUid = requireAfterUid(given.afterUid);
+        const uidValidity = requireUidValidity(given.uidValidity);
+        const plan = readPlanOf(given);
         const client = await this.getImapClient();
         try {
-            const lock = await client.getMailboxLock(folder);
-            const messages = [];
+            const lock = await client.getMailboxLock(path);
             try {
+                if (afterUid !== undefined) {
+                    // A UIDVALIDITY other than the cursor's means the folder's UIDs were given anew (RFC 3501 section 2.3.1.1), so
+                    // the cursor's UID names nothing of it and the read starts from its first message.
+                    const current = client.mailbox?.uidValidity;
+                    const changed = uidValidity !== undefined && current !== undefined && current !== null && String(current) !== uidValidity;
+                    const after = changed ? 0 : afterUid;
+                    // No UID is greater than the largest, and the search below could not name one.
+                    if (after >= LARGEST_UID)
+                        return [];
+                    const found = await client.search({ uid: `${after + 1}:*` }, { uid: true });
+                    if (!Array.isArray(found))
+                        throw new EmailMailboxError('refused', 'The read was refused: the server refused the search');
+                    // A range ending in "*" names the last message even when its UID is not greater (RFC 3501 section 9).
+                    const uids = found
+                        .filter((uid) => Number.isSafeInteger(uid) && uid > after)
+                        .sort((a, b) => a - b)
+                        .slice(0, count);
+                    if (uids.length === 0)
+                        return [];
+                    const later = await this.fetchMessages(client, path, uids, true, plan);
+                    return later.sort((a, b) => a.uid - b.uid);
+                }
                 // Fetch the most recent messages
                 const totalMessages = client.mailbox ? client.mailbox.exists : 0;
-                if (totalMessages === 0)
+                if (!totalMessages)
                     return [];
                 const startSeq = Math.max(1, totalMessages - count + 1);
-                for await (const msg of client.fetch(`${startSeq}:*`, {
-                    envelope: true,
-                    source: true,
-                    flags: true,
-                    uid: true,
-                })) {
-                    messages.push(emailMessageOf(msg, this.extractPlainText(msg.source?.toString() ?? '')));
-                }
+                const messages = await this.fetchMessages(client, path, `${startSeq}:*`, false, plan);
+                return messages.reverse(); // Most recent first
             }
             finally {
                 lock.release();
             }
-            return messages.reverse(); // Most recent first
         }
         finally {
             await client.logout();
@@ -258,24 +537,28 @@ class EmailService {
     /**
      * The messages of `folder` (INBOX unless given) whose subject, body or From holds `query`, ignoring case, received on
      * or after `since` when it is given: the last `limit` (20 unless given) the search finds, newest first. The search
-     * answers UIDs, and the messages are fetched by those UIDs, which need not follow the messages' sequence numbers.
+     * answers UIDs, and the messages are fetched by those UIDs, which need not follow the messages' sequence numbers. Each
+     * message carries what `readInbox` gives, its parts bounded by `maxBytes` and its Authentication-Results read as
+     * `authServId` says.
      *
      * `limit` must be a whole number of at least 1, and `since` an ISO 8601 date, such as `2026-10-15`, alone or followed
      * by a time and an offset, which are checked and then disregarded: the search starts from the day the date names, as
      * written, on every server. Either counts as not given when `null`, and `since` when empty. Any other value of either,
      * a day its month lacks such as `2026-02-30` among them, throws an `Error` before the search: imapflow leaves a date it
      * cannot read out of the search, which would answer mail of every date, and `Date` rolls a day past its month's end
-     * over into the next month. A message whose Date field does not read as a date is given with an empty `date`.
+     * over into the next month. `maxBytes` and `authServId` are checked as `readInbox` checks them. A message whose Date
+     * field does not read as a date is given with an empty `date`.
      */
     async searchEmails(options) {
         this.requireRunning();
         const limit = (0, reads_js_1.requireLimit)(options.limit, 20);
         const since = (0, reads_js_1.requireSince)(options.since);
+        const plan = readPlanOf(options);
         const client = await this.getImapClient();
         const folder = options.folder ?? 'INBOX';
         try {
             const lock = await client.getMailboxLock(folder);
-            const messages = [];
+            let messages = [];
             try {
                 const searchCriteria = {};
                 // Build IMAP search criteria
@@ -296,14 +579,7 @@ class EmailService {
                 const limitedUids = uidList.slice(-limit);
                 if (limitedUids.length > 0) {
                     // The search answered UIDs, so the fetch reads its range as UIDs rather than sequence numbers.
-                    for await (const msg of client.fetch(limitedUids, {
-                        envelope: true,
-                        source: true,
-                        flags: true,
-                        uid: true,
-                    }, { uid: true })) {
-                        messages.push(emailMessageOf(msg, this.extractPlainText(msg.source?.toString() ?? '')));
-                    }
+                    messages = await this.fetchMessages(client, folder, limitedUids, true, plan);
                 }
             }
             finally {
@@ -315,6 +591,142 @@ class EmailService {
             await client.logout();
         }
     }
+    // ── Move, Label, Flag and Delete ──
+    /**
+     * Moves the message whose UID is `uid` in `options.folder` (INBOX unless given) to `destination`: by `UID MOVE`
+     * (RFC 6851) where the server offers MOVE, else by `UID COPY`, the `\Deleted` flag and `UID EXPUNGE` (RFC 4315), which
+     * expunges no other message marked deleted. The copy must succeed before the original is touched.
+     *
+     * Rejects with `EmailMailboxError`: `gone` when the folder holds no message with that UID, which comes before any other
+     * answer, and when another session expunges the message before the move, as the COPYUID a server with UIDPLUS sends
+     * tells, or as a search after a copy that named none tells; `unsupported`, before anything changes, when the server
+     * offers neither MOVE nor UIDPLUS, where `EXPUNGE` would remove every message marked deleted; `refused` when the server
+     * refuses a command, as it does a destination that does not exist, or will not open the folder. A move another
+     * session's expunge overtakes on a server that sends no COPYUID resolves as done, the server having answered OK. A
+     * `uid` that is not a whole number from 1 to 4,294,967,295, or a folder or destination that is not a name, throws an
+     * `Error` before connecting.
+     */
+    async moveTo(uid, destination, options) {
+        this.requireRunning();
+        const target = requireUid(uid);
+        const to = requireName(destination, 'destination');
+        const folder = requireFolder(options?.folder);
+        await this.onMessage(target, folder, async (client, range) => {
+            if (offers(client, 'MOVE')) {
+                const moved = await client.messageMove(range, to, { uid: true });
+                if (!moved)
+                    throw new EmailMailboxError('refused', 'The move was refused by the server');
+                // The COPYUID names each UID the server moved (RFC 6851 section 4.3): one it leaves out was expunged first.
+                if (copiedBy(moved, target) === false)
+                    throw gone();
+                return;
+            }
+            if (!offers(client, 'UIDPLUS'))
+                throw new EmailMailboxError('unsupported', 'The move was refused: the server offers neither MOVE nor UIDPLUS');
+            // imapflow's own MOVE without the extension deletes the original whatever its COPY answered.
+            const copy = await client.messageCopy(range, to, { uid: true });
+            if (!copy)
+                throw new EmailMailboxError('refused', 'The move was refused by the server');
+            const copied = copiedBy(copy, target);
+            if (copied === false)
+                throw gone();
+            if (!(await holds(client, target))) {
+                // Another session expunged the original: the move is done when the copy was made, and gone when nothing says so.
+                if (copied === true)
+                    return;
+                throw gone();
+            }
+            await this.expungeOne(client, range, 'move');
+        });
+    }
+    /**
+     * Labels the message whose UID is `uid` in `options.folder` (INBOX unless given) with `label`: through Gmail's
+     * `X-GM-LABELS` where the server offers X-GM-EXT-1, else by `UID COPY` into the folder named `label`. The message
+     * stays where it is.
+     *
+     * Rejects with `EmailMailboxError` `gone` when the folder holds no message with that UID, and when another session
+     * expunges the message between the search for it and the change, which then did nothing (RFC 3501 section 6.4.8), as
+     * the COPYUID a server with UIDPLUS sends, or a search after the change, tells; and `refused` when the server refuses
+     * the command, as it does a copy into a folder that does not exist, or will not open the folder. A `uid` that is not
+     * a whole number from 1 to 4,294,967,295, or a folder or label that is not a name, throws an `Error` before
+     * connecting.
+     */
+    async addLabel(uid, label, options) {
+        this.requireRunning();
+        const target = requireUid(uid);
+        const name = requireName(label, 'label');
+        const folder = requireFolder(options?.folder);
+        await this.onMessage(target, folder, async (client, range) => {
+            if (offers(client, 'X-GM-EXT-1')) {
+                if ((await client.messageFlagsAdd(range, [name], { uid: true, useLabels: true })) !== true) {
+                    throw new EmailMailboxError('refused', 'The label was refused by the server');
+                }
+            }
+            else {
+                const copy = await client.messageCopy(range, name, { uid: true });
+                if (!copy)
+                    throw new EmailMailboxError('refused', 'The label was refused by the server');
+                const copied = copiedBy(copy, target);
+                if (copied === true)
+                    return;
+                if (copied === false)
+                    throw gone();
+            }
+            if (!(await holds(client, target)))
+                throw gone();
+        });
+    }
+    /**
+     * Replaces the flags of the message whose UID is `uid` in `options.folder` (INBOX unless given) with `flags`, by
+     * `UID STORE ... FLAGS`; an empty list clears them. Each flag is a flag name such as `\Seen` or `$Handled`; `\Recent`,
+     * which the server alone sets, is refused. A keyword goes in the spelling the folder's PERMANENTFLAGS give it, matched
+     * ignoring case, as IMAP reads a flag's name.
+     *
+     * Rejects with `EmailMailboxError` `gone` when the folder holds no message with that UID, which comes before any other
+     * answer, and when another session expunges the message between the search for it and the STORE, as a search after the
+     * STORE tells; `refused`, before anything is stored, when the folder's PERMANENTFLAGS keep neither `\*` nor every flag
+     * named, in any spelling, since imapflow would leave such a flag out and a set left with none clears every flag; and
+     * `refused` when the server refuses the STORE or will not open the folder. A `uid` that is not a whole number from 1
+     * to 4,294,967,295, flags that are not a list of flag names, or a folder that is not a name, throw an `Error` before
+     * connecting.
+     */
+    async setFlags(uid, flags, options) {
+        this.requireRunning();
+        const target = requireUid(uid);
+        const wanted = requireFlags(flags);
+        const folder = requireFolder(options?.folder);
+        await this.onMessage(target, folder, async (client, range) => {
+            const kept = keptFlags(wanted, client.mailbox?.permanentFlags);
+            if (kept === undefined)
+                throw new EmailMailboxError('refused', 'The flags were refused: the folder does not keep every flag named');
+            if ((await client.messageFlagsSet(range, kept, { uid: true })) !== true)
+                throw new EmailMailboxError('refused', 'The flags were refused by the server');
+            if (!(await holds(client, target)))
+                throw gone();
+        });
+    }
+    /**
+     * Deletes the message whose UID is `uid` in `options.folder` (INBOX unless given): the `\Deleted` flag, then
+     * `UID EXPUNGE` of that UID alone (RFC 4315), so no other message marked deleted is expunged. What an expunge does with
+     * the message beyond the folder is the server's to decide.
+     *
+     * Rejects with `EmailMailboxError`: `gone` when the folder holds no message with that UID, which a caller that wants
+     * the message gone counts as done, so a second call rejects with it, and which comes before any other answer;
+     * `unsupported`, before anything changes, when the server does not offer UIDPLUS, where `EXPUNGE` would remove every
+     * message marked deleted; `refused` when the server refuses the STORE or the expunge, or will not open the folder. A
+     * message another session expunges during the delete is gone either way, and the delete resolves. A `uid` that is not
+     * a whole number from 1 to 4,294,967,295, or a folder that is not a name, throws an `Error` before connecting.
+     */
+    async deleteMessage(uid, options) {
+        this.requireRunning();
+        const target = requireUid(uid);
+        const folder = requireFolder(options?.folder);
+        await this.onMessage(target, folder, async (client, range) => {
+            if (!offers(client, 'UIDPLUS'))
+                throw new EmailMailboxError('unsupported', 'The delete was refused: the server does not offer UIDPLUS');
+            await this.expungeOne(client, range, 'delete');
+        });
+    }
     // ── Extract Verification Codes ──
     /**
      * The codes in the INBOX message whose Message-ID is `messageId`, given with or without its angle brackets: the
@@ -488,6 +900,153 @@ class EmailService {
         await client.connect();
         return client;
     }
+    // ── Private: Reads ──
+    /**
+     * The messages a set names in the selected folder, as a read gives them: first their envelopes, flags, body
+     * structures and read header fields, then their text and HTML parts by UID under the bound.
+     */
+    async fetchMessages(client, folder, range, byUid, plan) {
+        const fetched = [];
+        const taken = new Set();
+        // imapflow runs no other command while a fetch's loop is open, so the parts are fetched once it has closed.
+        for await (const msg of client.fetch(range, READ_QUERY, byUid ? { uid: true } : undefined)) {
+            // A server may send FETCH responses of its own during the fetch, such as the flags another session changed (RFC 3501
+            // section 7.4.2), and imapflow yields each in the loop: only an answer that carries the envelope asked for is a
+            // message read, once for its UID, so a read gives no message it did not ask for and none twice.
+            if (typeof msg?.envelope !== 'object' || msg.envelope === null || !Number.isSafeInteger(msg.uid) || taken.has(msg.uid))
+                continue;
+            taken.add(msg.uid);
+            fetched.push(msg);
+        }
+        const planned = fetched.map((msg) => {
+            const parts = (0, attachments_js_1.partsOf)(msg.bodyStructure);
+            return { msg, parts, textWindows: (0, attachments_js_1.windowsOf)(parts.texts, plan.maxBytes), htmlWindows: (0, attachments_js_1.windowsOf)(parts.htmls, plan.maxBytes) };
+        });
+        const bodies = await this.fetchTextParts(client, planned);
+        const path = typeof client.mailbox?.path === 'string' ? client.mailbox.path : folder;
+        const uidValidity = client.mailbox?.uidValidity === undefined || client.mailbox?.uidValidity === null ? '' : String(client.mailbox.uidValidity);
+        const context = {
+            ...plan,
+            folder: path,
+            uidValidity,
+            serverIds: offers(client, 'OBJECTID') || offers(client, 'X-GM-EXT-1'),
+            readPart: (uid, info, maxBytes) => this.readAttachment(path, uidValidity, uid, info, maxBytes),
+        };
+        return planned.map((entry) => emailMessageOf(entry, bodies.get(entry.msg.uid), context));
+    }
+    /**
+     * The text and HTML bytes of each message by UID, each part up to one byte past its window: one fetch for the messages
+     * whose parts share their sections and windows, and no fetch of a part whose window is 0, since the parts before it
+     * fill the bound.
+     */
+    async fetchTextParts(client, planned) {
+        const groups = new Map();
+        for (const { msg, parts, textWindows, htmlWindows } of planned) {
+            if (!Number.isSafeInteger(msg.uid))
+                continue;
+            const wanted = [
+                ...parts.texts.map((info, index) => ({ info, window: textWindows[index] ?? 0 })),
+                ...parts.htmls.map((info, index) => ({ info, window: htmlWindows[index] ?? 0 })),
+            ].filter(({ window }) => window > 0);
+            if (wanted.length === 0)
+                continue;
+            const id = wanted.map(({ info, window }) => `${info.part}<${window}>`).join(' ');
+            const group = groups.get(id) ?? {
+                bodyParts: wanted.map(({ info, window }) => ({ key: info.part, start: 0, maxLength: window + 1 })),
+                uids: [],
+            };
+            group.uids.push(msg.uid);
+            groups.set(id, group);
+        }
+        const bodies = new Map();
+        for (const group of groups.values()) {
+            for await (const msg of client.fetch(group.uids, { uid: true, bodyParts: group.bodyParts }, { uid: true })) {
+                if (msg.bodyParts instanceof Map)
+                    bodies.set(msg.uid, msg.bodyParts);
+            }
+        }
+        return bodies;
+    }
+    /**
+     * An attachment's bytes, decoded, fetched by the message's UID in `folder` over a connection of its own, up to one byte
+     * past the bytes that can decode to the bound: an attachment's `read()`.
+     */
+    async readAttachment(folder, uidValidity, uid, info, maxBytes) {
+        const bound = requireBytes(maxBytes, DEFAULT_ATTACHMENT_BYTES);
+        this.requireRunning();
+        if ((0, attachments_js_1.tooLargeBySize)(info, bound))
+            throw new EmailMailboxError('too_large', 'The attachment was refused: it holds more bytes than the bound');
+        const client = await this.getImapClient();
+        let found = false;
+        let raw;
+        try {
+            const lock = await lockOf(client, folder, 'The attachment was refused: the server would not open the folder');
+            try {
+                // A new UIDVALIDITY means the folder's UIDs were given anew, so the UID no longer names the message read.
+                const current = client.mailbox?.uidValidity;
+                if (uidValidity !== '' && current !== undefined && String(current) !== uidValidity)
+                    throw gone();
+                const query = { uid: true, bodyParts: [{ key: info.part, start: 0, maxLength: (0, attachments_js_1.encodedBound)(info.encoding, bound) + 1 }] };
+                for await (const msg of client.fetch(String(uid), query, { uid: true })) {
+                    if (msg.uid !== uid)
+                        continue;
+                    found = true;
+                    const part = msg.bodyParts instanceof Map ? msg.bodyParts.get(info.part) : undefined;
+                    if (Buffer.isBuffer(part))
+                        raw = part;
+                }
+            }
+            finally {
+                lock.release();
+            }
+        }
+        finally {
+            await client.logout();
+        }
+        if (!found)
+            throw gone();
+        if (raw === undefined)
+            throw new EmailMailboxError('refused', 'The attachment was refused: the server gave none of its bytes');
+        const read = (0, attachments_js_1.boundedBytesOf)(raw, info, bound);
+        if (read.kind === 'too_large')
+            throw new EmailMailboxError('too_large', 'The attachment was refused: it holds more bytes than the bound');
+        return read.bytes;
+    }
+    // ── Private: Changes to One Message ──
+    /**
+     * Runs `work` on the message whose UID is `uid` in `folder`, over a connection of its own, once a search finds the UID:
+     * a UID STORE, COPY or MOVE of a UID no message has succeeds having done nothing (RFC 3501 section 6.4.8, which RFC 6851
+     * section 3.2 extends to UID MOVE), so no message with it rejects with `gone`, before `work` checks what the server
+     * offers, since a caller that wants the message gone counts gone as done.
+     */
+    async onMessage(uid, folder, work) {
+        const client = await this.getImapClient();
+        try {
+            const lock = await lockOf(client, folder, 'The change was refused: the server would not open the folder');
+            try {
+                if (!(await holds(client, uid)))
+                    throw gone();
+                await work(client, String(uid));
+            }
+            finally {
+                lock.release();
+            }
+        }
+        finally {
+            await client.logout();
+        }
+    }
+    /**
+     * Marks one message deleted and expunges it by UID, on a server the caller found to offer UIDPLUS. imapflow's delete
+     * goes on to the expunge whatever its STORE answered, so the STORE is sent and checked first.
+     */
+    async expungeOne(client, range, action) {
+        if ((await client.messageFlagsAdd(range, ['\\Deleted'], { uid: true })) !== true) {
+            throw new EmailMailboxError('refused', `The ${action} was refused: the server refused the \\Deleted flag`);
+        }
+        if ((await client.messageDelete(range, { uid: true })) !== true)
+            throw new EmailMailboxError('refused', `The ${action} was refused: the server refused the expunge`);
+    }
     // ── Private: Email Parsing ──
     extractPlainText(rawSource) {
         // Simple extraction of plain text body from raw email source