@yozz.app/imap 0.2.0 → 0.3.0

package/README.md

@@ -37,6 +37,15 @@ Or for a specific host with authentication:
 YOZZ_IMAP_HOST=imap.example.com YOZZ_IMAP_USER=me@example.com YOZZ_IMAP_PASSWORD=secret pnpm -F @yozz.app/imap live imap.example.com
 ```
 
+With credentials it also checks, read-only (`UID SEARCH` and `FETCH` only), that one `UID SEARCH` of several keys
+answers the uids its keys answer apart, intersected: `ok` or `MISMATCH` per command. A slow server
+(Forward Email takes 25 s or more a search) makes it take minutes.
+
+**Requires a global `Temporal`.** `append` stamps a `Temporal.ZonedDateTime` (written in its own zone), and
+`UID SEARCH` takes `BEFORE` / `SINCE` days as `Temporal.PlainDate`s. Node 26, Chrome and Firefox ship it; where the runtime has none (Safari, Node 24), install
+[`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill) and load it before this package is
+imported (`import 'temporal-polyfill/global'`). The package imports no polyfill itself.
+
 A literal over 64 MiB (`DEFAULT_MAX_LITERAL_BYTES`, or `maxLiteralBytes` in the options) is a protocol failure.
 
 `harness/relay-load.ts` pushes large messages through the hosted yozz.app relay, up over SMTP and

package/dist/index.d.mts

@@ -19,17 +19,13 @@ type UidSearchCriterion =
 /** By INTERNALDATE's day: `SINCE` is on or after it, `BEFORE` strictly before it. */
 {
   readonly key: 'BEFORE';
-  readonly date: ImapSearchDate;
+  readonly date: Temporal.PlainDate;
 } | {
   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;
+  readonly date: Temporal.PlainDate;
 };
+/** One key, or several that a message must all meet. */
+type UidSearchCriteria = UidSearchCriterion | readonly UidSearchCriterion[];
 //#endregion
 //#region src/tokenizer.d.ts
 export declare const DEFAULT_MAX_LITERAL_BYTES: number;
@@ -241,6 +237,10 @@ type ImapMessageFlags = {
   readonly uid: number;
   readonly flags: readonly string[];
 };
+type ImapRawMessage = {
+  readonly uid: number;
+  readonly bytes: Uint8Array;
+};
 type ImapMessageAttachmentNames = {
   readonly uid: number;
   readonly attachmentNames: readonly string[];
@@ -288,14 +288,16 @@ type ImapClient = {
   /** 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>>;
+  /** Many messages whole in one command; a uid the server no longer has is simply absent. */
+  readonly fetchRawMessages: (uidSet: string) => Promise<ImapResult<readonly ImapRawMessage[]>>;
   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. */
-  readonly append: (mailbox: string, message: Uint8Array, flags: readonly string[], internalDate?: Date) => Promise<ImapResult<AppendUid | null>>;
+  readonly append: (mailbox: string, message: Uint8Array, flags: readonly string[], internalDate?: Temporal.ZonedDateTime) => Promise<ImapResult<AppendUid | null>>;
   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>>;
-  /** The selected mailbox's uids matching one criterion, ascending. */
-  readonly uidSearch: (criterion: UidSearchCriterion) => Promise<ImapResult<readonly number[]>>;
+  /** The selected mailbox's uids matching every one of these keys, ascending. */
+  readonly uidSearch: (criteria: UidSearchCriteria) => 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>>;
@@ -340,4 +342,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, ImapMessageAttachmentNames, ImapMessageSummary, ImapResponse, ImapResponseCode, ImapResult, ImapSearchDate, ImapSelected, ImapTagged, ImapToken, ImapUntagged, UidSearchCriterion };
+export type { ByteDuplex, CopyUid, ImapAddress, ImapClient, ImapClientOptions, ImapContinuation, ImapEnvelope, ImapFailure, ImapFetchItem, ImapIdle, ImapMailbox, ImapMessageAttachmentNames, ImapMessageSummary, ImapRawMessage, ImapResponse, ImapResponseCode, ImapResult, ImapSelected, ImapTagged, ImapToken, ImapUntagged, UidSearchCriteria, UidSearchCriterion };

package/dist/index.mjs

@@ -217,7 +217,8 @@ const buildSelectCommand = (tag, mailbox, readOnly = false) => {
 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`) }] });
+/** `uidSet` is one uid or a uid set: each message comes back whole, unmarked. */
+const buildFetchRawCommand = (tag, uidSet) => ({ lines: [{ text: stringToBytes(`${tag} UID FETCH ${uidSet} (BODY.PEEK[])\r\n`) }] });
 const STORE_OPS = {
 	add: "+FLAGS",
 	remove: "-FLAGS",
@@ -242,11 +243,18 @@ const MONTHS = [
 	"Dec"
 ];
 const two = (value) => String(value).padStart(2, "0");
-/** RFC 9051 date-time. The day is space-padded, which the grammar requires and several servers enforce. */
-const formatImapDateTime = (date) => {
-	const offset = -date.getTimezoneOffset();
-	const zone = `${offset < 0 ? "-" : "+"}${two(Math.floor(Math.abs(offset) / 60))}${two(Math.abs(offset) % 60)}`;
-	return `"${String(date.getDate()).padStart(2, " ")}-${MONTHS[date.getMonth()]}-${date.getFullYear()} ${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())} ${zone}"`;
+/** `+hhmm` in whole minutes: an offset with seconds (a zone's local mean time before 1900) would break the grammar. */
+const zoneOf = ({ offsetNanoseconds }) => {
+	const minutes = Math.trunc(offsetNanoseconds / 6e10);
+	return `${minutes < 0 ? "-" : "+"}${two(Math.floor(Math.abs(minutes) / 60))}${two(Math.abs(minutes) % 60)}`;
+};
+/**
+* RFC 9051 date-time, in the date's own zone and always in the ISO calendar, whatever the caller's.
+* The day is space-padded, which the grammar requires and several servers enforce.
+*/
+const formatImapDateTime = (zoned) => {
+	const date = zoned.withCalendar("iso8601");
+	return `"${String(date.day).padStart(2, " ")}-${MONTHS[date.month - 1]}-${date.year} ${two(date.hour)}:${two(date.minute)}:${two(date.second)} ${zoneOf(date)}"`;
 };
 const buildAppendCommand = (tag, mailbox, flags, message, internalDate) => {
 	const mboxUtf7 = encodeModifiedUtf7(mailbox);
@@ -259,22 +267,39 @@ 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`) }] });
-/**
-* 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 buildUidSearchCommand = (tag, criterion) => {
-	if (criterion.key === "UNSEEN" || criterion.key === "FLAGGED") return { lines: [{ text: stringToBytes(`${tag} UID SEARCH ${criterion.key}\r\n`) }] };
+const searchPieceOf = (criterion) => {
+	if (criterion.key === "UNSEEN" || criterion.key === "FLAGGED") return { text: criterion.key };
 	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 { year, month, day } = criterion.date.withCalendar("iso8601");
+		return { text: `${criterion.key} ${day}-${MONTHS[month - 1]}-${String(year).padStart(4, "0")}` };
 	}
 	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} `),
+	return isSafeQuotedString(criterion.value) ? { text: `${key} ${quoteString(criterion.value)}` } : {
+		text: `${key} `,
 		literal: stringToBytes(criterion.value)
-	}, { text: stringToBytes("\r\n") }] };
+	};
+};
+/**
+* One `UID SEARCH <key> <key>…`: a message must meet every key (RFC 9051 §6.4.4), and no keys at all
+* is `ALL`. A printable-ASCII value is a quoted string in the default charset; if any value is not,
+* the command says `CHARSET UTF-8` and sends that value as a literal, which every server must accept.
+*/
+const buildUidSearchCommand = (tag, criteria) => {
+	const pieces = [criteria].flat().map(searchPieceOf);
+	const isUtf8 = pieces.some(({ literal }) => literal !== void 0);
+	const lines = [];
+	let text = `${tag} UID SEARCH${isUtf8 ? " CHARSET UTF-8" : ""}${pieces.length === 0 ? " ALL" : ""}`;
+	for (const piece of pieces) {
+		text += ` ${piece.text}`;
+		if (piece.literal === void 0) continue;
+		lines.push({
+			text: stringToBytes(text),
+			literal: piece.literal
+		});
+		text = "";
+	}
+	lines.push({ text: stringToBytes(`${text}\r\n`) });
+	return { lines };
 };
 /** RFC 6851. */
 const buildMoveCommand = (tag, uidSet, mailbox) => ({ lines: [{ text: stringToBytes(`${tag} UID MOVE ${uidSet} ${quoteString(encodeModifiedUtf7(mailbox))}\r\n`) }] });
@@ -2115,7 +2140,7 @@ const createImapClient = (transport, options) => {
 			};
 		}),
 		fetchRaw: (uid) => enqueueCommand(async () => {
-			const res = await executeCommand((tag) => buildFetchRawCommand(tag, uid));
+			const res = await executeCommand((tag) => buildFetchRawCommand(tag, String(uid)));
 			if (!res.ok) return res;
 			for (const item of res.value.untagged) if (item.kind === "fetch") {
 				for (const fItem of item.items) if (fItem.kind === "body" && fItem.bytes !== null) return {
@@ -2131,6 +2156,22 @@ const createImapClient = (transport, options) => {
 				}
 			};
 		}),
+		fetchRawMessages: (uidSet) => enqueueCommand(async () => {
+			const res = await executeCommand((tag) => buildFetchRawCommand(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 body = item.items.find(({ kind }) => kind === "body");
+					return uid?.kind === "uid" && body?.kind === "body" && body.bytes !== null ? [{
+						uid: uid.uid,
+						bytes: body.bytes
+					}] : [];
+				})
+			};
+		}),
 		storeFlags: (uidSet, mode, flags) => enqueueCommand(async () => {
 			const res = await executeCommand((tag) => buildStoreFlagsCommand(tag, uidSet, mode, flags));
 			if (!res.ok) return res;
@@ -2172,8 +2213,8 @@ const createImapClient = (transport, options) => {
 				value: void 0
 			};
 		}),
-		uidSearch: (criterion) => enqueueCommand(async () => {
-			const res = await executeCommand((tag) => buildUidSearchCommand(tag, criterion));
+		uidSearch: (criteria) => enqueueCommand(async () => {
+			const res = await executeCommand((tag) => buildUidSearchCommand(tag, criteria));
 			if (!res.ok) return res;
 			return {
 				ok: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yozz.app/imap",
-  "version": "0.2.0",
+  "version": "0.3.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.2.0",
-    "@yozz.app/tls": "0.2.0",
-    "@yozz.app/x509": "0.2.0",
+    "@yozz.app/smtp": "0.3.0",
+    "@yozz.app/tls": "0.3.0",
+    "@yozz.app/x509": "0.3.0",
     "tsdown": "^0.23.0"
   },
   "scripts": {