@remit/data-ports 0.0.45 → 0.0.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "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/interfaces/outbox-message.ts

@@ -59,6 +59,25 @@ export interface IOutboxMessageRepository {
 		outboxMessageId: string,
 		status: OutboxMessageItem["status"],
 	): Promise<OutboxMessageItem>;
+	/**
+	 * Write `input` only while the row still holds `expected`, and answer `null`
+	 * when it does not.
+	 *
+	 * Every status transition is a read the caller decided on followed by a
+	 * write, and the SMTP worker or a second request can move the row between
+	 * the two. Naming the status that decision was made against turns the write
+	 * into a compare-and-set: an edit no longer pulls a row back out of `queued`
+	 * while its send event is on the wire, and a settle no longer overwrites a
+	 * status the worker has already reached. `null` is the caller's to read —
+	 * a conflict for an action the user asked for, and nothing to do for a
+	 * settle that has been overtaken.
+	 */
+	updateIfStatus(
+		accountConfigId: string,
+		outboxMessageId: string,
+		expected: OutboxMessageItem["status"],
+		input: UpdateOutboxMessageInput,
+	): Promise<OutboxMessageItem | null>;
 	markSent(
 		accountConfigId: string,
 		outboxMessageId: string,