@yozz.app/imap 0.1.6 → 0.2.0

package/dist/index.d.mts

@@ -1,3 +1,36 @@
+//#region src/commands.d.ts
+/** One `UID SEARCH` key. */
+type UidSearchCriterion =
+/** `TEXT` is the body alone on some servers, and `OR` answers less than its operands on some. */
+{
+  readonly key: 'SUBJECT' | 'FROM' | 'TO' | 'CC' | 'BCC' | 'TEXT';
+  readonly value: string;
+} |
+/** A server need only index the headers IMAP names; on a private `X-` header it may answer the empty list. */
+{
+  readonly key: 'HEADER';
+  readonly header: 'Message-ID' | 'Reply-To';
+  readonly value: string;
+} | {
+  readonly key: 'UNSEEN';
+} | {
+  readonly key: 'FLAGGED';
+} |
+/** By INTERNALDATE's day: `SINCE` is on or after it, `BEFORE` strictly before it. */
+{
+  readonly key: 'BEFORE';
+  readonly date: ImapSearchDate;
+} | {
+  readonly key: 'SINCE';
+  readonly date: ImapSearchDate;
+};
+/** A calendar day; `month` runs 1 to 12. */
+type ImapSearchDate = {
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+};
+//#endregion
 //#region src/tokenizer.d.ts
 export declare const DEFAULT_MAX_LITERAL_BYTES: number;
 type ImapToken = {
@@ -91,7 +124,7 @@ type ImapFetchItem = {
   readonly bytes: Uint8Array | null;
 } | {
   readonly kind: 'bodyStructure';
-  readonly parts: readonly string[];
+  readonly attachmentNames: readonly string[];
 } |
 /** Gmail's `X-GM-THRID` is 64-bit, so it stays decimal digits. */
 {
@@ -201,11 +234,17 @@ type ImapMessageSummary = {
   readonly references: readonly string[];
   /** Gmail's thread id (decimal digits), when the server was asked and answered. */
   readonly gmailThreadId: string | null;
+  /** The file names its parts carry, from `BODYSTRUCTURE`. */
+  readonly attachmentNames: readonly string[];
 };
 type ImapMessageFlags = {
   readonly uid: number;
   readonly flags: readonly string[];
 };
+type ImapMessageAttachmentNames = {
+  readonly uid: number;
+  readonly attachmentNames: readonly string[];
+};
 type ImapSelected = {
   readonly name: string;
   readonly exists: number;
@@ -246,6 +285,8 @@ type ImapClient = {
   /** By message sequence number (dense, 1..EXISTS) rather than uid (sparse after deletions). */
   readonly fetchSummariesBySeq: (seqSet: string) => Promise<ImapResult<readonly ImapMessageSummary[]>>;
   readonly fetchFlags: (uidSet: string) => Promise<ImapResult<readonly ImapMessageFlags[]>>;
+  /** Just the file names of `fetchSummaries`, for summaries read without them. Marks nothing read. */
+  readonly fetchAttachmentNames: (uidSet: string) => Promise<ImapResult<readonly ImapMessageAttachmentNames[]>>;
   readonly fetchRaw: (uid: number) => Promise<ImapResult<Uint8Array>>;
   readonly storeFlags: (uidSet: string, mode: 'add' | 'remove' | 'set', flags: readonly string[]) => Promise<ImapResult<void>>;
   /** Resolves with the RFC 4315 `APPENDUID`, or `null` from a server without UIDPLUS. */
@@ -253,13 +294,8 @@ type ImapClient = {
   readonly expunge: () => Promise<ImapResult<void>>;
   /** RFC 4315. Refuses without UIDPLUS rather than falling back to EXPUNGE, which erases more than asked. */
   readonly uidExpunge: (uidSet: string) => Promise<ImapResult<void>>;
-  readonly uidSearchHeader: (header: string, value: string) => Promise<ImapResult<readonly number[]>>;
-  /**
-   * The selected mailbox's uids whose subject, sender, `To` or body contains `text`, ascending.
-   * One search per field and a union: `TEXT` alone is the body on Forward Email's server, and its
-   * `OR` answers a subset of what the operands do.
-   */
-  readonly uidSearchText: (text: string) => Promise<ImapResult<readonly number[]>>;
+  /** The selected mailbox's uids matching one criterion, ascending. */
+  readonly uidSearch: (criterion: UidSearchCriterion) => Promise<ImapResult<readonly number[]>>;
   /** RFC 6851. Answers with the RFC 4315 `COPYUID`, or null when the server gave none. Refuses without MOVE. */
   readonly move: (uidSet: string, mailbox: string) => Promise<ImapResult<CopyUid | null>>;
   readonly create: (mailbox: string) => Promise<ImapResult<void>>;
@@ -304,4 +340,4 @@ export declare const MAX_UID_SET_LENGTH = 4096;
  */
 export declare const uidSets: (uids: Iterable<number>, maxLength?: number) => readonly string[];
 //#endregion
-export type { ByteDuplex, CopyUid, ImapAddress, ImapClient, ImapClientOptions, ImapContinuation, ImapEnvelope, ImapFailure, ImapFetchItem, ImapIdle, ImapMailbox, ImapMessageSummary, ImapResponse, ImapResponseCode, ImapResult, ImapSelected, ImapTagged, ImapToken, ImapUntagged };
+export type { ByteDuplex, CopyUid, ImapAddress, ImapClient, ImapClientOptions, ImapContinuation, ImapEnvelope, ImapFailure, ImapFetchItem, ImapIdle, ImapMailbox, ImapMessageAttachmentNames, ImapMessageSummary, ImapResponse, ImapResponseCode, ImapResult, ImapSearchDate, ImapSelected, ImapTagged, ImapToken, ImapUntagged, UidSearchCriterion };

package/dist/index.mjs

@@ -214,8 +214,9 @@ const buildSelectCommand = (tag, mailbox, readOnly = false) => {
 	return { lines: [{ text: stringToBytes(`${tag} ${verb} ${quoteString(mboxUtf7)}\r\n`) }] };
 };
 /** `X-GM-THRID` is asked for only when the server advertised `X-GM-EXT-1`: an unknown item is a BAD. */
-const buildFetchSummariesCommand = (tag, set, { gmail, bySeq = false }) => ({ lines: [{ text: stringToBytes(`${tag} ${bySeq ? "FETCH" : "UID FETCH"} ${set} (FLAGS ENVELOPE INTERNALDATE RFC822.SIZE UID BODY.PEEK[HEADER.FIELDS (REFERENCES)]${gmail ? " X-GM-THRID" : ""})\r\n`) }] });
+const buildFetchSummariesCommand = (tag, set, { gmail, bySeq = false }) => ({ lines: [{ text: stringToBytes(`${tag} ${bySeq ? "FETCH" : "UID FETCH"} ${set} (FLAGS ENVELOPE INTERNALDATE RFC822.SIZE UID BODYSTRUCTURE BODY.PEEK[HEADER.FIELDS (REFERENCES)]${gmail ? " X-GM-THRID" : ""})\r\n`) }] });
 const buildFetchFlagsCommand = (tag, uidSet) => ({ lines: [{ text: stringToBytes(`${tag} UID FETCH ${uidSet} (FLAGS UID)\r\n`) }] });
+const buildFetchBodyStructureCommand = (tag, uidSet) => ({ lines: [{ text: stringToBytes(`${tag} UID FETCH ${uidSet} (UID BODYSTRUCTURE)\r\n`) }] });
 const buildFetchRawCommand = (tag, uid) => ({ lines: [{ text: stringToBytes(`${tag} UID FETCH ${uid} (BODY.PEEK[])\r\n`) }] });
 const STORE_OPS = {
 	add: "+FLAGS",
@@ -258,16 +259,23 @@ const buildAppendCommand = (tag, mailbox, flags, message, internalDate) => {
 const buildExpungeCommand = (tag) => ({ lines: [{ text: stringToBytes(`${tag} EXPUNGE\r\n`) }] });
 /** RFC 4315. */
 const buildUidExpungeCommand = (tag, uidSet) => ({ lines: [{ text: stringToBytes(`${tag} UID EXPUNGE ${uidSet}\r\n`) }] });
-/** A server need only index the headers IMAP names; on a private `X-` header it may answer the empty list. */
-const buildUidSearchHeaderCommand = (tag, header, value) => ({ lines: [{ text: stringToBytes(`${tag} UID SEARCH HEADER ${quoteString(header)} ${quoteString(value)}\r\n`) }] });
 /**
-* One `UID SEARCH <key> <text>`. A printable-ASCII query is a quoted string in the default charset;
+* One `UID SEARCH <key>`. A printable-ASCII value is a quoted string in the default charset;
 * anything else is a UTF-8 literal, which every server must accept.
 */
-const buildUidSearchTextCommand = (tag, key, text) => isSafeQuotedString(text) ? { lines: [{ text: stringToBytes(`${tag} UID SEARCH ${key} ${quoteString(text)}\r\n`) }] } : { lines: [{
-	text: stringToBytes(`${tag} UID SEARCH CHARSET UTF-8 ${key} `),
-	literal: stringToBytes(text)
-}, { text: stringToBytes("\r\n") }] };
+const buildUidSearchCommand = (tag, criterion) => {
+	if (criterion.key === "UNSEEN" || criterion.key === "FLAGGED") return { lines: [{ text: stringToBytes(`${tag} UID SEARCH ${criterion.key}\r\n`) }] };
+	if (criterion.key === "BEFORE" || criterion.key === "SINCE") {
+		const { year, month, day } = criterion.date;
+		const date = `${day}-${MONTHS[month - 1]}-${String(year).padStart(4, "0")}`;
+		return { lines: [{ text: stringToBytes(`${tag} UID SEARCH ${criterion.key} ${date}\r\n`) }] };
+	}
+	const key = criterion.key === "HEADER" ? `HEADER ${quoteString(criterion.header)}` : criterion.key;
+	return isSafeQuotedString(criterion.value) ? { lines: [{ text: stringToBytes(`${tag} UID SEARCH ${key} ${quoteString(criterion.value)}\r\n`) }] } : { lines: [{
+		text: stringToBytes(`${tag} UID SEARCH CHARSET UTF-8 ${key} `),
+		literal: stringToBytes(criterion.value)
+	}, { text: stringToBytes("\r\n") }] };
+};
 /** RFC 6851. */
 const buildMoveCommand = (tag, uidSet, mailbox) => ({ lines: [{ text: stringToBytes(`${tag} UID MOVE ${uidSet} ${quoteString(encodeModifiedUtf7(mailbox))}\r\n`) }] });
 const buildCreateCommand = (tag, mailbox) => ({ lines: [{ text: stringToBytes(`${tag} CREATE ${quoteString(encodeModifiedUtf7(mailbox))}\r\n`) }] });
@@ -405,6 +413,158 @@ const decodeRfc2047 = (header) => {
 	return result;
 };
 //#endregion
+//#region src/body-structure.ts
+/** Past this a structure is not mail anyone wrote, and a name in it is not worth finding. */
+const MAX_DEPTH = 32;
+const MAX_NAMES = 64;
+const MAX_NAME_LENGTH = 255;
+const readList = (tokens, start) => {
+	if (tokens[start]?.kind !== "lparen") return {
+		list: null,
+		nextIndex: start + 1
+	};
+	const list = {
+		kind: "list",
+		items: []
+	};
+	const open = [list];
+	let idx = start + 1;
+	while (idx < tokens.length && open.length > 0) {
+		const token = tokens[idx];
+		idx++;
+		const top = open.at(-1);
+		if (token === void 0 || top === void 0) break;
+		if (token.kind === "rparen") open.pop();
+		else if (token.kind === "lparen") {
+			const child = {
+				kind: "list",
+				items: []
+			};
+			top.items.push(child);
+			open.push(child);
+		} else top.items.push(token);
+	}
+	return {
+		list,
+		nextIndex: idx
+	};
+};
+/** A server may send a name as raw bytes; they are UTF-8 unless they cannot be. */
+const decodeRawName = (bytes) => {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return new TextDecoder("latin1").decode(bytes);
+	}
+};
+const textOf = (node) => {
+	if (node?.kind === "literal") return decodeRawName(node.value);
+	if (node?.kind === "quoted") return decodeRawName(Uint8Array.from(node.value, byteOf));
+	return node?.kind === "atom" ? node.value : null;
+};
+const byteOf = (character) => character.charCodeAt(0);
+/** `("KEY" "value" …)` by lowercased key. */
+const paramsIn = (node) => {
+	if (node?.kind !== "list") return /* @__PURE__ */ new Map();
+	return new Map(node.items.flatMap((key, index) => {
+		const value = textOf(node.items[index + 1]);
+		const name = index % 2 === 0 ? textOf(key) : null;
+		return name === null || value === null ? [] : [[name.toLowerCase(), value]];
+	}));
+};
+/** RFC 2231 §4 percent-encoding, as bytes; null when an escape is broken. */
+const percentDecoded = (text) => {
+	const bytes = new TextEncoder().encode(text);
+	const out = [];
+	for (let i = 0; i < bytes.length; i++) {
+		const byte = bytes[i] ?? 0;
+		if (byte !== 37) {
+			out.push(byte);
+			continue;
+		}
+		const hex = String.fromCharCode(bytes[i + 1] ?? 0, bytes[i + 2] ?? 0);
+		if (!/^[0-9a-fA-F]{2}$/u.test(hex)) return null;
+		out.push(Number.parseInt(hex, 16));
+		i += 2;
+	}
+	return out;
+};
+const decodedIn = (bytes, charset) => {
+	try {
+		return new TextDecoder(charset === "" ? "utf-8" : charset, { fatal: true }).decode(Uint8Array.from(bytes));
+	} catch {
+		return null;
+	}
+};
+/**
+* RFC 2231's `key*`, `key*0`, `key*0*`, `key*1`…: the sections in order, their bytes joined before
+* the charset decodes them, since a character may straddle two. Null when absent or odd.
+*/
+const extendedParam = (params, key) => {
+	const ordered = [...params].flatMap(([name, value]) => {
+		if (name === `${key}*`) return [{
+			index: 0,
+			isEncoded: true,
+			value
+		}];
+		if (!name.startsWith(`${key}*`)) return [];
+		const suffix = /^(\d{1,3})(\*?)$/u.exec(name.slice(key.length + 1));
+		return suffix === null ? [] : [{
+			index: Number(suffix[1]),
+			isEncoded: suffix[2] === "*",
+			value
+		}];
+	}).toSorted((a, b) => a.index - b.index);
+	const [first] = ordered;
+	if (first === void 0 || ordered.some(({ index }, at) => index !== at)) return null;
+	const opening = first.isEncoded ? /^([^']*)'[^']*'(.*)$/su.exec(first.value) : null;
+	if (first.isEncoded && opening === null) return null;
+	const bytes = ordered.map(({ isEncoded, value }, at) => {
+		const text = at === 0 && opening !== null ? opening[2] ?? "" : value;
+		return isEncoded ? percentDecoded(text) : [...new TextEncoder().encode(text)];
+	});
+	if (bytes.some((section) => section === null)) return null;
+	const decoded = decodedIn(bytes.flatMap((section) => section ?? []), opening?.[1] ?? "");
+	return decoded === null || first.isEncoded ? decoded : decodeRfc2047(decoded);
+};
+const paramNamed = (params, key) => {
+	const plain = params.get(key);
+	return extendedParam(params, key) ?? (plain === void 0 ? null : decodeRfc2047(plain));
+};
+/** The disposition's file name wins over the type's older `name`. Anything odd is no name. */
+const partName = (disposition, params) => {
+	const name = (paramNamed(disposition, "filename") ?? paramNamed(params, "name") ?? "").trim();
+	return name === "" || name.length > MAX_NAME_LENGTH ? null : name;
+};
+/** RFC 9051 body-type-1part: where the disposition sits differs by the part's type. */
+const dispositionAt = (type, subtype) => {
+	if (type === "TEXT") return 9;
+	return type === "MESSAGE" && ["RFC822", "GLOBAL"].includes(subtype) ? 11 : 8;
+};
+const namesIn = (node, depth) => {
+	if (node?.kind !== "list" || depth > MAX_DEPTH) return [];
+	const [first, second] = node.items;
+	if (first?.kind === "list") return node.items.flatMap((child) => namesIn(child, depth + 1));
+	const type = textOf(first)?.toUpperCase() ?? "";
+	const subtype = textOf(second)?.toUpperCase() ?? "";
+	const disposition = node.items[dispositionAt(type, subtype)];
+	const own = partName(paramsIn(disposition?.kind === "list" ? disposition.items[1] : void 0), paramsIn(node.items[2]));
+	const nested = dispositionAt(type, subtype) === 11 ? namesIn(node.items[8], depth + 1) : [];
+	return [...own === null ? [] : [own], ...nested];
+};
+/**
+* The names a message's parts carry, from a `BODYSTRUCTURE` or `BODY` response: `filename` or `name`
+* in the plain, RFC 2231 and RFC 2047 forms, once each, in part order. Total: what cannot be read
+* is no name, never a failure.
+*/
+const parseBodyStructure = (tokens, start) => {
+	const { list, nextIndex } = readList(tokens, start);
+	return {
+		attachmentNames: [...new Set(namesIn(list ?? void 0, 0))].slice(0, MAX_NAMES),
+		nextIndex
+	};
+};
+//#endregion
 //#region src/envelope.ts
 const tokenToString$1 = (token) => {
 	if (token === void 0 || token.kind === "nil") return null;
@@ -531,47 +691,6 @@ const parseEnvelope = (tokens, start) => {
 		nextIndex: idx
 	};
 };
-/** Only the MIME types, e.g. `['TEXT/PLAIN', 'TEXT/HTML']`. */
-const parseBodyStructureParts = (tokens, start) => {
-	if (tokens[start]?.kind !== "lparen") return {
-		parts: [],
-		nextIndex: start + 1
-	};
-	let idx = start + 1;
-	const parts = [];
-	if (tokens[idx]?.kind === "lparen") {
-		while (idx < tokens.length && tokens[idx]?.kind === "lparen") {
-			const child = parseBodyStructureParts(tokens, idx);
-			parts.push(...child.parts);
-			idx = child.nextIndex;
-		}
-		let depth = 1;
-		while (idx < tokens.length && depth > 0) {
-			if (tokens[idx]?.kind === "lparen") depth++;
-			else if (tokens[idx]?.kind === "rparen") depth--;
-			idx++;
-		}
-		return {
-			parts,
-			nextIndex: idx
-		};
-	}
-	const mediaType = tokenToString$1(tokens[idx]) ?? "APPLICATION";
-	idx++;
-	const subType = tokenToString$1(tokens[idx]) ?? "OCTET-STREAM";
-	idx++;
-	parts.push(`${mediaType.toUpperCase()}/${subType.toUpperCase()}`);
-	let depth = 1;
-	while (idx < tokens.length && depth > 0) {
-		if (tokens[idx]?.kind === "lparen") depth++;
-		else if (tokens[idx]?.kind === "rparen") depth--;
-		idx++;
-	}
-	return {
-		parts,
-		nextIndex: idx
-	};
-};
 const parseFetchItems = (tokens, start) => {
 	if (tokens[start]?.kind !== "lparen") return {
 		items: [],
@@ -637,12 +756,12 @@ const parseFetchItems = (tokens, start) => {
 				} else idx++;
 			} else if (itemName === "BODYSTRUCTURE" || itemName === "BODY" || itemName === "BODY.PEEK") {
 				if (tokens[idx]?.kind === "lparen") {
-					const bsResult = parseBodyStructureParts(tokens, idx);
+					const { attachmentNames, nextIndex } = parseBodyStructure(tokens, idx);
 					items.push({
 						kind: "bodyStructure",
-						parts: bsResult.parts
+						attachmentNames
 					});
-					idx = bsResult.nextIndex;
+					idx = nextIndex;
 				} else if (tokens[idx]?.kind === "lbracket") {
 					idx++;
 					const sectionParts = [];
@@ -1465,12 +1584,14 @@ const summariesFrom = (untagged) => untagged.flatMap((item) => {
 	let envelope = null;
 	let references = [];
 	let gmailThreadId = null;
+	let attachmentNames = [];
 	for (const fItem of item.items) if (fItem.kind === "uid") uid = fItem.uid;
 	else if (fItem.kind === "flags") flags = fItem.flags;
 	else if (fItem.kind === "internalDate") internalDate = fItem.date;
 	else if (fItem.kind === "size") size = fItem.size;
 	else if (fItem.kind === "envelope") envelope = fItem.envelope;
 	else if (fItem.kind === "gmailThreadId") gmailThreadId = fItem.id;
+	else if (fItem.kind === "bodyStructure") attachmentNames = fItem.attachmentNames;
 	else if (fItem.kind === "body" && fItem.section.toUpperCase().startsWith("HEADER.FIELDS")) references = parseReferencesHeader(fItem.bytes);
 	return [{
 		seq: item.seq,
@@ -1480,7 +1601,8 @@ const summariesFrom = (untagged) => untagged.flatMap((item) => {
 		size,
 		envelope,
 		references,
-		gmailThreadId
+		gmailThreadId,
+		attachmentNames
 	}];
 });
 const createImapClient = (transport, options) => {
@@ -1956,6 +2078,22 @@ const createImapClient = (transport, options) => {
 				value: summariesFrom(res.value.untagged)
 			};
 		}),
+		fetchAttachmentNames: (uidSet) => enqueueCommand(async () => {
+			const res = await executeCommand((tag) => buildFetchBodyStructureCommand(tag, uidSet));
+			if (!res.ok) return res;
+			return {
+				ok: true,
+				value: res.value.untagged.flatMap((item) => {
+					if (item.kind !== "fetch") return [];
+					const uid = item.items.find(({ kind }) => kind === "uid");
+					const structure = item.items.find(({ kind }) => kind === "bodyStructure");
+					return uid?.kind === "uid" && structure?.kind === "bodyStructure" ? [{
+						uid: uid.uid,
+						attachmentNames: structure.attachmentNames
+					}] : [];
+				})
+			};
+		}),
 		fetchFlags: (uidSet) => enqueueCommand(async () => {
 			const res = await executeCommand((tag) => buildFetchFlagsCommand(tag, uidSet));
 			if (!res.ok) return res;
@@ -2034,29 +2172,12 @@ const createImapClient = (transport, options) => {
 				value: void 0
 			};
 		}),
-		uidSearchHeader: (header, value) => enqueueCommand(async () => {
-			const res = await executeCommand((tag) => buildUidSearchHeaderCommand(tag, header, value));
+		uidSearch: (criterion) => enqueueCommand(async () => {
+			const res = await executeCommand((tag) => buildUidSearchCommand(tag, criterion));
 			if (!res.ok) return res;
 			return {
 				ok: true,
-				value: res.value.untagged.flatMap((item) => item.kind === "search" ? [...item.uids] : [])
-			};
-		}),
-		uidSearchText: (text) => enqueueCommand(async () => {
-			const found = /* @__PURE__ */ new Set();
-			for (const key of [
-				"SUBJECT",
-				"FROM",
-				"TO",
-				"TEXT"
-			]) {
-				const res = await executeCommand((tag) => buildUidSearchTextCommand(tag, key, text));
-				if (!res.ok) return res;
-				for (const item of res.value.untagged) if (item.kind === "search") for (const uid of item.uids) found.add(uid);
-			}
-			return {
-				ok: true,
-				value: [...found].toSorted((a, b) => a - b)
+				value: res.value.untagged.flatMap((item) => item.kind === "search" ? [...item.uids] : []).toSorted((a, b) => a - b)
 			};
 		}),
 		move: (uidSet, mailbox) => enqueueCommand(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yozz.app/imap",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Transport-agnostic IMAP4rev2/rev1 client core: literals, total parsing, RFC 2047, SASL PLAIN/LOGIN, IDLE, UID MOVE, APPEND with APPENDUID, UID EXPUNGE.",
   "license": "MIT",
   "homepage": "https://github.com/fishballapp/yozz",
@@ -30,9 +30,9 @@
   },
   "devDependencies": {
     "@types/node": "^24.13.4",
-    "@yozz.app/smtp": "0.1.6",
-    "@yozz.app/tls": "0.1.6",
-    "@yozz.app/x509": "0.1.6",
+    "@yozz.app/smtp": "0.2.0",
+    "@yozz.app/tls": "0.2.0",
+    "@yozz.app/x509": "0.2.0",
     "tsdown": "^0.23.0"
   },
   "scripts": {