@remit/data-ports 0.0.9 → 0.0.11

package/package.json

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

package/src/id.test.ts

@@ -1,6 +1,11 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { deriveQuarantineId, quarantineMessageIdHash } from "./id.js";
+import {
+	deriveCopyMessageId,
+	deriveMessageId,
+	deriveQuarantineId,
+	quarantineMessageIdHash,
+} from "./id.js";
 
 const ACCOUNT = "acct-1";
 const MAILBOX = "mbx-1";
@@ -30,6 +35,38 @@ describe("deriveQuarantineId", () => {
 	});
 });
 
+describe("deriveCopyMessageId", () => {
+	const SOURCE = deriveMessageId(ACCOUNT, "<abc@example.com>");
+	const DEST = "mbx-archive";
+
+	it("is stable for the same source and destination (idempotent copy)", () => {
+		assert.equal(
+			deriveCopyMessageId(SOURCE, DEST),
+			deriveCopyMessageId(SOURCE, DEST),
+		);
+	});
+
+	it("separates a copy of one mail into two folders", () => {
+		assert.notEqual(
+			deriveCopyMessageId(SOURCE, DEST),
+			deriveCopyMessageId(SOURCE, "mbx-other"),
+		);
+	});
+
+	it("separates copies of two different mails into one folder", () => {
+		assert.notEqual(
+			deriveCopyMessageId(SOURCE, DEST),
+			deriveCopyMessageId(deriveMessageId(ACCOUNT, "<xyz@example.com>"), DEST),
+		);
+	});
+
+	it("never equals the folder-independent id sync derives", () => {
+		// Sync keys a message on deriveMessageId; the copy id folds in the
+		// destination mailbox, so the two can never collide.
+		assert.notEqual(deriveCopyMessageId(SOURCE, DEST), SOURCE);
+	});
+});
+
 describe("quarantineMessageIdHash", () => {
 	it("hashes a real Message-ID to a pinned sha256 value", () => {
 		const hash = quarantineMessageIdHash("<abc@example.com>");

package/src/id.ts

@@ -73,6 +73,29 @@ export const deriveMessageIdFromSource = (
 	source: MessageIdSource,
 ): string => deriveMessageId(accountId, normalizeMessageIdHeader(source));
 
+/**
+ * Identity of a message copied into another folder (issue #75). Derived from
+ * the source message and the destination mailbox so a copy is deterministic:
+ * copying the same mail into the same folder twice — a replayed COPY event or a
+ * repeated user copy — resolves to one row instead of a fresh unreachable
+ * duplicate each time. A random id, which is what the copy path used before,
+ * gave every attempt a new identity that no later sync or delete could reach.
+ *
+ * The destination mailbox is part of the name so a copy of one mail into two
+ * folders is two rows, one per folder. It also keeps this id out of the space
+ * sync assigns: sync keys a message on `deriveMessageId(accountId,
+ * messageIdHeader)`, which is folder-independent, so the copy row can never
+ * collide with, or be overwritten by, the canonical synced row.
+ */
+export const deriveCopyMessageId = (
+	sourceMessageId: string,
+	destinationMailboxId: string,
+): string =>
+	base36uuidv5(
+		`messagecopy:${sourceMessageId}:${destinationMailboxId}`,
+		REMIT_NAMESPACE,
+	);
+
 export const deriveThreadId = (
 	accountId: string,
 	rootMessageIdHeader: string,

package/src/index.ts

@@ -83,6 +83,7 @@ export type {
 	PutMessagePlacementMoveInput,
 	QuarantineItem,
 	QuarantineMimeNodeItem,
+	QuarantineUpsertInput,
 	RawMessageStorageItem,
 	ResultList,
 	SearchOptions,

package/src/interfaces/quarantine.ts

@@ -1,4 +1,4 @@
-import type { QuarantineItem } from "../types.js";
+import type { QuarantineItem, QuarantineUpsertInput } from "../types.js";
 
 export interface IQuarantineRepository {
 	/**
@@ -7,4 +7,16 @@ export interface IQuarantineRepository {
 	 * surface and by a sync round that keeps it in memory.
 	 */
 	listByAccountConfigId(accountConfigId: string): Promise<QuarantineItem[]>;
+
+	/**
+	 * Record a message the sync path could not apply.
+	 *
+	 * Idempotent on the message's identity: the row is keyed by an id derived
+	 * from (accountId, mailboxId, uidValidity, uid), so quarantining the same
+	 * message twice rewrites one row instead of accumulating. The derivation
+	 * happens here rather than at the call site — see `QuarantineUpsertInput`.
+	 *
+	 * A cursor may only move past a message once this has resolved.
+	 */
+	upsert(input: QuarantineUpsertInput): Promise<void>;
 }

package/src/types.ts

@@ -89,6 +89,21 @@ export type MessageFlagPushItem = z.infer<typeof MessageFlagPushSchema>;
 export type QuarantineItem = z.infer<typeof QuarantineSchema>;
 export type QuarantineMimeNodeItem = QuarantineItem["structure"][number];
 
+/**
+ * What a caller supplies to quarantine a message.
+ *
+ * `quarantineId` is absent on purpose. The column carries a random-id default
+ * (the house pattern for every entity here), so an input that merely allowed
+ * the id would let a writer omit it, take a fresh random one on every retry,
+ * and turn the idempotent write this record depends on into an accumulating
+ * pile of rows that the derived-id lookup never finds. The repository derives
+ * it from the four fields that name the message, which are all required here.
+ */
+export type QuarantineUpsertInput = Omit<
+	QuarantineItem,
+	"quarantineId" | "createdAt" | "updatedAt" | "structure"
+> & { structure?: QuarantineMimeNodeItem[] };
+
 export type MailboxSpecialUseValue = z.infer<typeof MailboxSpecialUseSchema>;
 
 export type AccountSettingValue =