@remit/mailbox-service 0.0.112 → 0.0.113

package/src/quarantine.ts

@@ -1,229 +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: Pick<MessageItem, "rfc822Size">,
-	data: MessageData,
-	messageIdHeader: string | undefined,
-): 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(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/refusal.ts

@@ -1,29 +0,0 @@
-import type { MailboxItem } from "@remit/data-ports";
-
-export type AccessMode = "read" | "act";
-
-export type Refusal =
-	| { kind: "Invalid"; message: string }
-	| { kind: "Forbidden"; message: string }
-	| { kind: "NotFound"; message: string }
-	| { kind: "Conflict"; message: string }
-	| {
-			kind: "NotSettled";
-			message: string;
-			mailboxId: string;
-			syncStatus: MailboxItem["syncStatus"];
-	  };
-
-export interface Refused {
-	ok: false;
-	refusal: Refusal;
-}
-
-export type Refusable<T> = { ok: true; value: T } | Refused;
-
-export const accept = <T>(value: T): Refusable<T> => ({ ok: true, value });
-
-export const refuse = (refusal: Refusal): Refused => ({ ok: false, refusal });
-
-export const invalid = (message: string): Refused =>
-	refuse({ kind: "Invalid", message });

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, "");
-	});
-});

package/src/snippet.ts

@@ -1,152 +0,0 @@
-/**
- * Snippet generation utilities for email threading.
- *
- * Extracts preview text from email bodies by removing quoted content
- * and normalizing whitespace.
- */
-
-import {
-	createTextNormalizer,
-	type SupportedLanguage,
-} from "./text/normalizer.js";
-
-/**
- * Remove quoted reply content from email body.
- *
- * Stops at common quote indicators:
- * - Lines starting with ">"
- * - "On ... wrote:" patterns
- * - "--- Original Message ---" separators
- * - Outlook-style underline separators
- */
-export const removeQuotedContent = (text: string): string => {
-	const lines = text.split("\n");
-	const result: string[] = [];
-
-	for (const line of lines) {
-		// Stop at quote indicators
-		if (/^>/.test(line)) break;
-		if (/^On .+ wrote:$/i.test(line)) break;
-		if (/^-{3,}\s*Original Message\s*-{3,}$/i.test(line)) break;
-		if (/^_{3,}$/.test(line)) break; // Outlook separator
-		if (/^From:.*Sent:.*To:/i.test(line)) break; // Outlook forward header
-
-		result.push(line);
-	}
-
-	return result.join("\n");
-};
-
-const normalizer = createTextNormalizer();
-
-/**
- * Normalize subject for thread grouping and search.
- *
- * Processing steps:
- * 1. Remove Re:/Fwd:/etc prefixes (multi-language support)
- * 2. Auto-detect language or use provided language
- * 3. Normalize with stemming and stopword removal
- * 4. Deduplicate consecutive words
- *
- * Handles common prefixes across languages:
- * - Re, Fwd, Fw (English)
- * - Aw, Sv, Vs (German, Swedish, Danish)
- * - Ref, Rif (Italian, Spanish)
- * - Odp (Polish)
- * - Ynt (Turkish)
- * - Antw (Dutch)
- * - Res (Portuguese)
- *
- * @param subject - The email subject line
- * @param language - Optional language override (auto-detected if not provided)
- */
-export const normalizeSubject = (
-	subject: string,
-	language?: SupportedLanguage,
-): string => {
-	const SUBJECT_PREFIX_PATTERN =
-		/^(\s*(Re|Fwd|Fw|Aw|Sv|Vs|Ref|Rif|Odp|Ynt|Antw|Res)(\[\d+\])?:\s*)+/i;
-
-	// Step 1: Remove prefixes
-	const withoutPrefix = subject.replace(SUBJECT_PREFIX_PATTERN, "").trim();
-
-	// Step 2: Auto-detect language if not provided
-	const detectedLanguage = language ?? normalizer.detectLanguage(withoutPrefix);
-
-	// Step 3: Normalize with stemming and stopword removal
-	return normalizer.normalize(withoutPrefix, {
-		language: detectedLanguage,
-		stem: true,
-		removeStopwords: true,
-	});
-};
-
-/**
- * Generate a snippet from email text content.
- *
- * @param text - The text content (plain text or stripped HTML)
- * @param maxLength - Maximum snippet length (default 256)
- * @returns Truncated snippet with ellipsis if needed
- */
-export const generateSnippet = (text: string, maxLength = 256): string => {
-	// Remove quoted content
-	const unquoted = removeQuotedContent(text);
-
-	// Normalize whitespace: collapse multiple spaces/newlines to single space
-	const normalized = unquoted.replace(/\s+/g, " ").trim();
-
-	if (normalized.length <= maxLength) {
-		return normalized;
-	}
-
-	// Truncate at word boundary
-	const truncated = normalized.slice(0, maxLength);
-	const lastSpace = truncated.lastIndexOf(" ");
-
-	// If no space found, just truncate
-	if (lastSpace === -1) {
-		return `${truncated.slice(0, maxLength - 1)}...`;
-	}
-
-	// Truncate at word boundary and add ellipsis
-	return `${truncated.slice(0, lastSpace)}...`;
-};
-
-/**
- * Extract text content from parsed email for snippet generation.
- *
- * Prefers plain text over HTML. If only HTML is available,
- * the caller should strip HTML tags before calling generateSnippet.
- *
- * @param textContent - Plain text content (may be undefined)
- * @param htmlContent - HTML content (may be undefined)
- * @param maxLength - Maximum snippet length
- * @returns Generated snippet or empty string
- */
-export const extractSnippetFromEmail = (
-	textContent: string | undefined,
-	htmlContent: string | undefined,
-	maxLength = 256,
-): string => {
-	// Prefer plain text
-	if (textContent) {
-		return generateSnippet(textContent, maxLength);
-	}
-
-	// Fall back to HTML (caller should strip tags)
-	if (htmlContent) {
-		// Basic HTML tag stripping - for more robust handling, use html-to-text
-		const stripped = htmlContent
-			.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
-			.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
-			.replace(/<[^>]+>/g, " ")
-			.replace(/&nbsp;/g, " ")
-			.replace(/&amp;/g, "&")
-			.replace(/&lt;/g, "<")
-			.replace(/&gt;/g, ">")
-			.replace(/&quot;/g, '"');
-		return generateSnippet(stripped, maxLength);
-	}
-
-	return "";
-};