@remit/config-transfer 0.0.1

package/src/export.ts

@@ -0,0 +1,384 @@
+import {
+	CONFIG_KIND,
+	type ConfigAccount,
+	type ConfigAddressFlags,
+	type ConfigAddressFlagsEntry,
+	type ConfigFilter,
+	type ConfigLabel,
+	CURRENT_SCHEMA_VERSION,
+	type ReaderConfigDocument,
+	ReaderConfigDocumentSchema,
+} from "@remit/config-format";
+import type {
+	AccountItem,
+	AddressFlags,
+	AddressItem,
+	FilterAnchorItem,
+	FilterItem,
+	LabelItem,
+	MailboxItem,
+} from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { AccountAuthType } from "@remit/domain-enums";
+import type {
+	ConfigExportIdentity,
+	ConfigExportRepositories,
+} from "./repositories.js";
+import {
+	type AccountSettingsView,
+	emptyAccountSettings,
+	type MailboxSettingsView,
+	readSettings,
+	type SettingsView,
+} from "./settings.js";
+
+/**
+ * The named sentinel a Filter carries for "no action of this kind". Filter
+ * stores `"None"` rather than an absent field, so the export has to read the
+ * sentinel rather than a nullish check.
+ */
+const NO_ACTION = "None";
+
+/** Which credential the account needs before it can sync again. */
+const credentialsFor = (account: AccountItem): ConfigAccount["credentials"] =>
+	account.authType === AccountAuthType.OauthMicrosoft
+		? { required: "oauth", provider: "microsoft" }
+		: { required: "password" };
+
+/**
+ * Every mailbox in the configuration, by id, plus which account holds it.
+ * Folder-referencing config is stored against mailbox ids, and every one of
+ * them is regenerated by the next discovery — resolving each to its IMAP path
+ * here is what makes the file mean anything on the other side.
+ */
+interface MailboxIndex {
+	pathOf: (mailboxId: string) => string | undefined;
+	accountOf: (mailboxId: string) => string | undefined;
+	pathsOfAccount: (accountId: string) => Map<string, string>;
+}
+
+const buildMailboxIndex = (
+	byAccount: ReadonlyMap<string, MailboxItem[]>,
+): MailboxIndex => {
+	const paths = new Map<string, string>();
+	const owners = new Map<string, string>();
+	const perAccount = new Map<string, Map<string, string>>();
+	for (const [accountId, mailboxes] of byAccount) {
+		const own = new Map<string, string>();
+		for (const mailbox of mailboxes) {
+			paths.set(mailbox.mailboxId, mailbox.fullPath);
+			owners.set(mailbox.mailboxId, accountId);
+			own.set(mailbox.mailboxId, mailbox.fullPath);
+		}
+		perAccount.set(accountId, own);
+	}
+	return {
+		pathOf: (mailboxId) => paths.get(mailboxId),
+		accountOf: (mailboxId) => owners.get(mailboxId),
+		pathsOfAccount: (accountId) => perAccount.get(accountId) ?? new Map(),
+	};
+};
+
+/**
+ * A role's folder, by path. The live mailbox first; the path recorded when the
+ * appointment was made when the mailbox is gone, so a folder another client
+ * deleted still travels as the user's decision rather than vanishing.
+ */
+const folderRolesOf = (
+	settings: AccountSettingsView,
+	paths: ReadonlyMap<string, string>,
+): ConfigAccount["folderRoles"] => {
+	const roles: ConfigAccount["folderRoles"] = [];
+	for (const [role, appointment] of settings.roles) {
+		const folderPath =
+			paths.get(appointment.mailboxId) ?? appointment.lastKnownPath;
+		if (folderPath === undefined || folderPath === "") continue;
+		roles.push({ role, folderPath });
+	}
+	return roles;
+};
+
+const folderOverridesOf = (
+	accountId: string,
+	index: MailboxIndex,
+	byMailbox: ReadonlyMap<string, MailboxSettingsView>,
+): ConfigAccount["folderOverrides"] => {
+	const overrides: ConfigAccount["folderOverrides"] = [];
+	for (const [mailboxId, override] of byMailbox) {
+		if (index.accountOf(mailboxId) !== accountId) continue;
+		const folderPath = index.pathOf(mailboxId);
+		if (folderPath === undefined) continue;
+		overrides.push({
+			folderPath,
+			displayName: override.displayName,
+			muted: override.muted,
+		});
+	}
+	return overrides;
+};
+
+/**
+ * The pinned folders this account holds. The setting is one list for the whole
+ * configuration while the document spells the list per account, so each path is
+ * resolved against the account's own folders — the same rule every other folder
+ * reference here follows, and the only one that cannot put a path on an account
+ * that has no such folder.
+ */
+const pinnedFoldersOf = (
+	pinned: readonly string[],
+	paths: ReadonlyMap<string, string>,
+): ConfigAccount["pinnedFolders"] => {
+	const held = new Set(paths.values());
+	return pinned.filter((folderPath) => held.has(folderPath));
+};
+
+const toConfigAccount = (
+	account: AccountItem,
+	settings: AccountSettingsView,
+	pinned: readonly string[],
+	index: MailboxIndex,
+	byMailbox: ReadonlyMap<string, MailboxSettingsView>,
+): ConfigAccount => ({
+	// Field by field, never a spread of the stored row: the credential fields
+	// are absent because nothing here names them, which is a guarantee that
+	// survives a new column arriving on the entity.
+	accountId: account.accountId,
+	email: account.email,
+	username: account.username,
+	authType: account.authType,
+	credentials: credentialsFor(account),
+	isActive: account.isActive,
+	imap: {
+		host: account.imapHost,
+		port: account.imapPort,
+		tls: account.imapTls,
+		startTls: account.imapStartTls,
+	},
+	smtp: {
+		enabled: account.smtpEnabled,
+		host: account.smtpHost,
+		port: account.smtpPort,
+		tls: account.smtpTls,
+		startTls: account.smtpStartTls,
+		username: account.smtpUsername,
+	},
+	displayName: settings.displayName,
+	muted: settings.muted,
+	composeLanguages: settings.composeLanguages,
+	signature: {
+		plainText: settings.signaturePlainText,
+		html: settings.signatureHtml,
+	},
+	folderRoles: folderRolesOf(settings, index.pathsOfAccount(account.accountId)),
+	folderOverrides: folderOverridesOf(account.accountId, index, byMailbox),
+	pinnedFolders: pinnedFoldersOf(
+		pinned,
+		index.pathsOfAccount(account.accountId),
+	),
+});
+
+const toConfigLabel = (label: LabelItem): ConfigLabel => ({
+	name: label.name,
+	color: label.color,
+});
+
+const toConfigFilter = (
+	filter: FilterItem,
+	anchor: FilterAnchorItem | undefined,
+	labelNames: ReadonlyMap<string, string>,
+	index: MailboxIndex,
+): ConfigFilter => {
+	const actionAccountId =
+		filter.actionMailboxId === NO_ACTION
+			? undefined
+			: index.accountOf(filter.actionMailboxId);
+	const actionPath =
+		filter.actionMailboxId === NO_ACTION
+			? undefined
+			: index.pathOf(filter.actionMailboxId);
+	return {
+		name: filter.name,
+		scope: filter.scope,
+		expiresAt: filter.expiresAt ?? null,
+		matchOperator: filter.matchOperator,
+		literalClauses: filter.literalClauses.map((clause) => ({
+			field: clause.field,
+			value: clause.value,
+		})),
+		actionLabelName:
+			filter.actionLabelId === NO_ACTION
+				? null
+				: (labelNames.get(filter.actionLabelId) ?? null),
+		actionFolder:
+			actionAccountId === undefined || actionPath === undefined
+				? null
+				: { accountId: actionAccountId, folderPath: actionPath },
+		// The stored vector is a function of the model that produced it, so it
+		// means nothing on an instance running another one. The source text is
+		// what travels; import re-embeds from it.
+		anchor: anchor
+			? {
+					sourceText: anchor.anchorSourceText,
+					embeddingId: anchor.anchorEmbeddingId,
+					sourceMessageId: anchor.anchorMessageId,
+				}
+			: null,
+	};
+};
+
+/**
+ * The flags a user set, named one at a time. `wellknown` and `junkOnly` have no
+ * line here and so cannot be carried whatever the stored row holds — the same
+ * structural guarantee the account's credential fields get.
+ */
+const userFlagsOf = (flags: AddressFlags | undefined): ConfigAddressFlags => {
+	const stored = flags ?? {};
+	const user: ConfigAddressFlags = {};
+	if (stored.trusted) user.trusted = stored.trusted;
+	if (stored.blocked) user.blocked = stored.blocked;
+	if (stored.muted) user.muted = stored.muted;
+	if (stored.vip) user.vip = stored.vip;
+	if (stored.category) user.category = stored.category;
+	if (stored.autoArchive) user.autoArchive = stored.autoArchive;
+	if (stored.unsubscribed) user.unsubscribed = stored.unsubscribed;
+	return user;
+};
+
+/**
+ * An address exports exactly when the user decided something about it. A row
+ * carrying only `wellknown` or `junkOnly` was decided by the machine, and a row
+ * carrying nothing was merely harvested from an envelope; both come back on
+ * their own once mail resyncs.
+ */
+export const carriesUserFlag = (flags: AddressFlags | undefined): boolean =>
+	Object.keys(userFlagsOf(flags)).length > 0;
+
+const toConfigAddressFlags = (
+	address: AddressItem,
+): ConfigAddressFlagsEntry => ({
+	normalizedEmail: address.normalizedEmail,
+	displayName: address.displayName ?? "",
+	flags: userFlagsOf(address.flags),
+});
+
+const readAddresses = async (
+	repositories: ConfigExportRepositories,
+	accountConfigId: string,
+): Promise<AddressItem[]> => {
+	const addresses: AddressItem[] = [];
+	let cursor: string | undefined;
+	do {
+		const page = await repositories.address.listByAccountConfig({
+			accountConfigId,
+			cursor,
+		});
+		addresses.push(...page.items);
+		cursor = page.continuationToken;
+	} while (cursor);
+	return addresses;
+};
+
+const accountSettingsOf = (
+	settings: SettingsView,
+	accountId: string,
+): AccountSettingsView =>
+	settings.byAccount.get(accountId) ?? emptyAccountSettings();
+
+/**
+ * Read one configuration out as a v1 document: every decision its owner made,
+ * no credential, and no fact IMAP will hand back on the next resync.
+ *
+ * The result is parsed by the format's own schema before it is returned, so a
+ * reader that has drifted from the format fails here — while there is still a
+ * database to read again — rather than on the import that needed the file.
+ */
+export const readConfigForExport = async (
+	repositories: ConfigExportRepositories,
+	accountConfigId: string,
+	identity: ConfigExportIdentity,
+): Promise<ReaderConfigDocument> => {
+	const [accountConfig, accounts, settingRows, labels, filters, anchors] =
+		await Promise.all([
+			// A configuration nobody has added an account to yet holds no row. That
+			// is an empty export, not a failure: the file is the migration safety
+			// net, and refusing to write one is the outcome it exists to prevent.
+			repositories.accountConfig
+				.get(accountConfigId)
+				.catch((error: unknown) => {
+					if (error instanceof NotFoundError) return undefined;
+					throw error;
+				}),
+			repositories.account.listAllByAccountConfig(accountConfigId),
+			repositories.accountSetting.listByAccountConfig(accountConfigId),
+			repositories.label.listByAccountConfig(accountConfigId),
+			repositories.filter.listByAccountConfig(accountConfigId),
+			repositories.filterAnchor.listByAccountConfig(accountConfigId),
+		]);
+
+	const liveAccounts = accounts.filter(
+		(account) => account.deletedAt === undefined,
+	);
+	const mailboxesByAccount = new Map<string, MailboxItem[]>(
+		await Promise.all(
+			liveAccounts.map(
+				async (account): Promise<[string, MailboxItem[]]> => [
+					account.accountId,
+					await repositories.mailbox.listAllByAccount(account.accountId),
+				],
+			),
+		),
+	);
+
+	const settings = readSettings(settingRows);
+	const index = buildMailboxIndex(mailboxesByAccount);
+	const labelNames = new Map(
+		labels.map((label) => [label.labelId, label.name] as const),
+	);
+	const anchorsByFilter = new Map(
+		anchors.map((anchor) => [anchor.filterId, anchor] as const),
+	);
+	const addresses = await readAddresses(repositories, accountConfigId);
+
+	const document: ReaderConfigDocument = {
+		kind: CONFIG_KIND,
+		schemaVersion: CURRENT_SCHEMA_VERSION,
+		generator: {
+			app: identity.app,
+			version: identity.version,
+			exportedAt: identity.exportedAt,
+		},
+		provenance: {
+			accountConfigId,
+			instance: identity.instance,
+		},
+		accountConfig: {
+			name: accountConfig?.name ?? "",
+			...(settings.defaultComposerFormat === undefined
+				? {}
+				: { defaultComposerFormat: settings.defaultComposerFormat }),
+		},
+		accounts: liveAccounts.map((account) =>
+			toConfigAccount(
+				account,
+				accountSettingsOf(settings, account.accountId),
+				settings.pinnedFolders,
+				index,
+				settings.byMailbox,
+			),
+		),
+		labels: labels.map(toConfigLabel),
+		filters: filters.map((filter) =>
+			toConfigFilter(
+				filter,
+				anchorsByFilter.get(filter.filterId),
+				labelNames,
+				index,
+			),
+		),
+		addressFlags: addresses
+			.filter((address) => carriesUserFlag(address.flags))
+			.map(toConfigAddressFlags),
+	};
+
+	return ReaderConfigDocumentSchema.parse(document);
+};

package/src/fixtures.ts

@@ -0,0 +1,210 @@
+import type {
+	AccountConfigItem,
+	AccountItem,
+	AccountSettingItem,
+	AddressItem,
+	FilterAnchorItem,
+	FilterItem,
+	LabelItem,
+	MailboxItem,
+} from "@remit/data-ports";
+import type { ConfigExportRepositories } from "./repositories.js";
+
+/**
+ * A configuration held in memory, wired up as the repositories the export
+ * reads. Fixtures rather than a database: what is under test is which decisions
+ * reach the file and which never do, and a store is not the thing that decides
+ * either.
+ */
+export interface ConfigFixture {
+	accountConfig: AccountConfigItem;
+	accounts: AccountItem[];
+	settings: AccountSettingItem[];
+	mailboxes: MailboxItem[];
+	labels: LabelItem[];
+	filters: FilterItem[];
+	anchors: FilterAnchorItem[];
+	addresses: AddressItem[];
+	/** Page size for the address listing, so paging is exercised. */
+	addressPageSize?: number;
+}
+
+export const ACCOUNT_CONFIG_ID = "0d9c8b7a6e5f4d3cb2a10f9e8";
+export const PASSWORD_ACCOUNT_ID = "6f4c2c309a2c4a7f9f9f1f2c3";
+export const OAUTH_ACCOUNT_ID = "b3a1d0c75e644f1b8c2a77e9d";
+
+const NOW = 1756281600000;
+
+export const makeAccountConfig = (
+	overrides: Partial<AccountConfigItem> = {},
+): AccountConfigItem => ({
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	userId: "7c1f0a2e-3b4d-4c5e-8f90-a1b2c3d4e5f6",
+	name: "Matthijs",
+	state: "active",
+	createdAt: NOW,
+	updatedAt: NOW,
+	...overrides,
+});
+
+export const makeAccount = (
+	overrides: Partial<AccountItem> & Pick<AccountItem, "accountId">,
+): AccountItem => ({
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	username: "matthijs@ischen.nl",
+	email: "matthijs@ischen.nl",
+	authType: "password",
+	imapHost: "imap.ischen.nl",
+	imapPort: 993,
+	imapTls: true,
+	imapStartTls: false,
+	smtpEnabled: true,
+	smtpHost: "smtp.ischen.nl",
+	smtpPort: 587,
+	smtpTls: false,
+	smtpStartTls: true,
+	smtpUsername: "",
+	isActive: true,
+	connectionState: "authenticated",
+	createdAt: NOW,
+	updatedAt: NOW,
+	...overrides,
+});
+
+export const makeMailbox = (
+	overrides: Partial<MailboxItem> &
+		Pick<MailboxItem, "mailboxId" | "accountId" | "fullPath">,
+): MailboxItem => ({
+	namespaceType: "personal",
+	namespacePrefix: "",
+	hierarchyDelimiter: ".",
+	uidValidity: 1,
+	uidNext: 2,
+	highestModseq: "1",
+	messageCount: 0,
+	unseenCount: 0,
+	deletedCount: 0,
+	totalSize: 0,
+	lastSyncUid: 0,
+	highWaterMarkUid: 0,
+	lastMessageSyncAt: NOW,
+	parentMailboxId: "",
+	cursorState: "normal",
+	createdAt: NOW,
+	updatedAt: NOW,
+	...overrides,
+});
+
+export const makeSetting = (
+	name: string,
+	value: AccountSettingItem["value"],
+): AccountSettingItem => ({
+	accountSettingId: `setting:${name}`,
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	name,
+	value,
+	createdAt: NOW,
+	updatedAt: NOW,
+});
+
+export const makeLabel = (
+	overrides: Partial<LabelItem> & Pick<LabelItem, "labelId" | "name">,
+): LabelItem => ({
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	normalizedName: overrides.name.toLowerCase(),
+	color: "Default",
+	createdAt: NOW,
+	updatedAt: NOW,
+	...overrides,
+});
+
+export const makeFilter = (
+	overrides: Partial<FilterItem> & Pick<FilterItem, "filterId" | "name">,
+): FilterItem => ({
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	scope: "Standing",
+	state: "Active",
+	hasAnchor: false,
+	ruleChangedAt: NOW,
+	actionChangedAt: NOW,
+	matchOperator: "And",
+	literalClauses: [],
+	actionLabelId: "None",
+	actionMailboxId: "None",
+	createdAt: NOW,
+	updatedAt: NOW,
+	...overrides,
+});
+
+export const makeAnchor = (
+	overrides: Partial<FilterAnchorItem> & Pick<FilterAnchorItem, "filterId">,
+): FilterAnchorItem => ({
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	anchorEmbedding: [0.11, 0.22, 0.33],
+	anchorEmbeddingId: "amazon.titan-embed-text-v2:0@1024",
+	anchorSourceText: "the release note this filter was drawn from",
+	anchorMessageId: "2c9e4b117d5a4f609a315b8c0",
+	createdAt: NOW,
+	updatedAt: NOW,
+	...overrides,
+});
+
+export const makeAddress = (
+	overrides: Partial<AddressItem> &
+		Pick<AddressItem, "addressId" | "normalizedEmail">,
+): AddressItem => ({
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	localPart: overrides.normalizedEmail.split("@")[0] ?? "",
+	domain: overrides.normalizedEmail.split("@")[1] ?? "",
+	normalizedCompound: overrides.normalizedEmail,
+	flags: {},
+	inboundCount: 0,
+	outboundCount: 0,
+	replyCount: 0,
+	lastInboundAt: 0,
+	lastReplyAt: 0,
+	createdAt: NOW,
+	updatedAt: NOW,
+	...overrides,
+});
+
+/** The fixture, behind the repository interfaces the export takes. */
+export const asRepositories = (
+	fixture: ConfigFixture,
+): ConfigExportRepositories => ({
+	accountConfig: {
+		get: async () => fixture.accountConfig,
+	},
+	account: {
+		listAllByAccountConfig: async () => fixture.accounts,
+	},
+	accountSetting: {
+		listByAccountConfig: async () => fixture.settings,
+	},
+	mailbox: {
+		listAllByAccount: async (accountId: string) =>
+			fixture.mailboxes.filter((mailbox) => mailbox.accountId === accountId),
+	},
+	label: {
+		listByAccountConfig: async () => fixture.labels,
+	},
+	filter: {
+		listByAccountConfig: async () => fixture.filters,
+	},
+	filterAnchor: {
+		listByAccountConfig: async () => fixture.anchors,
+	},
+	address: {
+		listByAccountConfig: async ({ cursor }) => {
+			const size = fixture.addressPageSize ?? fixture.addresses.length + 1;
+			const offset = cursor ? Number(cursor) : 0;
+			const items = fixture.addresses.slice(offset, offset + size);
+			const next = offset + size;
+			return {
+				items,
+				continuationToken:
+					next < fixture.addresses.length ? String(next) : undefined,
+			};
+		},
+	},
+});

package/src/index.ts

@@ -0,0 +1,5 @@
+export { carriesUserFlag, readConfigForExport } from "./export.js";
+export type {
+	ConfigExportIdentity,
+	ConfigExportRepositories,
+} from "./repositories.js";

package/src/repositories.ts

@@ -0,0 +1,38 @@
+import type {
+	AccountConfigItem,
+	IAccountRepository,
+	IAccountSettingRepository,
+	IAddressRepository,
+	IFilterAnchorRepository,
+	IFilterRepository,
+	ILabelRepository,
+	IMailboxRepository,
+} from "@remit/data-ports";
+
+/**
+ * Everything the export reads, and nothing else. Repositories rather than a
+ * client or an HTTP surface: the same reader answers `GET /config/export` in
+ * the API process and `remit config save` in a container with no session, and
+ * neither is allowed to be the one that decides what a configuration contains.
+ */
+export interface ConfigExportRepositories {
+	accountConfig: {
+		get: (accountConfigId: string) => Promise<AccountConfigItem>;
+	};
+	account: Pick<IAccountRepository, "listAllByAccountConfig">;
+	accountSetting: Pick<IAccountSettingRepository, "listByAccountConfig">;
+	mailbox: Pick<IMailboxRepository, "listAllByAccount">;
+	label: Pick<ILabelRepository, "listByAccountConfig">;
+	filter: Pick<IFilterRepository, "listByAccountConfig">;
+	filterAnchor: Pick<IFilterAnchorRepository, "listByAccountConfig">;
+	address: Pick<IAddressRepository, "listByAccountConfig">;
+}
+
+/** Who wrote the file, and where from. Recorded; never authoritative on import. */
+export interface ConfigExportIdentity {
+	app: string;
+	version: string;
+	/** ISO 8601 with an explicit offset. */
+	exportedAt: string;
+	instance: string;
+}