@remit/data-ports 0.0.38 → 0.0.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "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/errors.ts

@@ -1,4 +1,9 @@
-import type { CanonicalMailboxRoleValue } from "./folder-role.js";
+import type {
+	CanonicalMailboxRoleValue,
+	FolderRoleUnresolvedReason,
+} from "./folder-role.js";
+
+export type { FolderRoleUnresolvedReason };
 
 /**
  * The half of an error a client may read: a stable `code` it branches on and
@@ -51,16 +56,6 @@ export class ConflictError extends HTTPError {
 	public statusCode = 409;
 }
 
-/**
- * Why a canonical role names no folder this action may act on. `none`: the
- * account has no candidate at all. `stale`: the folder the user appointed is
- * gone from the server. `unconfirmed`: a folder matches by name, but nobody —
- * neither the user nor the server's own flag — ever said it holds the role.
- * These three and no others; a target that is merely unsettled is a different
- * refusal under its own code.
- */
-export type FolderRoleUnresolvedReason = "none" | "stale" | "unconfirmed";
-
 /**
  * A destructive action refused because the role it needs is unresolved. The
  * client reads `code` and words its prompt from `details` — never from the

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,165 @@ 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("withholds a stale appointment's fallback from the confirmed answer only", () => {
+		// A vanished appointment is not confirmation of anything, so the expunge
+		// gate sees nothing. Filing mail still works: the fallback is a fine place
+		// to put a message the user can move back.
+		assert.equal(
+			resolveConfirmedMailboxForRole(
+				CanonicalMailboxRole.Trash,
+				mailboxes,
+				"mb-gone",
+			),
+			null,
+		);
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Trash, mailboxes, "mb-gone")
+				?.mailboxId,
+			"mb-trash",
+		);
+	});
+
+	it("keeps a stale appointment on the flag, never on a folder named like one", () => {
+		// The confirmed adapter is not built on top of the other one: were it,
+		// null-on-stale would drop the seven non-Trash roles past their
+		// SPECIAL-USE flag and into the name hint, and a folder somebody called
+		// "Sent" would start collecting this account's sent mail.
+		const sent = [
+			mailbox("mb-inbox", "INBOX"),
+			mailbox("mb-sent-copy", "Sent"),
+			mailbox("mb-sent", "[Gmail]/Sent Mail", [MailboxSpecialUse.Sent]),
+		];
+		assert.equal(
+			resolveMailboxForRole(CanonicalMailboxRole.Sent, sent, "mb-gone")
+				?.mailboxId,
+			"mb-sent",
+		);
+	});
+
+	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
@@ -119,44 +150,75 @@ export const FOLDER_ROLES_SETTINGS_PATH = "Settings › Folder roles";
  */
 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 folder somebody chose as this account's Trash is no longer on the mail
+ * server. Reader will not quietly file mail into whatever it would have picked
+ * had nobody chosen: the user's choice went missing and only they can replace
+ * it.
+ */
+export const STALE_TRASH_FOLDER_REASON = `The folder appointed as this account's Trash is no longer on the mail server, so nothing was deleted. Appoint one under ${FOLDER_ROLES_SETTINGS_PATH}, then try again.`;
+
+/**
+ * A folder matches the Trash name hint and nothing else — enough to file a
+ * delete somewhere retrievable, never enough to expunge a whole folder.
+ */
+export const UNCONFIRMED_TRASH_FOLDER_REASON = `Nobody has confirmed which folder is this account's Trash, so it was not emptied. 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.
+ * 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 +235,125 @@ 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";
+
+/**
+ * Why a canonical role names no folder an action may act on. `none`: the
+ * account has no candidate at all. `stale`: the folder the user appointed is
+ * gone from the server. `unconfirmed`: a folder matches by name, but nobody —
+ * neither the user nor the server's own flag — ever said it holds the role.
+ * These three and no others; a target that is merely unsettled is a different
+ * refusal under its own code.
+ */
+export type FolderRoleUnresolvedReason = "none" | "stale" | "unconfirmed";
+
+export type TrashGateOutcome<T> =
+	| { allowed: true; mailbox: T }
+	| { allowed: false; reason: FolderRoleUnresolvedReason };
+
+/**
+ * The Trash folder a verb at this assurance level may act on, or which of the
+ * three reasons stops it. One switch: the delete, the expunge and the count
+ * reported before one all decide here, so no two of them can answer a user
+ * differently about the same account.
+ */
+export const trashMailboxAt = <T>(
+	resolution: RoleResolution<T>,
+	level: TrashAssuranceLevel,
+): TrashGateOutcome<T> => {
+	switch (resolution.kind) {
+		case "appointed":
+		case "flagged":
+			return { allowed: true, mailbox: resolution.mailbox };
+		case "proposed":
+			return level === "resolved"
+				? { allowed: true, mailbox: resolution.mailbox }
+				: { allowed: false, reason: "unconfirmed" };
+		case "appointment_stale":
+			return { allowed: false, reason: "stale" };
+		default:
+			return { allowed: false, reason: "none" };
+	}
+};
+
+export const meetsTrashAssurance = <T>(
+	resolution: RoleResolution<T>,
+	level: TrashAssuranceLevel,
+): boolean => trashMailboxAt(resolution, level).allowed;
+
+/**
+ * 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 answers `null` here
+ * too: the fallback is the folder the user did not choose, which is fine to
+ * file mail into and no basis at all for destroying it.
  */
-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,
-	);
-	if (confirmed) return confirmed;
+	const resolution = resolveRoleForAccount(role, mailboxes, appointedMailboxId);
+	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. A stale appointment answers with its fallback — every role but Trash
+ * files mail on this read, and refusing them all would be a behaviour change
+ * with no surface to explain it.
+ *
+ * Built on `resolveRoleForAccount` directly, never on the confirmed adapter: a
+ * stale appointment must still reach the `\Sent` flag here, not fall past it
+ * into a folder that merely reads like one.
+ */
+export const resolveMailboxForRole = <T extends RoleMailboxCandidate>(
+	role: CanonicalMailboxRoleValue,
+	mailboxes: readonly T[],
+	appointedMailboxId?: string,
+): T | null => {
+	const resolution = resolveRoleForAccount(role, mailboxes, appointedMailboxId);
+	const effective =
+		resolution.kind === "appointment_stale" ? resolution.fallback : resolution;
+	return effective.kind === "none" ? null : effective.mailbox;
 };

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

@@ -1,3 +1,4 @@
+import type { RoleResolution } from "../folder-role.js";
 import type {
 	MailboxSpecialUseItem,
 	MailboxSpecialUseValue,
@@ -31,13 +32,15 @@ export interface IMailboxSpecialUseRepository {
 		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.
+	 * 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.
 	 */
-	findConfirmedTrashMailbox(
+	resolveTrashRole(
 		accountId: string,
-	): Promise<{ mailboxId: string; fullPath: string } | null>;
+	): Promise<RoleResolution<{ mailboxId: string; fullPath: string }>>;
 	findArchiveMailbox(
 		accountId: string,
 	): Promise<{ mailboxId: string; fullPath: string } | null>;