@remit/data-ports 0.0.32 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -29,6 +29,10 @@
       "types": "./src/display-name.ts",
       "default": "./src/display-name.ts"
     },
+    "./mailbox-name": {
+      "types": "./src/mailbox-name.ts",
+      "default": "./src/mailbox-name.ts"
+    },
     "./wellknown": {
       "types": "./src/wellknown.ts",
       "default": "./src/wellknown.ts"

package/src/mailbox-name.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { resolveMailboxByLeafName } from "./mailbox-name.js";
+
+const JUNK_NAMES = ["junk", "spam", "junk e-mail", "junk email", "bulk mail"];
+
+const mailbox = (
+	mailboxId: string,
+	fullPath: string,
+	hierarchyDelimiter = "/",
+) => ({ mailboxId, fullPath, hierarchyDelimiter });
+
+describe("resolveMailboxByLeafName", () => {
+	it("resolves a Junk folder nested under INBOX", () => {
+		// The layout that broke report-spam's name fallback: an INBOX-prefixed
+		// namespace where Junk is `INBOX/Spam`, which never equals "spam".
+		const found = resolveMailboxByLeafName(
+			[
+				mailbox("m-inbox", "INBOX"),
+				mailbox("m-spam", "INBOX/Spam"),
+				mailbox("m-sent", "INBOX/Sent"),
+			],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-spam");
+	});
+
+	it("resolves under a non-slash delimiter and a non-INBOX prefix", () => {
+		const found = resolveMailboxByLeafName(
+			[mailbox("m-junk", "Mail.Junk E-mail", ".")],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-junk");
+	});
+
+	it("treats a flat namespace with no delimiter as its own leaf", () => {
+		const found = resolveMailboxByLeafName(
+			[mailbox("m-junk", "Junk", "")],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-junk");
+	});
+
+	it("prefers the shallowest match over a deeper one", () => {
+		const found = resolveMailboxByLeafName(
+			[
+				mailbox("m-buried", "Archive/2019/Spam"),
+				mailbox("m-real", "INBOX/Junk"),
+			],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-real");
+	});
+
+	it("prefers the better name at equal depth", () => {
+		const found = resolveMailboxByLeafName(
+			[mailbox("m-bulk", "INBOX/Bulk Mail"), mailbox("m-junk", "INBOX/Junk")],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-junk");
+	});
+
+	it("answers null when no folder carries a conventional name", () => {
+		const found = resolveMailboxByLeafName(
+			[mailbox("m-inbox", "INBOX"), mailbox("m-work", "INBOX/Work")],
+			JUNK_NAMES,
+		);
+		assert.equal(found, null);
+	});
+});

package/src/mailbox-name.ts

@@ -0,0 +1,54 @@
+export interface MailboxNameCandidate {
+	mailboxId: string;
+	fullPath: string;
+	hierarchyDelimiter: string;
+}
+
+// A flat mailbox namespace reports no delimiter at all — ImapFlow gives `""`
+// for a NIL LIST delimiter — and splitting on "" returns single characters, so
+// the path is its own leaf.
+const segments = (mailbox: MailboxNameCandidate): string[] =>
+	mailbox.hierarchyDelimiter.length === 0
+		? [mailbox.fullPath]
+		: mailbox.fullPath.split(mailbox.hierarchyDelimiter);
+
+const rank = (
+	mailbox: MailboxNameCandidate,
+	names: readonly string[],
+): number | null => {
+	const parts = segments(mailbox);
+	const leaf = parts[parts.length - 1] ?? mailbox.fullPath;
+	const nameIndex = names.indexOf(leaf.toLowerCase());
+	if (nameIndex < 0) return null;
+	// Depth outranks the name: a "Spam" buried under Trash or an archive must
+	// never beat the account's real "Junk" one level up.
+	return parts.length * names.length + nameIndex;
+};
+
+/**
+ * A special-use folder by conventional name, for servers that advertise no
+ * special-use flag for it. Matches the folder's own leaf segment against its
+ * mailbox's own hierarchy delimiter, so it resolves at any depth under any
+ * prefix (`INBOX/Spam`, `Mail.Junk E-mail`, `[Gmail]/Spam`) without knowing
+ * which prefixes a server uses. `names` is ordered best-first and must be
+ * lower case.
+ */
+export const resolveMailboxByLeafName = <T extends MailboxNameCandidate>(
+	mailboxes: T[],
+	names: readonly string[],
+): T | null => {
+	let best: { mailbox: T; rank: number } | null = null;
+	for (const mailbox of mailboxes) {
+		const candidate = rank(mailbox, names);
+		if (candidate === null) continue;
+		if (
+			!best ||
+			candidate < best.rank ||
+			(candidate === best.rank &&
+				mailbox.fullPath.localeCompare(best.mailbox.fullPath) < 0)
+		) {
+			best = { mailbox, rank: candidate };
+		}
+	}
+	return best?.mailbox ?? null;
+};