@remit/data-ports 0.0.51 → 0.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.51",
+  "version": "0.0.52",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/conformance/calendar-collection.ts

@@ -0,0 +1,207 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { CalendarColor, CalendarSource } from "@remit/domain-enums";
+import { deriveCalendarId } from "../id.js";
+
+import type { ICalendarCollectionRepository } from "../interfaces/calendar-collection.js";
+import type { RepositoryConformanceHarness } from "./harness.js";
+
+export function calendarCollectionRepositoryConformance(
+	harness: RepositoryConformanceHarness<ICalendarCollectionRepository>,
+): void {
+	describe("ICalendarCollectionRepository conformance", () => {
+		let repo: ICalendarCollectionRepository;
+
+		before(async () => {
+			repo = await harness.createRepository();
+		});
+
+		after(() => harness.teardown());
+
+		test("create derives calendarId from the account config and the url segment", async () => {
+			const accountConfigId = harness.makeId();
+
+			const calendar = await repo.create({
+				accountConfigId,
+				urlSegment: "default",
+				displayName: "Calendar",
+			});
+
+			assert.equal(
+				calendar.calendarId,
+				deriveCalendarId(accountConfigId, "default"),
+			);
+			assert.equal(calendar.color, CalendarColor.Cal1);
+			assert.equal(calendar.source, CalendarSource.UserCreated);
+			assert.equal(calendar.componentSet, "VeventOnly");
+			assert.equal(calendar.timezone, "");
+			assert.equal(calendar.syncSequence, 0);
+		});
+
+		test("create is idempotent, so first-use provisioning never forks a second collection", async () => {
+			const accountConfigId = harness.makeId();
+
+			const first = await repo.create({
+				accountConfigId,
+				urlSegment: "default",
+				displayName: "Calendar",
+				source: CalendarSource.Default,
+			});
+			const second = await repo.create({
+				accountConfigId,
+				urlSegment: "default",
+				displayName: "Calendar",
+				source: CalendarSource.Default,
+			});
+
+			assert.equal(second.calendarId, first.calendarId);
+			const all = await repo.listByAccountConfig(accountConfigId);
+			assert.equal(all.length, 1);
+		});
+
+		test("get throws a not-found error for a missing collection", async () => {
+			await assert.rejects(
+				repo.get(harness.makeId(), harness.makeId()),
+				(error) => harness.isNotFoundError(error),
+			);
+		});
+
+		test("update changes the display overlay, never the key", async () => {
+			const accountConfigId = harness.makeId();
+			const calendar = await repo.create({
+				accountConfigId,
+				urlSegment: "work",
+				displayName: "Work",
+			});
+
+			const updated = await repo.update(accountConfigId, calendar.calendarId, {
+				displayName: "Work & Travel",
+				color: CalendarColor.Cal4,
+				timezone: "Europe/Amsterdam",
+			});
+
+			assert.equal(updated.calendarId, calendar.calendarId);
+			assert.equal(updated.urlSegment, "work");
+			assert.equal(updated.displayName, "Work & Travel");
+			assert.equal(updated.color, CalendarColor.Cal4);
+			assert.equal(updated.timezone, "Europe/Amsterdam");
+		});
+
+		test("update throws a not-found error for a missing collection", async () => {
+			await assert.rejects(
+				repo.update(harness.makeId(), harness.makeId(), {
+					displayName: "x",
+				}),
+				(error) => harness.isNotFoundError(error),
+			);
+		});
+
+		test("findByUrlSegment resolves the path segment a client bookmarked", async () => {
+			const accountConfigId = harness.makeId();
+			const calendar = await repo.create({
+				accountConfigId,
+				urlSegment: "personal",
+				displayName: "Personal",
+			});
+
+			const found = await repo.findByUrlSegment(accountConfigId, "personal");
+			assert.equal(found?.calendarId, calendar.calendarId);
+
+			assert.equal(
+				await repo.findByUrlSegment(accountConfigId, "nonexistent"),
+				null,
+			);
+		});
+
+		test("a segment stored in one casing is found in another, and by its derived id", async () => {
+			// The id derivation folds case; the stored column has to fold with it,
+			// or one DAV path resolves through `findByUrlSegment` and not through a
+			// `get` by derived id.
+			const accountConfigId = harness.makeId();
+
+			const calendar = await repo.create({
+				accountConfigId,
+				urlSegment: "Work-Calendar",
+				displayName: "Work",
+			});
+
+			assert.equal(calendar.urlSegment, "work-calendar");
+			assert.equal(
+				calendar.calendarId,
+				deriveCalendarId(accountConfigId, "WORK-CALENDAR"),
+			);
+			assert.equal(
+				(await repo.findByUrlSegment(accountConfigId, "WORK-CALENDAR"))
+					?.calendarId,
+				calendar.calendarId,
+			);
+			assert.equal(
+				(await repo.get(accountConfigId, calendar.calendarId)).urlSegment,
+				"work-calendar",
+			);
+		});
+
+		test("listByAccountConfig scopes to the account config", async () => {
+			const accountConfigId = harness.makeId();
+			const other = harness.makeId();
+
+			const mine = await repo.create({
+				accountConfigId,
+				urlSegment: "default",
+				displayName: "Mine",
+			});
+			await repo.create({
+				accountConfigId: other,
+				urlSegment: "default",
+				displayName: "Foreign",
+			});
+
+			const calendars = await repo.listByAccountConfig(accountConfigId);
+			assert.equal(calendars.length, 1);
+			assert.equal(calendars[0]?.calendarId, mine.calendarId);
+		});
+
+		test("bumpSyncSequence hands every caller a distinct increasing value", async () => {
+			const accountConfigId = harness.makeId();
+			const calendar = await repo.create({
+				accountConfigId,
+				urlSegment: "seq",
+				displayName: "Seq",
+			});
+
+			const sequences: number[] = [];
+			for (let i = 0; i < 5; i += 1) {
+				sequences.push(
+					await repo.bumpSyncSequence(accountConfigId, calendar.calendarId),
+				);
+			}
+
+			assert.deepEqual(sequences, [1, 2, 3, 4, 5]);
+			const reread = await repo.get(accountConfigId, calendar.calendarId);
+			assert.equal(reread.syncSequence, 5);
+		});
+
+		test("bumpSyncSequence throws a not-found error for a missing collection", async () => {
+			await assert.rejects(
+				repo.bumpSyncSequence(harness.makeId(), harness.makeId()),
+				(error) => harness.isNotFoundError(error),
+			);
+		});
+
+		test("delete removes the row", async () => {
+			const accountConfigId = harness.makeId();
+			const calendar = await repo.create({
+				accountConfigId,
+				urlSegment: "gone",
+				displayName: "Gone",
+			});
+
+			await repo.delete(accountConfigId, calendar.calendarId);
+
+			await assert.rejects(
+				repo.get(accountConfigId, calendar.calendarId),
+				(error) => harness.isNotFoundError(error),
+			);
+		});
+	});
+}

package/src/conformance/calendar-event-index.ts

@@ -0,0 +1,157 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import type { ICalendarEventIndexRepository } from "../interfaces/calendar-event-index.js";
+import type { CalendarOccurrenceInput } from "../types.js";
+import type { RepositoryConformanceHarness } from "./harness.js";
+
+const occurrence = (
+	recurrenceId: string,
+	startAt: string,
+	endAt: string,
+): CalendarOccurrenceInput => ({
+	recurrenceId,
+	startAt,
+	endAt,
+	allDay: false,
+});
+
+export function calendarEventIndexRepositoryConformance(
+	harness: RepositoryConformanceHarness<ICalendarEventIndexRepository>,
+): void {
+	describe("ICalendarEventIndexRepository conformance", () => {
+		let repo: ICalendarEventIndexRepository;
+
+		before(async () => {
+			repo = await harness.createRepository();
+		});
+
+		after(() => harness.teardown());
+
+		test("replaceForObject writes the master occurrence under an empty recurrenceId", async () => {
+			const calendarId = harness.makeId();
+			const calendarObjectId = harness.makeId();
+
+			await repo.replaceForObject(calendarId, calendarObjectId, [
+				occurrence("", "2026-08-26T07:00:00Z", "2026-08-26T08:00:00Z"),
+			]);
+
+			const rows = await repo.listForObject(calendarId, calendarObjectId);
+			assert.equal(rows.length, 1);
+			assert.equal(rows[0]?.recurrenceId, "");
+			assert.equal(rows[0]?.startAt, "2026-08-26T07:00:00Z");
+		});
+
+		test("replaceForObject drops the occurrences a shortened series no longer has", async () => {
+			const calendarId = harness.makeId();
+			const calendarObjectId = harness.makeId();
+
+			await repo.replaceForObject(calendarId, calendarObjectId, [
+				occurrence(
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T08:00:00Z",
+				),
+				occurrence(
+					"2026-09-02T07:00:00Z",
+					"2026-09-02T07:00:00Z",
+					"2026-09-02T08:00:00Z",
+				),
+			]);
+			await repo.replaceForObject(calendarId, calendarObjectId, [
+				occurrence(
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T08:00:00Z",
+				),
+			]);
+
+			const rows = await repo.listForObject(calendarId, calendarObjectId);
+			assert.deepEqual(
+				rows.map((row) => row.recurrenceId),
+				["2026-08-26T07:00:00Z"],
+			);
+		});
+
+		test("replaceForObject leaves the other resources of the collection alone", async () => {
+			const calendarId = harness.makeId();
+			const mine = harness.makeId();
+			const other = harness.makeId();
+
+			await repo.replaceForObject(calendarId, other, [
+				occurrence("", "2026-08-26T07:00:00Z", "2026-08-26T08:00:00Z"),
+			]);
+			await repo.replaceForObject(calendarId, mine, []);
+
+			assert.equal((await repo.listForObject(calendarId, other)).length, 1);
+			assert.equal((await repo.listForObject(calendarId, mine)).length, 0);
+		});
+
+		test("listByStartRange returns occurrences in start order, half-open on the end", async () => {
+			const calendarId = harness.makeId();
+			const calendarObjectId = harness.makeId();
+
+			await repo.replaceForObject(calendarId, calendarObjectId, [
+				occurrence(
+					"2026-09-02T07:00:00Z",
+					"2026-09-02T07:00:00Z",
+					"2026-09-02T08:00:00Z",
+				),
+				occurrence(
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T08:00:00Z",
+				),
+				occurrence(
+					"2026-09-09T07:00:00Z",
+					"2026-09-09T07:00:00Z",
+					"2026-09-09T08:00:00Z",
+				),
+			]);
+
+			const rows = await repo.listByStartRange(
+				calendarId,
+				"2026-08-26T07:00:00Z",
+				"2026-09-09T07:00:00Z",
+			);
+
+			assert.deepEqual(
+				rows.map((row) => row.startAt),
+				["2026-08-26T07:00:00Z", "2026-09-02T07:00:00Z"],
+			);
+		});
+
+		test("listByStartRange scopes to the collection", async () => {
+			const calendarId = harness.makeId();
+			const other = harness.makeId();
+
+			await repo.replaceForObject(calendarId, harness.makeId(), [
+				occurrence("", "2026-08-26T07:00:00Z", "2026-08-26T08:00:00Z"),
+			]);
+			await repo.replaceForObject(other, harness.makeId(), [
+				occurrence("", "2026-08-26T07:00:00Z", "2026-08-26T08:00:00Z"),
+			]);
+
+			const rows = await repo.listByStartRange(
+				calendarId,
+				"2026-08-01T00:00:00Z",
+				"2026-09-01T00:00:00Z",
+			);
+			assert.equal(rows.length, 1);
+		});
+
+		test("deleteForObject removes every occurrence of one resource", async () => {
+			const calendarId = harness.makeId();
+			const calendarObjectId = harness.makeId();
+
+			await repo.replaceForObject(calendarId, calendarObjectId, [
+				occurrence("", "2026-08-26T07:00:00Z", "2026-08-26T08:00:00Z"),
+			]);
+			await repo.deleteForObject(calendarId, calendarObjectId);
+
+			assert.equal(
+				(await repo.listForObject(calendarId, calendarObjectId)).length,
+				0,
+			);
+		});
+	});
+}

package/src/conformance/calendar-object.ts

@@ -0,0 +1,187 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import {
+	CalendarEventStatus,
+	CalendarTransparency,
+	ZoneCertainty,
+} from "@remit/domain-enums";
+import { deriveCalendarObjectId } from "../id.js";
+import type { ICalendarObjectRepository } from "../interfaces/calendar-object.js";
+import type { PutCalendarObjectInput } from "../types.js";
+import type { RepositoryConformanceHarness } from "./harness.js";
+
+const ICAL_DATA = [
+	"BEGIN:VCALENDAR",
+	"VERSION:2.0",
+	"BEGIN:VEVENT",
+	"UID:conformance@example.com",
+	"DTSTART:20260826T090000Z",
+	"DTEND:20260826T100000Z",
+	"SUMMARY:Stand-up",
+	"END:VEVENT",
+	"END:VCALENDAR",
+	"",
+].join("\r\n");
+
+const objectInput = (
+	calendarId: string,
+	overrides: Partial<PutCalendarObjectInput> = {},
+): PutCalendarObjectInput => ({
+	calendarId,
+	resourceName: "conformance.ics",
+	icalUid: "conformance@example.com",
+	icalData: ICAL_DATA,
+	etag: "a".repeat(64),
+	sequence: 0,
+	syncSequence: 1,
+	summary: "Stand-up",
+	dtStart: "2026-08-26T09:00:00+00:00",
+	dtEnd: "2026-08-26T10:00:00+00:00",
+	allDay: false,
+	zoneCertainty: ZoneCertainty.Explicit,
+	status: CalendarEventStatus.Confirmed,
+	transparency: CalendarTransparency.Opaque,
+	hasRecurrence: false,
+	expandedThrough: "",
+	...overrides,
+});
+
+export function calendarObjectRepositoryConformance(
+	harness: RepositoryConformanceHarness<ICalendarObjectRepository>,
+): void {
+	describe("ICalendarObjectRepository conformance", () => {
+		let repo: ICalendarObjectRepository;
+
+		before(async () => {
+			repo = await harness.createRepository();
+		});
+
+		after(() => harness.teardown());
+
+		test("put derives calendarObjectId from the collection and the resource name", async () => {
+			const calendarId = harness.makeId();
+
+			const object = await repo.put(objectInput(calendarId));
+
+			assert.equal(
+				object.calendarObjectId,
+				deriveCalendarObjectId(calendarId, "conformance.ics"),
+			);
+		});
+
+		test("put stores the iCalendar bytes verbatim, CRLF intact", async () => {
+			const calendarId = harness.makeId();
+
+			await repo.put(objectInput(calendarId));
+			const stored = await repo.findByResourceName(
+				calendarId,
+				"conformance.ics",
+			);
+
+			assert.equal(stored?.icalData, ICAL_DATA);
+			assert.ok(stored?.icalData.includes("\r\n"));
+		});
+
+		test("put rewrites the same resource rather than forking a duplicate", async () => {
+			const calendarId = harness.makeId();
+
+			await repo.put(objectInput(calendarId));
+			const second = await repo.put(
+				objectInput(calendarId, {
+					summary: "Stand-up (moved)",
+					etag: "b".repeat(64),
+					syncSequence: 2,
+				}),
+			);
+
+			assert.equal(second.summary, "Stand-up (moved)");
+			assert.equal(second.syncSequence, 2);
+			const all = await repo.listByCalendar(calendarId);
+			assert.equal(all.length, 1);
+		});
+
+		test("get throws a not-found error for a missing resource", async () => {
+			await assert.rejects(
+				repo.get(harness.makeId(), harness.makeId()),
+				(error) => harness.isNotFoundError(error),
+			);
+		});
+
+		test("findByResourceName returns null for a name the collection does not hold", async () => {
+			assert.equal(
+				await repo.findByResourceName(harness.makeId(), "absent.ics"),
+				null,
+			);
+		});
+
+		test("findByUid resolves the resource carrying an iCalendar UID", async () => {
+			const calendarId = harness.makeId();
+			const object = await repo.put(objectInput(calendarId));
+
+			const found = await repo.findByUid(calendarId, "conformance@example.com");
+			assert.equal(found?.calendarObjectId, object.calendarObjectId);
+
+			assert.equal(
+				await repo.findByUid(calendarId, "absent@example.com"),
+				null,
+			);
+		});
+
+		test("listByCalendar scopes to the collection", async () => {
+			const calendarId = harness.makeId();
+			const other = harness.makeId();
+
+			const mine = await repo.put(objectInput(calendarId));
+			await repo.put(objectInput(other));
+
+			const objects = await repo.listByCalendar(calendarId);
+			assert.equal(objects.length, 1);
+			assert.equal(objects[0]?.calendarObjectId, mine.calendarObjectId);
+		});
+
+		test("listChangedSince returns later writes in change order, excluding the token itself", async () => {
+			const calendarId = harness.makeId();
+
+			await repo.put(
+				objectInput(calendarId, {
+					resourceName: "one.ics",
+					icalUid: "one@example.com",
+					syncSequence: 1,
+				}),
+			);
+			await repo.put(
+				objectInput(calendarId, {
+					resourceName: "two.ics",
+					icalUid: "two@example.com",
+					syncSequence: 2,
+				}),
+			);
+			await repo.put(
+				objectInput(calendarId, {
+					resourceName: "three.ics",
+					icalUid: "three@example.com",
+					syncSequence: 3,
+				}),
+			);
+
+			const changed = await repo.listChangedSince(calendarId, 1);
+
+			assert.deepEqual(
+				changed.map((object) => object.resourceName),
+				["two.ics", "three.ics"],
+			);
+		});
+
+		test("delete removes the row", async () => {
+			const calendarId = harness.makeId();
+			const object = await repo.put(objectInput(calendarId));
+
+			await repo.delete(calendarId, object.calendarObjectId);
+
+			await assert.rejects(
+				repo.get(calendarId, object.calendarObjectId),
+				(error) => harness.isNotFoundError(error),
+			);
+		});
+	});
+}

package/src/conformance/index.ts

@@ -1,3 +1,6 @@
+export { calendarCollectionRepositoryConformance } from "./calendar-collection.js";
+export { calendarEventIndexRepositoryConformance } from "./calendar-event-index.js";
+export { calendarObjectRepositoryConformance } from "./calendar-object.js";
 export type { RepositoryConformanceHarness } from "./harness.js";
 export { labelRepositoryConformance } from "./label.js";
 export { senderSignerStandingRepositoryConformance } from "./sender-signer-standing.js";

package/src/id.test.ts

@@ -4,12 +4,15 @@ import {
 	base36uuidv5,
 	deriveAddressId,
 	deriveBodyPartId,
+	deriveCalendarId,
+	deriveCalendarObjectId,
 	deriveCopyMessageId,
 	deriveEnvelopeId,
 	deriveMessageId,
 	deriveMessageIdFromSource,
 	deriveQuarantineId,
 	deriveThreadId,
+	normalizeCalendarUrlSegment,
 	normalizeMessageIdHeader,
 	quarantineMessageIdHash,
 	REMIT_NAMESPACE,
@@ -100,6 +103,64 @@ describe("quarantineMessageIdHash", () => {
 	});
 });
 
+describe("normalizeCalendarUrlSegment", () => {
+	it("folds a segment to the one form the id and the stored column share", () => {
+		assert.equal(
+			normalizeCalendarUrlSegment("  Work-Calendar "),
+			"work-calendar",
+		);
+	});
+});
+
+describe("deriveCalendarId", () => {
+	it("resolves a DAV path segment case-insensitively", () => {
+		assert.equal(
+			deriveCalendarId(ACCOUNT, "Work"),
+			deriveCalendarId(ACCOUNT, "work"),
+		);
+	});
+
+	it("derives from the folded segment, so a stored segment resolves to its own id", () => {
+		assert.equal(
+			deriveCalendarId(ACCOUNT, " Work "),
+			deriveCalendarId(ACCOUNT, normalizeCalendarUrlSegment(" Work ")),
+		);
+	});
+
+	it("separates the same segment across two account configs", () => {
+		assert.notEqual(
+			deriveCalendarId(ACCOUNT, "default"),
+			deriveCalendarId("acct-2", "default"),
+		);
+	});
+});
+
+describe("deriveCalendarObjectId", () => {
+	it("is stable for the same resource", () => {
+		assert.equal(
+			deriveCalendarObjectId("cal-1", "event.ics"),
+			deriveCalendarObjectId("cal-1", "event.ics"),
+		);
+	});
+
+	it("separates the same resource name across two collections", () => {
+		assert.notEqual(
+			deriveCalendarObjectId("cal-1", "event.ics"),
+			deriveCalendarObjectId("cal-2", "event.ics"),
+		);
+	});
+
+	it("keeps a resource name case-sensitive, unlike a collection segment", () => {
+		// A resource name is the literal last path segment a client PUT to, and
+		// CalDAV lets two resources in one collection differ only by case. Folding
+		// it would merge them into one row and lose the second.
+		assert.notEqual(
+			deriveCalendarObjectId("cal-1", "Event.ics"),
+			deriveCalendarObjectId("cal-1", "event.ics"),
+		);
+	});
+});
+
 describe("derived ids are stored primary keys: a changed value orphans every row already written and needs a migration, never a new expectation here", () => {
 	const ACCOUNT = "account-golden";
 	const MESSAGE = "message-golden";
@@ -186,6 +247,27 @@ describe("derived ids are stored primary keys: a changed value orphans every row
 		);
 	});
 
+	it("deriveCalendarId pins the calendar primary key, lowercased segment included", () => {
+		assert.equal(
+			deriveCalendarId(ACCOUNT, "Work-Calendar"),
+			"ckygmpewwbyhzkrjs6ui29iuw",
+		);
+	});
+
+	it("deriveCalendarId pins the key of the default collection every account is provisioned", () => {
+		assert.equal(
+			deriveCalendarId(ACCOUNT, "default"),
+			"bg614rmeq926iyti6npylfzja",
+		);
+	});
+
+	it("deriveCalendarObjectId pins the calendar_object primary key, resource name case intact", () => {
+		assert.equal(
+			deriveCalendarObjectId("calendar-golden", "golden-event.ics"),
+			"aklxxezhc8icpuewggz983okb",
+		);
+	});
+
 	it("quarantineMessageIdHash pins the stored Message-ID hash that correlates reports", () => {
 		assert.equal(
 			quarantineMessageIdHash("<golden@example.com>"),

package/src/id.ts

@@ -21,6 +21,49 @@ export const deriveAddressId = (
 		REMIT_NAMESPACE,
 	);
 
+/**
+ * The stored form of a calendar's URL segment (issue #15). A DAV path segment
+ * is matched case-insensitively by the clients that bookmark one, so the folded
+ * form is what both the derived id and the stored column are built from — the
+ * id derivation folding on its own would let `findByUrlSegment` and a `get` by
+ * derived id disagree about the same path.
+ */
+export const normalizeCalendarUrlSegment = (urlSegment: string): string =>
+	urlSegment.trim().toLowerCase();
+
+/**
+ * Identity of a calendar collection (issue #15). Derived from the account
+ * config and the collection's URL segment, so the CalDAV path a client
+ * bookmarks resolves to a row with no lookup table, and provisioning the
+ * default collection twice — two concurrent first uses of the same account —
+ * writes the same row rather than a second, unreachable one.
+ */
+export const deriveCalendarId = (
+	accountConfigId: string,
+	urlSegment: string,
+): string =>
+	base36uuidv5(
+		`calendar:${accountConfigId}:${normalizeCalendarUrlSegment(urlSegment)}`,
+		REMIT_NAMESPACE,
+	);
+
+/**
+ * Identity of a calendar resource (issue #15). Derived from its collection and
+ * its resource name — the last path segment of the resource's URL — so a
+ * repeated PUT of the same resource rewrites its own row instead of forking a
+ * duplicate the collection can never reach.
+ *
+ * The resource name, not the iCalendar UID, is the name: CalDAV addresses a
+ * resource by URL, and a client is free to store the same UID under a second
+ * name (RFC 4791 4.1). Keying on the UID would make those two resources one
+ * row and silently lose the second.
+ */
+export const deriveCalendarObjectId = (
+	calendarId: string,
+	resourceName: string,
+): string =>
+	base36uuidv5(`calendarobject:${calendarId}:${resourceName}`, REMIT_NAMESPACE);
+
 export const isValidMessageId = (messageId: string | undefined): boolean => {
 	if (!messageId) return false;
 	const trimmed = messageId.trim();

package/src/index.ts

@@ -4,6 +4,13 @@ export type { IAccountConfigRepository } from "./interfaces/account-config.js";
 export type { IAccountExportRequestRepository } from "./interfaces/account-export-request.js";
 export type { IAccountSettingRepository } from "./interfaces/account-setting.js";
 export type { IAddressRepository } from "./interfaces/address.js";
+export type { ICalendarCollectionRepository } from "./interfaces/calendar-collection.js";
+export type { ICalendarEventIndexRepository } from "./interfaces/calendar-event-index.js";
+export type { ICalendarObjectRepository } from "./interfaces/calendar-object.js";
+export type {
+	CalendarUnitOfWorkRepositories,
+	ICalendarUnitOfWork,
+} from "./interfaces/calendar-unit-of-work.js";
 export type { IConfigImportRepository } from "./interfaces/config-import.js";
 export type { IEnvelopeRepository } from "./interfaces/envelope.js";
 export type { IFilterRepository } from "./interfaces/filter.js";
@@ -57,12 +64,17 @@ export type {
 	BodyPartParameterUpsertInput,
 	BodyPartStorageItem,
 	BodyPartUpsertInput,
+	CalendarCollectionItem,
+	CalendarEventIndexItem,
+	CalendarObjectItem,
+	CalendarOccurrenceInput,
 	ConfigImportItem,
 	ConfigImportUnresolvedRefItem,
 	CreateAccountConfigInput,
 	CreateAccountExportRequestInput,
 	CreateAccountInput,
 	CreateAddressInput,
+	CreateCalendarCollectionInput,
 	CreateConfigImportInput,
 	CreateEnvelopeAddressInput,
 	CreateEnvelopeInput,
@@ -100,6 +112,7 @@ export type {
 	OrganizeJobRequestItem,
 	OutboxAttachmentItem,
 	OutboxMessageItem,
+	PutCalendarObjectInput,
 	PutMessageFlagPushInput,
 	PutMessagePlacementMoveInput,
 	QuarantineItem,
@@ -114,6 +127,7 @@ export type {
 	UpdateAccountExportRequestInput,
 	UpdateAccountInput,
 	UpdateAddressInput,
+	UpdateCalendarCollectionInput,
 	UpdateConfigImportInput,
 	UpdateEnvelopeInput,
 	UpdateFilterInput,

package/src/interfaces/calendar-collection.ts

@@ -0,0 +1,42 @@
+import type {
+	CalendarCollectionItem,
+	CreateCalendarCollectionInput,
+	UpdateCalendarCollectionInput,
+} from "../types.js";
+
+export interface ICalendarCollectionRepository {
+	/**
+	 * Writes the collection under its derived `calendarId`. Provisioning the
+	 * same `(accountConfigId, urlSegment)` twice returns the existing row rather
+	 * than a second one, so first-use provisioning is safe to run on every
+	 * request without a prior read.
+	 */
+	create(input: CreateCalendarCollectionInput): Promise<CalendarCollectionItem>;
+	get(
+		accountConfigId: string,
+		calendarId: string,
+	): Promise<CalendarCollectionItem>;
+	update(
+		accountConfigId: string,
+		calendarId: string,
+		input: UpdateCalendarCollectionInput,
+	): Promise<CalendarCollectionItem>;
+	delete(accountConfigId: string, calendarId: string): Promise<void>;
+	listByAccountConfig(
+		accountConfigId: string,
+	): Promise<CalendarCollectionItem[]>;
+	findByUrlSegment(
+		accountConfigId: string,
+		urlSegment: string,
+	): Promise<CalendarCollectionItem | null>;
+	/**
+	 * Advances the collection's change counter by one and returns the new value,
+	 * which the caller stamps on the object it just wrote. Atomic with respect
+	 * to concurrent writers: a read-then-write here would hand two writers the
+	 * same sequence and lose one of them from every later sync report.
+	 */
+	bumpSyncSequence(
+		accountConfigId: string,
+		calendarId: string,
+	): Promise<number>;
+}

package/src/interfaces/calendar-event-index.ts

@@ -0,0 +1,34 @@
+import type {
+	CalendarEventIndexItem,
+	CalendarOccurrenceInput,
+} from "../types.js";
+
+export interface ICalendarEventIndexRepository {
+	/**
+	 * Replaces every occurrence row of one resource with `occurrences`. Whole
+	 * replacement rather than a merge: an edit that shortens a series must
+	 * remove the occurrences it dropped, and a diff would leave them behind as
+	 * events the calendar view still shows but the resource no longer has.
+	 */
+	replaceForObject(
+		calendarId: string,
+		calendarObjectId: string,
+		occurrences: CalendarOccurrenceInput[],
+	): Promise<void>;
+	deleteForObject(calendarId: string, calendarObjectId: string): Promise<void>;
+	listForObject(
+		calendarId: string,
+		calendarObjectId: string,
+	): Promise<CalendarEventIndexItem[]>;
+	/**
+	 * Occurrences starting within `[startAt, endAt)`, in start order — the
+	 * calendar-view read. Bounded by start rather than by overlap: an
+	 * occurrence that began before the window and runs into it is not returned,
+	 * so a caller that must show those widens the window by its longest event.
+	 */
+	listByStartRange(
+		calendarId: string,
+		startAt: string,
+		endAt: string,
+	): Promise<CalendarEventIndexItem[]>;
+}

package/src/interfaces/calendar-object.ts

@@ -0,0 +1,33 @@
+import type { CalendarObjectItem, PutCalendarObjectInput } from "../types.js";
+
+export interface ICalendarObjectRepository {
+	put(input: PutCalendarObjectInput): Promise<CalendarObjectItem>;
+	get(
+		calendarId: string,
+		calendarObjectId: string,
+	): Promise<CalendarObjectItem>;
+	delete(calendarId: string, calendarObjectId: string): Promise<void>;
+	findByResourceName(
+		calendarId: string,
+		resourceName: string,
+	): Promise<CalendarObjectItem | null>;
+	/**
+	 * The resource carrying an iCalendar UID, which is how a scheduling message
+	 * or a calendar-query REPORT addresses an event — a client that has the UID
+	 * generally does not have the resource name.
+	 */
+	findByUid(
+		calendarId: string,
+		icalUid: string,
+	): Promise<CalendarObjectItem | null>;
+	listByCalendar(calendarId: string): Promise<CalendarObjectItem[]>;
+	/**
+	 * Everything written to the collection after `syncSequence`, in change
+	 * order — the read behind a WebDAV-Sync report. Exclusive of the token
+	 * itself, so replaying a token returns only what the client has not seen.
+	 */
+	listChangedSince(
+		calendarId: string,
+		syncSequence: number,
+	): Promise<CalendarObjectItem[]>;
+}

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

@@ -0,0 +1,31 @@
+import type { ICalendarCollectionRepository } from "./calendar-collection.js";
+import type { ICalendarEventIndexRepository } from "./calendar-event-index.js";
+import type { ICalendarObjectRepository } from "./calendar-object.js";
+
+/**
+ * The repositories one calendar write set touches, bound to a single unit of
+ * work.
+ */
+export interface CalendarUnitOfWorkRepositories {
+	calendarCollection: ICalendarCollectionRepository;
+	calendarObject: ICalendarObjectRepository;
+	calendarEventIndex: ICalendarEventIndexRepository;
+}
+
+/**
+ * Runs a calendar write set as one atomic unit (issue #15). Writing a resource
+ * is three writes — the object, its replaced occurrence rows, and the
+ * collection's sequence bump — and none of them is meaningful without the
+ * others: an object with stale occurrences is a calendar showing events the
+ * resource no longer has, and an object written without the bump is a change no
+ * sync report will ever hand a client.
+ *
+ * A throw rolls the whole set back. Backends without cross-entity transactions
+ * supply a pass-through implementation that runs the callback against the plain
+ * repositories.
+ */
+export interface ICalendarUnitOfWork {
+	transaction<T>(
+		fn: (repos: CalendarUnitOfWorkRepositories) => Promise<T>,
+	): Promise<T>;
+}

package/src/types.ts

@@ -6,6 +6,9 @@ import type {
 	BodyPartParameterSchema,
 	BodyPartSchema,
 	BodyPartStorageSchema,
+	CalendarCollectionSchema,
+	CalendarEventIndexSchema,
+	CalendarObjectSchema,
 	ConfigImportSchema,
 	ConfigImportUnresolvedRefSchema,
 	EnvelopeAddressSchema,
@@ -552,6 +555,58 @@ export type CreateFilterAnchorInput = Omit<
 	"createdAt" | "updatedAt"
 >;
 
+export type CalendarCollectionItem = z.infer<typeof CalendarCollectionSchema>;
+export type CalendarObjectItem = z.infer<typeof CalendarObjectSchema>;
+export type CalendarEventIndexItem = z.infer<typeof CalendarEventIndexSchema>;
+
+// `calendarId` is derived from accountConfigId + urlSegment, and syncSequence
+// starts at zero and only ever moves through the collection's own bump — so
+// neither is ever supplied here.
+export type CreateCalendarCollectionInput = Omit<
+	CalendarCollectionItem,
+	| "calendarId"
+	| "syncSequence"
+	| "createdAt"
+	| "updatedAt"
+	| "color"
+	| "componentSet"
+	| "source"
+	| "timezone"
+> & {
+	color?: CalendarCollectionItem["color"];
+	componentSet?: CalendarCollectionItem["componentSet"];
+	source?: CalendarCollectionItem["source"];
+	timezone?: CalendarCollectionItem["timezone"];
+};
+
+export type UpdateCalendarCollectionInput = Partial<
+	Pick<CalendarCollectionItem, "displayName" | "color" | "timezone">
+>;
+
+/**
+ * A whole calendar resource. Every projected column is supplied together with
+ * the `icalData` it was projected from — the repository never derives one from
+ * the other, so the projection can only ever be produced by the one place that
+ * owns it (`@remit/calendar-service`) and can never drift from the bytes.
+ *
+ * `calendarObjectId` is derived from calendarId + resourceName, so this is an
+ * upsert: writing the same resource twice rewrites its own row.
+ */
+export type PutCalendarObjectInput = Omit<
+	CalendarObjectItem,
+	"calendarObjectId" | "createdAt" | "updatedAt"
+>;
+
+/**
+ * One expanded occurrence. Written only as part of a full replacement of a
+ * resource's occurrences — there is no single-occurrence write, because a row
+ * here is never authoritative and never edited in place.
+ */
+export type CalendarOccurrenceInput = Omit<
+	CalendarEventIndexItem,
+	"calendarId" | "calendarObjectId" | "createdAt" | "updatedAt"
+>;
+
 export type SenderSignerStandingItem = z.infer<
 	typeof SenderSignerStandingSchema
 >;