@remit/data-ports 0.0.40 → 0.0.42

package/package.json

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

@@ -80,6 +80,24 @@ export class FolderRoleUnresolvedError extends ConflictError {
 	}
 }
 
+/**
+ * A role cannot be appointed to a mailbox the mail server has not settled yet
+ * (imap-mutations R2: wait). Its own code, because the role is not unresolved —
+ * the target is: the client words a wait, not a retry. Clearing a role is never
+ * refused this way.
+ */
+export class MailboxNotSettledError extends ConflictError {
+	name = "MailboxNotSettledError";
+
+	constructor(message: string, mailboxId: string, syncStatus: string) {
+		super(message);
+		this.publicApiError = {
+			code: "mailbox_not_settled",
+			details: { mailboxId, syncStatus },
+		};
+	}
+}
+
 /**
  * A message exists but its body could not be fetched/parsed after every
  * body-sync retry was spent (issue #1270 / epic #1281 invariant 3). This is

package/src/folder-role.test.ts

@@ -1,6 +1,10 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { CanonicalMailboxRole, MailboxSpecialUse } from "@remit/domain-enums";
+import {
+	CanonicalMailboxRole,
+	MailboxSpecialUse,
+	MailboxSyncStatus,
+} from "@remit/domain-enums";
 import {
 	composeFolderRoleAppointmentLabelName,
 	composeFolderRoleAppointmentName,
@@ -173,6 +177,24 @@ describe("resolveConfirmedMailboxForRole", () => {
 });
 
 describe("resolveRoleForAccount", () => {
+	it("resolves an appointment naming a mailbox whose last sync failed", () => {
+		// `failed` has three writers (imap-worker mailbox-management: create :166
+		// rolls nothing back, rename :275 restores oldPath, delete :384 leaves the
+		// folder) and in two the folder is really at the path the row names.
+		const failed: RoleMailboxCandidate & { syncStatus: string } = {
+			...mailbox("mb-trash", "INBOX/Prullenbak"),
+			syncStatus: MailboxSyncStatus.failed,
+		};
+		assert.deepEqual(
+			resolveRoleForAccount(
+				CanonicalMailboxRole.Trash,
+				[mailbox("mb-inbox", "INBOX"), failed],
+				"mb-trash",
+			),
+			{ kind: "appointed", mailbox: failed },
+		);
+	});
+
 	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,

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;