@yozz.app/imap 0.1.1 → 0.1.3

package/README.md

@@ -8,8 +8,9 @@ pnpm add @yozz.app/imap
 
 ## The seam
 
-`@yozz.app/imap` speaks IMAP over any `ByteDuplex` (`{ read(): Promise<Uint8Array | null>; write(bytes): Promise<void> }`)
-from `@yozz.app/tls`. It knows protocol lines, `{n}` literals, command state, and RFC 2047 header
+`@yozz.app/imap` speaks IMAP over any `ByteDuplex` (`{ read(): Promise<Uint8Array | null>; write(bytes): Promise<void> }`),
+a type it declares itself; a `@yozz.app/tls` connection satisfies it, and so does anything else with
+those two methods. The package has no runtime dependencies. It knows protocol lines, `{n}` literals, command state, and RFC 2047 header
 decoding. It **never knows** TLS records, certificates, session keys, or vault storage.
 
 In the browser, the duplex wraps `@yozz.app/tls` over the production WebSocket relay. In tests, it

package/dist/index.d.mts

@@ -1,5 +1,3 @@
-import { ByteDuplex } from "@yozz.app/tls";
-
 //#region src/tokenizer.d.ts
 /**
  * Hand-written tokenizer over byte offsets for IMAP4rev2/rev1 stream.
@@ -194,6 +192,17 @@ type ImapResponse = ImapTagged | {
 } | ImapContinuation;
 declare const parseResponse: (tokens: readonly ImapToken[]) => ImapResult<ImapResponse>;
 //#endregion
+//#region src/transport.d.ts
+/**
+ * What this client needs from a transport: bytes in, bytes out. Declared here rather than
+ * imported from `@yozz.app/tls` so the package has no runtime dependency at all; it is the same
+ * two-method shape, so a `TlsConnection` satisfies it structurally.
+ */
+type ByteDuplex = {
+  readonly read: () => Promise<Uint8Array | null>;
+  readonly write: (bytes: Uint8Array) => Promise<void>;
+};
+//#endregion
 //#region src/client.d.ts
 type ImapMessageSummary = {
   readonly seq: number;
@@ -253,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>>;
@@ -267,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
@@ -282,4 +317,4 @@ declare const createImapClient: (transport: ByteDuplex, options?: ImapClientOpti
  */
 declare const decodeRfc2047: (header: string) => string;
 //#endregion
-export { DEFAULT_MAX_LITERAL_BYTES, type ImapAddress, type ImapClient, type ImapClientOptions, type ImapContinuation, type ImapEnvelope, type ImapFailure, type ImapFetchItem, type ImapIdle, type ImapMailbox, type ImapMessageSummary, type ImapResponse, type ImapResponseCode, type ImapResult, type ImapSelected, type ImapTagged, type ImapToken, type ImapUntagged, createImapClient, decodeRfc2047, parseResponse };
+export { type ByteDuplex, DEFAULT_MAX_LITERAL_BYTES, type ImapAddress, type ImapClient, type ImapClientOptions, type ImapContinuation, type ImapEnvelope, type ImapFailure, type ImapFetchItem, type ImapIdle, type ImapMailbox, type ImapMessageSummary, type ImapResponse, type ImapResponseCode, type ImapResult, type ImapSelected, type ImapTagged, type ImapToken, type ImapUntagged, createImapClient, decodeRfc2047, parseResponse };

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). */
@@ -1392,6 +1442,31 @@ const tokenizeLogicalLine = (line) => {
 //#endregion
 //#region src/client.ts
 /**
+* IMAP client state machine over ByteDuplex.
+*
+* Invariants:
+* - One IMAP connection object per device (no connection pool).
+* - Transport is ByteDuplex from @yozz.app/tls.
+* - Parsing is total: parser never throws, returns typed ImapFailure and closes.
+* - Commands are serialised: one in-flight command at a time, queued in order (no pipelining in this slice).
+* - 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.
 */
@@ -1957,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.1",
-  "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": {
@@ -28,17 +28,17 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@yozz.app/tls": "0.1.1"
-  },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "tsdown": "^0.22.3",
-    "@yozz.app/x509": "0.1.1"
+    "@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"
   }
 }