@remit/drizzle-service 0.0.68 → 0.0.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/drizzle-service",
-  "version": "0.0.68",
+  "version": "0.0.70",
   "description": "Drizzle ORM service over SQLite",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -2,6 +2,7 @@ export { CreateFailedConflictError, NotFoundError } from "./error.js";
 export { CalendarCollectionRepo } from "./repos/calendar-collection.js";
 export { CalendarEventIndexRepo } from "./repos/calendar-event-index.js";
 export { CalendarObjectRepo } from "./repos/calendar-object.js";
+export { CalendarSuggestionRepo } from "./repos/calendar-suggestion.js";
 export { DrizzleCalendarUnitOfWork } from "./repos/calendar-unit-of-work.js";
 export {
 	type CascadeDeleteLogger,

package/src/repos/calendar-migrations.sqlite.test.ts

@@ -0,0 +1,258 @@
+/**
+ * The calendar tables against the shape a deployment actually runs: every
+ * committed entity migration applied in journal order to an empty database,
+ * rather than a schema pushed from the drizzle table objects.
+ *
+ * Nothing else ran these files. Every calendar SQLite test builds its database
+ * with `createSqliteTestDb`, which regenerates the DDL from the table objects on
+ * each run, and the drift guard only diffs the latest snapshot — so a migration
+ * that fails to apply, or applies to a different shape than its snapshot claims,
+ * passes the whole suite while a self-host upgrade breaks. That is reader#73 one
+ * layer up: there the shipped DDL was wrong, here the shipped DDL was never
+ * executed at all.
+ *
+ * Everything below walks the journal, so a migration added tomorrow is covered
+ * the moment it is committed.
+ */
+
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import {
+	CalendarEventStatus,
+	CalendarInviteMethod,
+	CalendarSuggestionSource,
+	CalendarSuggestionState,
+	CalendarTransparency,
+	ZoneCertainty,
+} from "@remit/domain-enums";
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import type { Db } from "../db.js";
+import {
+	calendarEventIndexTable,
+	calendarObjectTable,
+	calendarSuggestionTable,
+	calendarTable,
+} from "../schema.js";
+import {
+	applyMigration,
+	migrationJournal,
+	migrationSnapshot,
+	migrationTagsOnDisk,
+} from "../test-shipped-sqlite-schema.js";
+import { CalendarCollectionRepo } from "./calendar-collection.js";
+import { CalendarEventIndexRepo } from "./calendar-event-index.js";
+import { CalendarObjectRepo } from "./calendar-object.js";
+import { CalendarSuggestionRepo } from "./calendar-suggestion.js";
+
+const ACCOUNT_CONFIG_ID = "account-config-shipped";
+const ROOT_SNAPSHOT_PREV_ID = "00000000-0000-0000-0000-000000000000";
+
+const ICAL_DATA = [
+	"BEGIN:VCALENDAR",
+	"VERSION:2.0",
+	"BEGIN:VEVENT",
+	"UID:shipped@example.test",
+	"DTSTART:20260901T080000Z",
+	"DTEND:20260901T090000Z",
+	"SUMMARY:Shipped-migrations round trip",
+	"END:VEVENT",
+	"END:VCALENDAR",
+	"",
+].join("\r\n");
+
+describe("the committed sqlite migration journal", () => {
+	const entries = migrationJournal();
+
+	test("names each migration once, in a strictly rising order", () => {
+		// Not "consecutive": drizzle-kit skipped 0009, and a withdrawn number is
+		// harmless. A repeated or reordered one is not — two branches generating
+		// against the same predecessor is the collision this pins.
+		for (const [position, entry] of entries.entries()) {
+			const previous = entries[position - 1];
+			assert.ok(
+				previous === undefined || entry.idx > previous.idx,
+				`journal entry ${entry.tag} does not follow ${previous?.tag}`,
+			);
+			assert.equal(
+				entry.tag.slice(0, 4),
+				String(entry.idx).padStart(4, "0"),
+				`journal entry ${entry.tag} is filed under idx ${entry.idx}`,
+			);
+		}
+	});
+
+	test("accounts for every migration file on disk", () => {
+		// An orphan .sql is a migration a deployment never runs; a journal entry
+		// with no file is one that crashes the migrator on the next upgrade.
+		assert.deepEqual(
+			migrationTagsOnDisk(),
+			entries.map((entry) => entry.tag).sort(),
+		);
+	});
+
+	test("chains every snapshot to its predecessor", () => {
+		for (const [position, entry] of entries.entries()) {
+			const snapshot = migrationSnapshot(entry.idx);
+			const previous = entries[position - 1];
+			assert.equal(
+				snapshot.prevId,
+				previous === undefined
+					? ROOT_SNAPSHOT_PREV_ID
+					: migrationSnapshot(previous.idx).id,
+				`snapshot ${entry.tag} does not follow ${previous?.tag ?? "the root"}`,
+			);
+		}
+	});
+});
+
+describe("the calendar tables under the shipped migrations", () => {
+	let sqlite: Database.Database;
+	let db: Db<Record<string, unknown>>;
+
+	before(() => {
+		sqlite = new Database(":memory:");
+		for (const entry of migrationJournal()) {
+			applyMigration(sqlite, entry.tag);
+		}
+		sqlite.pragma("foreign_keys = ON");
+		db = drizzle(sqlite, {
+			schema: {
+				calendars: calendarTable,
+				calendarObjects: calendarObjectTable,
+				calendarEventIndexes: calendarEventIndexTable,
+				calendarSuggestions: calendarSuggestionTable,
+			},
+		}) as unknown as Db<Record<string, unknown>>;
+	});
+
+	after(() => {
+		sqlite.close();
+	});
+
+	test("leaves all four calendar tables behind", () => {
+		const present = new Set(
+			sqlite
+				.prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
+				.all()
+				.map((row) => (row as { name: string }).name),
+		);
+
+		for (const table of [
+			"calendar",
+			"calendar_object",
+			"calendar_event_index",
+			"calendar_suggestion",
+		]) {
+			assert.ok(present.has(table), `${table} was never created`);
+		}
+	});
+
+	test("round-trips a collection", async () => {
+		const repo = new CalendarCollectionRepo(db);
+
+		const created = await repo.create({
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			urlSegment: "shipped",
+			displayName: "Shipped",
+		});
+
+		const fetched = await repo.get(ACCOUNT_CONFIG_ID, created.calendarId);
+		assert.equal(fetched.displayName, "Shipped");
+		assert.equal(fetched.urlSegment, "shipped");
+		assert.equal(fetched.syncSequence, 0);
+	});
+
+	test("round-trips an object and its occurrence", async () => {
+		const collection = await new CalendarCollectionRepo(db).create({
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			urlSegment: "objects",
+			displayName: "Objects",
+		});
+		const objects = new CalendarObjectRepo(db);
+
+		const written = await objects.put({
+			calendarId: collection.calendarId,
+			resourceName: "shipped.ics",
+			icalUid: "shipped@example.test",
+			icalData: ICAL_DATA,
+			etag: "b".repeat(64),
+			sequence: 0,
+			syncSequence: 1,
+			summary: "Shipped-migrations round trip",
+			dtStart: "2026-09-01T08:00:00+00:00",
+			dtEnd: "2026-09-01T09:00:00+00:00",
+			allDay: false,
+			zoneCertainty: ZoneCertainty.Explicit,
+			status: CalendarEventStatus.Confirmed,
+			transparency: CalendarTransparency.Opaque,
+			hasRecurrence: false,
+			expandedThrough: "",
+		});
+
+		const fetched = await objects.get(
+			collection.calendarId,
+			written.calendarObjectId,
+		);
+		assert.equal(fetched.icalData, ICAL_DATA);
+		assert.equal(fetched.summary, "Shipped-migrations round trip");
+		assert.equal(fetched.allDay, false);
+
+		const index = new CalendarEventIndexRepo(db);
+		await index.replaceForObject(
+			collection.calendarId,
+			written.calendarObjectId,
+			[
+				{
+					recurrenceId: "",
+					startAt: "2026-09-01T08:00:00Z",
+					endAt: "2026-09-01T09:00:00Z",
+					allDay: false,
+					// The three columns 0018 added. A migration that never ran leaves
+					// the repo selecting columns the table does not have.
+					summary: "Shipped-migrations round trip",
+					status: CalendarEventStatus.Confirmed,
+					transparency: CalendarTransparency.Opaque,
+				},
+			],
+		);
+
+		const occurrences = await index.listForObject(
+			collection.calendarId,
+			written.calendarObjectId,
+		);
+		assert.equal(occurrences.length, 1);
+		assert.equal(occurrences[0]?.startAt, "2026-09-01T08:00:00Z");
+		assert.equal(occurrences[0]?.summary, "Shipped-migrations round trip");
+		assert.equal(occurrences[0]?.status, CalendarEventStatus.Confirmed);
+		assert.equal(occurrences[0]?.transparency, CalendarTransparency.Opaque);
+	});
+
+	test("round-trips a suggestion", async () => {
+		const repo = new CalendarSuggestionRepo(db);
+
+		const written = await repo.put({
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			messageId: "message-1",
+			bodyPartId: "body-part-1",
+			icalUid: "invite@example.test",
+			sequence: 0,
+			method: CalendarInviteMethod.Request,
+			source: CalendarSuggestionSource.IcalendarPart,
+			summary: "Design review",
+			dtStart: "2026-09-01T10:00:00+02:00",
+			dtEnd: "2026-09-01T11:00:00+02:00",
+			allDay: false,
+			location: "",
+			organizer: "organizer@example.test",
+			zoneCertainty: ZoneCertainty.Explicit,
+			icalData: "BEGIN:VCALENDAR\r\nEND:VCALENDAR\r\n",
+		});
+
+		const fetched = await repo.get(ACCOUNT_CONFIG_ID, written.suggestionId);
+		assert.equal(fetched.summary, "Design review");
+		assert.equal(fetched.state, CalendarSuggestionState.Pending);
+		assert.equal(fetched.acceptedCalendarObjectId, "");
+		assert.equal(fetched.organizer, "organizer@example.test");
+	});
+});

package/src/repos/calendar-suggestion.conformance.sqlite.test.ts

@@ -0,0 +1,23 @@
+import { calendarSuggestionRepositoryConformance } from "@remit/data-ports/conformance";
+import { NotFoundError } from "../error.js";
+import { randomId } from "../id.js";
+import { calendarSuggestionTable } from "../schema.js";
+import { createSqliteTestDb } from "../test-db-sqlite.js";
+import { CalendarSuggestionRepo } from "./calendar-suggestion.js";
+
+let close: (() => Promise<void>) | undefined;
+
+calendarSuggestionRepositoryConformance({
+	async createRepository() {
+		const { db, close: closeDb } = await createSqliteTestDb({
+			calendarSuggestions: calendarSuggestionTable,
+		});
+		close = closeDb;
+		return new CalendarSuggestionRepo(db as never);
+	},
+	teardown: async () => {
+		await close?.();
+	},
+	makeId: () => randomId(),
+	isNotFoundError: (error) => error instanceof NotFoundError,
+});

package/src/repos/calendar-suggestion.ts

@@ -0,0 +1,223 @@
+import type {
+	CalendarSuggestionItem,
+	ICalendarSuggestionRepository,
+	PutCalendarSuggestionInput,
+	ResultList,
+	SettleCalendarSuggestionInput,
+} from "@remit/data-ports";
+import { deriveCalendarSuggestionId } from "@remit/data-ports/id";
+import { CalendarSuggestionState } from "@remit/domain-enums";
+import { and, asc, desc, eq, lt, or } from "drizzle-orm";
+import type { Db } from "../db.js";
+import { NotFoundError } from "../error.js";
+import { decodeToken, resultList } from "../pagination.js";
+import { calendarSuggestionTable } from "../schema.js";
+
+type DB = Db<Record<string, unknown>>;
+
+function rowToCalendarSuggestion(
+	row: typeof calendarSuggestionTable.$inferSelect,
+): CalendarSuggestionItem {
+	return {
+		suggestionId: row.suggestionId,
+		accountConfigId: row.accountConfigId,
+		messageId: row.messageId,
+		bodyPartId: row.bodyPartId,
+		icalUid: row.icalUid,
+		sequence: row.sequence,
+		method: row.method,
+		source: row.source,
+		state: row.state,
+		summary: row.summary,
+		dtStart: row.dtStart,
+		dtEnd: row.dtEnd,
+		allDay: row.allDay,
+		location: row.location,
+		organizer: row.organizer,
+		zoneCertainty: row.zoneCertainty,
+		icalData: row.icalData,
+		acceptedCalendarObjectId: row.acceptedCalendarObjectId,
+		createdAt: row.createdAt,
+		updatedAt: row.updatedAt,
+	};
+}
+
+export class CalendarSuggestionRepo implements ICalendarSuggestionRepository {
+	constructor(private db: DB) {}
+
+	async put(
+		input: PutCalendarSuggestionInput,
+	): Promise<CalendarSuggestionItem> {
+		const now = Date.now();
+		const suggestionId = deriveCalendarSuggestionId(
+			input.messageId,
+			input.bodyPartId,
+			input.icalUid,
+		);
+		const [row] = await this.db
+			.insert(calendarSuggestionTable)
+			.values({
+				...input,
+				suggestionId,
+				state: CalendarSuggestionState.Pending,
+				acceptedCalendarObjectId: "",
+				createdAt: now,
+				updatedAt: now,
+			})
+			.onConflictDoUpdate({
+				target: [
+					calendarSuggestionTable.accountConfigId,
+					calendarSuggestionTable.suggestionId,
+				],
+				// `state` and `acceptedCalendarObjectId` are deliberately absent from
+				// the update set: they carry what a person decided, and a producer
+				// re-reading the message must not walk that back to Pending.
+				set: { ...input, updatedAt: now },
+			})
+			.returning();
+		return rowToCalendarSuggestion(row);
+	}
+
+	async get(
+		accountConfigId: string,
+		suggestionId: string,
+	): Promise<CalendarSuggestionItem> {
+		const [row] = await this.db
+			.select()
+			.from(calendarSuggestionTable)
+			.where(
+				and(
+					eq(calendarSuggestionTable.accountConfigId, accountConfigId),
+					eq(calendarSuggestionTable.suggestionId, suggestionId),
+				),
+			);
+		if (!row) {
+			throw new NotFoundError(`Calendar suggestion not found: ${suggestionId}`);
+		}
+		return rowToCalendarSuggestion(row);
+	}
+
+	async listByMessage(
+		accountConfigId: string,
+		messageId: string,
+	): Promise<CalendarSuggestionItem[]> {
+		const rows = await this.db
+			.select()
+			.from(calendarSuggestionTable)
+			.where(
+				and(
+					eq(calendarSuggestionTable.accountConfigId, accountConfigId),
+					eq(calendarSuggestionTable.messageId, messageId),
+				),
+			)
+			.orderBy(
+				asc(calendarSuggestionTable.createdAt),
+				asc(calendarSuggestionTable.suggestionId),
+			);
+		return rows.map(rowToCalendarSuggestion);
+	}
+
+	/**
+	 * Newest first, paged on a keyset over `(createdAt, suggestionId)` — the
+	 * exact trailing members of the `byState` index's sort key, read backwards.
+	 * The order is the index's own, never a sort applied on top of it.
+	 */
+	async listByState(
+		accountConfigId: string,
+		state: CalendarSuggestionItem["state"],
+		options?: { limit?: number; continuationToken?: string },
+	): Promise<ResultList<CalendarSuggestionItem>> {
+		const limit = options?.limit ?? 100;
+		const cursor = options?.continuationToken
+			? decodeToken(options.continuationToken)
+			: undefined;
+		const after = cursor
+			? {
+					createdAt: cursor.createdAt as number,
+					suggestionId: cursor.suggestionId as string,
+				}
+			: undefined;
+
+		const rows = await this.db
+			.select()
+			.from(calendarSuggestionTable)
+			.where(
+				and(
+					eq(calendarSuggestionTable.accountConfigId, accountConfigId),
+					eq(calendarSuggestionTable.state, state),
+					after
+						? or(
+								lt(calendarSuggestionTable.createdAt, after.createdAt),
+								and(
+									eq(calendarSuggestionTable.createdAt, after.createdAt),
+									lt(calendarSuggestionTable.suggestionId, after.suggestionId),
+								),
+							)
+						: undefined,
+				),
+			)
+			.orderBy(
+				desc(calendarSuggestionTable.createdAt),
+				desc(calendarSuggestionTable.suggestionId),
+			)
+			.limit(limit);
+
+		const items = rows.map(rowToCalendarSuggestion);
+		const lastItem = items[items.length - 1];
+		return resultList(
+			items,
+			limit,
+			lastItem
+				? {
+						createdAt: lastItem.createdAt,
+						suggestionId: lastItem.suggestionId,
+					}
+				: undefined,
+		);
+	}
+
+	async settle(
+		accountConfigId: string,
+		suggestionId: string,
+		input: SettleCalendarSuggestionInput,
+	): Promise<CalendarSuggestionItem> {
+		const [row] = await this.db
+			.update(calendarSuggestionTable)
+			.set({ ...input, updatedAt: Date.now() })
+			.where(
+				and(
+					eq(calendarSuggestionTable.accountConfigId, accountConfigId),
+					eq(calendarSuggestionTable.suggestionId, suggestionId),
+				),
+			)
+			.returning();
+		if (!row) {
+			throw new NotFoundError(`Calendar suggestion not found: ${suggestionId}`);
+		}
+		return rowToCalendarSuggestion(row);
+	}
+
+	async supersedeIfPending(
+		accountConfigId: string,
+		suggestionId: string,
+	): Promise<CalendarSuggestionItem | null> {
+		const [row] = await this.db
+			.update(calendarSuggestionTable)
+			.set({
+				state: CalendarSuggestionState.Superseded,
+				acceptedCalendarObjectId: "",
+				updatedAt: Date.now(),
+			})
+			.where(
+				and(
+					eq(calendarSuggestionTable.accountConfigId, accountConfigId),
+					eq(calendarSuggestionTable.suggestionId, suggestionId),
+					// The condition is the point: a card the user answered between
+					// the producer's read and this write must keep their answer.
+					eq(calendarSuggestionTable.state, CalendarSuggestionState.Pending),
+				),
+			)
+			.returning();
+		return row ? rowToCalendarSuggestion(row) : null;
+	}
+}

package/src/repos/calendar-unit-of-work.ts

@@ -7,6 +7,7 @@ import { runInTransaction } from "../tx.js";
 import { CalendarCollectionRepo } from "./calendar-collection.js";
 import { CalendarEventIndexRepo } from "./calendar-event-index.js";
 import { CalendarObjectRepo } from "./calendar-object.js";
+import { CalendarSuggestionRepo } from "./calendar-suggestion.js";
 
 type DB = Db<Record<string, unknown>>;
 
@@ -21,6 +22,7 @@ export class DrizzleCalendarUnitOfWork implements ICalendarUnitOfWork {
 				calendarCollection: new CalendarCollectionRepo(tx as never),
 				calendarObject: new CalendarObjectRepo(tx as never),
 				calendarEventIndex: new CalendarEventIndexRepo(tx as never),
+				calendarSuggestion: new CalendarSuggestionRepo(tx as never),
 			}),
 		);
 	}

package/src/schema.ts

@@ -11,6 +11,7 @@ import * as entities from "@remit/drizzle-sqlite-schema";
 export const calendarTable = entities.calendarCollections;
 export const calendarObjectTable = entities.calendarObjects;
 export const calendarEventIndexTable = entities.calendarEventIndexes;
+export const calendarSuggestionTable = entities.calendarSuggestions;
 export const filterAnchorTable = entities.filterAnchors;
 export const filterTable = entities.filters;
 export const labelTable = entities.labels;

package/src/test-shipped-sqlite-schema.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
 import type Database from "better-sqlite3";
 
 // Read the committed SQLite entity migrations — the DDL a self-host deployment
@@ -17,6 +17,42 @@ const MIGRATIONS_DIR = new URL(
 export const migrationSql = (tag: string): string =>
 	readFileSync(new URL(`${tag}.sql`, MIGRATIONS_DIR), "utf8");
 
+export interface MigrationJournalEntry {
+	idx: number;
+	tag: string;
+}
+
+/** Every committed entity migration, in the order the migrator runs them. */
+export const migrationJournal = (): MigrationJournalEntry[] =>
+	(
+		JSON.parse(
+			readFileSync(new URL("meta/_journal.json", MIGRATIONS_DIR), "utf8"),
+		) as { entries: MigrationJournalEntry[] }
+	).entries;
+
+/** The `.sql` files present on disk, whatever the journal says about them. */
+export const migrationTagsOnDisk = (): string[] =>
+	readdirSync(MIGRATIONS_DIR)
+		.filter((name) => name.endsWith(".sql"))
+		.map((name) => name.slice(0, -".sql".length))
+		.sort();
+
+export interface MigrationSnapshot {
+	id: string;
+	prevId: string;
+}
+
+export const migrationSnapshot = (idx: number): MigrationSnapshot =>
+	JSON.parse(
+		readFileSync(
+			new URL(
+				`meta/${String(idx).padStart(4, "0")}_snapshot.json`,
+				MIGRATIONS_DIR,
+			),
+			"utf8",
+		),
+	) as MigrationSnapshot;
+
 /** The `CREATE TABLE` block for one table, as that migration declares it. */
 export const shippedTableDdl = (tag: string, table: string): string => {
 	const match = migrationSql(tag).match(