@remit/data-ports 0.0.38 → 0.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/account-settings.ts

@@ -70,6 +70,7 @@ export const accountSettingRegistry = {
 	[AccountSettingName.MailboxDisplayName]: StringSettingSchema,
 	[AccountSettingName.MailboxMuted]: MutedFlagSettingSchema,
 	[AccountSettingName.FolderRoleAppointment]: StringSettingSchema,
+	[AccountSettingName.FolderRoleAppointmentLabel]: StringSettingSchema,
 	/**
 	 * Deprecated tombstone: superseded by `FolderRoleAppointment` (RFC 032
 	 * exclusive-folder-appointment, #976). Kept only so `baseSettingName`

package/src/folder-role.test.ts

@@ -2,9 +2,15 @@ import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import { CanonicalMailboxRole, MailboxSpecialUse } from "@remit/domain-enums";
 import {
+	composeFolderRoleAppointmentLabelName,
+	composeFolderRoleAppointmentName,
+	meetsTrashAssurance,
+	parseFolderRoleAppointmentLabelName,
+	parseFolderRoleAppointmentName,
 	type RoleMailboxCandidate,
 	resolveConfirmedMailboxForRole,
 	resolveMailboxForRole,
+	resolveRoleForAccount,
 } from "./folder-role.js";
 
 const mailbox = (
@@ -165,3 +171,148 @@ describe("resolveConfirmedMailboxForRole", () => {
 		);
 	});
 });
+
+describe("resolveRoleForAccount", () => {
+	it("answers none when nothing names a Trash folder", () => {
+		// #887 Done item 4: an account whose folders happen to include a Dutch
+		// "Prullenbak" has no Trash reader may act on — no flag, no appointment,
+		// and "prullenbak" is not a hint.
+		const mailboxes = [
+			mailbox("mb-inbox", "INBOX"),
+			mailbox("mb-werk", "Werk"),
+			mailbox("mb-prullenbak", "Prullenbak"),
+		];
+		assert.deepEqual(
+			resolveRoleForAccount(CanonicalMailboxRole.Trash, mailboxes),
+			{ kind: "none" },
+		);
+	});
+
+	it("proposes a folder named Trash, and that is not enough to empty it", () => {
+		// #887 Done item 1: the name is a guess. It files a delete somewhere
+		// retrievable; it never authorises an expunge.
+		const mailboxes = [
+			mailbox("mb-inbox", "INBOX"),
+			mailbox("mb-werk", "Werk"),
+			mailbox("mb-trash", "Trash"),
+		];
+		const resolution = resolveRoleForAccount(
+			CanonicalMailboxRole.Trash,
+			mailboxes,
+		);
+		assert.deepEqual(resolution, {
+			kind: "proposed",
+			mailbox: mailboxes[2],
+		});
+		assert.equal(meetsTrashAssurance(resolution, "confirmed"), false);
+		assert.equal(meetsTrashAssurance(resolution, "resolved"), true);
+	});
+
+	it("names the appointment that went stale, and what took its place", () => {
+		const mailboxes = [
+			mailbox("mb-inbox", "INBOX"),
+			mailbox("mb-trash", "[Gmail]/Trash", [MailboxSpecialUse.Trash]),
+		];
+		const resolution = resolveRoleForAccount(
+			CanonicalMailboxRole.Trash,
+			mailboxes,
+			"mb-rubbish-deleted-by-apple-mail",
+		);
+		assert.deepEqual(resolution, {
+			kind: "appointment_stale",
+			appointedMailboxId: "mb-rubbish-deleted-by-apple-mail",
+			fallback: { kind: "flagged", mailbox: mailboxes[1] },
+		});
+		assert.equal(meetsTrashAssurance(resolution, "confirmed"), false);
+		assert.equal(meetsTrashAssurance(resolution, "resolved"), false);
+	});
+
+	it("tags the appointment the user made and the flag the server set apart", () => {
+		const mailboxes = [
+			mailbox("mb-inbox", "INBOX"),
+			mailbox("mb-trash", "[Gmail]/Trash", [MailboxSpecialUse.Trash]),
+		];
+		assert.equal(
+			resolveRoleForAccount(CanonicalMailboxRole.Trash, mailboxes).kind,
+			"flagged",
+		);
+		assert.equal(
+			resolveRoleForAccount(CanonicalMailboxRole.Trash, mailboxes, "mb-inbox")
+				.kind,
+			"appointed",
+		);
+		assert.equal(
+			resolveRoleForAccount(CanonicalMailboxRole.Inbox, mailboxes).kind,
+			"reserved",
+		);
+	});
+});
+
+describe("the adapters over resolveRoleForAccount", () => {
+	const mailboxes = [
+		mailbox("mb-inbox", "INBOX"),
+		mailbox("mb-trash", "[Gmail]/Trash", [MailboxSpecialUse.Trash]),
+	];
+
+	it("still hands a stale appointment the flagged mailbox", () => {
+		// The refusal that makes this return null lands with the surface that can
+		// tell the user why (S3). Until then, both adapters answer exactly as they
+		// did before the union existed.
+		assert.equal(
+			resolveConfirmedMailboxForRole(
+				CanonicalMailboxRole.Trash,
+				mailboxes,
+				"mb-gone",
+			)?.mailboxId,
+			"mb-trash",
+		);
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Trash, mailboxes, "mb-gone")
+				?.mailboxId,
+			"mb-trash",
+		);
+	});
+
+	it("keeps the name guess out of the confirmed answer", () => {
+		const unflagged = [
+			mailbox("mb-inbox", "INBOX"),
+			mailbox("mb-bak", "Trash"),
+		];
+		assert.equal(
+			resolveConfirmedMailboxForRole(CanonicalMailboxRole.Trash, unflagged),
+			null,
+		);
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Trash, unflagged)?.mailboxId,
+			"mb-bak",
+		);
+	});
+});
+
+describe("the appointment name and its label sibling", () => {
+	it("never lets the label row parse as an appointment", () => {
+		// The label is display only. If the appointment parser matched it, a path
+		// string would be read back as a mailboxId and resolution would follow it.
+		const label = composeFolderRoleAppointmentLabelName(
+			"acc-1",
+			CanonicalMailboxRole.Trash,
+		);
+		assert.equal(parseFolderRoleAppointmentName(label), undefined);
+		assert.deepEqual(parseFolderRoleAppointmentLabelName(label), {
+			accountId: "acc-1",
+			role: CanonicalMailboxRole.Trash,
+		});
+	});
+
+	it("never lets an appointment row parse as a label", () => {
+		const appointment = composeFolderRoleAppointmentName(
+			"acc-1",
+			CanonicalMailboxRole.Trash,
+		);
+		assert.equal(parseFolderRoleAppointmentLabelName(appointment), undefined);
+		assert.deepEqual(parseFolderRoleAppointmentName(appointment), {
+			accountId: "acc-1",
+			role: CanonicalMailboxRole.Trash,
+		});
+	});
+});

package/src/folder-role.ts

@@ -4,6 +4,7 @@ import {
 	MailboxSpecialUse,
 } from "@remit/domain-enums";
 import {
+	type AccountSettingNameValue,
 	composeSettingName,
 	SETTING_NAME_SEPARATOR,
 } from "./account-settings.js";
@@ -37,22 +38,52 @@ export const composeFolderRoleAppointmentName = (
 	);
 
 /**
- * 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`.
+ * The stored `AccountSetting` name holding the path one role's appointed
+ * mailbox had at the moment it was appointed. A sibling row rather than a field
+ * on the appointment, so "never read by resolution" is structural: the
+ * repository composes only the appointment name and cannot reach this one.
  */
-export const parseFolderRoleAppointmentName = (
+export const composeFolderRoleAppointmentLabelName = (
+	accountId: string,
+	role: CanonicalMailboxRoleValue,
+): string =>
+	composeSettingName(
+		AccountSettingName.FolderRoleAppointmentLabel,
+		`${accountId}${SETTING_NAME_SEPARATOR}${role}`,
+	);
+
+const parseFolderRoleTarget = (
+	base: AccountSettingNameValue,
 	name: string,
 ): { accountId: string; role: CanonicalMailboxRoleValue } | undefined => {
-	const [base, ...rest] = name.split(SETTING_NAME_SEPARATOR);
-	if (base !== AccountSettingName.FolderRoleAppointment) return undefined;
+	const [candidate, ...rest] = name.split(SETTING_NAME_SEPARATOR);
+	if (candidate !== base) 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 };
 };
 
+/**
+ * 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 =>
+	parseFolderRoleTarget(AccountSettingName.FolderRoleAppointment, name);
+
+/**
+ * The label row's counterpart, so the config-wide settings batch can recover
+ * the recorded path for a role the same way it recovers the appointment.
+ */
+export const parseFolderRoleAppointmentLabelName = (
+	name: string,
+): { accountId: string; role: CanonicalMailboxRoleValue } | undefined =>
+	parseFolderRoleTarget(AccountSettingName.FolderRoleAppointmentLabel, name);
+
 /**
  * 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
@@ -125,38 +156,55 @@ export interface RoleMailboxCandidate extends MailboxNameCandidate {
 }
 
 /**
- * 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.
+ * What an account with no appointment for the role resolves to, and equally
+ * what a stale appointment falls back to — the fallback can never itself be an
+ * appointment, stale or otherwise.
+ */
+export type UnappointedRoleResolution<T> =
+	| { kind: "flagged"; mailbox: T }
+	| { kind: "reserved"; mailbox: T }
+	| { kind: "proposed"; mailbox: T }
+	| { kind: "none" };
+
+/**
+ * What resolving a role for an account answered, and on what evidence. Total:
+ * there is a member for every outcome, so a caller that must weigh the evidence
+ * — Empty Trash may only expunge what somebody designated — reads the tag
+ * instead of inferring it from a `null` that means four different things.
  *
- * 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.
+ * `appointment_stale` is the case a nullable answer cannot express: the user
+ * appointed a mailbox the account no longer holds. It carries the id they chose
+ * so a surface can offer the repair, and the resolution that would have applied
+ * had they appointed nothing.
  */
-export const resolveConfirmedMailboxForRole = <T extends RoleMailboxCandidate>(
+export type RoleResolution<T> =
+	| { kind: "appointed"; mailbox: T }
+	| UnappointedRoleResolution<T>
+	| {
+			kind: "appointment_stale";
+			appointedMailboxId: string;
+			fallback: UnappointedRoleResolution<T>;
+	  };
+
+const resolveWithoutAppointment = <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;
-	}
-
+): UnappointedRoleResolution<T> => {
 	const specialUse = ROLE_SPECIAL_USE[role];
 	if (specialUse) {
 		const flagged = mailboxes.find((m) => m.specialUse?.includes(specialUse));
-		if (flagged) return flagged;
+		if (flagged) return { kind: "flagged", mailbox: flagged };
 	}
 
 	if (role === CanonicalMailboxRole.Inbox) {
-		return mailboxes.find((m) => m.fullPath.toUpperCase() === "INBOX") ?? null;
+		const inbox = mailboxes.find((m) => m.fullPath.toUpperCase() === "INBOX");
+		return inbox ? { kind: "reserved", mailbox: inbox } : { kind: "none" };
 	}
 
-	return null;
+	const hints = ROLE_NAME_HINTS[role];
+	if (!hints) return { kind: "none" };
+	const proposed = resolveMailboxByLeafName(mailboxes, hints);
+	return proposed ? { kind: "proposed", mailbox: proposed } : { kind: "none" };
 };
 
 /**
@@ -173,23 +221,96 @@ export const resolveConfirmedMailboxForRole = <T extends RoleMailboxCandidate>(
  * 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.
+ */
+export const resolveRoleForAccount = <T extends RoleMailboxCandidate>(
+	role: CanonicalMailboxRoleValue,
+	mailboxes: readonly T[],
+	appointedMailboxId?: string,
+): RoleResolution<T> => {
+	if (!appointedMailboxId) return resolveWithoutAppointment(role, mailboxes);
+
+	const appointed = mailboxes.find((m) => m.mailboxId === appointedMailboxId);
+	if (appointed) return { kind: "appointed", mailbox: appointed };
+
+	return {
+		kind: "appointment_stale",
+		appointedMailboxId,
+		fallback: resolveWithoutAppointment(role, mailboxes),
+	};
+};
+
+/**
+ * How much evidence a Trash verb demands. `confirmed` is what an expunge
+ * requires: somebody designated this folder, either the user or the server.
+ * `resolved` additionally accepts the name guess, for filing mail somewhere the
+ * user can retrieve it from. Trash only, deliberately — no other role and no
+ * other verb weighs its evidence, and a matrix over eight roles would be five
+ * gates nobody asked for.
+ */
+export type TrashAssuranceLevel = "confirmed" | "resolved";
+
+export const meetsTrashAssurance = <T>(
+	resolution: RoleResolution<T>,
+	level: TrashAssuranceLevel,
+): boolean => {
+	switch (resolution.kind) {
+		case "appointed":
+		case "flagged":
+			return true;
+		case "proposed":
+			return level === "resolved";
+		default:
+			return false;
+	}
+};
+
+const withoutStale = <T>(
+	resolution: RoleResolution<T>,
+): { kind: "appointed"; mailbox: T } | UnappointedRoleResolution<T> =>
+	resolution.kind === "appointment_stale" ? resolution.fallback : resolution;
+
+/**
+ * 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.
  *
- * `null` when nothing matches: the role has no folder, and the caller says so
- * rather than picking one.
+ * 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 resolveMailboxForRole = <T extends RoleMailboxCandidate>(
+export const resolveConfirmedMailboxForRole = <T extends RoleMailboxCandidate>(
 	role: CanonicalMailboxRoleValue,
 	mailboxes: readonly T[],
 	appointedMailboxId?: string,
 ): T | null => {
-	const confirmed = resolveConfirmedMailboxForRole(
-		role,
-		mailboxes,
-		appointedMailboxId,
+	const resolution = withoutStale(
+		resolveRoleForAccount(role, mailboxes, appointedMailboxId),
 	);
-	if (confirmed) return confirmed;
+	switch (resolution.kind) {
+		case "appointed":
+		case "flagged":
+		case "reserved":
+			return resolution.mailbox;
+		default:
+			return null;
+	}
+};
 
-	const hints = ROLE_NAME_HINTS[role];
-	if (!hints) return null;
-	return resolveMailboxByLeafName(mailboxes, hints);
+/**
+ * The role's mailbox including the name guess: `null` only when nothing
+ * matches at all, so the caller says the role has no folder rather than picking
+ * one.
+ */
+export const resolveMailboxForRole = <T extends RoleMailboxCandidate>(
+	role: CanonicalMailboxRoleValue,
+	mailboxes: readonly T[],
+	appointedMailboxId?: string,
+): T | null => {
+	const resolution = withoutStale(
+		resolveRoleForAccount(role, mailboxes, appointedMailboxId),
+	);
+	return resolution.kind === "none" ? null : resolution.mailbox;
 };

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

@@ -1,3 +1,4 @@
+import type { RoleResolution } from "../folder-role.js";
 import type {
 	MailboxSpecialUseItem,
 	MailboxSpecialUseValue,
@@ -38,6 +39,16 @@ export interface IMailboxSpecialUseRepository {
 	findConfirmedTrashMailbox(
 		accountId: string,
 	): Promise<{ mailboxId: string; fullPath: string } | null>;
+	/**
+	 * Trash with the evidence attached, for the two verbs that weigh it: a
+	 * delete files mail somewhere retrievable, an Empty Trash destroys it, and
+	 * they refuse on different grounds. `null` cannot tell them apart — an
+	 * appointment naming a folder that is gone is a different answer from no
+	 * folder at all, and only this read distinguishes them.
+	 */
+	resolveTrashRole(
+		accountId: string,
+	): Promise<RoleResolution<{ mailboxId: string; fullPath: string }>>;
 	findArchiveMailbox(
 		accountId: string,
 	): Promise<{ mailboxId: string; fullPath: string } | null>;