@remit/mailbox-service 0.0.111 → 0.0.113

package/src/quarantine.test.ts

@@ -1,191 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import type {
-	IMailboxSpecialUseRepository,
-	IQuarantineRepository,
-	MessageData,
-	MessageItem,
-	QuarantineItem,
-	QuarantineUpsertInput,
-} from "@remit/data-ports";
-import {
-	QuarantinedUids,
-	QuarantineService,
-	resolveMailboxRole,
-	shapeFromMessageData,
-} from "./quarantine.js";
-
-const noopLog = { info: () => {}, warn: () => {} };
-
-const buildService = (
-	specialUse: string[] = [],
-): {
-	service: QuarantineService;
-	writes: QuarantineUpsertInput[];
-	listed: string[];
-} => {
-	const writes: QuarantineUpsertInput[] = [];
-	const listed: string[] = [];
-	const repository = {
-		listByAccountConfigId: async (accountConfigId: string) => {
-			listed.push(accountConfigId);
-			return [] as QuarantineItem[];
-		},
-		upsert: async (input: QuarantineUpsertInput) => {
-			writes.push(input);
-		},
-	} satisfies IQuarantineRepository;
-
-	const mailboxSpecialUseService = {
-		listByMailboxId: async () => specialUse.map((use) => ({ specialUse: use })),
-	} as unknown as IMailboxSpecialUseRepository;
-
-	return {
-		service: new QuarantineService(
-			repository,
-			mailboxSpecialUseService,
-			"sha-abc",
-			noopLog,
-		),
-		writes,
-		listed,
-	};
-};
-
-const context = {
-	accountId: "acct-1",
-	accountConfigId: "cfg-1",
-	mailboxId: "mbx-1",
-	mailboxPath: "INBOX",
-	uidValidity: 1_712_000_000,
-	attempts: 2,
-};
-
-const failure = {
-	stage: "BodyParse" as const,
-	code: "UnreadableBody" as const,
-	message: "the parser said no",
-};
-
-describe("QuarantineService.record", () => {
-	it("stamps the worker build, not the client's", async () => {
-		const { service, writes } = buildService();
-		await service.record(context, 40217, failure);
-		assert.equal(writes[0]?.workerVersion, "sha-abc");
-	});
-
-	it("names the message by mailbox, uidValidity and uid", async () => {
-		const { service, writes } = buildService();
-		await service.record(context, 40217, failure);
-		assert.deepEqual(
-			{
-				mailboxId: writes[0]?.mailboxId,
-				uidValidity: writes[0]?.uidValidity,
-				uid: writes[0]?.uid,
-			},
-			{ mailboxId: "mbx-1", uidValidity: 1_712_000_000, uid: 40217 },
-		);
-	});
-
-	it("supplies no quarantineId, so the random-id default is unreachable", async () => {
-		const { service, writes } = buildService();
-		await service.record(context, 40217, failure);
-		assert.ok(!("quarantineId" in (writes[0] as object)));
-	});
-
-	it("omits an absent diagnostic rather than writing a null through", async () => {
-		const { service, writes } = buildService();
-		await service.record(
-			{ ...context, mailboxPath: "Clients/Acme" },
-			1,
-			failure,
-		);
-		assert.ok(!("failurePartPath" in (writes[0] as object)));
-		assert.ok(!("mailboxRole" in (writes[0] as object)));
-	});
-
-	it("reads the folder's role off the server's SPECIAL-USE", async () => {
-		const { service, writes } = buildService(["Junk"]);
-		await service.record({ ...context, mailboxPath: "Spam" }, 1, failure);
-		assert.equal(writes[0]?.mailboxRole, "Junk");
-	});
-});
-
-describe("resolveMailboxRole", () => {
-	it("gives INBOX its role without a SPECIAL-USE flag, which it never has", () => {
-		assert.equal(resolveMailboxRole("INBOX", []), "Inbox");
-	});
-
-	it("leaves a plain folder roleless instead of inventing one", () => {
-		assert.equal(resolveMailboxRole("Clients/Acme", []), undefined);
-	});
-
-	it("drops a SPECIAL-USE that is not a canonical role", () => {
-		assert.equal(resolveMailboxRole("Priority", ["Important"]), undefined);
-	});
-});
-
-describe("QuarantinedUids", () => {
-	const entries = [
-		{ mailboxId: "mbx-1", uidValidity: 10, uid: 5 },
-	] as QuarantineItem[];
-
-	it("matches a uid on the same mailbox and UIDVALIDITY", () => {
-		assert.equal(new QuarantinedUids(entries).has("mbx-1", 10, 5), true);
-	});
-
-	it("does not match the same uid on a new UIDVALIDITY, which is a different message", () => {
-		assert.equal(new QuarantinedUids(entries).has("mbx-1", 11, 5), false);
-	});
-
-	it("does not match the same uid in another mailbox", () => {
-		assert.equal(new QuarantinedUids(entries).has("mbx-2", 10, 5), false);
-	});
-});
-
-describe("shapeFromMessageData", () => {
-	const message = {
-		rfc822Size: 2048,
-		messageIdHeader: "<xyz@example.com>",
-	} as MessageItem;
-
-	const data = {
-		bodyPart: [
-			{
-				bodyPartId: "bp-0",
-				partPath: "0",
-				mediaType: "multipart",
-				mediaSubtype: "alternative",
-				transferEncoding: "7bit",
-			},
-			{
-				bodyPartId: "bp-1",
-				partPath: "1",
-				mediaType: "text",
-				mediaSubtype: "plain",
-				transferEncoding: "quoted-printable",
-			},
-		],
-		bodyPartParameter: [
-			{
-				bodyPartId: "bp-0",
-				parameterName: "charset",
-				parameterValue: "iso-8859-1",
-			},
-		],
-	} as unknown as MessageData;
-
-	it("rebuilds the tree from the rows metadata sync already wrote", () => {
-		assert.deepEqual(shapeFromMessageData(message, data).structure, [
-			{ depth: 0, contentType: "multipart/alternative" },
-			{ depth: 1, contentType: "text/plain" },
-		]);
-	});
-
-	it("takes the root part's declared charset and encoding", () => {
-		const shape = shapeFromMessageData(message, data);
-		assert.equal(shape.charset, "iso-8859-1");
-		assert.equal(shape.transferEncoding, "7bit");
-		assert.equal(shape.contentType, "multipart/alternative");
-	});
-});

package/src/quarantine.ts

@@ -1,228 +0,0 @@
-import type {
-	IMailboxSpecialUseRepository,
-	IQuarantineRepository,
-	MessageData,
-	MessageItem,
-	QuarantineItem,
-	QuarantineMimeNodeItem,
-} from "@remit/data-ports";
-import { quarantineMessageIdHash, ROOT_PART_PATH } from "@remit/data-ports/id";
-import { CanonicalMailboxRole } from "@remit/domain-enums";
-
-type CanonicalRole = NonNullable<QuarantineItem["mailboxRole"]>;
-type FailureStage = QuarantineItem["failureStage"];
-type FailureCode = QuarantineItem["failureCode"];
-
-const CANONICAL_ROLES = new Set<string>(Object.values(CanonicalMailboxRole));
-
-/**
- * The canonical role of the folder a quarantined message arrived in, read from
- * the server's own RFC 6154 SPECIAL-USE declaration — the same source the
- * appointment flow seeds from. A folder the server declares nothing about has
- * no role, which is the normal state for a plain folder and is why the field
- * is optional. `Important` is a SPECIAL-USE with no canonical role and drops
- * out here rather than being invented into one.
- */
-export const resolveMailboxRole = (
-	mailboxPath: string,
-	specialUse: readonly string[],
-): CanonicalRole | undefined => {
-	if (mailboxPath.toUpperCase() === "INBOX") return CanonicalMailboxRole.Inbox;
-	const matched = specialUse.find((use) => CANONICAL_ROLES.has(use));
-	return matched as CanonicalRole | undefined;
-};
-
-/** Everything about the quarantine that is the same for every uid in a round. */
-export interface QuarantineContext {
-	accountId: string;
-	accountConfigId: string;
-	mailboxId: string;
-	mailboxPath: string;
-	uidValidity: number;
-	/** Rounds tried before the message was set aside. */
-	attempts: number;
-}
-
-/**
- * The repro fingerprint: what the message declared itself to be. Every field
- * is optional-by-absence because a message can fail before its shape was read,
- * and a required column would force the writer to invent a value or drop the
- * record.
- */
-export interface QuarantineMessageShape {
-	contentType?: string;
-	transferEncoding?: string;
-	charset?: string;
-	sizeBytes?: number;
-	structure: QuarantineMimeNodeItem[];
-	messageIdHash?: string;
-}
-
-export interface QuarantineFailure {
-	stage: FailureStage;
-	code: FailureCode;
-	/** Parser error text. Stored, shown on screen, never published. */
-	message: string;
-	partPath?: string;
-}
-
-const EMPTY_SHAPE: QuarantineMessageShape = { structure: [] };
-
-/**
- * Message shape off the rows metadata sync already wrote. The body path has no
- * FETCH result to read — it streams raw bytes — but the MIME tree it needs was
- * walked into BodyPart rows when the message's metadata was synced, so the
- * fingerprint comes from there rather than from re-reading headers the parser
- * has just refused.
- */
-export const shapeFromMessageData = (
-	message: MessageItem,
-	data: MessageData,
-): QuarantineMessageShape => {
-	const parts = [...data.bodyPart].sort((a, b) =>
-		a.partPath.localeCompare(b.partPath, "en", { numeric: true }),
-	);
-	const root = parts.find((part) => part.partPath === ROOT_PART_PATH);
-	const rootCharset = root
-		? data.bodyPartParameter.find(
-				(param) =>
-					param.bodyPartId === root.bodyPartId &&
-					param.parameterName.toLowerCase() === "charset",
-			)?.parameterValue
-		: undefined;
-
-	return {
-		...(root ? { contentType: `${root.mediaType}/${root.mediaSubtype}` } : {}),
-		...(root ? { transferEncoding: root.transferEncoding } : {}),
-		...(rootCharset ? { charset: rootCharset } : {}),
-		...(message.rfc822Size ? { sizeBytes: message.rfc822Size } : {}),
-		structure: parts.map((part) => ({
-			depth: partPathDepth(part.partPath),
-			contentType: `${part.mediaType}/${part.mediaSubtype}`,
-		})),
-		...hashOf(message.messageIdHeader),
-	};
-};
-
-const partPathDepth = (partPath: string): number =>
-	partPath === ROOT_PART_PATH ? 0 : partPath.split(".").length;
-
-const hashOf = (
-	messageIdHeader: string | undefined,
-): { messageIdHash?: string } => {
-	const messageIdHash = quarantineMessageIdHash(messageIdHeader);
-	return messageIdHash ? { messageIdHash } : {};
-};
-
-/**
- * The set of messages already set aside, held for the duration of one sync
- * round. A round loads it once and filters against it in memory: the list is
- * small by design — a growing one is a bug being reported, not a page to
- * paginate — and a lookup per message would put a query on the hot path for a
- * state that is almost always empty.
- */
-export class QuarantinedUids {
-	private readonly keys: ReadonlySet<string>;
-
-	constructor(entries: readonly QuarantineItem[]) {
-		this.keys = new Set(
-			entries.map((entry) =>
-				uidKey(entry.mailboxId, entry.uidValidity, entry.uid),
-			),
-		);
-	}
-
-	get size(): number {
-		return this.keys.size;
-	}
-
-	has(mailboxId: string, uidValidity: number, uid: number): boolean {
-		return this.keys.has(uidKey(mailboxId, uidValidity, uid));
-	}
-}
-
-const uidKey = (mailboxId: string, uidValidity: number, uid: number): string =>
-	`${mailboxId}:${uidValidity}:${uid}`;
-
-export interface QuarantineLogger {
-	info(obj: Record<string, unknown>, msg: string): void;
-	warn(obj: Record<string, unknown>, msg: string): void;
-}
-
-/**
- * Writes the record a message becomes when the sync path cannot apply it
- * (issue #72), and loads the set a round filters against.
- *
- * Only a message defect reaches this class. Deciding that is the caller's job
- * and it is made at exactly one kind of catch site — one narrow enough that
- * the error can only have come from the message itself. An S3, queue or
- * database failure propagates; writing one here would advance a cursor past
- * mail that is fine and tell the user it was unreadable.
- */
-export class QuarantineService {
-	constructor(
-		private readonly repository: IQuarantineRepository,
-		private readonly mailboxSpecialUseService: IMailboxSpecialUseRepository,
-		private readonly workerVersion: string,
-		private readonly log: QuarantineLogger,
-	) {}
-
-	async load(accountConfigId: string): Promise<QuarantinedUids> {
-		return new QuarantinedUids(
-			await this.repository.listByAccountConfigId(accountConfigId),
-		);
-	}
-
-	/**
-	 * Set a message aside. Resolves only once the row is durable, because the
-	 * caller's next act is to let a cursor move past this uid — and a cursor
-	 * that moves past work no record survives is the silent loss this whole
-	 * feature exists to end.
-	 */
-	async record(
-		context: QuarantineContext,
-		uid: number,
-		failure: QuarantineFailure,
-		shape: QuarantineMessageShape = EMPTY_SHAPE,
-	): Promise<void> {
-		// Resolved here rather than per round: a round almost never writes a row,
-		// so the lookup belongs on the write and not on the hot path.
-		const specialUse = await this.mailboxSpecialUseService.listByMailboxId(
-			context.mailboxId,
-		);
-		const mailboxRole = resolveMailboxRole(
-			context.mailboxPath,
-			specialUse.map((entry) => entry.specialUse),
-		);
-
-		await this.repository.upsert({
-			accountConfigId: context.accountConfigId,
-			accountId: context.accountId,
-			mailboxId: context.mailboxId,
-			uidValidity: context.uidValidity,
-			uid,
-			...(mailboxRole ? { mailboxRole } : {}),
-			mailboxPath: context.mailboxPath,
-			quarantinedAt: Date.now(),
-			attempts: context.attempts,
-			failureStage: failure.stage,
-			failureCode: failure.code,
-			failureMessage: failure.message,
-			...(failure.partPath ? { failurePartPath: failure.partPath } : {}),
-			workerVersion: this.workerVersion,
-			...shape,
-		});
-
-		this.log.warn(
-			{
-				mailboxId: context.mailboxId,
-				mailboxPath: context.mailboxPath,
-				uid,
-				uidValidity: context.uidValidity,
-				failureStage: failure.stage,
-				failureCode: failure.code,
-			},
-			"Message quarantined; cursor may advance past it",
-		);
-	}
-}

package/src/snippet.test.ts

@@ -1,213 +0,0 @@
-import assert from "node:assert";
-import { describe, it } from "node:test";
-import {
-	extractSnippetFromEmail,
-	generateSnippet,
-	normalizeSubject,
-	removeQuotedContent,
-} from "./snippet.js";
-
-describe("removeQuotedContent", () => {
-	it("removes content after > quote marker", () => {
-		const text = "Hello\nWorld\n> quoted line\nmore quoted";
-		assert.strictEqual(removeQuotedContent(text), "Hello\nWorld");
-	});
-
-	it("removes content after 'On ... wrote:' pattern", () => {
-		const text = "Hello\nOn Monday, John wrote:\nQuoted content";
-		assert.strictEqual(removeQuotedContent(text), "Hello");
-	});
-
-	it("removes content after original message separator", () => {
-		const text = "Hello\n--- Original Message ---\nQuoted content";
-		assert.strictEqual(removeQuotedContent(text), "Hello");
-	});
-
-	it("removes content after Outlook underline separator", () => {
-		const text = "Hello\n___\nQuoted content";
-		assert.strictEqual(removeQuotedContent(text), "Hello");
-	});
-
-	it("removes content after Outlook forward header", () => {
-		const text = "Hello\nFrom: John Sent: Today To: Jane\nQuoted content";
-		assert.strictEqual(removeQuotedContent(text), "Hello");
-	});
-
-	it("returns full text when no quote markers", () => {
-		const text = "Hello\nWorld\nNo quotes here";
-		assert.strictEqual(removeQuotedContent(text), text);
-	});
-});
-
-describe("normalizeSubject", () => {
-	describe("prefix removal", () => {
-		it("removes Re: prefix", () => {
-			const result = normalizeSubject("Re: Meeting tomorrow");
-			assert.ok(!result.includes("re"));
-			assert.ok(result.includes("meet"));
-		});
-
-		it("removes Fwd: prefix", () => {
-			const result = normalizeSubject("Fwd: Important document");
-			assert.ok(!result.includes("fwd"));
-		});
-
-		it("removes numbered Re: prefix", () => {
-			const result = normalizeSubject("Re[3]: Meeting tomorrow");
-			assert.ok(!result.includes("re"));
-		});
-
-		it("removes multiple prefixes", () => {
-			const result = normalizeSubject("Re: Fwd: Re: Original subject");
-			assert.ok(!result.includes("re"));
-			assert.ok(!result.includes("fwd"));
-		});
-
-		it("removes German Aw: prefix", () => {
-			const result = normalizeSubject("Aw: Besprechung morgen");
-			assert.ok(!result.includes("aw"));
-		});
-
-		it("removes Portuguese Res: prefix", () => {
-			const result = normalizeSubject("Res: Reunião amanhã");
-			assert.ok(!result.includes("res"));
-		});
-	});
-
-	describe("language detection", () => {
-		it("auto-detects English and uses English stemming", () => {
-			const result = normalizeSubject(
-				"Meeting tomorrow about running the project quickly",
-			);
-			// Should stem "running" to "run", "quickly" to "quick"
-			assert.ok(result.includes("run") || result.includes("quick"));
-		});
-
-		it("auto-detects German and uses German processing", () => {
-			const result = normalizeSubject(
-				"Besprechung über die Verbindung und den Projektstand morgen",
-			);
-			// Should process with German stemmer
-			assert.ok(result.length > 0);
-		});
-
-		it("auto-detects French and uses French processing", () => {
-			const result = normalizeSubject(
-				"Réunion demain matin pour discuter du projet",
-			);
-			// Should preserve French accented characters and process
-			assert.ok(result.includes("réunion") || result.includes("reunion"));
-		});
-
-		it("uses provided language override", () => {
-			const result = normalizeSubject("Meeting tomorrow", "en");
-			assert.ok(result.includes("meet"));
-		});
-	});
-
-	describe("normalization", () => {
-		it("removes stopwords", () => {
-			const result = normalizeSubject("The meeting is about the project");
-			// "the" and "is" should be removed
-			assert.ok(!result.split(" ").includes("the"));
-		});
-
-		it("handles Unicode characters", () => {
-			const result = normalizeSubject("Réunion à Paris");
-			// Should not strip accented characters
-			assert.ok(result.includes("réunion") || result.includes("reunion"));
-			assert.ok(result.includes("pari"));
-		});
-
-		it("deduplicates consecutive words", () => {
-			const result = normalizeSubject("Meeting meeting meeting update");
-			// After stemming, should dedupe
-			const words = result.split(" ");
-			for (let i = 1; i < words.length; i++) {
-				assert.notStrictEqual(
-					words[i],
-					words[i - 1],
-					"Should not have consecutive duplicates",
-				);
-			}
-		});
-	});
-});
-
-describe("generateSnippet", () => {
-	it("generates snippet from text", () => {
-		const text = "Hello, this is a test message.";
-		assert.strictEqual(generateSnippet(text), text);
-	});
-
-	it("removes quoted content", () => {
-		const text = "Hello\n> quoted line";
-		assert.strictEqual(generateSnippet(text), "Hello");
-	});
-
-	it("normalizes whitespace", () => {
-		const text = "Hello   world\n\nmultiple  spaces";
-		assert.strictEqual(generateSnippet(text), "Hello world multiple spaces");
-	});
-
-	it("truncates long text at word boundary", () => {
-		const text = "The quick brown fox jumps over the lazy dog repeatedly";
-		const result = generateSnippet(text, 30);
-		assert.ok(result.length <= 30);
-		assert.ok(result.endsWith("..."));
-	});
-
-	it("truncates single long word", () => {
-		const text = "supercalifragilisticexpialidocious";
-		const result = generateSnippet(text, 20);
-		assert.ok(result.endsWith("..."));
-		// When no word boundary found, truncates at maxLength-1 + "..."
-		// so result is at most maxLength + 2 (for the extra chars in "...")
-		assert.ok(result.length <= 22);
-	});
-});
-
-describe("extractSnippetFromEmail", () => {
-	it("prefers plain text over HTML", () => {
-		const result = extractSnippetFromEmail("Plain text", "<p>HTML</p>");
-		assert.strictEqual(result, "Plain text");
-	});
-
-	it("falls back to HTML when no plain text", () => {
-		const result = extractSnippetFromEmail(undefined, "<p>HTML content</p>");
-		assert.ok(result.includes("HTML content"));
-	});
-
-	it("strips HTML tags", () => {
-		const result = extractSnippetFromEmail(
-			undefined,
-			"<p><strong>Bold</strong> text</p>",
-		);
-		assert.ok(!result.includes("<"));
-		assert.ok(!result.includes(">"));
-		assert.ok(result.includes("Bold"));
-		assert.ok(result.includes("text"));
-	});
-
-	it("removes script and style tags", () => {
-		const html = "<style>body{}</style><script>alert(1)</script><p>Content</p>";
-		const result = extractSnippetFromEmail(undefined, html);
-		assert.ok(!result.includes("body"));
-		assert.ok(!result.includes("alert"));
-		assert.ok(result.includes("Content"));
-	});
-
-	it("decodes HTML entities", () => {
-		const html = "<p>&amp; &lt; &gt; &quot; &nbsp;</p>";
-		const result = extractSnippetFromEmail(undefined, html);
-		assert.ok(result.includes("&"));
-		assert.ok(result.includes("<"));
-		assert.ok(result.includes(">"));
-		assert.ok(result.includes('"'));
-	});
-
-	it("returns empty string when no content", () => {
-		const result = extractSnippetFromEmail(undefined, undefined);
-		assert.strictEqual(result, "");
-	});
-});