@remit/config-format 0.0.1

package/src/fixtures/reader-config.v1.json

@@ -0,0 +1,169 @@
+{
+	"kind": "reader.config",
+	"schemaVersion": 1,
+	"generator": {
+		"app": "reader",
+		"version": "0.1.0",
+		"exportedAt": "2026-08-27T09:15:00+02:00"
+	},
+	"provenance": {
+		"accountConfigId": "0d9c8b7a-6e5f-4d3c-b2a1-0f9e8d7c6b5a",
+		"instance": "reader.ischen.nl"
+	},
+	"accountConfig": {
+		"name": "Matthijs"
+	},
+	"accounts": [
+		{
+			"accountId": "6f4c2c30-9a2c-4a7f-9f9f-1f2c3d4e5a6b",
+			"email": "matthijs@ischen.nl",
+			"username": "matthijs@ischen.nl",
+			"authType": "password",
+			"credentials": { "required": "password" },
+			"isActive": true,
+			"imap": {
+				"host": "imap.ischen.nl",
+				"port": 993,
+				"tls": true,
+				"startTls": false
+			},
+			"smtp": {
+				"enabled": true,
+				"host": "smtp.ischen.nl",
+				"port": 587,
+				"tls": false,
+				"startTls": true,
+				"username": ""
+			},
+			"displayName": "Matthijs van Henten",
+			"muted": null,
+			"composeLanguages": ["nl-NL", "en-GB"],
+			"signature": {
+				"plainText": "Matthijs van Henten\n",
+				"html": "<p>Matthijs van Henten</p>"
+			},
+			"folderRoles": [
+				{ "role": "Inbox", "folderPath": "INBOX" },
+				{ "role": "Sent", "folderPath": "INBOX.Sent" },
+				{ "role": "Junk", "folderPath": "INBOX.Junk" },
+				{ "role": "Trash", "folderPath": "INBOX.Trash" }
+			],
+			"folderOverrides": [
+				{
+					"folderPath": "INBOX.Lists.dev-null",
+					"displayName": "dev/null",
+					"muted": {
+						"value": true,
+						"setAt": 1756281600000,
+						"setBy": "web-client",
+						"reason": "high volume, read on demand"
+					}
+				}
+			],
+			"pinnedFolders": ["INBOX", "INBOX.Facturen"]
+		},
+		{
+			"accountId": "b3a1d0c7-5e64-4f1b-8c2a-77e9d3b40f18",
+			"email": "work@example.com",
+			"username": "work@example.com",
+			"authType": "oauthMicrosoft",
+			"credentials": { "required": "oauth", "provider": "microsoft" },
+			"isActive": true,
+			"imap": {
+				"host": "outlook.office365.com",
+				"port": 993,
+				"tls": true,
+				"startTls": false
+			},
+			"smtp": {
+				"enabled": false,
+				"host": "",
+				"port": 587,
+				"tls": false,
+				"startTls": true,
+				"username": ""
+			},
+			"displayName": "",
+			"muted": null,
+			"composeLanguages": [],
+			"signature": { "plainText": "", "html": "" },
+			"folderRoles": [{ "role": "Inbox", "folderPath": "INBOX" }],
+			"folderOverrides": [],
+			"pinnedFolders": []
+		}
+	],
+	"labels": [
+		{ "name": "Facturen", "color": "Blue" },
+		{ "name": "Te lezen", "color": "Default" }
+	],
+	"filters": [
+		{
+			"name": "Invoices to Facturen",
+			"scope": "Standing",
+			"expiresAt": null,
+			"matchOperator": "Or",
+			"literalClauses": [
+				{ "field": "Subject", "value": "factuur" },
+				{ "field": "FromDomain", "value": "moneybird.com" }
+			],
+			"actionLabelName": "Facturen",
+			"actionFolder": {
+				"accountId": "6f4c2c30-9a2c-4a7f-9f9f-1f2c3d4e5a6b",
+				"folderPath": "INBOX.Facturen"
+			},
+			"anchor": null
+		},
+		{
+			"name": "Anything like this release note",
+			"scope": "Temporary",
+			"expiresAt": "2026-12-31T23:59:59+01:00",
+			"matchOperator": "And",
+			"literalClauses": [],
+			"actionLabelName": "Te lezen",
+			"actionFolder": null,
+			"anchor": {
+				"sourceText": "We have shipped version 4.2 of the runtime; the changelog covers the new scheduler.",
+				"embeddingId": "amazon.titan-embed-text-v2:0@1024",
+				"sourceMessageId": "2c9e4b11-7d5a-4f60-9a31-5b8c0e7f2d44"
+			}
+		}
+	],
+	"addressFlags": [
+		{
+			"normalizedEmail": "post@bank.example",
+			"displayName": "Bank",
+			"flags": {
+				"vip": {
+					"value": true,
+					"setAt": 1750000000000,
+					"setBy": "web-client",
+					"reason": "payment alerts"
+				},
+				"category": {
+					"value": "transactional",
+					"setAt": 1750000000000
+				}
+			}
+		},
+		{
+			"normalizedEmail": "noreply@newsletter.example",
+			"displayName": "Weekly Roundup",
+			"flags": {
+				"unsubscribed": {
+					"value": true,
+					"setAt": 1755000000000,
+					"expiresAt": 1790000000000,
+					"reason": "unsubscribe link never worked"
+				},
+				"muted": { "value": true, "setAt": 1755000000000 }
+			}
+		}
+	],
+	"clientPreferences": {
+		"theme": "dark",
+		"density": "comfortable",
+		"defaultComposerFormat": "markdown",
+		"savedSearches": [{ "name": "Unpaid invoices", "query": "label:Facturen is:unread" }]
+	},
+	"messageDecisions": []
+}

package/src/fixtures.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The committed v1 document. It is the seed the migration chain regresses
+ * against: every later version has to lift this exact file, so the shape v1
+ * shipped with can never be quietly redefined.
+ */
+export const goldenConfigDocumentPath = (): string =>
+	fileURLToPath(new URL("./fixtures/reader-config.v1.json", import.meta.url));
+
+export const readGoldenConfigDocument = (): unknown =>
+	JSON.parse(readFileSync(goldenConfigDocumentPath(), "utf8"));

package/src/golden.test.ts

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readGoldenConfigDocument } from "./fixtures.js";
+import { readConfigDocument } from "./read.js";
+import { CURRENT_SCHEMA_VERSION } from "./version.js";
+
+test("the golden v1 document parses", () => {
+	const document = readConfigDocument(readGoldenConfigDocument());
+
+	assert.equal(document.schemaVersion, CURRENT_SCHEMA_VERSION);
+	assert.equal(document.accounts.length, 2);
+	assert.deepEqual(
+		document.accounts.map((account) => account.credentials.required),
+		["password", "oauth"],
+	);
+});
+
+test("the golden v1 document round-trips through JSON unchanged", () => {
+	const source = readGoldenConfigDocument();
+
+	const parsed = readConfigDocument(source);
+
+	assert.deepEqual(JSON.parse(JSON.stringify(parsed)), source);
+});
+
+test("the golden v1 document carries the parts a move has to preserve", () => {
+	const document = readConfigDocument(readGoldenConfigDocument());
+	const [primary] = document.accounts;
+	assert.ok(primary);
+
+	assert.deepEqual(
+		primary.folderRoles.find((role) => role.role === "Sent"),
+		{ role: "Sent", folderPath: "INBOX.Sent" },
+	);
+	assert.deepEqual(primary.pinnedFolders, ["INBOX", "INBOX.Facturen"]);
+	assert.equal(
+		primary.folderOverrides[0]?.muted?.reason,
+		"high volume, read on demand",
+	);
+	assert.equal(document.filters[0]?.actionFolder?.folderPath, "INBOX.Facturen");
+	assert.equal(document.filters[0]?.actionLabelName, "Facturen");
+	assert.ok(document.filters[1]?.anchor?.sourceText);
+	assert.equal(document.addressFlags[0]?.flags.vip?.reason, "payment alerts");
+	assert.equal(
+		document.addressFlags[1]?.flags.unsubscribed?.expiresAt,
+		1790000000000,
+	);
+});

package/src/index.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import * as configFormat from "./index.js";
+
+test("the package exports the reader, the schemas and the named failures", () => {
+	for (const name of [
+		"CONFIG_KIND",
+		"CURRENT_SCHEMA_VERSION",
+		"ConfigEnvelopeSchema",
+		"ReaderConfigDocumentSchema",
+		"readConfigDocument",
+		"liftToCurrentVersion",
+		"configMigrations",
+		"buildConfigJsonSchema",
+		"readGoldenConfigDocument",
+		"ConfigKindError",
+		"ConfigVersionError",
+		"ConfigUnknownKeysError",
+		"ConfigCredentialError",
+		"ConfigMalformedError",
+		"ConfigNotAnObjectError",
+	]) {
+		assert.ok(name in configFormat, `missing export: ${name}`);
+	}
+});

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./document.js";
+export * from "./envelope.js";
+export * from "./errors.js";
+export * from "./fixtures.js";
+export * from "./json-schema.js";
+export * from "./migrations.js";
+export * from "./read.js";
+export * from "./schema-artifact.js";
+export * from "./version.js";

package/src/json-schema.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import {
+	buildConfigJsonSchema,
+	serializeConfigJsonSchema,
+} from "./json-schema.js";
+import { artifactSchemaPath, committedSchemaPath } from "./schema-artifact.js";
+import { CONFIG_SCHEMA_ARTIFACT_PATH, CONFIG_SCHEMA_ID } from "./version.js";
+
+type JsonObject = Record<string, unknown>;
+
+const schema = () => buildConfigJsonSchema() as JsonObject;
+
+test("the emitted schema identifies itself", () => {
+	const emitted = schema();
+
+	assert.equal(emitted.$id, CONFIG_SCHEMA_ID);
+	assert.equal(emitted.$schema, "https://json-schema.org/draft/2020-12/schema");
+});
+
+test("the emitted schema pins the envelope and closes the document", () => {
+	const emitted = schema();
+	const properties = emitted.properties as JsonObject;
+
+	assert.deepEqual((properties.kind as JsonObject).const, "reader.config");
+	assert.deepEqual((properties.schemaVersion as JsonObject).const, 1);
+	assert.equal(emitted.additionalProperties, false);
+	assert.deepEqual(emitted.required, [
+		"kind",
+		"schemaVersion",
+		"generator",
+		"provenance",
+		"accountConfig",
+		"accounts",
+		"labels",
+		"filters",
+		"addressFlags",
+	]);
+});
+
+test("the emitted schema closes every account object too", () => {
+	const properties = schema().properties as JsonObject;
+	const account = (properties.accounts as JsonObject).items as JsonObject;
+
+	assert.equal(account.additionalProperties, false);
+	assert.equal(
+		Object.hasOwn(account.properties as JsonObject, "credentials"),
+		true,
+	);
+	assert.equal(
+		Object.hasOwn(account.properties as JsonObject, "password"),
+		false,
+	);
+});
+
+test("the generated artifact lands at its declared path under the repository root", () => {
+	assert.ok(artifactSchemaPath().endsWith(`/${CONFIG_SCHEMA_ARTIFACT_PATH}`));
+});
+
+test("the committed schema artifact matches what the code emits", () => {
+	assert.equal(
+		readFileSync(committedSchemaPath(), "utf8"),
+		serializeConfigJsonSchema(),
+	);
+});

package/src/json-schema.ts

@@ -0,0 +1,24 @@
+import { z } from "zod/v4";
+import { ReaderConfigDocumentSchema } from "./document.js";
+import { CONFIG_SCHEMA_ID, CURRENT_SCHEMA_VERSION } from "./version.js";
+
+/**
+ * The document schema as JSON Schema, for anyone writing a reader
+ * configuration file without this package: an editor, a script, another client.
+ * Derived from the zod schema rather than maintained beside it, so the two
+ * cannot describe different documents.
+ */
+export function buildConfigJsonSchema(): Record<string, unknown> {
+	return {
+		...z.toJSONSchema(ReaderConfigDocumentSchema, {
+			target: "draft-2020-12",
+			io: "input",
+		}),
+		$id: CONFIG_SCHEMA_ID,
+		title: `reader configuration document, v${CURRENT_SCHEMA_VERSION}`,
+	};
+}
+
+export function serializeConfigJsonSchema(): string {
+	return `${JSON.stringify(buildConfigJsonSchema(), null, "\t")}\n`;
+}

package/src/migrations.test.ts

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { ConfigVersionError } from "./errors.js";
+import { readGoldenConfigDocument } from "./fixtures.js";
+import {
+	type ConfigMigration,
+	configMigrations,
+	liftToCurrentVersion,
+} from "./migrations.js";
+import { readConfigDocument } from "./read.js";
+import { CURRENT_SCHEMA_VERSION } from "./version.js";
+
+test("v1 needs no migrations, and the chain is empty rather than absent", () => {
+	assert.deepEqual(configMigrations, []);
+});
+
+test("a document already at the current version passes through untouched", () => {
+	const source = readGoldenConfigDocument() as Record<string, unknown>;
+
+	assert.equal(liftToCurrentVersion(source, CURRENT_SCHEMA_VERSION), source);
+});
+
+test("the chain lifts one version at a time", () => {
+	const migrations: ConfigMigration[] = [
+		{
+			from: 1,
+			to: 2,
+			migrate: (document) => ({ ...document, schemaVersion: 2, added: "two" }),
+		},
+		{
+			from: 2,
+			to: 3,
+			migrate: (document) => ({
+				...document,
+				schemaVersion: 3,
+				added: "three",
+			}),
+		},
+	];
+
+	const lifted = liftToCurrentVersion({ schemaVersion: 1 }, 1, migrations, 3);
+
+	assert.deepEqual(lifted, { schemaVersion: 3, added: "three" });
+});
+
+test("a gap in the chain fails instead of leaving the document at its old version", () => {
+	const migrations: ConfigMigration[] = [
+		{ from: 2, to: 3, migrate: (document) => document },
+	];
+
+	assert.throws(
+		() => liftToCurrentVersion({ schemaVersion: 1 }, 1, migrations, 3),
+		(error: unknown) => {
+			assert.ok(error instanceof ConfigVersionError);
+			assert.equal(error.documentVersion, 1);
+			assert.equal(error.supportedVersion, 3);
+			return true;
+		},
+	);
+});
+
+test("a document already at the current version never enters the chain", () => {
+	let ran = 0;
+	const migrations: ConfigMigration[] = [
+		{
+			from: 1,
+			to: 2,
+			migrate: (document) => {
+				ran += 1;
+				return document;
+			},
+		},
+	];
+
+	const parsed = readConfigDocument(readGoldenConfigDocument(), migrations);
+
+	assert.equal(ran, 0);
+	assert.equal(parsed.schemaVersion, CURRENT_SCHEMA_VERSION);
+});

package/src/migrations.ts

@@ -0,0 +1,45 @@
+import { ConfigVersionError } from "./errors.js";
+import { CURRENT_SCHEMA_VERSION } from "./version.js";
+
+export type ConfigDocumentShape = Record<string, unknown>;
+
+/**
+ * One step of the chain that lifts an older document to the current version.
+ * A migration works on the raw object, before the strict parse: the shape it
+ * receives satisfied an older schema, and the shape it returns is only claimed
+ * to satisfy the next one.
+ */
+export type ConfigMigration = {
+	readonly from: number;
+	readonly to: number;
+	migrate(document: ConfigDocumentShape): ConfigDocumentShape;
+};
+
+/**
+ * Empty at v1, and the golden fixture is the seed that keeps it honest: the
+ * first migration added here has a committed v1 document to lift, so the chain
+ * is exercised by the same test that proves v1 still parses.
+ */
+export const configMigrations: readonly ConfigMigration[] = [];
+
+/**
+ * Apply the chain from `fromVersion` up to the current version. A gap in the
+ * chain is a fault, not a skipped step — silently leaving a document at an old
+ * version would hand the strict parse a shape it was never meant to see.
+ */
+export function liftToCurrentVersion(
+	document: ConfigDocumentShape,
+	fromVersion: number,
+	migrations: readonly ConfigMigration[] = configMigrations,
+	targetVersion: number = CURRENT_SCHEMA_VERSION,
+): ConfigDocumentShape {
+	let version = fromVersion;
+	let lifted = document;
+	while (version < targetVersion) {
+		const step = migrations.find((migration) => migration.from === version);
+		if (!step) throw new ConfigVersionError(fromVersion, targetVersion);
+		lifted = step.migrate(lifted);
+		version = step.to;
+	}
+	return lifted;
+}

package/src/read.test.ts

@@ -0,0 +1,198 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	ConfigCredentialError,
+	ConfigKindError,
+	ConfigMalformedError,
+	ConfigNotAnObjectError,
+	ConfigReadErrorCode,
+	ConfigUnknownKeysError,
+	ConfigVersionError,
+} from "./errors.js";
+import { readGoldenConfigDocument } from "./fixtures.js";
+import { readConfigDocument } from "./read.js";
+
+type Mutable = Record<string, unknown>;
+type MutableAccount = Record<string, unknown>;
+
+const document = (): Mutable =>
+	structuredClone(readGoldenConfigDocument()) as Mutable;
+
+const firstAccount = (source: Mutable): MutableAccount =>
+	(source.accounts as MutableAccount[])[0] as MutableAccount;
+
+test("a value that is not a JSON object is refused before anything else", () => {
+	for (const input of ["{}", 1, null, [], undefined]) {
+		assert.throws(() => readConfigDocument(input), ConfigNotAnObjectError);
+	}
+});
+
+test("a foreign document is named by kind, not by its unknown keys", () => {
+	const source = { ...document(), kind: "some.other.format" };
+
+	assert.throws(
+		() => readConfigDocument(source),
+		(error: unknown) => {
+			assert.ok(error instanceof ConfigKindError);
+			assert.equal(error.code, ConfigReadErrorCode.WrongKind);
+			assert.equal(error.expected, "reader.config");
+			assert.equal(error.received, "some.other.format");
+			return true;
+		},
+	);
+});
+
+test("a document with no kind at all is refused as the wrong kind", () => {
+	const source = document();
+	delete source.kind;
+
+	assert.throws(() => readConfigDocument(source), ConfigKindError);
+});
+
+test("a newer document is refused by version, before its shape is judged", () => {
+	const source = { ...document(), schemaVersion: 2, somethingV2Added: true };
+
+	assert.throws(
+		() => readConfigDocument(source),
+		(error: unknown) => {
+			assert.ok(error instanceof ConfigVersionError);
+			assert.equal(error.documentVersion, 2);
+			assert.equal(error.supportedVersion, 1);
+			return true;
+		},
+	);
+});
+
+test("a version that is not a positive integer is malformed, not unsupported", () => {
+	for (const schemaVersion of [0, -1, 1.5, "1", null]) {
+		assert.throws(
+			() => readConfigDocument({ ...document(), schemaVersion }),
+			ConfigMalformedError,
+		);
+	}
+});
+
+test("an unknown top-level key is refused rather than dropped", () => {
+	const source = { ...document(), notes: "hand-edited" };
+
+	assert.throws(
+		() => readConfigDocument(source),
+		(error: unknown) => {
+			assert.ok(error instanceof ConfigUnknownKeysError);
+			assert.equal(error.path, "(document root)");
+			assert.deepEqual(error.keys, ["notes"]);
+			return true;
+		},
+	);
+});
+
+test("an unknown key names the nested object it sits in", () => {
+	const source = document();
+	firstAccount(source).imapDebug = true;
+
+	assert.throws(
+		() => readConfigDocument(source),
+		(error: unknown) => {
+			assert.ok(error instanceof ConfigUnknownKeysError);
+			assert.equal(error.path, "accounts[0]");
+			return true;
+		},
+	);
+});
+
+test("an account carrying a password is refused as a credential, not as an unknown key", () => {
+	const source = document();
+	firstAccount(source).password = "hunter2";
+
+	assert.throws(
+		() => readConfigDocument(source),
+		(error: unknown) => {
+			assert.ok(error instanceof ConfigCredentialError);
+			assert.equal(error.code, ConfigReadErrorCode.CredentialPresent);
+			assert.equal(error.path, "accounts[0]");
+			assert.deepEqual(error.keys, ["password"]);
+			return true;
+		},
+	);
+});
+
+test("a blank credential is refused exactly like a filled one", () => {
+	const source = document();
+	firstAccount(source).password = "";
+
+	assert.throws(() => readConfigDocument(source), ConfigCredentialError);
+});
+
+test("every spelling of a credential is refused", () => {
+	for (const key of [
+		"passwordHash",
+		"smtpPassword",
+		"smtpPasswordHash",
+		"oauthRefreshToken",
+		"oauthRefreshTokenHash",
+		"accessToken",
+		"clientSecret",
+		"apiKey",
+	]) {
+		const source = document();
+		firstAccount(source)[key] = "value";
+
+		assert.throws(
+			() => readConfigDocument(source),
+			(error: unknown) => {
+				assert.ok(error instanceof ConfigCredentialError);
+				assert.deepEqual(error.keys, [key]);
+				return true;
+			},
+		);
+	}
+});
+
+test("a credential smuggled into the requirement declaration is refused", () => {
+	const source = document();
+	firstAccount(source).credentials = {
+		required: "password",
+		password: "hunter2",
+	};
+
+	assert.throws(
+		() => readConfigDocument(source),
+		(error: unknown) => {
+			assert.ok(error instanceof ConfigCredentialError);
+			assert.equal(error.path, "accounts[0].credentials");
+			return true;
+		},
+	);
+});
+
+test("a declared credential requirement is what a valid document carries instead", () => {
+	const parsed = readConfigDocument(document());
+
+	assert.deepEqual(parsed.accounts[0]?.credentials, { required: "password" });
+	assert.equal(Object.hasOwn(parsed.accounts[0] as object, "password"), false);
+});
+
+test("a body that fails the schema for any other reason is malformed", () => {
+	const source = document();
+	source.accounts = "none";
+
+	assert.throws(() => readConfigDocument(source), ConfigMalformedError);
+});
+
+test("the reserved decisions slot accepts nothing in v1", () => {
+	const source = document();
+	source.messageDecisions = [{ messageId: "x", decision: "filed" }];
+
+	assert.throws(() => readConfigDocument(source), ConfigMalformedError);
+});
+
+test("the optional slots may be omitted entirely", () => {
+	const source = document();
+	delete source.clientPreferences;
+	delete source.messageDecisions;
+
+	const parsed = readConfigDocument(source);
+
+	assert.equal(parsed.clientPreferences, undefined);
+	assert.equal(parsed.messageDecisions, undefined);
+});