@remit/mailbox-service 0.0.111 → 0.0.113

package/src/spam-report.ts

@@ -1,357 +0,0 @@
-import type {
-	IAccountRepository,
-	IAddressRepository,
-	IMailboxSpecialUseRepository,
-	IMessageRepository,
-} from "@remit/data-ports";
-import { deriveAddressId } from "@remit/data-ports/id";
-import { AddressRole, MessageKeywordFlag } from "@remit/domain-enums";
-import type { FlagPushService } from "./flag-push.js";
-import type { MessageMoveService } from "./message-move.js";
-import {
-	isPlacementUnsettled,
-	waitForPlacementToSettle,
-} from "./placement-settled.js";
-
-export interface SpamReportLogger {
-	info(obj: Record<string, unknown>, msg: string): void;
-	error(obj: Record<string, unknown>, msg: string): void;
-}
-
-/**
- * The one designed, user-facing outcome of `notSpam`'s R2 wait timing out —
- * distinct from any other failure so a caller surfacing failures to the user
- * (the bulk handlers in packages/backend) can allowlist this specific,
- * pre-written message instead of relaying an arbitrary thrown error's text.
- */
-export class MoveNotSettledError extends Error {
-	constructor(messageId: string) {
-		super(
-			`Message ${messageId}'s move to Junk has not settled yet; try again in a moment.`,
-		);
-		this.name = "MoveNotSettledError";
-	}
-}
-
-/**
- * The account advertises no Junk folder and has none under any conventional
- * name, so there is nowhere to file the report. A designed, user-facing
- * outcome — the user has to create the folder, and no amount of retrying
- * changes that — so it carries its own text through the bulk handler's
- * allowlist rather than being flattened to the generic retry copy.
- */
-export class NoJunkMailboxError extends Error {
-	constructor() {
-		super(
-			"This account has no Junk folder. Create one named Junk or Spam in your mail provider, then report this message again.",
-		);
-		this.name = "NoJunkMailboxError";
-	}
-}
-
-const noopLogger: SpamReportLogger = {
-	info: () => {},
-	error: () => {},
-};
-
-const DEFAULT_MOVE_SETTLE_TIMEOUT_MS = 5_000;
-const DEFAULT_MOVE_SETTLE_POLL_MS = 250;
-
-export interface SpamReportConfig {
-	messageService: IMessageRepository;
-	addressService: IAddressRepository;
-	accountService: IAccountRepository;
-	mailboxSpecialUseService: IMailboxSpecialUseRepository;
-	messageMoveService: MessageMoveService;
-	flagPushService: FlagPushService;
-	logger?: SpamReportLogger;
-	/** How long `notSpam` waits for a still-in-flight move before giving up. */
-	moveSettleTimeoutMs?: number;
-	moveSettlePollMs?: number;
-}
-
-export interface SpamReportParams {
-	accountConfigId: string;
-	accountId: string;
-	messageId: string;
-	setBy?: string;
-}
-
-export class SpamReportService {
-	private messageService: IMessageRepository;
-	private addressService: IAddressRepository;
-	private accountService: IAccountRepository;
-	private mailboxSpecialUseService: IMailboxSpecialUseRepository;
-	private messageMoveService: MessageMoveService;
-	private flagPushService: FlagPushService;
-	private log: SpamReportLogger;
-	private moveSettleTimeoutMs: number;
-	private moveSettlePollMs: number;
-
-	constructor(config: SpamReportConfig) {
-		this.messageService = config.messageService;
-		this.addressService = config.addressService;
-		this.accountService = config.accountService;
-		this.mailboxSpecialUseService = config.mailboxSpecialUseService;
-		this.messageMoveService = config.messageMoveService;
-		this.flagPushService = config.flagPushService;
-		this.log = config.logger ?? noopLogger;
-		this.moveSettleTimeoutMs =
-			config.moveSettleTimeoutMs ?? DEFAULT_MOVE_SETTLE_TIMEOUT_MS;
-		this.moveSettlePollMs =
-			config.moveSettlePollMs ?? DEFAULT_MOVE_SETTLE_POLL_MS;
-	}
-
-	/**
-	 * The sender to act on. `addressId` is derived rather than read off the
-	 * envelope row so it always names the row `ensureSenderAddress` writes and
-	 * the harvester writes — one derivation, one row, whatever the envelope
-	 * happens to carry.
-	 */
-	private resolveFromAddress = async (
-		accountConfigId: string,
-		messageId: string,
-	): Promise<{
-		addressId: string;
-		normalizedEmail: string;
-		displayName: string;
-	}> => {
-		const description = await this.messageService.describe(messageId);
-		const from = description.envelopeAddress.find(
-			(a) => a.addressRole === AddressRole.From,
-		);
-		if (!from) {
-			throw new Error(`Message ${messageId} has no From address to act on`);
-		}
-		return {
-			addressId: deriveAddressId(accountConfigId, from.normalizedEmail),
-			normalizedEmail: from.normalizedEmail,
-			displayName: from.displayName ?? "",
-		};
-	};
-
-	/**
-	 * The list form answers `[]` for a row that is not there, where the single
-	 * form throws — absence is a case both callers handle, not a fault.
-	 */
-	private senderIsKnown = async (
-		accountConfigId: string,
-		addressId: string,
-	): Promise<boolean> => {
-		const [known] = await this.addressService.getAddress(accountConfigId, [
-			addressId,
-		]);
-		return known !== undefined;
-	};
-
-	/**
-	 * Blocking a sender owns the row it writes to. Harvesting is what ordinarily
-	 * creates it, but a message whose harvest never landed — or whose row was
-	 * taken by a cascade — still has a sender the user is entitled to block, and
-	 * a missing row used to abort report-spam before the message ever reached
-	 * Junk. The id is the harvester's own derivation, so this converges on the
-	 * one row rather than minting a parallel one.
-	 *
-	 * A row that already exists is left exactly as it stands. Reporting spam is
-	 * evidence about the sender, never about the account's standing record of
-	 * them: an upsert here would carry whatever the upsert path does on
-	 * conflict — today a display name chosen by the spammer, and any flag a
-	 * later sighting-clearing rule hangs off it — into an operation that means
-	 * the opposite.
-	 */
-	private ensureSenderAddress = async (
-		accountConfigId: string,
-		from: { addressId: string; normalizedEmail: string; displayName: string },
-	): Promise<void> => {
-		const separator = from.normalizedEmail.lastIndexOf("@");
-		const localPart = from.normalizedEmail.slice(0, separator);
-		const domain = from.normalizedEmail.slice(separator + 1);
-		if (separator < 0 || localPart.length === 0 || domain.length === 0) {
-			throw new Error(
-				`Sender address ${from.normalizedEmail} is not a usable email address`,
-			);
-		}
-		if (await this.senderIsKnown(accountConfigId, from.addressId)) return;
-		await this.addressService.upsertAddress({
-			addressId: from.addressId,
-			accountConfigId,
-			localPart,
-			domain,
-			normalizedEmail: from.normalizedEmail,
-			normalizedCompound:
-				`${from.displayName.toLowerCase()} ${from.normalizedEmail}`.trim(),
-			displayName: from.displayName,
-		});
-	};
-
-	reportSpam = async (params: SpamReportParams): Promise<void> => {
-		const { accountConfigId, accountId, messageId, setBy } = params;
-		const now = Date.now();
-
-		// Resolved before anything is written: with nowhere to file the report,
-		// the operation cannot happen, and a blocked sender plus a `spamReport`
-		// stamp on a message still sitting in the inbox is a report that half
-		// happened. Fail here and the press changed nothing.
-		const junkMailbox =
-			await this.mailboxSpecialUseService.findJunkMailbox(accountId);
-		if (!junkMailbox) {
-			this.log.error({ accountId, messageId }, "No Junk mailbox for account");
-			throw new NoJunkMailboxError();
-		}
-
-		const from = await this.resolveFromAddress(accountConfigId, messageId);
-		const account = await this.accountService.get(accountId);
-		const isOwnAddress =
-			from.normalizedEmail.toLowerCase() === account.email.toLowerCase();
-
-		if (!isOwnAddress) {
-			await this.ensureSenderAddress(accountConfigId, from);
-			await this.addressService.mergeFlags(accountConfigId, from.addressId, {
-				blocked: { value: true, setAt: now, setBy },
-			});
-		}
-
-		// Captured before this call writes anything: `before.spamReport` tells
-		// apart the two reasons the message can already be in Junk. If it is
-		// already set, a PREVIOUS report-spam press put it there and owns
-		// `originalMailboxId` — that value is exactly what Undo needs and must
-		// survive a repeated press. Only when it is absent is the message in
-		// Junk for some unrelated reason (a provider filter, a manual move),
-		// making any `originalMailboxId` on the row stale.
-		const before = await this.messageService.get(messageId);
-		const hadSpamReportAlready = Boolean(before.spamReport);
-
-		await this.messageService.update(messageId, {
-			spamReport: { reportedAt: now },
-		});
-
-		const alreadyInJunk = before.mailboxId === junkMailbox.mailboxId;
-
-		await this.messageMoveService.moveMessage(
-			accountConfigId,
-			messageId,
-			junkMailbox.mailboxId,
-			accountId,
-		);
-
-		if (alreadyInJunk && before.originalMailboxId && !hadSpamReportAlready) {
-			// moveMessage's same-mailbox guard no-opped — it never touches
-			// originalMailboxId, so a stale value left by some earlier, unrelated
-			// move would otherwise survive and send a later notSpam to the wrong
-			// folder. This report-spam action established no move of its own.
-			//
-			// A transition off the row this call read (imap-mutations R3): the pair
-			// being cleared belongs to a placement, and a lane that has claimed the
-			// row since keeps its own — its settle manages the pair.
-			await this.messageService.transitionPlacement(
-				messageId,
-				{
-					status: before.status,
-					mailboxId: before.mailboxId,
-					uid: before.uid,
-				},
-				{ originalMailboxId: null, originalUid: null },
-			);
-		}
-
-		await this.flagPushService.flip({
-			accountId,
-			accountConfigId,
-			messageId,
-			mailboxId: junkMailbox.mailboxId,
-			flagName: MessageKeywordFlag.Junk,
-			operation: "add",
-		});
-
-		this.log.info(
-			{
-				accountId,
-				messageId,
-				addressId: from.addressId,
-				junkMailboxId: junkMailbox.mailboxId,
-				skippedBlock: isOwnAddress,
-			},
-			"Reported message as spam",
-		);
-	};
-
-	notSpam = async (params: SpamReportParams): Promise<void> => {
-		const { accountConfigId, accountId, messageId } = params;
-
-		// Unblocking a sender the account has no row for is already true, and
-		// minting one here would put an address nothing ever harvested into the
-		// address book — the withdrawal of a judgement is not a sighting.
-		const from = await this.resolveFromAddress(accountConfigId, messageId);
-		if (await this.senderIsKnown(accountConfigId, from.addressId)) {
-			await this.addressService.mergeFlags(accountConfigId, from.addressId, {
-				blocked: null,
-			});
-		}
-
-		const message = await this.messageService.get(messageId);
-
-		if (message.originalMailboxId) {
-			// Only wait on the move's settlement when there is actually a
-			// dependent write to make (the restore below) — a move in flight for
-			// an unrelated reason is not this operation's concern.
-			const settled = await waitForPlacementToSettle(
-				this.messageService,
-				messageId,
-				{
-					timeoutMs: this.moveSettleTimeoutMs,
-					pollMs: this.moveSettlePollMs,
-				},
-			);
-			if (isPlacementUnsettled(settled)) {
-				throw new MoveNotSettledError(messageId);
-			}
-
-			await this.messageMoveService.restoreMessage(
-				accountConfigId,
-				messageId,
-				accountId,
-			);
-
-			// Re-read, then clear against what was read. The restore just wrote a
-			// placement, so the row here is not the one above; predicating on it is
-			// what keeps this from erasing a pair some other lane is relying on
-			// (imap-mutations R3).
-			const restored = await this.messageService.get(messageId);
-			await this.messageService.transitionPlacement(
-				messageId,
-				{
-					status: restored.status,
-					mailboxId: restored.mailboxId,
-					uid: restored.uid,
-				},
-				{ originalMailboxId: null, originalUid: null },
-			);
-		}
-
-		const current = await this.messageService.get(messageId);
-
-		await this.flagPushService.flip({
-			accountId,
-			accountConfigId,
-			messageId,
-			mailboxId: current.mailboxId,
-			flagName: MessageKeywordFlag.Junk,
-			operation: "remove",
-		});
-		await this.flagPushService.flip({
-			accountId,
-			accountConfigId,
-			messageId,
-			mailboxId: current.mailboxId,
-			flagName: MessageKeywordFlag.NotJunk,
-			operation: "add",
-		});
-
-		await this.messageService.clearSpamReport(messageId);
-
-		this.log.info(
-			{ accountId, messageId, addressId: from.addressId },
-			"Undid spam report",
-		);
-	};
-}

package/src/stale-message-reconcile.test.ts

@@ -1,82 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import type {
-	IMessageRepository,
-	IThreadMessageRepository,
-} from "@remit/data-ports";
-import {
-	reconcileStaleMessage,
-	type StaleMessageReconcileDeps,
-} from "./stale-message-reconcile.js";
-
-describe("reconcileStaleMessage", () => {
-	it("deletes the Message row and every ThreadMessage copy that points at it", async () => {
-		const deletedMessages: string[] = [];
-		const deletedThreadMessageKeys: Array<{
-			accountConfigId: string;
-			threadMessageId: string;
-		}> = [];
-
-		const deps: StaleMessageReconcileDeps = {
-			messageService: {
-				delete: async (messageId: string) => {
-					deletedMessages.push(messageId);
-				},
-			} as unknown as Pick<IMessageRepository, "delete">,
-			threadMessageService: {
-				findAllByMessageId: async (
-					accountConfigId: string,
-					messageId: string,
-				) => [
-					{ accountConfigId, threadMessageId: `tm-inbox-${messageId}` },
-					{ accountConfigId, threadMessageId: `tm-label-${messageId}` },
-				],
-				deleteMany: async (
-					keys: Array<{ accountConfigId: string; threadMessageId: string }>,
-				) => {
-					deletedThreadMessageKeys.push(...keys);
-				},
-			} as unknown as Pick<
-				IThreadMessageRepository,
-				"findAllByMessageId" | "deleteMany"
-			>,
-		};
-
-		const result = await reconcileStaleMessage(deps, "cfg-1", "msg-1");
-
-		assert.equal(result.threadMessagesDeleted, 2);
-		assert.deepEqual(deletedMessages, ["msg-1"]);
-		assert.deepEqual(deletedThreadMessageKeys, [
-			{ accountConfigId: "cfg-1", threadMessageId: "tm-inbox-msg-1" },
-			{ accountConfigId: "cfg-1", threadMessageId: "tm-label-msg-1" },
-		]);
-	});
-
-	it("skips the batch delete (never calls deleteMany with an empty array) when no copies exist", async () => {
-		const deletedMessages: string[] = [];
-		let deleteManyCalls = 0;
-
-		const deps: StaleMessageReconcileDeps = {
-			messageService: {
-				delete: async (messageId: string) => {
-					deletedMessages.push(messageId);
-				},
-			} as unknown as Pick<IMessageRepository, "delete">,
-			threadMessageService: {
-				findAllByMessageId: async () => [],
-				deleteMany: async () => {
-					deleteManyCalls++;
-				},
-			} as unknown as Pick<
-				IThreadMessageRepository,
-				"findAllByMessageId" | "deleteMany"
-			>,
-		};
-
-		const result = await reconcileStaleMessage(deps, "cfg-1", "msg-solo");
-
-		assert.equal(result.threadMessagesDeleted, 0);
-		assert.deepEqual(deletedMessages, ["msg-solo"]);
-		assert.equal(deleteManyCalls, 0);
-	});
-});

package/src/stale-message-reconcile.ts

@@ -1,55 +0,0 @@
-import type {
-	IMessageRepository,
-	IThreadMessageRepository,
-} from "@remit/data-ports";
-
-export interface StaleMessageReconcileDeps {
-	messageService: Pick<IMessageRepository, "delete">;
-	threadMessageService: Pick<
-		IThreadMessageRepository,
-		"findAllByMessageId" | "deleteMany"
-	>;
-}
-
-export interface StaleMessageReconcileResult {
-	threadMessagesDeleted: number;
-}
-
-/**
- * Delete a Message row (and every ThreadMessage copy that points at it) once
- * the caller has confirmed the message no longer exists on the IMAP server.
- *
- * A row outliving an upstream expunge (or a UIDVALIDITY change — #1272) is
- * the EXPECTED terminal outcome for a body that can never be fetched (issue
- * #1270 / epic #1281 invariant 3): expunges are routine, so cleaning up here
- * is normal operation, not an incident. Deleting the row makes the existing
- * missing-row 404 path (`MessageService.get` / `describe`) authoritative
- * again — nothing renders the row, nothing re-arms a sync for it.
- *
- * Exported standalone, not inlined in the body-sync retry path, so #1272's
- * UIDVALIDITY cursor rebuild can call the same reconciliation when it finds
- * rows whose UIDs no longer resolve after a cursor rebuild.
- */
-export const reconcileStaleMessage = async (
-	deps: StaleMessageReconcileDeps,
-	accountConfigId: string,
-	messageId: string,
-): Promise<StaleMessageReconcileResult> => {
-	const threadMessages = await deps.threadMessageService.findAllByMessageId(
-		accountConfigId,
-		messageId,
-	);
-
-	if (threadMessages.length > 0) {
-		await deps.threadMessageService.deleteMany(
-			threadMessages.map((row) => ({
-				accountConfigId: row.accountConfigId,
-				threadMessageId: row.threadMessageId,
-			})),
-		);
-	}
-
-	await deps.messageService.delete(messageId);
-
-	return { threadMessagesDeleted: threadMessages.length };
-};