@remit/calendar-service 0.0.1

package/src/fixtures.ts

@@ -0,0 +1,52 @@
+/**
+ * iCalendar fixtures, assembled from lines so the CRLF the RFC requires is
+ * explicit rather than a property of this file's own line endings.
+ */
+export const ical = (...lines: string[]): string => `${lines.join("\r\n")}\r\n`;
+
+/**
+ * The same resource as a client that ignores RFC 5545 3.1 would send it. Real
+ * `.ics` files arrive LF-only often enough — anything that has been through a
+ * text-mode checkout, an editor, or a naive copy — that reading them is part of
+ * the job, not an edge case.
+ */
+export const asLf = (icalData: string): string =>
+	icalData.replace(/\r\n/g, "\n");
+
+/**
+ * Europe/Amsterdam as a client writes it into a resource. Present so a
+ * DST-crossing series resolves against the definition the resource itself
+ * carries, which is the only zone data RFC 5545 promises a server.
+ */
+export const AMSTERDAM_VTIMEZONE = [
+	"BEGIN:VTIMEZONE",
+	"TZID:Europe/Amsterdam",
+	"BEGIN:DAYLIGHT",
+	"TZOFFSETFROM:+0100",
+	"TZOFFSETTO:+0200",
+	"TZNAME:CEST",
+	"DTSTART:19700329T020000",
+	"RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU",
+	"END:DAYLIGHT",
+	"BEGIN:STANDARD",
+	"TZOFFSETFROM:+0200",
+	"TZOFFSETTO:+0100",
+	"TZNAME:CET",
+	"DTSTART:19701025T030000",
+	"RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU",
+	"END:STANDARD",
+	"END:VTIMEZONE",
+];
+
+export const singleEvent = (...eventLines: string[]): string =>
+	ical(
+		"BEGIN:VCALENDAR",
+		"VERSION:2.0",
+		"PRODID:-//Remit//Calendar Tests//EN",
+		"BEGIN:VEVENT",
+		"UID:fixture@example.com",
+		"DTSTAMP:20260801T090000Z",
+		...eventLines,
+		"END:VEVENT",
+		"END:VCALENDAR",
+	);

package/src/index.ts

@@ -0,0 +1,29 @@
+export type {
+	CalendarResult,
+	CalendarValidationCode,
+	CalendarValidationError,
+} from "./errors.js";
+export { computeEtag } from "./etag.js";
+export {
+	CALENDAR_EXPANSION_HORIZON_DAYS,
+	CALENDAR_EXPANSION_MAX_OCCURRENCES,
+	type CalendarExpansion,
+	expandCalendar,
+} from "./expand.js";
+export {
+	type ParsedCalendar,
+	parseCalendar,
+	serializeCalendar,
+} from "./parse.js";
+export {
+	type CalendarObjectProjection,
+	projectCalendar,
+} from "./project.js";
+export {
+	DEFAULT_CALENDAR_URL_SEGMENT,
+	deleteCalendarObject,
+	type PutCalendarObjectInput,
+	provisionDefaultCalendar,
+	putCalendarObject,
+} from "./put.js";
+export { type ResolvedTime, resolveTime, toUtcIso } from "./time.js";

package/src/parse.test.ts

@@ -0,0 +1,253 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { asLf, ical, singleEvent } from "./fixtures.js";
+import { parseCalendar, serializeCalendar } from "./parse.js";
+
+const parsed = async (icalData: string) => {
+	const result = await parseCalendar(icalData);
+	assert.ok(result.ok, `expected a parse, got ${JSON.stringify(result)}`);
+	return result.value;
+};
+
+const refusalCode = async (icalData: string) => {
+	const result = await parseCalendar(icalData);
+	assert.ok(!result.ok, "expected a refusal");
+	return result.error;
+};
+
+describe("parseCalendar", () => {
+	it("reads the master event and its UID", async () => {
+		const calendar = await parsed(
+			singleEvent("DTSTART:20260826T090000Z", "DTEND:20260826T100000Z"),
+		);
+
+		assert.equal(calendar.uid, "fixture@example.com");
+		assert.equal(calendar.master.name, "vevent");
+		assert.deepEqual(calendar.overrides, []);
+	});
+
+	it("separates the overrides from the master", async () => {
+		const calendar = await parsed(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"UID:series@example.com",
+				"DTSTART:20260826T090000Z",
+				"RRULE:FREQ=WEEKLY;COUNT=3",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"UID:series@example.com",
+				"RECURRENCE-ID:20260902T090000Z",
+				"DTSTART:20260902T110000Z",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.equal(calendar.overrides.length, 1);
+		assert.ok(!calendar.master.hasProperty("recurrence-id"));
+	});
+
+	it("refuses bytes that are not iCalendar", async () => {
+		assert.equal(
+			(await refusalCode("this is not a calendar")).code,
+			"MalformedIcalendar",
+		);
+	});
+
+	it("refuses a document whose root is not a VCALENDAR", async () => {
+		assert.equal(
+			(
+				await refusalCode(
+					ical("BEGIN:VCARD", "VERSION:4.0", "FN:Someone", "END:VCARD"),
+				)
+			).code,
+			"NotACalendar",
+		);
+	});
+
+	it("refuses a component this collection does not store, naming it", async () => {
+		const error = await refusalCode(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VTODO",
+				"UID:todo@example.com",
+				"SUMMARY:Buy milk",
+				"END:VTODO",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.equal(error.code, "UnsupportedComponent");
+		assert.match(error.message, /VTODO/);
+	});
+
+	it("refuses a VCALENDAR with no VEVENT", async () => {
+		assert.equal(
+			(
+				await refusalCode(
+					ical("BEGIN:VCALENDAR", "VERSION:2.0", "END:VCALENDAR"),
+				)
+			).code,
+			"NoEvent",
+		);
+	});
+
+	it("refuses overrides with no event to override", async () => {
+		const error = await refusalCode(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"UID:orphan@example.com",
+				"RECURRENCE-ID:20260902T090000Z",
+				"DTSTART:20260902T110000Z",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.equal(error.code, "NoMasterEvent");
+	});
+
+	it("refuses two unrelated events in one resource", async () => {
+		const error = await refusalCode(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"UID:one@example.com",
+				"DTSTART:20260826T090000Z",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"UID:two@example.com",
+				"DTSTART:20260827T090000Z",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.equal(error.code, "MultipleMasterEvents");
+	});
+
+	it("refuses a VEVENT with no UID", async () => {
+		const error = await refusalCode(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"DTSTART:20260826T090000Z",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.equal(error.code, "MissingUid");
+	});
+
+	it("refuses an override that belongs to a different event", async () => {
+		const error = await refusalCode(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"UID:series@example.com",
+				"DTSTART:20260826T090000Z",
+				"RRULE:FREQ=WEEKLY;COUNT=3",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"UID:stranger@example.com",
+				"RECURRENCE-ID:20260902T090000Z",
+				"DTSTART:20260902T110000Z",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.equal(error.code, "MismatchedUid");
+	});
+
+	it("refuses a VEVENT with no DTSTART", async () => {
+		assert.equal(
+			(await refusalCode(singleEvent("SUMMARY:Undated"))).code,
+			"MissingDtStart",
+		);
+	});
+});
+
+describe("serializeCalendar", () => {
+	it("keeps the line endings RFC 5545 requires", async () => {
+		const source = singleEvent(
+			"DTSTART:20260826T090000Z",
+			"DTEND:20260826T100000Z",
+		);
+
+		const serialized = serializeCalendar((await parsed(source)).component);
+
+		assert.ok(serialized.includes("\r\n"));
+		assert.doesNotMatch(
+			serialized,
+			/(?<!\r)\n/,
+			"every line break is a CRLF, with no bare LF left behind",
+		);
+	});
+
+	it("reads an LF-only resource and writes it back as CRLF", async () => {
+		// RFC 5545 says CRLF; real files arrive both ways, and a parser that only
+		// recognises CRLF reads an LF-only resource as one enormous line.
+		const source = asLf(
+			singleEvent("DTSTART:20260826T090000Z", "DTEND:20260826T100000Z"),
+		);
+		assert.ok(!source.includes("\r"), "the fixture is LF-only");
+
+		const calendar = await parsed(source);
+		const serialized = serializeCalendar(calendar.component);
+
+		assert.equal(calendar.uid, "fixture@example.com");
+		assert.ok(calendar.master.hasProperty("dtstart"));
+		assert.doesNotMatch(serialized, /(?<!\r)\n/);
+	});
+
+	it("round-trips a resource losslessly, unknown properties included", async () => {
+		const source = singleEvent(
+			"DTSTART:20260826T090000Z",
+			"DTEND:20260826T100000Z",
+			"SUMMARY:Quarterly review",
+			"X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:AUTOMATIC",
+			"X-MICROSOFT-CDO-BUSYSTATUS:BUSY",
+			"ATTENDEE;CN=Someone;X-NUM-GUESTS=0:mailto:someone@example.com",
+		);
+
+		const once = serializeCalendar((await parsed(source)).component);
+		const twice = serializeCalendar((await parsed(once)).component);
+
+		assert.equal(twice, once);
+		for (const line of [
+			"X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:AUTOMATIC",
+			"X-MICROSOFT-CDO-BUSYSTATUS:BUSY",
+			"X-NUM-GUESTS=0",
+			"SUMMARY:Quarterly review",
+		]) {
+			assert.ok(once.includes(line), `${line} did not survive the round trip`);
+		}
+	});
+
+	it("keeps a whole unknown subcomponent of the event", async () => {
+		const source = singleEvent(
+			"DTSTART:20260826T090000Z",
+			"DTEND:20260826T100000Z",
+			"BEGIN:VALARM",
+			"ACTION:DISPLAY",
+			"DESCRIPTION:Reminder",
+			"TRIGGER:-PT15M",
+			"END:VALARM",
+		);
+
+		const serialized = serializeCalendar((await parsed(source)).component);
+
+		assert.ok(serialized.includes("BEGIN:VALARM"));
+		assert.ok(serialized.includes("TRIGGER:-PT15M"));
+	});
+});

package/src/parse.ts

@@ -0,0 +1,132 @@
+import ICAL from "ical.js";
+import { type CalendarResult, calendarFailure } from "./errors.js";
+
+/** Components a VEVENT-only collection accepts at the top level of a resource. */
+const ACCEPTED_COMPONENTS = new Set(["vevent", "vtimezone"]);
+
+export interface ParsedCalendar {
+	/** The VCALENDAR, with every property and component the input carried. */
+	component: ICAL.Component;
+	/** The VEVENT without a RECURRENCE-ID. */
+	master: ICAL.Component;
+	/** The VEVENTs carrying a RECURRENCE-ID, in document order. */
+	overrides: ICAL.Component[];
+	uid: string;
+}
+
+/**
+ * Serializes a VCALENDAR back to iCalendar text.
+ *
+ * Lossless by construction: ical.js keeps every property it parsed, including
+ * ones it has no design rule for, so an X- property or a whole unknown
+ * component survives the round trip. The output is always CRLF (RFC 5545 3.1),
+ * whatever the input used.
+ *
+ * The write path does not call this. A resource is stored as the bytes it
+ * arrived in — LF-only ones included — because the etag is a digest of exactly
+ * what the writer sent; running a stored resource through here would rewrite
+ * its line endings, refold its long lines, and move the tag of a resource
+ * nobody edited. This is for building a VCALENDAR, not for keeping one.
+ */
+export const serializeCalendar = (component: ICAL.Component): string =>
+	component.toString();
+
+/**
+ * ical.js's parser in a promise, so unreadable bytes arrive as a rejection to
+ * branch on rather than a synchronous throw.
+ */
+const readComponent = (
+	icalData: string,
+): Promise<CalendarResult<ICAL.Component>> =>
+	new Promise<ICAL.Component>((resolve) => {
+		resolve(new ICAL.Component(ICAL.parse(icalData)));
+	}).then(
+		(component) => ({ ok: true, value: component }) as const,
+		(error: unknown) =>
+			calendarFailure<ICAL.Component>(
+				"MalformedIcalendar",
+				error instanceof Error ? error.message : "unreadable iCalendar data",
+			),
+	);
+
+/**
+ * Reads and validates a VCALENDAR carrying exactly one event.
+ *
+ * Every refusal is a returned value. The input is client-supplied bytes, so a
+ * malformed resource is an ordinary outcome of this function rather than a
+ * fault.
+ */
+export const parseCalendar = async (
+	icalData: string,
+): Promise<CalendarResult<ParsedCalendar>> => {
+	const read = await readComponent(icalData);
+	if (!read.ok) return read;
+	const component = read.value;
+
+	if (component.name !== "vcalendar") {
+		return calendarFailure(
+			"NotACalendar",
+			`expected a VCALENDAR, found ${component.name.toUpperCase()}`,
+		);
+	}
+
+	const unsupported = component
+		.getAllSubcomponents()
+		.map((child) => child.name)
+		.find((name) => !ACCEPTED_COMPONENTS.has(name));
+	if (unsupported) {
+		return calendarFailure(
+			"UnsupportedComponent",
+			`this calendar stores VEVENT only, and the resource carries a ${unsupported.toUpperCase()}`,
+		);
+	}
+
+	const events = component.getAllSubcomponents("vevent");
+	if (events.length === 0) {
+		return calendarFailure("NoEvent", "the resource carries no VEVENT");
+	}
+
+	const masters = events.filter((event) => !event.hasProperty("recurrence-id"));
+	if (masters.length === 0) {
+		return calendarFailure(
+			"NoMasterEvent",
+			"every VEVENT carries a RECURRENCE-ID, so there is no event for them to override",
+		);
+	}
+	if (masters.length > 1) {
+		return calendarFailure(
+			"MultipleMasterEvents",
+			`one resource holds one event, and this one holds ${masters.length}`,
+		);
+	}
+
+	const master = masters[0] as ICAL.Component;
+	const uid = master.getFirstPropertyValue("uid");
+	if (typeof uid !== "string" || uid === "") {
+		return calendarFailure("MissingUid", "the VEVENT declares no UID");
+	}
+
+	const mismatched = events.find(
+		(event) => event.getFirstPropertyValue("uid") !== uid,
+	);
+	if (mismatched) {
+		return calendarFailure(
+			"MismatchedUid",
+			"the VEVENTs in this resource declare different UIDs",
+		);
+	}
+
+	if (!master.hasProperty("dtstart")) {
+		return calendarFailure("MissingDtStart", "the VEVENT declares no DTSTART");
+	}
+
+	return {
+		ok: true,
+		value: {
+			component,
+			master,
+			overrides: events.filter((event) => event.hasProperty("recurrence-id")),
+			uid,
+		},
+	};
+};