@remit/data-ports 0.0.44 → 0.0.46

package/package.json

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

package/src/folder-role.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import {
 	CanonicalMailboxRole,
+	FolderAppointmentSource,
 	MailboxSpecialUse,
 	MailboxSyncStatus,
 } from "@remit/domain-enums";
@@ -15,6 +16,7 @@ import {
 	resolveConfirmedMailboxForRole,
 	resolveMailboxForRole,
 	resolveRoleForAccount,
+	trashSourceMeetsAssurance,
 } from "./folder-role.js";
 
 const mailbox = (
@@ -328,6 +330,31 @@ describe("the adapters over resolveRoleForAccount", () => {
 	});
 });
 
+describe("trashSourceMeetsAssurance", () => {
+	it("confirms the user's appointment and the server's flag, and nothing else", () => {
+		// The set a client may word an expunge from. `Reserved` reads as
+		// designated and is not: it is the INBOX name rule, which nobody chose.
+		const confirmed = Object.values(FolderAppointmentSource).filter((source) =>
+			trashSourceMeetsAssurance(source, "confirmed"),
+		);
+		assert.deepEqual(confirmed, [
+			FolderAppointmentSource.Appointed,
+			FolderAppointmentSource.Flagged,
+		]);
+	});
+
+	it("adds the name guess at `resolved`, where a wrong guess only misfiles", () => {
+		const resolved = Object.values(FolderAppointmentSource).filter((source) =>
+			trashSourceMeetsAssurance(source, "resolved"),
+		);
+		assert.deepEqual(resolved, [
+			FolderAppointmentSource.Appointed,
+			FolderAppointmentSource.Flagged,
+			FolderAppointmentSource.Proposed,
+		]);
+	});
+});
+
 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

package/src/folder-role.ts

@@ -1,6 +1,7 @@
 import {
 	AccountSettingName,
 	CanonicalMailboxRole,
+	FolderAppointmentSource,
 	MailboxSpecialUse,
 } from "@remit/domain-enums";
 import {
@@ -160,9 +161,12 @@ export const STALE_TRASH_FOLDER_REASON = `The folder appointed as this account's
 
 /**
  * A folder matches the Trash name hint and nothing else — enough to file a
- * delete somewhere retrievable, never enough to expunge a whole folder.
+ * delete somewhere retrievable, never enough to erase what is already in it.
+ * Emptying that folder and deleting a message already inside it both land here
+ * (#876), so the sentence names neither verb: "nothing was deleted" is true of
+ * both, the way its two siblings above are.
  */
-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.`;
+export const UNCONFIRMED_TRASH_FOLDER_REASON = `Nobody has confirmed which folder is this account's Trash, so nothing was deleted. Appoint one under ${FOLDER_ROLES_SETTINGS_PATH}, then try again.`;
 
 /** The minimal mailbox shape role resolution reads. */
 export interface RoleMailboxCandidate extends MailboxNameCandidate {
@@ -307,6 +311,40 @@ export const meetsTrashAssurance = <T>(
 	level: TrashAssuranceLevel,
 ): boolean => trashMailboxAt(resolution, level).allowed;
 
+export type FolderAppointmentSourceValue =
+	(typeof FolderAppointmentSource)[keyof typeof FolderAppointmentSource];
+
+/** The resolution each reported source came from (`toFolderAppointment`). */
+const RESOLUTION_FOR_SOURCE: Record<
+	FolderAppointmentSourceValue,
+	RoleResolution<null>
+> = {
+	[FolderAppointmentSource.Appointed]: { kind: "appointed", mailbox: null },
+	[FolderAppointmentSource.Flagged]: { kind: "flagged", mailbox: null },
+	[FolderAppointmentSource.Reserved]: { kind: "reserved", mailbox: null },
+	[FolderAppointmentSource.Proposed]: { kind: "proposed", mailbox: null },
+	[FolderAppointmentSource.Stale]: {
+		kind: "appointment_stale",
+		appointedMailboxId: "",
+		fallback: { kind: "none" },
+	},
+	[FolderAppointmentSource.None]: { kind: "none" },
+};
+
+/**
+ * The same gate as {@link trashMailboxAt}, asked of the source `/config`
+ * reports rather than of the resolution the server computed — so a client can
+ * word a delete from the answer the service will give it.
+ *
+ * It runs that switch rather than restating it. A hand-written mirror gets
+ * `Reserved` wrong: it reads as designated, and the gate accepts only the user's
+ * appointment and the server's flag.
+ */
+export const trashSourceMeetsAssurance = (
+	source: FolderAppointmentSourceValue,
+	level: TrashAssuranceLevel,
+): boolean => meetsTrashAssurance(RESOLUTION_FOR_SOURCE[source], level);
+
 /**
  * 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

package/src/id.test.ts

@@ -1,10 +1,19 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import {
+	base36uuidv5,
+	deriveAddressId,
+	deriveBodyPartId,
 	deriveCopyMessageId,
+	deriveEnvelopeId,
 	deriveMessageId,
+	deriveMessageIdFromSource,
 	deriveQuarantineId,
+	deriveThreadId,
+	normalizeMessageIdHeader,
 	quarantineMessageIdHash,
+	REMIT_NAMESPACE,
+	ROOT_PART_PATH,
 } from "./id.js";
 
 const ACCOUNT = "acct-1";
@@ -90,3 +99,97 @@ describe("quarantineMessageIdHash", () => {
 		}
 	});
 });
+
+describe("derived ids are stored primary keys: a changed value orphans every row already written and needs a migration, never a new expectation here", () => {
+	const ACCOUNT = "account-golden";
+	const MESSAGE = "message-golden";
+	const MAILBOX = "mailbox-golden";
+	const ABSENT_HEADER_SOURCE = {
+		messageId: undefined,
+		mailboxId: MAILBOX,
+		uid: 40217,
+		date: "2026-08-23T00:00:00Z",
+		subject: "Golden",
+		fromMailbox: "golden",
+		fromHost: "example.com",
+	};
+
+	it("REMIT_NAMESPACE is the seed of every derived id and can never change", () => {
+		assert.equal(REMIT_NAMESPACE, "9e89694d-214b-4d9b-99f5-214b4d9b99f5");
+	});
+
+	it("base36uuidv5 pins the encoding every derivation below is built on", () => {
+		assert.equal(
+			base36uuidv5("golden-seed", REMIT_NAMESPACE),
+			"67hxxs95ofdk5frbprqyrgwmo",
+		);
+	});
+
+	it("deriveAddressId pins the address primary key, lowercased email included", () => {
+		assert.equal(
+			deriveAddressId(ACCOUNT, "Golden.User@Example.COM"),
+			"dzu01kz6aj1ro8fr8l375tfbr",
+		);
+	});
+
+	it("deriveMessageId pins the message primary key", () => {
+		assert.equal(
+			deriveMessageId(ACCOUNT, "<golden@example.com>"),
+			"bfthbm5n4279aacb5a1q1c94h",
+		);
+	});
+
+	it("normalizeMessageIdHeader pins the synthetic header that seeds a Message-ID-less message", () => {
+		assert.equal(
+			normalizeMessageIdHeader(ABSENT_HEADER_SOURCE),
+			"generated:mailbox-golden:40217:2026-08-23T00:00:00Z:Golden:golden:example.com",
+		);
+	});
+
+	it("deriveMessageIdFromSource pins the key of a message that declared no Message-ID", () => {
+		assert.equal(
+			deriveMessageIdFromSource(ACCOUNT, ABSENT_HEADER_SOURCE),
+			"0rae70onzy4ufhlnndqe7lwml",
+		);
+	});
+
+	it("deriveCopyMessageId pins the key of a message copied into another folder", () => {
+		assert.equal(
+			deriveCopyMessageId(MESSAGE, MAILBOX),
+			"43cwqvpfh4o1fcbmaciabmqo3",
+		);
+	});
+
+	it("deriveThreadId pins the thread primary key, lowercased root header included", () => {
+		assert.equal(
+			deriveThreadId(ACCOUNT, "<Golden.Root@Example.COM>"),
+			"bcy76e2uat5yq3xd1p7j7z4pr",
+		);
+	});
+
+	it("deriveEnvelopeId pins the envelope primary key", () => {
+		assert.equal(deriveEnvelopeId(MESSAGE), "f1bngysevoxuqt625rd5hvtzt");
+	});
+
+	it("ROOT_PART_PATH is baked into stored body part keys and S3 keys", () => {
+		assert.equal(ROOT_PART_PATH, "0");
+	});
+
+	it("deriveBodyPartId pins the body_part primary key", () => {
+		assert.equal(deriveBodyPartId(MESSAGE, "1.2"), "363nl1jzgh77ki2ojk1hqvxxe");
+	});
+
+	it("deriveQuarantineId pins the quarantine primary key", () => {
+		assert.equal(
+			deriveQuarantineId(ACCOUNT, MAILBOX, 1_700_000_000, 40217),
+			"4xg2y7x2j7nmvy0wtwgdq8b8p",
+		);
+	});
+
+	it("quarantineMessageIdHash pins the stored Message-ID hash that correlates reports", () => {
+		assert.equal(
+			quarantineMessageIdHash("<golden@example.com>"),
+			"sha256:5e888fd63760269e96a61e1a09b83ddec28556d0e3cda7e480897e58c8e6a2f5",
+		);
+	});
+});