@remit/data-ports 0.0.39 → 0.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -37,6 +37,10 @@
       "types": "./src/folder-role.ts",
       "default": "./src/folder-role.ts"
     },
+    "./mutation-events": {
+      "types": "./src/mutation-events.ts",
+      "default": "./src/mutation-events.ts"
+    },
     "./mailbox-name": {
       "types": "./src/mailbox-name.ts",
       "default": "./src/mailbox-name.ts"

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

@@ -254,17 +254,17 @@ describe("the adapters over resolveRoleForAccount", () => {
 		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.
+	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",
-			)?.mailboxId,
-			"mb-trash",
+			),
+			null,
 		);
 		assert.equal(
 			resolveMailboxForRole(CanonicalMailboxRole.Trash, mailboxes, "mb-gone")
@@ -273,6 +273,23 @@ describe("the adapters over resolveRoleForAccount", () => {
 		);
 	});
 
+	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"),

package/src/folder-role.ts

@@ -150,6 +150,20 @@ 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[];
@@ -249,25 +263,49 @@ export const resolveRoleForAccount = <T extends RoleMailboxCandidate>(
  */
 export type TrashAssuranceLevel = "confirmed" | "resolved";
 
-export const meetsTrashAssurance = <T>(
+/**
+ * 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,
-): boolean => {
+): TrashGateOutcome<T> => {
 	switch (resolution.kind) {
 		case "appointed":
 		case "flagged":
-			return true;
+			return { allowed: true, mailbox: resolution.mailbox };
 		case "proposed":
-			return level === "resolved";
+			return level === "resolved"
+				? { allowed: true, mailbox: resolution.mailbox }
+				: { allowed: false, reason: "unconfirmed" };
+		case "appointment_stale":
+			return { allowed: false, reason: "stale" };
 		default:
-			return false;
+			return { allowed: false, reason: "none" };
 	}
 };
 
-const withoutStale = <T>(
+export const meetsTrashAssurance = <T>(
 	resolution: RoleResolution<T>,
-): { kind: "appointed"; mailbox: T } | UnappointedRoleResolution<T> =>
-	resolution.kind === "appointment_stale" ? resolution.fallback : resolution;
+	level: TrashAssuranceLevel,
+): boolean => trashMailboxAt(resolution, level).allowed;
 
 /**
  * The mailbox a role is CONFIRMED to hold: the one the user appointed, or the
@@ -278,17 +316,16 @@ const withoutStale = <T>(
  * 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.
+ * 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 resolveConfirmedMailboxForRole = <T extends RoleMailboxCandidate>(
 	role: CanonicalMailboxRoleValue,
 	mailboxes: readonly T[],
 	appointedMailboxId?: string,
 ): T | null => {
-	const resolution = withoutStale(
-		resolveRoleForAccount(role, mailboxes, appointedMailboxId),
-	);
+	const resolution = resolveRoleForAccount(role, mailboxes, appointedMailboxId);
 	switch (resolution.kind) {
 		case "appointed":
 		case "flagged":
@@ -302,15 +339,21 @@ export const resolveConfirmedMailboxForRole = <T extends RoleMailboxCandidate>(
 /**
  * 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.
+ * 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 = withoutStale(
-		resolveRoleForAccount(role, mailboxes, appointedMailboxId),
-	);
-	return resolution.kind === "none" ? null : resolution.mailbox;
+	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

@@ -31,14 +31,6 @@ export interface IMailboxSpecialUseRepository {
 	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>;
 	/**
 	 * Trash with the evidence attached, for the two verbs that weigh it: a
 	 * delete files mail somewhere retrievable, an Empty Trash destroys it, and

package/src/mutation-events.ts

@@ -0,0 +1,20 @@
+/**
+ * The contract version the mail-destroying queue events are minted under.
+ *
+ * It lives here because the producer (`MessageMoveService`) and the consumer
+ * (the imap-worker's handlers) sit in packages that cannot import each other,
+ * and a version the two sides disagree about is worse than no version at all.
+ * Bump it whenever a handler starts relying on a field an older producer never
+ * set.
+ */
+export const MUTATION_EVENT_SCHEMA_VERSION = 2;
+
+/**
+ * Queue payloads are `JSON.parse`d and cast with no validation, so the declared
+ * type is a promise the queue cannot keep. A handler that cannot vouch for an
+ * event's shape abandons it — treating a missing field as "skip the check"
+ * makes the unverified expunge the default for every event we cannot vouch for,
+ * including any future producer that forgets the field.
+ */
+export const isCurrentSchemaVersion = (value: unknown): boolean =>
+	value === MUTATION_EVENT_SCHEMA_VERSION;