@yozz.app/imap 0.1.2 → 0.1.3

package/dist/index.d.mts

@@ -262,8 +262,29 @@ type ImapClient = {
   readonly fetchSummariesBySeq: (seqSet: string) => Promise<ImapResult<readonly ImapMessageSummary[]>>; /** UID FETCH FLAGS only — what a resync of already-known messages asks for. */
   readonly fetchFlags: (uidSet: string) => Promise<ImapResult<readonly ImapMessageFlags[]>>; /** UID FETCH BODY.PEEK[] — the whole raw message. */
   readonly fetchRaw: (uid: number) => Promise<ImapResult<Uint8Array>>;
-  readonly storeFlags: (uidSet: string, mode: 'add' | 'remove' | 'set', flags: readonly string[]) => Promise<ImapResult<void>>; /** APPEND a whole RFC 5322 message to a mailbox, e.g. a Sent copy after SMTP accepted it. */
-  readonly append: (mailbox: string, message: Uint8Array, flags: readonly string[]) => Promise<ImapResult<void>>; /** RFC 6851 UID MOVE. Refuses without the MOVE capability (no COPY+EXPUNGE fallback). */
+  readonly storeFlags: (uidSet: string, mode: 'add' | 'remove' | 'set', flags: readonly string[]) => Promise<ImapResult<void>>;
+  /**
+   * APPEND a whole RFC 5322 message to a mailbox, e.g. a Sent copy after SMTP accepted it.
+   * Without `internalDate` the server stamps the message with its own clock.
+   *
+   * Resolves with the `APPENDUID` the server issued (RFC 4315), or `null` where it issued none —
+   * a server without UIDPLUS. That locator is how a caller addresses what it just wrote without
+   * searching for it, which matters for a draft: the alternative is finding it by Message-ID, and
+   * a retry after a lost response would then be indistinguishable from a duplicate.
+   */
+  readonly append: (mailbox: string, message: Uint8Array, flags: readonly string[], internalDate?: Date) => Promise<ImapResult<AppendUid | null>>; /** EXPUNGE: erases every `\\Deleted` message in the selected mailbox. */
+  readonly expunge: () => Promise<ImapResult<void>>;
+  /**
+   * RFC 4315 UID EXPUNGE: erases only these `\\Deleted` messages, leaving anything another
+   * client flagged alone. Refuses without UIDPLUS rather than falling back to plain EXPUNGE,
+   * which would erase more than was asked.
+   */
+  readonly uidExpunge: (uidSet: string) => Promise<ImapResult<void>>;
+  /**
+   * UID SEARCH over one header's exact value in the selected mailbox, newest-last uid order as
+   * the server gives it. An empty array means the mailbox does not hold it.
+   */
+  readonly uidSearchHeader: (header: string, value: string) => Promise<ImapResult<readonly number[]>>; /** RFC 6851 UID MOVE. Refuses without the MOVE capability (no COPY+EXPUNGE fallback). */
   readonly move: (uidSet: string, mailbox: string) => Promise<ImapResult<void>>; /** CREATE a mailbox. */
   readonly create: (mailbox: string) => Promise<ImapResult<void>>;
   readonly noop: () => Promise<ImapResult<void>>;
@@ -276,6 +297,11 @@ type ImapClient = {
   readonly idle: () => ImapIdle;
   readonly logout: () => Promise<ImapResult<void>>;
 };
+/** Where an APPEND landed: RFC 4315's `[APPENDUID <uidvalidity> <uid>]`. */
+type AppendUid = {
+  readonly uidValidity: number;
+  readonly uid: number;
+};
 declare const createImapClient: (transport: ByteDuplex, options?: ImapClientOptions) => ImapClient;
 //#endregion
 //#region src/rfc2047.d.ts

package/dist/index.mjs

@@ -234,13 +234,63 @@ const buildFetchRawCommand = (tag, uid) => ({ lines: [{ text: stringToBytes(`${t
 const buildStoreFlagsCommand = (tag, uidSet, mode, flags) => {
 	return { lines: [{ text: stringToBytes(`${tag} UID STORE ${uidSet} ${mode === "add" ? "+FLAGS" : mode === "remove" ? "-FLAGS" : "FLAGS"} (${flags.join(" ")})\r\n`) }] };
 };
+const MONTHS = [
+	"Jan",
+	"Feb",
+	"Mar",
+	"Apr",
+	"May",
+	"Jun",
+	"Jul",
+	"Aug",
+	"Sep",
+	"Oct",
+	"Nov",
+	"Dec"
+];
+const two = (value) => String(value).padStart(2, "0");
+/**
+* RFC 9051 date-time, quoted: `"28-Aug-2026 09:48:00 +0800"`. The day is space-padded rather
+* than zero-padded, which the grammar requires and several servers enforce. Local zone, so it
+* says when the message reached this client.
+*/
+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}"`;
+};
 /** APPEND with the message as a literal; flags are IMAP atoms such as `\\Seen`, sent unquoted. */
-const buildAppendCommand = (tag, mailbox, flags, message) => {
+const buildAppendCommand = (tag, mailbox, flags, message, internalDate) => {
+	const mboxUtf7 = encodeModifiedUtf7(mailbox);
+	const stamp = internalDate === void 0 ? "" : `${formatImapDateTime(internalDate)} `;
 	return { lines: [{
-		text: stringToBytes(`${tag} APPEND ${quoteString(encodeModifiedUtf7(mailbox))} (${flags.join(" ")}) `),
+		text: stringToBytes(`${tag} APPEND ${quoteString(mboxUtf7)} (${flags.join(" ")}) ${stamp}`),
 		literal: message
 	}, { text: stringToBytes("\r\n") }] };
 };
+/** EXPUNGE: erases every `\\Deleted` message in the selected mailbox. */
+const buildExpungeCommand = (tag) => ({ lines: [{ text: stringToBytes(`${tag} EXPUNGE\r\n`) }] });
+/**
+* RFC 4315 UID EXPUNGE: erases only the named `\\Deleted` messages. Plain EXPUNGE erases every
+* `\\Deleted` message in the mailbox, including ones another client flagged and has not yet
+* erased itself — so replacing a draft with it would quietly take somebody else's deletions with
+* it. Needs UIDPLUS; the client refuses without it rather than falling back.
+*/
+const buildUidExpungeCommand = (tag, uidSet) => ({ lines: [{ text: stringToBytes(`${tag} UID EXPUNGE ${uidSet}\r\n`) }] });
+/**
+* UID SEARCH for one header's exact value, e.g. `HEADER "Message-ID" "<id>"`.
+*
+* What makes an APPEND retry safe: after a lost response the client asks whether the copy it was
+* about to write is already there, instead of writing a second one.
+*
+* **Ask it about a header IMAP names.** A private `X-` header looks like the better question — a
+* Message-ID can be rewritten by a provider, a subject match is a guess — but a server need only
+* index the headers the protocol defines, and one that does not index yours answers the EMPTY LIST
+* rather than an error. That is indistinguishable from "no copy is there", so the caller writes
+* the second copy, or decides it has nothing to erase. Measured on Forward Email:
+* docs/knowledge/forwardemail-api.md.
+*/
+const buildUidSearchHeaderCommand = (tag, header, value) => ({ lines: [{ text: stringToBytes(`${tag} UID SEARCH HEADER ${quoteString(header)} ${quoteString(value)}\r\n`) }] });
 /** RFC 6851 UID MOVE — relocates messages into another mailbox in one round trip. */
 const buildMoveCommand = (tag, uidSet, mailbox) => ({ lines: [{ text: stringToBytes(`${tag} UID MOVE ${uidSet} ${quoteString(encodeModifiedUtf7(mailbox))}\r\n`) }] });
 /** CREATE a mailbox (e.g. Archive the first time the client needs one). */
@@ -1402,6 +1452,21 @@ const tokenizeLogicalLine = (line) => {
 * - Greeting is captured immediately upon creation.
 */
 /**
+* The `APPENDUID` of a tagged OK, when the server issued one. It arrives as an unrecognised
+* response code, which is exactly what `other` is for — no parser change, and a server without
+* UIDPLUS simply has nothing here.
+*/
+const appendUidOf = (tagged) => {
+	const code = tagged.code;
+	if (code?.kind !== "other" || code.code !== "APPENDUID") return null;
+	const [uidValidity, uid] = code.args.map(Number);
+	if (uidValidity === void 0 || uid === void 0) return null;
+	return Number.isInteger(uidValidity) && Number.isInteger(uid) ? {
+		uidValidity,
+		uid
+	} : null;
+};
+/**
 * The msg-ids out of a `HEADER.FIELDS (REFERENCES)` section: the header unfolded, then every
 * `<...>` in order. A truncated or absent header is simply fewer ids.
 */
@@ -1967,14 +2032,47 @@ const createImapClient = (transport, options) => {
 				value: void 0
 			};
 		}),
-		append: (mailbox, message, flags) => enqueueCommand(async () => {
-			const res = await executeCommand((tag) => buildAppendCommand(tag, mailbox, flags, message));
+		append: (mailbox, message, flags, internalDate) => enqueueCommand(async () => {
+			const res = await executeCommand((tag) => buildAppendCommand(tag, mailbox, flags, message, internalDate));
+			if (!res.ok) return res;
+			return {
+				ok: true,
+				value: appendUidOf(res.value.tagged)
+			};
+		}),
+		expunge: () => enqueueCommand(async () => {
+			const res = await executeCommand(buildExpungeCommand);
 			if (!res.ok) return res;
 			return {
 				ok: true,
 				value: void 0
 			};
 		}),
+		uidExpunge: (uidSet) => enqueueCommand(async () => {
+			const greetRes = await greetingPromise;
+			if (!greetRes.ok) return greetRes;
+			if (!knownCapabilities.some((c) => c.toUpperCase() === "UIDPLUS")) return {
+				ok: false,
+				reason: {
+					kind: "no",
+					text: "UID EXPUNGE needs UIDPLUS, which this server lacks"
+				}
+			};
+			const res = await executeCommand((tag) => buildUidExpungeCommand(tag, uidSet));
+			if (!res.ok) return res;
+			return {
+				ok: true,
+				value: void 0
+			};
+		}),
+		uidSearchHeader: (header, value) => enqueueCommand(async () => {
+			const res = await executeCommand((tag) => buildUidSearchHeaderCommand(tag, header, value));
+			if (!res.ok) return res;
+			return {
+				ok: true,
+				value: res.value.untagged.flatMap((item) => item.kind === "search" ? [...item.uids] : [])
+			};
+		}),
 		move: (uidSet, mailbox) => enqueueCommand(async () => {
 			const greetRes = await greetingPromise;
 			if (!greetRes.ok) return greetRes;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yozz.app/imap",
-  "version": "0.1.2",
-  "description": "Transport-agnostic IMAP4rev2/rev1 client core: literals, total parsing, RFC 2047, SASL PLAIN/LOGIN, IDLE, UID MOVE.",
+  "version": "0.1.3",
+  "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",
   "repository": {
@@ -31,12 +31,14 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "tsdown": "^0.22.3",
-    "@yozz.app/tls": "0.1.2",
-    "@yozz.app/x509": "0.1.2"
+    "@yozz.app/smtp": "0.1.3",
+    "@yozz.app/tls": "0.1.3",
+    "@yozz.app/x509": "0.1.3"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm --dts",
     "test": "vitest run",
-    "live": "node harness/live.ts"
+    "live": "node harness/live.ts",
+    "seed": "node harness/seed-inbox.ts"
   }
 }