@remit/mailbox-service 0.0.56 → 0.0.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.56",
+  "version": "0.0.57",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -254,6 +254,7 @@ export {
 } from "./snippet.js";
 export {
 	MoveNotSettledError,
+	NoJunkMailboxError,
 	type SpamReportConfig,
 	type SpamReportLogger,
 	type SpamReportParams,

package/src/spam-report.test.ts

@@ -10,10 +10,15 @@ import type {
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
+import { deriveAddressId } from "@remit/data-ports/id";
 import { AddressRole } from "@remit/domain-enums";
 import { FlagPushService } from "./flag-push.js";
 import { MessageMoveService } from "./message-move.js";
-import { MoveNotSettledError, SpamReportService } from "./spam-report.js";
+import {
+	MoveNotSettledError,
+	NoJunkMailboxError,
+	SpamReportService,
+} from "./spam-report.js";
 
 const ACCOUNT = "acc-1";
 const ACCOUNT_CONFIG = "cfg-1";
@@ -21,7 +26,8 @@ const ACCOUNT_EMAIL = "me@example.com";
 const INBOX_MAILBOX = "mbx-inbox";
 const JUNK_MAILBOX = "mbx-junk";
 const MESSAGE_ID = "msg-1";
-const ADDRESS_ID = "addr-1";
+const SENDER_EMAIL = "sender@example.com";
+const ADDRESS_ID = deriveAddressId(ACCOUNT_CONFIG, SENDER_EMAIL);
 const THREAD_ID = "thread-1";
 
 interface ThreadRow {
@@ -59,10 +65,21 @@ const buildWorld = (
 		startMailbox?: string;
 		fromEmail?: string;
 		originalMailboxId?: string;
+		/** Whether the sender was ever harvested into an `address` row. */
+		harvestedSender?: boolean;
+		/** Flags already standing on the harvested sender's row. */
+		senderFlags?: Record<string, unknown>;
+		junkMailbox?: { mailboxId: string; fullPath: string } | null;
 	} = {},
 ): World => {
 	const startMailbox = opts.startMailbox ?? INBOX_MAILBOX;
-	const fromEmail = opts.fromEmail ?? "sender@example.com";
+	const fromEmail = opts.fromEmail ?? SENDER_EMAIL;
+	const fromAddressId = deriveAddressId(ACCOUNT_CONFIG, fromEmail);
+	const harvestedSender = opts.harvestedSender ?? true;
+	const junkMailbox =
+		opts.junkMailbox === undefined
+			? { mailboxId: JUNK_MAILBOX, fullPath: "Junk" }
+			: opts.junkMailbox;
 
 	const messages = new Map<string, Record<string, unknown>>([
 		[
@@ -85,9 +102,11 @@ const buildWorld = (
 		],
 	]);
 
-	const addresses = new Map<string, { flags: AddressFlags }>([
-		[ADDRESS_ID, { flags: {} }],
-	]);
+	const addresses = new Map<string, { flags: AddressFlags }>(
+		harvestedSender
+			? [[fromAddressId, { flags: (opts.senderFlags ?? {}) as AddressFlags }]]
+			: [],
+	);
 
 	const threadRows: ThreadRow[] = [
 		{
@@ -134,7 +153,8 @@ const buildWorld = (
 					{
 						envelopeAddressId: "ea-1",
 						messageId: id,
-						addressId: ADDRESS_ID,
+						addressId: fromAddressId,
+						displayName: "Spammy Sender",
 						normalizedEmail: fromEmail,
 						addressRole: AddressRole.From,
 						addressOrder: 0,
@@ -173,6 +193,17 @@ const buildWorld = (
 	} as unknown as IMessageRepository;
 
 	const addressService = {
+		getAddress: async (_accountConfigId: string, addressIds: string[]) =>
+			addressIds
+				.filter((id) => addresses.has(id))
+				.map((id) => ({ addressId: id, ...addresses.get(id) })),
+		// Deliberately destructive on conflict, mirroring the real repo's
+		// `onConflictDoUpdate`: a caller that upserts over a row it did not
+		// create loses what stood on it.
+		upsertAddress: async (input: { addressId: string }) => {
+			addresses.set(input.addressId, { flags: {} });
+			return { ...input, flags: {} };
+		},
 		mergeFlags: async (
 			_accountConfigId: string,
 			addressId: string,
@@ -199,10 +230,7 @@ const buildWorld = (
 	} as unknown as IAccountRepository;
 
 	const mailboxSpecialUseService = {
-		findJunkMailbox: async () => ({
-			mailboxId: JUNK_MAILBOX,
-			fullPath: "Junk",
-		}),
+		findJunkMailbox: async () => junkMailbox,
 		findTrashMailbox: async () => null,
 	} as unknown as IMailboxSpecialUseRepository;
 
@@ -399,9 +427,133 @@ describe("SpamReportService.reportSpam", () => {
 		assert.ok(message !== undefined);
 		assert.ok((message.spamReport as { reportedAt: number }).reportedAt > 0);
 	});
+
+	it("refuses to mint a row for a sender address carrying no @ at all", async () => {
+		// slice() around a lastIndexOf of -1 splits "no-at-sign" into a
+		// plausible-looking local part and domain, so a length check alone
+		// waves the one input it exists to catch straight through into a
+		// corrupt address row.
+		const { service, addresses } = buildWorld({
+			harvestedSender: false,
+			fromEmail: "no-at-sign",
+		});
+
+		await assert.rejects(
+			() =>
+				service.reportSpam({
+					accountConfigId: ACCOUNT_CONFIG,
+					accountId: ACCOUNT,
+					messageId: MESSAGE_ID,
+				}),
+			/not a usable email address/,
+		);
+
+		assert.equal(addresses.size, 0);
+	});
+
+	it("reports a message whose sender was never harvested into an address row", async () => {
+		// The row is what carries the blocked flag, and harvesting is what
+		// ordinarily writes it. When it is absent, blocking the sender used to
+		// throw NotFoundError and take the whole report down with it — the
+		// message never reached Junk and the user got a retry that could not
+		// work (test.remit.email, 18 Aug 2026).
+		const { service, messages, addresses, sent } = buildWorld({
+			harvestedSender: false,
+		});
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+			setBy: "user-1",
+		});
+
+		const address = addresses.get(ADDRESS_ID);
+		assert.equal(address?.flags.blocked?.value, true);
+
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(message?.mailboxId, JUNK_MAILBOX);
+		assert.equal(moveEvents(sent).length, 1);
+	});
+
+	it("keeps the junkOnly mark that withholds the sender from autocomplete", async () => {
+		// Report spam adds the block; it is not a sighting of the sender and
+		// must not carry an upsert's on-conflict behaviour onto a row it did
+		// not create. The mark that withholds a spammer from autocomplete (#822)
+		// lives in these same flags, and clearing it here would put the spammer
+		// back in the compose picker — the opposite of what the button means.
+		const { service, addresses } = buildWorld({
+			senderFlags: {
+				junkOnly: { value: true, setAt: 1, setBy: "junk-harvest" },
+			},
+		});
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+			setBy: "user-1",
+		});
+
+		const flags = addresses.get(ADDRESS_ID)?.flags as Record<string, unknown>;
+		assert.equal((flags.blocked as { value: boolean }).value, true);
+		assert.deepEqual(flags.junkOnly, {
+			value: true,
+			setAt: 1,
+			setBy: "junk-harvest",
+		});
+	});
+
+	it("names the missing Junk folder and changes nothing when the account has none", async () => {
+		const { service, messages, addresses, sent, markerPuts } = buildWorld({
+			junkMailbox: null,
+		});
+
+		await assert.rejects(
+			() =>
+				service.reportSpam({
+					accountConfigId: ACCOUNT_CONFIG,
+					accountId: ACCOUNT,
+					messageId: MESSAGE_ID,
+				}),
+			(error: unknown) =>
+				error instanceof NoJunkMailboxError &&
+				/no Junk folder/.test(error.message) &&
+				/Create one/.test(error.message),
+		);
+
+		// Nothing half-applied: no sender blocked, no report stamp on a message
+		// still sitting where it was, no move, no keyword marker.
+		assert.equal(addresses.get(ADDRESS_ID)?.flags.blocked, undefined);
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(message?.spamReport, undefined);
+		assert.equal(message?.mailboxId, INBOX_MAILBOX);
+		assert.equal(moveEvents(sent).length, 0);
+		assert.equal(markerPuts.length, 0);
+	});
 });
 
 describe("SpamReportService.notSpam", () => {
+	it("mints no address row for a sender that was never harvested", async () => {
+		// A sender with no row has no block to lift, so the flag write is
+		// already true. Creating the row to write it would put an address
+		// nothing ever harvested into the address book, where autocomplete
+		// would then offer it.
+		const { service, messages, addresses } = buildWorld({
+			harvestedSender: false,
+			startMailbox: JUNK_MAILBOX,
+		});
+
+		await service.notSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		assert.equal(addresses.size, 0);
+		assert.equal(messages.get(MESSAGE_ID)?.spamReport, undefined);
+	});
+
 	it("restores the original mailbox and clears the flag without setting trust", async () => {
 		const { service, messages, addresses } = buildWorld();
 

package/src/spam-report.ts

@@ -5,6 +5,7 @@ import type {
 	IMessageRepository,
 	MessageItem,
 } from "@remit/data-ports";
+import { deriveAddressId } from "@remit/data-ports/id";
 import {
 	AddressRole,
 	MessageKeywordFlag,
@@ -33,6 +34,22 @@ export class MoveNotSettledError extends Error {
 	}
 }
 
+/**
+ * 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: () => {},
@@ -86,9 +103,20 @@ export class SpamReportService {
 			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 }> => {
+	): Promise<{
+		addressId: string;
+		normalizedEmail: string;
+		displayName: string;
+	}> => {
 		const description = await this.messageService.describe(messageId);
 		const from = description.envelopeAddress.find(
 			(a) => a.addressRole === AddressRole.From,
@@ -96,7 +124,65 @@ export class SpamReportService {
 		if (!from) {
 			throw new Error(`Message ${messageId} has no From address to act on`);
 		}
-		return { addressId: from.addressId, normalizedEmail: from.normalizedEmail };
+		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,
+		});
 	};
 
 	/**
@@ -128,12 +214,24 @@ export class SpamReportService {
 		const { accountConfigId, accountId, messageId, setBy } = params;
 		const now = Date.now();
 
-		const from = await this.resolveFromAddress(messageId);
+		// 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 },
 			});
@@ -153,12 +251,6 @@ export class SpamReportService {
 			spamReport: { reportedAt: now },
 		});
 
-		const junkMailbox =
-			await this.mailboxSpecialUseService.findJunkMailbox(accountId);
-		if (!junkMailbox) {
-			throw new Error(`No Junk mailbox found for account ${accountId}`);
-		}
-
 		const alreadyInJunk = before.mailboxId === junkMailbox.mailboxId;
 
 		await this.messageMoveService.moveMessage(
@@ -200,10 +292,15 @@ export class SpamReportService {
 	notSpam = async (params: SpamReportParams): Promise<void> => {
 		const { accountConfigId, accountId, messageId } = params;
 
-		const from = await this.resolveFromAddress(messageId);
-		await this.addressService.mergeFlags(accountConfigId, from.addressId, {
-			blocked: null,
-		});
+		// 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);