@remit/account-worker 0.0.24 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/account-worker",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/src/events.ts

@@ -1,3 +1,7 @@
+import type { ThreadMessageItem } from "@remit/data-ports";
+
+type MessageCategoryValue = ThreadMessageItem["category"];
+
 export type AccountDeleteEvent = {
 	type: "AccountDelete";
 	accountConfigId: string;
@@ -33,11 +37,38 @@ export type OrganizeJobEvent = {
 	organizeJobId: string;
 };
 
+/**
+ * Retroactive half of a sender-category override (#415, RFC 039 Decision 3).
+ * Rides the same account-fanout queue as the organize back-apply: the API
+ * enqueues one when `Address.flags.category` is SET, and the fanout worker
+ * re-labels a bounded recent batch of that sender's already-classified mail.
+ * A CLEAR never enqueues one: reverting to auto-classification says nothing
+ * about what the classifier would have answered, and re-deriving it would need
+ * every message's body back.
+ *
+ * `category` and `categorySetAt` together name WHICH set this job was fired
+ * for, and the worker refuses a job whose set no longer stands on the Address.
+ * That check is what the standard queue's semantics make necessary rather than
+ * merely tidy: delivery is at-least-once and unordered, so without it a job
+ * that fails and redelivers after the user has corrected the category re-labels
+ * those 500 messages back to the superseded one, leaving the flag and the mail
+ * permanently disagreeing with nothing to reconcile them.
+ */
+export type SenderCategoryBackApplyEvent = {
+	type: "SenderCategoryBackApply";
+	accountConfigId: string;
+	addressId: string;
+	normalizedEmail: string;
+	category: MessageCategoryValue;
+	categorySetAt: number;
+};
+
 export type AccountFanoutEvent =
 	| AccountDeleteEvent
 	| AccountDataPurgeEvent
 	| AccountExportEvent
-	| OrganizeJobEvent;
+	| OrganizeJobEvent
+	| SenderCategoryBackApplyEvent;
 
 export type AccountDeleteFinalizeEvent = {
 	type: "FinalizeAccountDelete";

package/src/handlers/account-fanout.ts

@@ -28,6 +28,7 @@ import type {
 import { processAccountExport } from "./account-export.js";
 import { processAccountDataPurge } from "./account-purge.js";
 import { processOrganizeJob } from "./organize-job.js";
+import { processSenderCategoryBackApply } from "./sender-category-backapply.js";
 
 export interface ProcessAccountFanoutDeps {
 	services?: CascadeServices;
@@ -74,6 +75,11 @@ export const processAccountFanout = async (
 		return;
 	}
 
+	if (event.type === "SenderCategoryBackApply") {
+		await processSenderCategoryBackApply(event, log);
+		return;
+	}
+
 	await processAccountDelete(event, log, services, sqsFor, deps);
 };
 

package/src/handlers/sender-category-backapply.test.ts

@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { RemitClient } from "@remit/backend/client";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { noopLogger } from "@remit/logger-lambda/noop-logger";
+import type { SenderCategoryBackApplyEvent } from "../events.js";
+import { processSenderCategoryBackApply } from "./sender-category-backapply.js";
+
+const SET_AT = 1_700;
+
+const event: SenderCategoryBackApplyEvent = {
+	type: "SenderCategoryBackApply",
+	accountConfigId: "cfg-1",
+	addressId: "addr-1",
+	normalizedEmail: "post@ns.nl",
+	category: "newsletter",
+	categorySetAt: SET_AT,
+};
+
+const row = {
+	threadMessageId: "tm-1",
+	messageId: "msg-1",
+	mailboxId: "mbx-inbox",
+	fromEmail: "post@ns.nl",
+	category: "personal",
+	sentDate: 1_000,
+	isRead: false,
+	isDeleted: false,
+	hasStars: false,
+	hasAttachment: false,
+};
+
+interface ClientShape {
+	relabelled: Array<{ messageId: string; category: unknown }>;
+	storedFlag?: { value: string; setAt: number } | "cleared" | "address-gone";
+	listByFieldTerms?: () => Promise<unknown>;
+	updateMessage?: (messageId: string) => Promise<void>;
+}
+
+const clientOver = ({
+	relabelled,
+	storedFlag = { value: "newsletter", setAt: SET_AT },
+	listByFieldTerms = async () => ({
+		items: [row],
+		continuationToken: undefined,
+	}),
+	updateMessage,
+}: ClientShape): RemitClient =>
+	({
+		address: {
+			getAddress: async () => {
+				if (storedFlag === "address-gone") {
+					throw new NotFoundError("Address addr-1 not found");
+				}
+				if (storedFlag === "cleared") {
+					return { addressId: "addr-1", flags: {} };
+				}
+				return { addressId: "addr-1", flags: { category: storedFlag } };
+			},
+		},
+		message: {
+			update: async (messageId: string, input: { category: unknown }) => {
+				if (updateMessage) await updateMessage(messageId);
+				relabelled.push({ messageId, category: input.category });
+			},
+		},
+		threadMessage: {
+			listByFieldTerms,
+			findAllByMessageId: async () => [row],
+			update: async () => {},
+		},
+	}) as unknown as RemitClient;
+
+describe("processSenderCategoryBackApply (#415)", () => {
+	it("re-labels the sender's stored mail to the category the event carries", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({ relabelled }),
+		});
+
+		assert.deepEqual(relabelled, [
+			{ messageId: "msg-1", category: "newsletter" },
+		]);
+	});
+
+	it("applies nothing when the user has since corrected the category", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({
+				relabelled,
+				storedFlag: { value: "promotions", setAt: SET_AT + 60 },
+			}),
+		});
+
+		assert.deepEqual(
+			relabelled,
+			[],
+			"a redelivery after a correction must not put the superseded category back",
+		);
+	});
+
+	it("applies nothing when the same category was cleared and set again", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({
+				relabelled,
+				storedFlag: { value: "newsletter", setAt: SET_AT + 60 },
+			}),
+		});
+
+		assert.deepEqual(relabelled, []);
+	});
+
+	it("applies nothing when the override was cleared outright", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({ relabelled, storedFlag: "cleared" }),
+		});
+
+		assert.deepEqual(relabelled, []);
+	});
+
+	it("declines quietly when the address is gone", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({ relabelled, storedFlag: "address-gone" }),
+		});
+
+		assert.deepEqual(relabelled, []);
+	});
+
+	it("leaves a pass with a failed message unacknowledged so it redelivers", async () => {
+		await assert.rejects(
+			processSenderCategoryBackApply(event, noopLogger, {
+				client: clientOver({
+					relabelled: [],
+					updateMessage: async () => {
+						throw new Error("SQLITE_BUSY");
+					},
+				}),
+			}),
+			/1 of 1/,
+			"acknowledging would strand the thread rows re-labelled and the Message row not",
+		);
+	});
+
+	it("propagates a store failure so partial batch failure redelivers the record", async () => {
+		await assert.rejects(
+			processSenderCategoryBackApply(event, noopLogger, {
+				client: clientOver({
+					relabelled: [],
+					listByFieldTerms: async () => {
+						throw new Error("SQLITE_BUSY");
+					},
+				}),
+			}),
+			/SQLITE_BUSY/,
+			"the pass writes only idempotent local rows, so a retry is safe and must happen",
+		);
+	});
+});

package/src/handlers/sender-category-backapply.ts

@@ -0,0 +1,98 @@
+import { getClient, type RemitClient } from "@remit/backend/client";
+import {
+	backApplySenderCategory,
+	SENDER_CATEGORY_BACKAPPLY_LIMIT,
+} from "@remit/backend/sender-category";
+import { NotFoundError } from "@remit/data-ports/errors";
+import type { Logger } from "@remit/logger-lambda";
+import type { SenderCategoryBackApplyEvent } from "../events.js";
+
+export interface ProcessSenderCategoryBackApplyDeps {
+	client?: RemitClient;
+}
+
+/**
+ * Whether the override this job was fired for is still the one standing on the
+ * Address. Both halves are compared: `value` alone would let a set → clear →
+ * re-set to the same category count as unchanged, and `setAt` alone would
+ * refuse a legitimate redelivery.
+ *
+ * A vanished Address is a stale job, not a fault — the account was purged
+ * between the PATCH and the delivery — so it declines quietly. Every other
+ * read failure propagates, because a job that cannot tell whether it is stale
+ * must not guess.
+ */
+const overrideStillStands = async (
+	client: RemitClient,
+	event: SenderCategoryBackApplyEvent,
+): Promise<boolean> => {
+	const address = await client.address
+		.getAddress(event.accountConfigId, event.addressId)
+		.catch((error: unknown) => {
+			if (error instanceof NotFoundError) return undefined;
+			throw error;
+		});
+	const flag = address?.flags?.category;
+	return flag?.value === event.category && flag?.setAt === event.categorySetAt;
+};
+
+/**
+ * Run the retroactive half of a sender-category override (#415): re-label the
+ * bounded recent batch of that sender's already-classified mail, in one pass.
+ * Rides the organize back-apply's seam without its job row — a flag PATCH
+ * returns the address, not a job to poll, so there is no lifecycle for a client
+ * to read and nothing for a row to carry.
+ *
+ * The delivery is at-least-once and unordered, so the pass starts by
+ * re-reading the flag and declines unless the set it was fired for is still
+ * the standing one ({@link overrideStillStands}). Re-labelling blind would let
+ * a redelivered job undo a correction the user has since made.
+ *
+ * A pass in which any message failed is NOT acknowledged: the writes are
+ * idempotent and the converged rows are skipped on the way through, so
+ * redelivery re-runs only what is still wrong. Acknowledging instead would
+ * leave a message whose thread rows were re-labelled but whose Message row was
+ * not — the badge and the detail view disagreeing, permanently, with nothing
+ * left to repair it.
+ */
+export const processSenderCategoryBackApply = async (
+	event: SenderCategoryBackApplyEvent,
+	log: Logger,
+	deps: ProcessSenderCategoryBackApplyDeps = {},
+): Promise<void> => {
+	const { accountConfigId, addressId, normalizedEmail, category } = event;
+	const client = deps.client ?? (await getClient());
+
+	if (!(await overrideStillStands(client, event))) {
+		log.warn(
+			{ accountConfigId, addressId, category },
+			"Sender category back-apply skipped: the override it was fired for no longer stands",
+		);
+		return;
+	}
+
+	const result = await backApplySenderCategory(
+		{ client },
+		accountConfigId,
+		normalizedEmail,
+		category,
+	);
+
+	// biome-ignore lint/plugin/no-logger-info: a back-apply is an audit-grade signal
+	log.info(
+		{
+			accountConfigId,
+			addressId,
+			category,
+			limit: SENDER_CATEGORY_BACKAPPLY_LIMIT,
+			...result,
+		},
+		"Sender category back-apply pass finished",
+	);
+
+	if (result.failed > 0) {
+		throw new Error(
+			`Sender category back-apply left ${result.failed} of ${result.matched} messages unlabelled for address ${addressId}`,
+		);
+	}
+};