@remit/mailbox-service 0.0.112 → 0.0.114

package/package.json

@@ -1,90 +1,88 @@
 {
-  "name": "@remit/mailbox-service",
-  "version": "0.0.112",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
-    },
-    "./filter-config": {
-      "types": "./src/filters/filter-config.ts",
-      "default": "./src/filters/filter-config.ts"
-    },
-    "./body-sync-queue": {
-      "types": "./src/body-sync-queue.ts",
-      "default": "./src/body-sync-queue.ts"
-    },
-    "./imapflow-connection": {
-      "types": "./src/imapflow-connection.ts",
-      "default": "./src/imapflow-connection.ts"
-    },
-    "./account-credentials": {
-      "types": "./src/account-credentials.ts",
-      "default": "./src/account-credentials.ts"
-    },
-    "./outbox-attachment-content": {
-      "types": "./src/outbox-attachment-content.ts",
-      "default": "./src/outbox-attachment-content.ts"
-    },
-    "./types": {
-      "types": "./src/types.ts",
-      "default": "./src/types.ts"
-    },
-    "./test-helpers/fake-imap": {
-      "types": "./src/test-helpers/fake-imap.ts",
-      "default": "./src/test-helpers/fake-imap.ts"
-    },
-    "./test-helpers/test-queue": {
-      "types": "./src/test-helpers/test-queue.ts",
-      "default": "./src/test-helpers/test-queue.ts"
-    },
-    "./test-helpers/test-store": {
-      "types": "./src/test-helpers/test-store.ts",
-      "default": "./src/test-helpers/test-store.ts"
-    }
-  },
-  "scripts": {
-    "test:typecheck": "tsgo --noEmit",
-    "test:run": "node $NODE_TEST_FLAGS --env-file=../../localhost-test-unit.env --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=86 --test 'src/**/*.test.ts'",
-    "test": "npm run test:typecheck && npm run test:run"
-  },
-  "devDependencies": {
-    "@remit/drizzle-service": "*",
-    "@types/better-sqlite3": "^7.6.13",
-    "aws-sdk-client-mock": "*",
-    "better-sqlite3": "^12.11.1"
-  },
-  "dependencies": {
-    "imapflow": "^1.3.3",
-    "mailparser": "3.12.2",
-    "nodemailer": "^10.0.6",
-    "p-map": "^7.0.4",
-    "tldts": "^7.4.9",
-    "@remit/data-ports": "*",
-    "@remit/domain-enums": "*",
-    "@remit/mail-oauth-service": "*",
-    "@remit/secrets-service": "*",
-    "@remit/sqs-client": "*",
-    "@remit/storage-service": "*",
-    "@aws-sdk/client-sqs": "*",
-    "franc": "*",
-    "natural": "^8.1.1",
-    "stopword": "*",
-    "@types/mailparser": "*",
-    "@types/nodemailer": "*",
-    "@types/stopword": "^2.0.3",
-    "@remit/calendar-service": "*"
-  },
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/remit-mail/reader.git",
-    "directory": "packages/mailbox-service"
-  }
+	"name": "@remit/mailbox-service",
+	"version": "0.0.114",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./filter-config": {
+			"types": "./dist/filters/filter-config.d.ts",
+			"default": "./dist/filters/filter-config.js"
+		},
+		"./body-sync-queue": {
+			"types": "./dist/body-sync-queue.d.ts",
+			"default": "./dist/body-sync-queue.js"
+		},
+		"./imapflow-connection": {
+			"types": "./dist/imapflow-connection.d.ts",
+			"default": "./dist/imapflow-connection.js"
+		},
+		"./account-credentials": {
+			"types": "./dist/account-credentials.d.ts",
+			"default": "./dist/account-credentials.js"
+		},
+		"./outbox-attachment-content": {
+			"types": "./dist/outbox-attachment-content.d.ts",
+			"default": "./dist/outbox-attachment-content.js"
+		},
+		"./types": {
+			"types": "./dist/types.d.ts",
+			"default": "./dist/types.js"
+		},
+		"./test-helpers/fake-imap": {
+			"types": "./dist/test-helpers/fake-imap.d.ts",
+			"default": "./dist/test-helpers/fake-imap.js"
+		},
+		"./test-helpers/test-store": {
+			"types": "./dist/test-helpers/test-store.d.ts",
+			"default": "./dist/test-helpers/test-store.js"
+		}
+	},
+	"scripts": {
+		"prepack": "node ../../npm-scripts/pack-dist.mjs prepack",
+		"postpack": "node ../../npm-scripts/pack-dist.mjs postpack",
+		"test:typecheck": "tsgo --noEmit",
+		"test:run": "node $NODE_TEST_FLAGS --env-file=../../localhost-test-unit.env --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=86 --test 'src/**/*.test.ts'",
+		"test": "npm run test:typecheck && npm run test:run"
+	},
+	"devDependencies": {
+		"@remit/drizzle-service": "*",
+		"@types/better-sqlite3": "^7.6.13",
+		"better-sqlite3": "^12.11.1"
+	},
+	"dependencies": {
+		"imapflow": "^1.3.3",
+		"mailparser": "3.12.2",
+		"nodemailer": "^10.0.6",
+		"p-map": "^7.0.4",
+		"tldts": "^7.4.9",
+		"@remit/data-ports": "*",
+		"@remit/domain-enums": "*",
+		"@remit/mail-oauth-service": "*",
+		"@remit/secrets-service": "*",
+		"@remit/storage-service": "*",
+		"franc": "^6.2.0",
+		"natural": "^8.1.1",
+		"stopword": "^3.1.5",
+		"@types/mailparser": "^3.4.6",
+		"@types/nodemailer": "^8.0.1",
+		"@types/stopword": "^2.0.3",
+		"@remit/calendar-service": "*"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/remit-mail/reader.git",
+		"directory": "packages/mailbox-service"
+	},
+	"files": [
+		"dist"
+	]
 }

package/src/account-credentials.ts

@@ -1,210 +0,0 @@
-/**
- * account-credentials.ts
- *
- * Single place in the codebase that branches on account.authType.
- * All sync handlers (IMAP, SMTP) must call resolveConnectionCredentials
- * rather than duplicating credential logic.
- *
- * Grep-verifiable constraint: `account.authType` must only appear here.
- */
-
-import type { AccountItem } from "@remit/data-ports";
-import { AccountAuthType, ConnectionState } from "@remit/domain-enums";
-import type { MailOAuthService } from "@remit/mail-oauth-service";
-import { RefreshTokenError } from "@remit/mail-oauth-service";
-import {
-	deserializeEncryptedPayload,
-	type SecretsService,
-	serializeEncryptedPayload,
-} from "@remit/secrets-service";
-import type { MailCredentials } from "./types.js";
-
-/** ConnectionState is a const object (not a TS enum); this is its value type. */
-export type ConnectionStateValue =
-	(typeof ConnectionState)[keyof typeof ConnectionState];
-
-/**
- * The fields that say whether an account holds a credential at all. Narrower
- * than AccountItem so a caller holding only an account summary can ask.
- */
-export type StoredCredentialFields = Partial<
-	Pick<AccountItem, "authType" | "passwordHash" | "oauthRefreshTokenHash">
->;
-
-/**
- * No credential of the kind this account's authType needs is stored. An
- * imported account holds none by design until its owner types one, so this is
- * a normal state of the world rather than a fault: no retry can change it, and
- * it is distinct from a credential the mail server rejected.
- *
- * `terminalState` is the connectionState that describes the account while it
- * stays this way, decided here so nothing downstream branches on authType.
- */
-export interface MissingCredential {
-	readonly status: "missing";
-	readonly terminalState: ConnectionStateValue;
-	readonly reason: string;
-}
-
-export type CredentialResolution =
-	| { readonly status: "resolved"; readonly credentials: MailCredentials }
-	| MissingCredential;
-
-type StoredCredential =
-	| { readonly status: "password"; readonly passwordHash: string }
-	| { readonly status: "oauthMicrosoft"; readonly refreshTokenHash: string }
-	| MissingCredential;
-
-const readStoredCredential = (
-	account: StoredCredentialFields,
-): StoredCredential => {
-	const authType = account.authType ?? AccountAuthType.Password;
-
-	if (authType === AccountAuthType.OauthMicrosoft) {
-		if (!account.oauthRefreshTokenHash) {
-			return {
-				status: "missing",
-				terminalState: ConnectionState.ReauthRequired,
-				reason: "authType=oauthMicrosoft but no oauthRefreshTokenHash",
-			};
-		}
-		return {
-			status: "oauthMicrosoft",
-			refreshTokenHash: account.oauthRefreshTokenHash,
-		};
-	}
-
-	if (!account.passwordHash) {
-		return {
-			status: "missing",
-			terminalState: ConnectionState.CredentialsMissing,
-			reason: "authType=password but no passwordHash",
-		};
-	}
-	return { status: "password", passwordHash: account.passwordHash };
-};
-
-/**
- * Whether the account holds the credential its authType requires.
- *
- * Keyed on the stored credential, never on `connectionState`: PATCH
- * /accounts/{id} writes a password without clearing `credentials_missing` —
- * only a successful connect clears it, via markAuthenticated — so a
- * state-based check would go on skipping an account that can sync perfectly
- * well.
- */
-export const hasStoredCredential = (account: StoredCredentialFields): boolean =>
-	readStoredCredential(account).status !== "missing";
-
-export interface AccountCredentialsDeps {
-	secrets: Pick<SecretsService, "decrypt" | "encrypt">;
-	tokenService: Pick<MailOAuthService, "getAccessToken">;
-	/**
-	 * Called when the OAuth provider rotated the refresh token.
-	 * Must be awaited BEFORE the credentials are returned so the new token
-	 * is persisted before any IMAP command is issued.
-	 */
-	persistRotatedToken: (
-		accountId: string,
-		encryptedHash: string,
-		updatedAt: number,
-	) => Promise<void>;
-}
-
-/**
- * Resolve IMAP credentials for an account.
- *
- * - Password accounts: decrypt passwordHash → return password credential.
- * - OAuth accounts: decrypt oauthRefreshTokenHash → mint access token via
- *   tokenService.  If the provider rotated the refresh token, persist the
- *   new token via `deps.persistRotatedToken` BEFORE returning credentials.
- *
- * Returns `{ status: "missing" }` when the account stores no credential —
- * an expected outcome every caller settles terminally, never retries.
- *
- * Throws `RefreshTokenError` on OAuth failures; callers should handle:
- * - `kind === "reauth-required"` → set connectionState to reauth_required, ACK
- * - `kind === "transient"` → rethrow (SQS retry)
- * - `kind === "config"` → rethrow (SQS retry / alert)
- */
-export const resolveConnectionCredentials = async (
-	account: AccountItem,
-	deps: AccountCredentialsDeps,
-): Promise<CredentialResolution> => {
-	const stored = readStoredCredential(account);
-
-	if (stored.status === "missing") {
-		return stored;
-	}
-
-	if (stored.status === "oauthMicrosoft") {
-		return {
-			status: "resolved",
-			credentials: await resolveOauthCredentials(
-				account.accountId,
-				stored.refreshTokenHash,
-				deps,
-			),
-		};
-	}
-
-	return {
-		status: "resolved",
-		credentials: await resolvePasswordCredentials(
-			stored.passwordHash,
-			deps.secrets,
-		),
-	};
-};
-
-const resolvePasswordCredentials = async (
-	passwordHash: string,
-	secrets: Pick<SecretsService, "decrypt">,
-): Promise<MailCredentials> => {
-	const password = await secrets.decrypt(
-		deserializeEncryptedPayload(JSON.parse(passwordHash)),
-	);
-	return { kind: "password", password };
-};
-
-const resolveOauthCredentials = async (
-	accountId: string,
-	refreshTokenHash: string,
-	deps: AccountCredentialsDeps,
-): Promise<MailCredentials> => {
-	const refreshToken = await deps.secrets.decrypt(
-		deserializeEncryptedPayload(JSON.parse(refreshTokenHash)),
-	);
-
-	// getAccessToken throws RefreshTokenError on failure
-	const tokenSet = await deps.tokenService.getAccessToken(
-		accountId,
-		refreshToken,
-	);
-
-	// If the provider rotated the refresh token, persist it BEFORE returning.
-	// This guarantees the new token is stored even if a subsequent error occurs.
-	if (tokenSet.refreshToken) {
-		const encryptedPayload = await deps.secrets.encrypt(tokenSet.refreshToken);
-		const encryptedHash = JSON.stringify(
-			serializeEncryptedPayload(encryptedPayload),
-		);
-		await deps.persistRotatedToken(accountId, encryptedHash, Date.now());
-	}
-
-	return { kind: "accessToken", accessToken: tokenSet.accessToken };
-};
-
-/**
- * Build the encrypted hash string for an OAuth refresh token.
- * Helper used when first storing an OAuth token (e.g. after OAuth callback).
- */
-export const encryptRefreshToken = async (
-	refreshToken: string,
-	secrets: Pick<SecretsService, "encrypt">,
-): Promise<string> => {
-	const payload = await secrets.encrypt(refreshToken);
-	return JSON.stringify(serializeEncryptedPayload(payload));
-};
-
-export { ConnectionState, RefreshTokenError };

package/src/attribute-mapper.test.ts

@@ -1,104 +0,0 @@
-import assert from "node:assert";
-import { describe, it } from "node:test";
-import { MailboxAttribute, MailboxSpecialUse } from "@remit/domain-enums";
-import {
-	hasChildren,
-	isNoSelect,
-	parseImapAttributes,
-} from "./attribute-mapper.js";
-
-describe("parseImapAttributes special-use", () => {
-	it("maps an IMAP \\Junk attribute to the canonical bare enum value", () => {
-		const parsed = parseImapAttributes(["\\Junk"]);
-		assert.deepStrictEqual(parsed.specialUse, [MailboxSpecialUse.Junk]);
-		assert.strictEqual(parsed.specialUse[0], "Junk");
-	});
-
-	it("normalizes case-insensitive special-use attributes", () => {
-		const parsed = parseImapAttributes(["\\junk", "\\SENT", "\\Drafts"]);
-		assert.deepStrictEqual(parsed.specialUse, [
-			MailboxSpecialUse.Junk,
-			MailboxSpecialUse.Sent,
-			MailboxSpecialUse.Drafts,
-		]);
-	});
-
-	it("emits every value in the bare form the runtime stores and the spec validates", () => {
-		const parsed = parseImapAttributes([
-			"\\All",
-			"\\Archive",
-			"\\Drafts",
-			"\\Flagged",
-			"\\Junk",
-			"\\Sent",
-			"\\Trash",
-			"\\Important",
-		]);
-		assert.deepStrictEqual(parsed.specialUse, [
-			"All",
-			"Archive",
-			"Drafts",
-			"Flagged",
-			"Junk",
-			"Sent",
-			"Trash",
-			"Important",
-		]);
-		assert.ok(parsed.specialUse.every((v) => !v.startsWith("\\")));
-	});
-
-	it("separates standard attributes from special-use", () => {
-		const parsed = parseImapAttributes(["\\HasChildren", "\\Sent"]);
-		assert.deepStrictEqual(parsed.specialUse, [MailboxSpecialUse.Sent]);
-		assert.deepStrictEqual(parsed.attributes, ["\\HasChildren"]);
-	});
-
-	it("keeps standard attributes in the RFC 9051 backslash-prefixed form", () => {
-		const parsed = parseImapAttributes([
-			"\\NonExistent",
-			"\\Noinferiors",
-			"\\Noselect",
-			"\\HasChildren",
-			"\\HasNoChildren",
-			"\\Marked",
-			"\\Unmarked",
-			"\\Subscribed",
-			"\\Remote",
-		]);
-		assert.deepStrictEqual(parsed.attributes, [
-			"\\NonExistent",
-			"\\Noinferiors",
-			"\\Noselect",
-			"\\HasChildren",
-			"\\HasNoChildren",
-			"\\Marked",
-			"\\Unmarked",
-			"\\Subscribed",
-			"\\Remote",
-		]);
-		assert.deepStrictEqual(parsed.attributes, Object.values(MailboxAttribute));
-	});
-
-	it("collects unknown attributes without dropping them", () => {
-		const parsed = parseImapAttributes(["\\Junk", "\\SomethingNovel"]);
-		assert.deepStrictEqual(parsed.specialUse, [MailboxSpecialUse.Junk]);
-		assert.deepStrictEqual(parsed.unknown, ["\\SomethingNovel"]);
-	});
-
-	it("yields no special-use for a plain folder", () => {
-		const parsed = parseImapAttributes(["\\HasNoChildren"]);
-		assert.deepStrictEqual(parsed.specialUse, []);
-	});
-});
-
-describe("attribute predicates", () => {
-	it("detects no-select mailboxes", () => {
-		assert.strictEqual(isNoSelect(["\\Noselect"]), true);
-		assert.strictEqual(isNoSelect(["\\HasChildren"]), false);
-	});
-
-	it("detects mailboxes with children", () => {
-		assert.strictEqual(hasChildren(["\\HasChildren"]), true);
-		assert.strictEqual(hasChildren(["\\HasNoChildren"]), false);
-	});
-});

package/src/attribute-mapper.ts

@@ -1,148 +0,0 @@
-/**
- * Maps IMAP mailbox attributes to entity enum values
- */
-
-import { MailboxAttribute, MailboxSpecialUse } from "@remit/domain-enums";
-
-// Type for enum values
-type MailboxAttributeValue =
-	(typeof MailboxAttribute)[keyof typeof MailboxAttribute];
-type MailboxSpecialUseValue =
-	(typeof MailboxSpecialUse)[keyof typeof MailboxSpecialUse];
-
-/**
- * Map from IMAP attribute strings to MailboxAttribute enum values.
- * MailboxAttribute keeps the RFC 9051 backslash prefix; MailboxSpecialUse
- * below is a canonical bare designation, so only that map strips it.
- */
-const ATTRIBUTE_MAP: Record<string, MailboxAttributeValue> = {
-	"\\NonExistent": MailboxAttribute.NonExistent,
-	"\\Noinferiors": MailboxAttribute.NoInferiors,
-	"\\Noselect": MailboxAttribute.NoSelect,
-	"\\HasChildren": MailboxAttribute.HasChildren,
-	"\\HasNoChildren": MailboxAttribute.HasNoChildren,
-	"\\Marked": MailboxAttribute.Marked,
-	"\\Unmarked": MailboxAttribute.Unmarked,
-	"\\Subscribed": MailboxAttribute.Subscribed,
-	"\\Remote": MailboxAttribute.Remote,
-};
-
-/**
- * Map from IMAP special-use attribute strings to MailboxSpecialUse enum values
- */
-const SPECIAL_USE_MAP: Record<string, MailboxSpecialUseValue> = {
-	"\\All": MailboxSpecialUse.All,
-	"\\Archive": MailboxSpecialUse.Archive,
-	"\\Drafts": MailboxSpecialUse.Drafts,
-	"\\Flagged": MailboxSpecialUse.Flagged,
-	"\\Junk": MailboxSpecialUse.Junk,
-	"\\Sent": MailboxSpecialUse.Sent,
-	"\\Trash": MailboxSpecialUse.Trash,
-	"\\Important": MailboxSpecialUse.Important,
-};
-
-/**
- * Set of all known special-use attributes for quick lookup
- */
-const SPECIAL_USE_ATTRS = new Set(Object.keys(SPECIAL_USE_MAP));
-
-/**
- * Result of parsing IMAP attributes
- */
-export interface ParsedAttributes {
-	/** Standard mailbox attributes */
-	attributes: MailboxAttributeValue[];
-	/** Special-use designations */
-	specialUse: MailboxSpecialUseValue[];
-	/** Unknown attributes that couldn't be mapped */
-	unknown: string[];
-}
-
-/**
- * Parse IMAP mailbox attributes into our enum types
- *
- * IMAP attributes come as strings like "\\Noselect", "\\Drafts", etc.
- * This function categorizes them into:
- * - Standard attributes (MailboxAttribute)
- * - Special-use attributes (MailboxSpecialUse)
- * - Unknown attributes
- */
-export const parseImapAttributes = (attribs: string[]): ParsedAttributes => {
-	const result: ParsedAttributes = {
-		attributes: [],
-		specialUse: [],
-		unknown: [],
-	};
-
-	for (const attr of attribs) {
-		// Normalize attribute (IMAP attributes are case-insensitive)
-		const normalized = normalizeAttribute(attr);
-
-		if (SPECIAL_USE_ATTRS.has(normalized)) {
-			const specialUse = SPECIAL_USE_MAP[normalized];
-			if (specialUse) {
-				result.specialUse.push(specialUse);
-			}
-		} else if (ATTRIBUTE_MAP[normalized]) {
-			result.attributes.push(ATTRIBUTE_MAP[normalized]);
-		} else {
-			result.unknown.push(attr);
-		}
-	}
-
-	return result;
-};
-
-/**
- * Normalize an IMAP attribute to canonical form
- *
- * IMAP attributes are case-insensitive per RFC 9051.
- * We normalize to the canonical form used in the RFCs.
- */
-const normalizeAttribute = (attr: string): string => {
-	// Handle common variations
-	const lower = attr.toLowerCase();
-
-	// Map common case variations to canonical form
-	const canonicalMap: Record<string, string> = {
-		"\\nonexistent": "\\NonExistent",
-		"\\noinferiors": "\\Noinferiors",
-		"\\noselect": "\\Noselect",
-		"\\haschildren": "\\HasChildren",
-		"\\hasnochildren": "\\HasNoChildren",
-		"\\marked": "\\Marked",
-		"\\unmarked": "\\Unmarked",
-		"\\subscribed": "\\Subscribed",
-		"\\remote": "\\Remote",
-		"\\all": "\\All",
-		"\\archive": "\\Archive",
-		"\\drafts": "\\Drafts",
-		"\\flagged": "\\Flagged",
-		"\\junk": "\\Junk",
-		"\\sent": "\\Sent",
-		"\\trash": "\\Trash",
-		"\\important": "\\Important",
-	};
-
-	return canonicalMap[lower] ?? attr;
-};
-
-/**
- * Check if an attribute indicates the mailbox cannot be selected
- */
-export const isNoSelect = (attribs: string[]): boolean => {
-	return attribs.some((attr) => {
-		const normalized = normalizeAttribute(attr);
-		return normalized === "\\Noselect" || normalized === "\\NonExistent";
-	});
-};
-
-/**
- * Check if an attribute indicates the mailbox has children
- */
-export const hasChildren = (attribs: string[]): boolean => {
-	return attribs.some((attr) => {
-		const normalized = normalizeAttribute(attr);
-		return normalized === "\\HasChildren";
-	});
-};