@remit/data-ports 0.0.32 → 0.0.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -25,10 +25,18 @@
       "types": "./src/account-settings.ts",
       "default": "./src/account-settings.ts"
     },
+    "./mailbox-role": {
+      "types": "./src/mailbox-role.ts",
+      "default": "./src/mailbox-role.ts"
+    },
     "./display-name": {
       "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/interfaces/address.ts

@@ -11,6 +11,9 @@ import type {
 export interface IAddressRepository {
 	createAddress(input: CreateAddressInput): Promise<AddressItem>;
 	upsertAddress(input: CreateAddressInput): Promise<AddressItem>;
+	upsertCorrespondentAddress(input: CreateAddressInput): Promise<AddressItem>;
+	upsertJunkAddress(input: CreateAddressInput): Promise<AddressItem>;
+	reconcileJunkOnlyForMessage(messageId: string): Promise<void>;
 	getAddress(accountConfigId: string, addressId: string): Promise<AddressItem>;
 	getAddress(
 		accountConfigId: string,

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;
+};

package/src/mailbox-role.ts

@@ -0,0 +1,46 @@
+import { MailboxSpecialUse } from "@remit/domain-enums";
+import { resolveMailboxByLeafName } from "./mailbox-name.js";
+
+export const JUNK_FOLDER_NAMES: readonly string[] = [
+	"junk",
+	"spam",
+	"junk e-mail",
+	"junk email",
+	"bulk mail",
+];
+
+export const TRASH_FOLDER_NAMES: readonly string[] = [
+	"trash",
+	"deleted items",
+	"deleted",
+	"bin",
+];
+
+export interface MailboxRole {
+	readonly fullPath: string;
+	readonly hierarchyDelimiter?: string;
+	readonly specialUse?: readonly string[];
+}
+
+const carriesRole = (
+	mailbox: MailboxRole,
+	specialUse: string,
+	namesWhenServerDoesNotSaySo: readonly string[],
+): boolean =>
+	mailbox.specialUse?.includes(specialUse) === true ||
+	resolveMailboxByLeafName(
+		[
+			{
+				mailboxId: "",
+				fullPath: mailbox.fullPath,
+				hierarchyDelimiter: mailbox.hierarchyDelimiter ?? "",
+			},
+		],
+		namesWhenServerDoesNotSaySo,
+	) !== null;
+
+export const isJunkMailbox = (mailbox: MailboxRole): boolean =>
+	carriesRole(mailbox, MailboxSpecialUse.Junk, JUNK_FOLDER_NAMES);
+
+export const isTrashMailbox = (mailbox: MailboxRole): boolean =>
+	carriesRole(mailbox, MailboxSpecialUse.Trash, TRASH_FOLDER_NAMES);