@remit/data-ports 0.0.34 → 0.0.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -33,6 +33,10 @@
       "types": "./src/display-name.ts",
       "default": "./src/display-name.ts"
     },
+    "./folder-role": {
+      "types": "./src/folder-role.ts",
+      "default": "./src/folder-role.ts"
+    },
     "./mailbox-name": {
       "types": "./src/mailbox-name.ts",
       "default": "./src/mailbox-name.ts"

package/src/folder-role.test.ts

@@ -0,0 +1,167 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { CanonicalMailboxRole, MailboxSpecialUse } from "@remit/domain-enums";
+import {
+	type RoleMailboxCandidate,
+	resolveConfirmedMailboxForRole,
+	resolveMailboxForRole,
+} from "./folder-role.js";
+
+const mailbox = (
+	mailboxId: string,
+	fullPath: string,
+	specialUse: readonly string[] = [],
+	hierarchyDelimiter = "/",
+): RoleMailboxCandidate => ({
+	mailboxId,
+	fullPath,
+	hierarchyDelimiter,
+	specialUse,
+});
+
+describe("resolveMailboxForRole precedence", () => {
+	const mailboxes = [
+		mailbox("mb-inbox", "INBOX"),
+		mailbox("mb-spam", "INBOX/Spam"),
+		mailbox("mb-junk", "Junk", [MailboxSpecialUse.Junk]),
+		mailbox("mb-project", "INBOX/Project X"),
+	];
+
+	it("puts the user's appointment above both the flag and the name", () => {
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Junk, mailboxes, "mb-project")
+				?.mailboxId,
+			"mb-project",
+		);
+	});
+
+	it("takes the server's SPECIAL-USE flag when nothing is appointed", () => {
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Junk, mailboxes)?.mailboxId,
+			"mb-junk",
+		);
+	});
+
+	it("falls back to the name only when no flag is present", () => {
+		const unflagged = mailboxes.filter((m) => m.mailboxId !== "mb-junk");
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Junk, unflagged)?.mailboxId,
+			"mb-spam",
+		);
+	});
+
+	it("reads the leaf against the mailbox's own delimiter, not a hardcoded slash", () => {
+		const dotted = [
+			mailbox("mb-inbox", "INBOX", [], "."),
+			mailbox("mb-trash", "INBOX.Deleted Items", [], "."),
+		];
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Trash, dotted)?.mailboxId,
+			"mb-trash",
+		);
+	});
+
+	it("matches the reserved INBOX name for Inbox", () => {
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Inbox, mailboxes)?.mailboxId,
+			"mb-inbox",
+		);
+	});
+
+	it("returns null rather than guessing when nothing matches", () => {
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Archive, mailboxes),
+			null,
+		);
+	});
+
+	it("re-proposes when the appointment names a mailbox that is gone", () => {
+		assert.equal(
+			resolveMailboxForRole(
+				CanonicalMailboxRole.Junk,
+				mailboxes,
+				"mb-deleted-last-week",
+			)?.mailboxId,
+			"mb-junk",
+		);
+	});
+});
+
+describe("resolveMailboxForRole on [Gmail]/Trash beside a top-level Bin", () => {
+	// #837: joining Trash to the leaf-name resolver made depth outrank the name,
+	// so a top-level `Bin` beat `[Gmail]/Trash` and deletes landed in the wrong
+	// folder. `bin` is no longer a hint — Gmail flags both \Trash — so the name
+	// rule reaches `[Gmail]/Trash` and nothing reaches `Bin`.
+	const mailboxes = [
+		mailbox("mb-inbox", "INBOX"),
+		mailbox("mb-bin", "Bin"),
+		mailbox("mb-gmail-trash", "[Gmail]/Trash"),
+	];
+
+	it("proposes [Gmail]/Trash, never the folder called Bin", () => {
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Trash, mailboxes)?.mailboxId,
+			"mb-gmail-trash",
+		);
+	});
+
+	it("resolves to whichever folder the user appointed", () => {
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Trash, mailboxes, "mb-bin")
+				?.mailboxId,
+			"mb-bin",
+		);
+	});
+
+	it("still takes the SPECIAL-USE flag over the name when nothing is appointed", () => {
+		const flagged = [
+			mailbox("mb-inbox", "INBOX"),
+			mailbox("mb-bin", "Bin"),
+			mailbox("mb-gmail-trash", "[Gmail]/Trash", [MailboxSpecialUse.Trash]),
+		];
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Trash, flagged)?.mailboxId,
+			"mb-gmail-trash",
+		);
+	});
+});
+
+describe("resolveConfirmedMailboxForRole", () => {
+	// What Empty Trash resolves through: an expunge may only touch a folder
+	// somebody actually designated (audit #841).
+	const mailboxes = [
+		mailbox("mb-inbox", "INBOX"),
+		mailbox("mb-deleted", "Deleted"),
+		mailbox("mb-gmail-trash", "[Gmail]/Trash"),
+	];
+
+	it("refuses a folder that only matches by name", () => {
+		assert.equal(
+			resolveConfirmedMailboxForRole(CanonicalMailboxRole.Trash, mailboxes),
+			null,
+		);
+	});
+
+	it("takes the appointment over the folder the name rule would have picked", () => {
+		assert.equal(
+			resolveConfirmedMailboxForRole(
+				CanonicalMailboxRole.Trash,
+				mailboxes,
+				"mb-gmail-trash",
+			)?.mailboxId,
+			"mb-gmail-trash",
+		);
+	});
+
+	it("takes the server flag when nothing is appointed", () => {
+		const flagged = [
+			mailbox("mb-deleted", "Deleted"),
+			mailbox("mb-trash", "[Gmail]/Trash", [MailboxSpecialUse.Trash]),
+		];
+		assert.equal(
+			resolveConfirmedMailboxForRole(CanonicalMailboxRole.Trash, flagged)
+				?.mailboxId,
+			"mb-trash",
+		);
+	});
+});

package/src/folder-role.ts

@@ -0,0 +1,195 @@
+import {
+	AccountSettingName,
+	CanonicalMailboxRole,
+	MailboxSpecialUse,
+} from "@remit/domain-enums";
+import {
+	composeSettingName,
+	SETTING_NAME_SEPARATOR,
+} from "./account-settings.js";
+import {
+	type MailboxNameCandidate,
+	resolveMailboxByLeafName,
+} from "./mailbox-name.js";
+
+export type CanonicalMailboxRoleValue =
+	(typeof CanonicalMailboxRole)[keyof typeof CanonicalMailboxRole];
+
+/** The fixed anchor set, in the RFC's canonical display order. */
+export const CANONICAL_ROLES: readonly CanonicalMailboxRoleValue[] =
+	Object.values(CanonicalMailboxRole);
+
+const isCanonicalRole = (value: string): value is CanonicalMailboxRoleValue =>
+	(CANONICAL_ROLES as readonly string[]).includes(value);
+
+/**
+ * The stored `AccountSetting` name holding one role's appointment. Composed
+ * here rather than at either reader, so the backend that writes it and the
+ * repository that reads it can never disagree about the key.
+ */
+export const composeFolderRoleAppointmentName = (
+	accountId: string,
+	role: CanonicalMailboxRoleValue,
+): string =>
+	composeSettingName(
+		AccountSettingName.FolderRoleAppointment,
+		`${accountId}${SETTING_NAME_SEPARATOR}${role}`,
+	);
+
+/**
+ * Split a stored appointment name back into its two-part target. Unlike the
+ * single-target composites (`MailboxRole#<id>`), this setting composes two ids
+ * after the base, so it parses the suffix itself rather than reusing
+ * `targetIdOf`.
+ */
+export const parseFolderRoleAppointmentName = (
+	name: string,
+): { accountId: string; role: CanonicalMailboxRoleValue } | undefined => {
+	const [base, ...rest] = name.split(SETTING_NAME_SEPARATOR);
+	if (base !== AccountSettingName.FolderRoleAppointment) return undefined;
+	const role = rest[rest.length - 1];
+	const accountId = rest.slice(0, -1).join(SETTING_NAME_SEPARATOR);
+	if (!accountId || !role || !isCanonicalRole(role)) return undefined;
+	return { accountId, role };
+};
+
+/**
+ * RFC 6154 SPECIAL-USE flag per role. Inbox has no SPECIAL-USE flag (RFC 3501
+ * reserves the name itself); a role with no entry here is matched by name hint
+ * only.
+ */
+export const ROLE_SPECIAL_USE: Partial<
+	Record<CanonicalMailboxRoleValue, string>
+> = {
+	[CanonicalMailboxRole.Drafts]: MailboxSpecialUse.Drafts,
+	[CanonicalMailboxRole.Sent]: MailboxSpecialUse.Sent,
+	[CanonicalMailboxRole.Archive]: MailboxSpecialUse.Archive,
+	[CanonicalMailboxRole.Junk]: MailboxSpecialUse.Junk,
+	[CanonicalMailboxRole.Trash]: MailboxSpecialUse.Trash,
+	[CanonicalMailboxRole.All]: MailboxSpecialUse.All,
+	[CanonicalMailboxRole.Flagged]: MailboxSpecialUse.Flagged,
+};
+
+/**
+ * Weak name hints, ordered best-first and lower case: the last resort for a
+ * provider that advertises no SPECIAL-USE and whose user has appointed
+ * nothing. Deliberately small — a guess that seeds a proposal, never a
+ * substitute for server truth or for what the user chose.
+ */
+export const ROLE_NAME_HINTS: Partial<
+	Record<CanonicalMailboxRoleValue, readonly string[]>
+> = {
+	[CanonicalMailboxRole.Drafts]: ["drafts", "draft", "concepten"],
+	[CanonicalMailboxRole.Sent]: [
+		"sent",
+		"sent items",
+		"sent messages",
+		"sent mail",
+	],
+	[CanonicalMailboxRole.Archive]: ["archive", "archives", "all mail"],
+	[CanonicalMailboxRole.Junk]: [
+		"junk",
+		"spam",
+		"junk e-mail",
+		"junk email",
+		"bulk mail",
+	],
+	// No bare "deleted" and no "bin": both are ordinary folder names a user
+	// keeps mail in, and a wrong guess here files deletes into a folder the
+	// user never meant as Trash. Gmail's en-GB "Bin" and its "[Gmail]/Trash"
+	// both advertise \Trash, so the flag already covers them (#837).
+	[CanonicalMailboxRole.Trash]: ["trash", "deleted items", "deleted messages"],
+	[CanonicalMailboxRole.All]: ["all mail", "all"],
+};
+
+/**
+ * The pane where a user appoints a folder to a role, named as it is labelled.
+ * Every refusal that asks for an appointment points here, in one wording — the
+ * settings screen is titled "Folder roles", and copies of this sentence had
+ * already drifted to "Folders".
+ */
+export const FOLDER_ROLES_SETTINGS_PATH = "Settings › Folder roles";
+
+/**
+ * Why an operation that files or destroys mail was refused. A delete, an
+ * Empty Trash and the count the handler reports before one all act on the
+ * folder the user appointed or the server flagged, and all refuse in these
+ * words — one sentence, so two surfaces cannot tell a user two things about
+ * one account.
+ */
+export const NO_TRASH_FOLDER_REASON = `This account has no Trash folder, so nothing was deleted. Appoint one under ${FOLDER_ROLES_SETTINGS_PATH}, then try again.`;
+
+/** The minimal mailbox shape role resolution reads. */
+export interface RoleMailboxCandidate extends MailboxNameCandidate {
+	specialUse?: readonly string[];
+}
+
+/**
+ * The mailbox a role is CONFIRMED to hold: the one the user appointed, or the
+ * one the server flagged (RFC 6154). No name guessing — `null` here means
+ * nobody has said which folder this is, only that a folder happens to be named
+ * something plausible. An operation that destroys mail resolves through this
+ * and refuses when it comes back empty; `resolveMailboxForRole` adds the guess
+ * on top for the operations where being wrong only misfiles a message.
+ *
+ * An appointment naming a mailbox this account does not hold — deleted,
+ * renamed, or carried in from elsewhere — is stale, and falls through to the
+ * flag as if unset.
+ */
+export const resolveConfirmedMailboxForRole = <T extends RoleMailboxCandidate>(
+	role: CanonicalMailboxRoleValue,
+	mailboxes: readonly T[],
+	appointedMailboxId?: string,
+): T | null => {
+	if (appointedMailboxId) {
+		const appointed = mailboxes.find((m) => m.mailboxId === appointedMailboxId);
+		if (appointed) return appointed;
+	}
+
+	const specialUse = ROLE_SPECIAL_USE[role];
+	if (specialUse) {
+		const flagged = mailboxes.find((m) => m.specialUse?.includes(specialUse));
+		if (flagged) return flagged;
+	}
+
+	if (role === CanonicalMailboxRole.Inbox) {
+		return mailboxes.find((m) => m.fullPath.toUpperCase() === "INBOX") ?? null;
+	}
+
+	return null;
+};
+
+/**
+ * The single mailbox that holds a canonical role for an account (RFC 032
+ * exclusive-folder-appointment, #976), in one precedence order every caller
+ * shares:
+ *
+ * 1. the mailbox the user appointed;
+ * 2. the server's own SPECIAL-USE flag (RFC 6154) — language-independent truth;
+ * 3. the reserved `INBOX` name, for the Inbox role only (RFC 3501);
+ * 4. a conventional name, matched on the folder's own leaf segment so it
+ *    resolves at any depth under any prefix.
+ *
+ * The last of those is a guess: a folder named `Deleted` is not evidence that
+ * the user means it as Trash. Use it only where being wrong misfiles a message
+ * a user can move back — never where it destroys mail.
+ *
+ * `null` when nothing matches: the role has no folder, and the caller says so
+ * rather than picking one.
+ */
+export const resolveMailboxForRole = <T extends RoleMailboxCandidate>(
+	role: CanonicalMailboxRoleValue,
+	mailboxes: readonly T[],
+	appointedMailboxId?: string,
+): T | null => {
+	const confirmed = resolveConfirmedMailboxForRole(
+		role,
+		mailboxes,
+		appointedMailboxId,
+	);
+	if (confirmed) return confirmed;
+
+	const hints = ROLE_NAME_HINTS[role];
+	if (!hints) return null;
+	return resolveMailboxByLeafName(mailboxes, hints);
+};

package/src/interfaces/mailbox-special-use.ts

@@ -3,6 +3,13 @@ import type {
 	MailboxSpecialUseValue,
 } from "../types.js";
 
+/**
+ * Special-use entries, plus the per-role lookup every special-folder operation
+ * goes through. The `find<Role>Mailbox` reads answer "which folder holds this
+ * role for this account", in the one precedence order `resolveMailboxForRole`
+ * defines: the user's appointment first (RFC 032 exclusive-folder-appointment,
+ * #976), then the server's SPECIAL-USE flag, then a conventional name.
+ */
 export interface IMailboxSpecialUseRepository {
 	create(
 		mailboxId: string,
@@ -14,16 +21,23 @@ export interface IMailboxSpecialUseRepository {
 	): Promise<MailboxSpecialUseItem[]>;
 	listByMailboxId(mailboxId: string): Promise<MailboxSpecialUseItem[]>;
 	deleteByMailboxId(mailboxId: string): Promise<number>;
-	findBySpecialUse(
+	findInboxMailbox(
 		accountId: string,
-		specialUse: MailboxSpecialUseValue,
 	): Promise<{ mailboxId: string; fullPath: string } | null>;
-	findInboxMailbox(
+	findSentMailbox(
 		accountId: string,
 	): Promise<{ mailboxId: string; fullPath: string } | null>;
 	findTrashMailbox(
 		accountId: string,
 	): Promise<{ mailboxId: string; fullPath: string } | null>;
+	/**
+	 * Trash without the name guess: the appointment or the \Trash flag, nothing
+	 * else. Empty Trash expunges whatever this returns, and a folder merely
+	 * named `Deleted` is not consent to destroy its contents.
+	 */
+	findConfirmedTrashMailbox(
+		accountId: string,
+	): Promise<{ mailboxId: string; fullPath: string } | null>;
 	findArchiveMailbox(
 		accountId: string,
 	): Promise<{ mailboxId: string; fullPath: string } | null>;

package/src/mailbox-name.ts

@@ -34,7 +34,7 @@ const rank = (
  * lower case.
  */
 export const resolveMailboxByLeafName = <T extends MailboxNameCandidate>(
-	mailboxes: T[],
+	mailboxes: readonly T[],
 	names: readonly string[],
 ): T | null => {
 	let best: { mailbox: T; rank: number } | null = null;

package/src/mailbox-role.ts

@@ -1,20 +1,17 @@
-import { MailboxSpecialUse } from "@remit/domain-enums";
-import { resolveMailboxByLeafName } from "./mailbox-name.js";
+import { CanonicalMailboxRole } from "@remit/domain-enums";
+import { ROLE_NAME_HINTS, resolveMailboxForRole } from "./folder-role.js";
 
-export const JUNK_FOLDER_NAMES: readonly string[] = [
-	"junk",
-	"spam",
-	"junk e-mail",
-	"junk email",
-	"bulk mail",
-];
+/**
+ * The conventional names for a role, taken from the one table every
+ * special-folder lookup shares (`folder-role.ts`). Exported so the SQLite junk
+ * repair can spell the same rule; a second list here is how `INBOX/Sent` and
+ * `INBOX/Spam` came to be resolvable in one place and not another.
+ */
+export const JUNK_FOLDER_NAMES: readonly string[] =
+	ROLE_NAME_HINTS[CanonicalMailboxRole.Junk] ?? [];
 
-export const TRASH_FOLDER_NAMES: readonly string[] = [
-	"trash",
-	"deleted items",
-	"deleted",
-	"bin",
-];
+export const TRASH_FOLDER_NAMES: readonly string[] =
+	ROLE_NAME_HINTS[CanonicalMailboxRole.Trash] ?? [];
 
 export interface MailboxRole {
 	readonly fullPath: string;
@@ -22,25 +19,27 @@ export interface MailboxRole {
 	readonly specialUse?: readonly string[];
 }
 
+/**
+ * Whether one mailbox, considered alone, carries a role: its SPECIAL-USE flag
+ * or its conventional name. A single mailbox carries no account context, so
+ * this cannot see the user's appointment — a caller holding an accountId asks
+ * `IMailboxSpecialUseRepository` instead, which does.
+ */
 const carriesRole = (
 	mailbox: MailboxRole,
-	specialUse: string,
-	namesWhenServerDoesNotSaySo: readonly string[],
+	role: (typeof CanonicalMailboxRole)[keyof typeof CanonicalMailboxRole],
 ): boolean =>
-	mailbox.specialUse?.includes(specialUse) === true ||
-	resolveMailboxByLeafName(
-		[
-			{
-				mailboxId: "",
-				fullPath: mailbox.fullPath,
-				hierarchyDelimiter: mailbox.hierarchyDelimiter ?? "",
-			},
-		],
-		namesWhenServerDoesNotSaySo,
-	) !== null;
+	resolveMailboxForRole(role, [
+		{
+			mailboxId: "",
+			fullPath: mailbox.fullPath,
+			hierarchyDelimiter: mailbox.hierarchyDelimiter ?? "",
+			specialUse: mailbox.specialUse,
+		},
+	]) !== null;
 
 export const isJunkMailbox = (mailbox: MailboxRole): boolean =>
-	carriesRole(mailbox, MailboxSpecialUse.Junk, JUNK_FOLDER_NAMES);
+	carriesRole(mailbox, CanonicalMailboxRole.Junk);
 
 export const isTrashMailbox = (mailbox: MailboxRole): boolean =>
-	carriesRole(mailbox, MailboxSpecialUse.Trash, TRASH_FOLDER_NAMES);
+	carriesRole(mailbox, CanonicalMailboxRole.Trash);