@remit/backend 0.0.67 → 0.0.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",

package/src/handlers/folder-role-appointments.test.ts

@@ -1,11 +1,10 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import type { AccountSettingItem } from "@remit/data-ports";
+import type { RoleMailboxCandidate } from "@remit/data-ports/folder-role";
 import { CanonicalMailboxRole, MailboxSpecialUse } from "@remit/domain-enums";
 import {
 	CANONICAL_ROLES,
-	type FolderCandidate,
-	findFolderForRole,
 	groupFolderAppointmentsByAccount,
 	loadFolderAppointmentsForAccount,
 	resolveFolderAppointments,
@@ -40,60 +39,18 @@ describe("CANONICAL_ROLES", () => {
 	});
 });
 
-describe("findFolderForRole", () => {
-	const folders: FolderCandidate[] = [
-		{ mailboxId: "mb-inbox", fullPath: "INBOX" },
+describe("resolveFolderAppointments", () => {
+	const folders: RoleMailboxCandidate[] = [
+		{ mailboxId: "mb-inbox", fullPath: "INBOX", hierarchyDelimiter: "/" },
 		{
-			mailboxId: "mb-drafts-empty",
-			fullPath: "INBOX/Drafts",
-			specialUse: [MailboxSpecialUse.Drafts],
+			mailboxId: "mb-concepten",
+			fullPath: "INBOX/Concepten",
+			hierarchyDelimiter: "/",
 		},
-		{ mailboxId: "mb-concepten", fullPath: "INBOX/Concepten" },
-		{ mailboxId: "mb-sent", fullPath: "INBOX/Sent" },
-		{ mailboxId: "mb-sent-messages", fullPath: "INBOX/Sent Messages" },
-		{ mailboxId: "mb-news", fullPath: "INBOX/Nieuwsbrieven" },
-	];
-
-	it("matches the reserved INBOX name for Inbox", () => {
-		assert.equal(
-			findFolderForRole(CanonicalMailboxRole.Inbox, folders),
-			"mb-inbox",
-		);
-	});
-
-	it("prefers the SPECIAL-USE flag over a name hint", () => {
-		assert.equal(
-			findFolderForRole(CanonicalMailboxRole.Drafts, folders),
-			"mb-drafts-empty",
-		);
-	});
-
-	it("falls back to a weak name hint when no flag is present", () => {
-		assert.equal(
-			findFolderForRole(CanonicalMailboxRole.Sent, folders),
-			"mb-sent",
-		);
-	});
-
-	it("returns null when nothing matches", () => {
-		assert.equal(findFolderForRole(CanonicalMailboxRole.Junk, folders), null);
-	});
-
-	it("never matches a plain user folder", () => {
-		assert.equal(
-			findFolderForRole(CanonicalMailboxRole.Archive, folders),
-			null,
-		);
-	});
-});
-
-describe("resolveFolderAppointments", () => {
-	const folders: FolderCandidate[] = [
-		{ mailboxId: "mb-inbox", fullPath: "INBOX" },
-		{ mailboxId: "mb-concepten", fullPath: "INBOX/Concepten" },
 		{
 			mailboxId: "mb-spam",
 			fullPath: "INBOX/Spam",
+			hierarchyDelimiter: "/",
 			specialUse: [MailboxSpecialUse.Junk],
 		},
 	];

package/src/handlers/folder-role-appointments.ts

@@ -1,67 +1,29 @@
-import type {
-	CanonicalMailboxRole as CanonicalMailboxRoleValue,
-	FolderAppointment,
-} from "@remit/api-openapi-types";
+import type { FolderAppointment } from "@remit/api-openapi-types";
 import type {
 	AccountSettingItem,
 	IAccountSettingRepository,
 	IMailboxRepository,
 } from "@remit/data-ports";
 import {
-	baseSettingName,
-	composeSettingName,
-	SETTING_NAME_SEPARATOR,
-} from "@remit/data-ports/account-settings";
-import {
-	AccountSettingName,
-	CanonicalMailboxRole,
-	MailboxSpecialUse,
-} from "@remit/domain-enums";
+	CANONICAL_ROLES,
+	type CanonicalMailboxRoleValue,
+	composeFolderRoleAppointmentName,
+	parseFolderRoleAppointmentName,
+	type RoleMailboxCandidate,
+	resolveMailboxForRole,
+} from "@remit/data-ports/folder-role";
 
 /**
  * RFC 032 exclusive-folder-appointment (#976): a per-account role→mailbox map.
  * Each row is a `FolderRoleAppointment#<accountId>#<role>` AccountSetting (RFC
  * 032 settings tiers), so a role can never be persisted twice for one account —
  * writing it replaces whichever mailbox previously held it. This module owns
- * that persistence plus the read-side proposal (`findFolderForRole`) that fills
- * any role the user hasn't appointed yet.
+ * that persistence; the read side is `resolveMailboxForRole`
+ * (`@remit/data-ports/folder-role`), the same rule every special-folder lookup
+ * in the backend and the workers goes through.
  */
 
-const FOLDER_ROLE_APPOINTMENT = AccountSettingName.FolderRoleAppointment;
-
-/** The fixed anchor set, in the RFC's canonical display order. */
-export const CANONICAL_ROLES: readonly CanonicalMailboxRoleValue[] =
-	Object.values(CanonicalMailboxRole);
-
-const composeAppointmentName = (
-	accountId: string,
-	role: CanonicalMailboxRoleValue,
-): string =>
-	composeSettingName(
-		FOLDER_ROLE_APPOINTMENT,
-		`${accountId}${SETTING_NAME_SEPARATOR}${role}`,
-	);
-
-/**
- * Split a stored `FolderRoleAppointment#<accountId>#<role>` 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`.
- */
-const parseAppointmentTarget = (
-	name: string,
-): { accountId: string; role: string } | undefined => {
-	if (baseSettingName(name) !== FOLDER_ROLE_APPOINTMENT) return undefined;
-	const idx = name.indexOf(SETTING_NAME_SEPARATOR);
-	if (idx === -1) return undefined;
-	const rest = name.slice(idx + SETTING_NAME_SEPARATOR.length);
-	const roleIdx = rest.lastIndexOf(SETTING_NAME_SEPARATOR);
-	if (roleIdx === -1) return undefined;
-	const accountId = rest.slice(0, roleIdx);
-	const role = rest.slice(roleIdx + SETTING_NAME_SEPARATOR.length);
-	if (!accountId || !role) return undefined;
-	return { accountId, role };
-};
+export { CANONICAL_ROLES };
 
 const stringValueOf = (item: AccountSettingItem): string | undefined => {
 	const { value } = item;
@@ -78,7 +40,7 @@ export const groupFolderAppointmentsByAccount = (
 ): Map<string, Map<string, string>> => {
 	const byAccount = new Map<string, Map<string, string>>();
 	for (const setting of settings) {
-		const target = parseAppointmentTarget(setting.name);
+		const target = parseFolderRoleAppointmentName(setting.name);
 		if (!target) continue;
 		const mailboxId = stringValueOf(setting);
 		if (mailboxId === undefined) continue;
@@ -103,7 +65,7 @@ export const loadFolderAppointmentsForAccount = async (
 		CANONICAL_ROLES.map(async (role) => {
 			const item = await accountSetting.get(
 				accountConfigId,
-				composeAppointmentName(accountId, role),
+				composeFolderRoleAppointmentName(accountId, role),
 			);
 			return [role, item ? stringValueOf(item) : undefined] as const;
 		}),
@@ -128,7 +90,7 @@ export const writeFolderRoleAppointment = (
 	role: CanonicalMailboxRoleValue,
 	mailboxId: string | null,
 ): Promise<unknown> => {
-	const name = composeAppointmentName(accountId, role);
+	const name = composeFolderRoleAppointmentName(accountId, role);
 	if (mailboxId === null) {
 		return accountSetting.delete(accountConfigId, name);
 	}
@@ -139,110 +101,21 @@ export const writeFolderRoleAppointment = (
 	});
 };
 
-/** The minimal folder shape `findFolderForRole` needs to detect a role. */
-export interface FolderCandidate {
-	mailboxId: string;
-	fullPath: string;
-	specialUse?: readonly string[];
-}
-
-// 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.
-const ROLE_TO_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 (RFC 032's tier 3 of `findFolderForRole`): used solely to
-// seed a PROPOSAL a human confirms, never to persist a role by itself. Kept
-// intentionally small — this is a fallback for providers with no SPECIAL-USE
-// support, not a substitute for server truth.
-const ROLE_NAME_HINTS: Partial<
-	Record<CanonicalMailboxRoleValue, readonly string[]>
-> = {
-	[CanonicalMailboxRole.Drafts]: ["drafts", "draft", "concepten"],
-	[CanonicalMailboxRole.Sent]: [
-		"sent",
-		"sent mail",
-		"sent items",
-		"sent messages",
-	],
-	[CanonicalMailboxRole.Archive]: ["archive", "archives"],
-	[CanonicalMailboxRole.Junk]: ["junk", "spam"],
-	[CanonicalMailboxRole.Trash]: [
-		"trash",
-		"bin",
-		"deleted",
-		"deleted items",
-		"deleted messages",
-	],
-	[CanonicalMailboxRole.All]: ["all mail", "all"],
-};
-
-const leafName = (fullPath: string): string => {
-	const parts = fullPath.split("/");
-	return (parts[parts.length - 1] || fullPath).toLowerCase();
-};
-
-/**
- * The single best EXISTING folder for a canonical role (RFC 032
- * exclusive-folder-appointment): the IMAP SPECIAL-USE flag first (server
- * truth, language-independent), then — for Inbox only — the reserved `INBOX`
- * name (RFC 3501), then a weak name hint used solely to seed a proposal a
- * human confirms. `null` when nothing matches; the role stays unfilled.
- */
-export const findFolderForRole = (
-	role: CanonicalMailboxRoleValue,
-	folders: readonly FolderCandidate[],
-): string | null => {
-	const specialUse = ROLE_TO_SPECIAL_USE[role];
-	if (specialUse) {
-		const flagged = folders.find((f) => f.specialUse?.includes(specialUse));
-		if (flagged) return flagged.mailboxId;
-	}
-
-	if (role === CanonicalMailboxRole.Inbox) {
-		const inbox = folders.find((f) => f.fullPath.toUpperCase() === "INBOX");
-		if (inbox) return inbox.mailboxId;
-	}
-
-	const hints = ROLE_NAME_HINTS[role];
-	if (hints) {
-		const match = folders.find((f) => hints.includes(leafName(f.fullPath)));
-		if (match) return match.mailboxId;
-	}
-
-	return null;
-};
-
 /**
  * Resolve the full appointment set for one account: the user's persisted
  * choice when set (and still a real mailbox — a deleted mailbox's stale
- * appointment is treated as unfilled and re-proposed), else a server-proposed
- * `findFolderForRole` guess. Always returns one entry per `CANONICAL_ROLES`
- * member (RFC 032 settings tiers: total, never a sparse array), so the map is
- * never empty for a normal provider.
+ * appointment is treated as unfilled and re-proposed), else the server's
+ * SPECIAL-USE flag, else a name proposal. Always returns one entry per
+ * `CANONICAL_ROLES` member (RFC 032 settings tiers: total, never a sparse
+ * array), so the map is never empty for a normal provider.
  */
 export const resolveFolderAppointments = (
 	persisted: ReadonlyMap<string, string>,
-	mailboxes: readonly FolderCandidate[],
+	mailboxes: readonly RoleMailboxCandidate[],
 ): FolderAppointment[] =>
 	CANONICAL_ROLES.map((role) => {
-		const persistedId = persisted.get(role);
-		const validPersisted =
-			persistedId && mailboxes.some((m) => m.mailboxId === persistedId)
-				? persistedId
-				: undefined;
-		const mailboxId =
-			validPersisted ?? findFolderForRole(role, mailboxes) ?? undefined;
-		return mailboxId ? { role, mailboxId } : { role };
+		const found = resolveMailboxForRole(role, mailboxes, persisted.get(role));
+		return found ? { role, mailboxId: found.mailboxId } : { role };
 	});
 
 /**

package/src/handlers/mailbox.ts

@@ -5,6 +5,7 @@ import type {
 import type { IAccountSettingRepository, MailboxItem } from "@remit/data-ports";
 import { ForbiddenError, NotFoundError } from "@remit/data-ports/errors";
 import { MailboxSyncStatus, MessageSystemFlag } from "@remit/domain-enums";
+import { NoTrashMailboxError } from "@remit/mailbox-service";
 import type { APIGatewayProxyEvent } from "aws-lambda";
 import { getAccountConfigIdFromEvent } from "../auth.js";
 import {
@@ -411,14 +412,18 @@ export const TrashOperations: Record<
 		const account = await client.account.get(accountId);
 		assertAccountOwnership(account, accountConfigId, "act");
 
+		// The same confirmed resolution `emptyTrash` expunges through, so the
+		// count reported is the count of the folder that gets emptied. It
+		// refuses rather than returning zero when no folder is appointed and
+		// none is flagged: "0 deleted" reads as success, and the user goes on
+		// believing their Trash is empty.
 		const trashMailbox =
-			await client.mailboxSpecialUse.findTrashMailbox(accountId);
+			await client.mailboxSpecialUse.findConfirmedTrashMailbox(accountId);
 
 		if (!trashMailbox) {
-			return { deletedCount: 0 };
+			throw new NoTrashMailboxError();
 		}
 
-		// Get count of messages in trash before emptying
 		const messages = await client.message.listAllByMailbox(
 			trashMailbox.mailboxId,
 		);