@remit/calendar-service 0.0.11 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/calendar-service",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "iCalendar (RFC 5545) parsing, projection and recurrence expansion over the calendar store",
   "type": "module",
   "main": "src/index.ts",

package/src/errors.ts

@@ -35,7 +35,9 @@ export type CalendarValidationCode =
 	| "NotRecurring"
 	/** A RECURRENCE-ID naming no occurrence this series produces. */
 	| "UnknownOccurrence"
-	| "UnmovableRecurrenceRule";
+	| "UnmovableRecurrenceRule"
+	/** A subscription address that is not an http, https or webcal URL. */
+	| "InvalidSubscriptionUrl";
 
 export interface CalendarValidationError {
 	code: CalendarValidationCode;

package/src/feeds/google-secret-address.ics

@@ -0,0 +1,99 @@
+BEGIN:VCALENDAR
+PRODID:-//Google Inc//Google Calendar 70.9054//EN
+VERSION:2.0
+CALSCALE:GREGORIAN
+METHOD:PUBLISH
+X-WR-CALNAME:Harbour rota
+X-WR-TIMEZONE:Europe/Amsterdam
+BEGIN:VTIMEZONE
+TZID:Europe/Amsterdam
+X-LIC-LOCATION: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
+BEGIN:VTIMEZONE
+TZID:America/New_York
+BEGIN:DAYLIGHT
+TZOFFSETFROM:-0500
+TZOFFSETTO:-0400
+TZNAME:EDT
+DTSTART:19700308T020000
+RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
+END:DAYLIGHT
+BEGIN:STANDARD
+TZOFFSETFROM:-0400
+TZOFFSETTO:-0500
+TZNAME:EST
+DTSTART:19701101T020000
+RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
+END:STANDARD
+END:VTIMEZONE
+BEGIN:VEVENT
+DTSTART;TZID=Europe/Amsterdam:20261005T090000
+DTEND;TZID=Europe/Amsterdam:20261005T093000
+RRULE:FREQ=WEEKLY;COUNT=6;BYDAY=MO
+EXDATE;TZID=Europe/Amsterdam:20261019T090000
+DTSTAMP:20260925T120000Z
+UID:pilot-standup@google.com
+CREATED:20260901T080000Z
+LAST-MODIFIED:20260920T080000Z
+SEQUENCE:0
+STATUS:CONFIRMED
+SUMMARY:Pilot standup
+TRANSP:OPAQUE
+END:VEVENT
+BEGIN:VEVENT
+DTSTART;TZID=Europe/Amsterdam:20261012T100000
+DTEND;TZID=Europe/Amsterdam:20261012T103000
+DTSTAMP:20260925T120000Z
+UID:pilot-standup@google.com
+RECURRENCE-ID;TZID=Europe/Amsterdam:20261012T090000
+SEQUENCE:1
+STATUS:CONFIRMED
+SUMMARY:Pilot standup (moved)
+TRANSP:OPAQUE
+END:VEVENT
+BEGIN:VEVENT
+DTSTART;TZID=Europe/Amsterdam:20261102T090000
+DTEND;TZID=Europe/Amsterdam:20261102T093000
+DTSTAMP:20260925T120000Z
+UID:pilot-standup@google.com
+RECURRENCE-ID;TZID=Europe/Amsterdam:20261102T090000
+SEQUENCE:1
+STATUS:CANCELLED
+SUMMARY:Pilot standup
+TRANSP:OPAQUE
+END:VEVENT
+BEGIN:VEVENT
+DTSTART;VALUE=DATE:20261007
+DTEND;VALUE=DATE:20261009
+DTSTAMP:20260925T120000Z
+UID:quay-offsite@google.com
+SEQUENCE:0
+STATUS:CONFIRMED
+SUMMARY:Quay offsite
+TRANSP:TRANSPARENT
+END:VEVENT
+BEGIN:VEVENT
+DTSTART:20261008T140000Z
+DTEND:20261008T150000Z
+DTSTAMP:20260925T120000Z
+UID:tide-review@google.com
+SEQUENCE:0
+STATUS:CONFIRMED
+SUMMARY:Tide table review
+TRANSP:OPAQUE
+END:VEVENT
+END:VCALENDAR

package/src/index.ts

@@ -67,6 +67,25 @@ export {
 	type ScopedWrite,
 	type ScopedWriteInput,
 } from "./scope.js";
+export {
+	CALENDAR_SUBSCRIPTION_MAX_BYTES,
+	CALENDAR_SUBSCRIPTION_TIMEOUT_MS,
+	type CalendarFeedFetch,
+	type CalendarFeedFetcher,
+	type CalendarFeedResource,
+	type CalendarFeedSplit,
+	type CalendarFeedWrite,
+	type CalendarSubscriptionRefresh,
+	type CalendarSubscriptionTarget,
+	fetchCalendarFeed,
+	isSubscriptionDue,
+	readCalendarFeed,
+	readSubscriptionUrl,
+	recordCalendarFeedFailure,
+	refreshCalendarSubscription,
+	splitCalendarFeed,
+	writeCalendarFeed,
+} from "./subscribe.js";
 export {
 	type CalendarSuggestionProjection,
 	inviteMethodOf,

package/src/memory-store.ts

@@ -65,6 +65,11 @@ export class MemoryCalendarStore implements ICalendarUnitOfWork {
 				source: input.source ?? "UserCreated",
 				timezone: input.timezone ?? "",
 				syncSequence: 0,
+				subscriptionUrl: input.subscriptionUrl ?? "",
+				subscriptionEnabled: input.subscriptionEnabled ?? false,
+				subscriptionCheckedAt: 0,
+				subscriptionFetchedAt: 0,
+				subscriptionError: "",
 				createdAt: now,
 				updatedAt: now,
 			};
@@ -102,6 +107,11 @@ export class MemoryCalendarStore implements ICalendarUnitOfWork {
 			if (this.collections.has(calendarId)) return null;
 			return this.collectionRepo.create(input);
 		},
+		listEnabledSubscriptions: async () =>
+			[...this.collections.values()].filter(
+				(collection) =>
+					collection.source === "Subscribed" && collection.subscriptionEnabled,
+			),
 		findByUrlSegment: async (accountConfigId: string, urlSegment: string) =>
 			this.collections.get(deriveCalendarId(accountConfigId, urlSegment)) ??
 			null,

package/src/parse.ts

@@ -35,7 +35,7 @@ export const serializeCalendar = (component: ICAL.Component): string =>
  * ical.js's parser in a promise, so unreadable bytes arrive as a rejection to
  * branch on rather than a synchronous throw.
  */
-const readComponent = (
+export const readCalendarComponent = (
 	icalData: string,
 ): Promise<CalendarResult<ICAL.Component>> =>
 	new Promise<ICAL.Component>((resolve) => {
@@ -59,7 +59,7 @@ const readComponent = (
 export const parseCalendar = async (
 	icalData: string,
 ): Promise<CalendarResult<ParsedCalendar>> => {
-	const read = await readComponent(icalData);
+	const read = await readCalendarComponent(icalData);
 	if (!read.ok) return read;
 	const component = read.value;
 

package/src/subscribe.test.ts

@@ -0,0 +1,578 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { describe, it } from "node:test";
+import type { CalendarCollectionItem } from "@remit/data-ports";
+import { CalendarSource } from "@remit/domain-enums";
+import { ical } from "./fixtures.js";
+import { MemoryCalendarStore } from "./memory-store.js";
+import { parseCalendar } from "./parse.js";
+import {
+	type CalendarFeedFetcher,
+	fetchCalendarFeed,
+	isSubscriptionDue,
+	readSubscriptionUrl,
+	refreshCalendarSubscription,
+	splitCalendarFeed,
+	writeCalendarFeed,
+} from "./subscribe.js";
+import { listCalendarInstances } from "./window.js";
+
+const ACCOUNT_CONFIG_ID = "account-config-1";
+const SECRET_URL =
+	"https://calendar.example/calendar/ical/harbour%40example.com/private-5f1c0ffee/basic.ics";
+const GOOGLE_FEED = readFileSync(
+	new URL("./feeds/google-secret-address.ics", import.meta.url),
+	"utf8",
+);
+const WINDOW = {
+	from: "2026-10-01T00:00:00Z",
+	to: "2026-11-16T00:00:00Z",
+};
+
+const answering =
+	(body: string, init: ResponseInit = {}): CalendarFeedFetcher =>
+	async () =>
+		new Response(body, init);
+
+const subscribed = async (): Promise<{
+	store: MemoryCalendarStore;
+	collection: CalendarCollectionItem;
+}> => {
+	const store = new MemoryCalendarStore();
+	const collection = await store.transaction((repos) =>
+		repos.calendarCollection.create({
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			urlSegment: "harbour-rota",
+			displayName: "Harbour rota",
+			source: CalendarSource.Subscribed,
+			subscriptionUrl: SECRET_URL,
+			subscriptionEnabled: true,
+		}),
+	);
+	return { store, collection };
+};
+
+const drawn = async (
+	store: MemoryCalendarStore,
+	collection: CalendarCollectionItem,
+) => {
+	const current = await store.transaction((repos) =>
+		repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+	);
+	const instances = await store.transaction((repos) =>
+		listCalendarInstances(repos, [current], WINDOW),
+	);
+	return instances.map((instance) => ({
+		summary: instance.summary,
+		startAt: instance.startAt,
+		allDay: instance.allDay,
+		status: instance.status,
+	}));
+};
+
+const writeFeed = async (
+	store: MemoryCalendarStore,
+	collection: CalendarCollectionItem,
+	feed: string,
+	now: number,
+) => {
+	const split = await splitCalendarFeed(feed);
+	assert.ok(split.ok);
+	return writeCalendarFeed(
+		store,
+		{
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId: collection.calendarId,
+		},
+		split.value,
+		now,
+	);
+};
+
+describe("readSubscriptionUrl", () => {
+	it("reads webcal as the same address over https", () => {
+		const url = readSubscriptionUrl(
+			"  webcal://calendar.example/feeds/rota.ics ",
+		);
+		assert.deepEqual(url, {
+			ok: true,
+			value: "https://calendar.example/feeds/rota.ics",
+		});
+	});
+
+	it("keeps http and https as given", () => {
+		assert.deepEqual(readSubscriptionUrl("http://127.0.0.1:8080/a.ics"), {
+			ok: true,
+			value: "http://127.0.0.1:8080/a.ics",
+		});
+		assert.deepEqual(readSubscriptionUrl(SECRET_URL), {
+			ok: true,
+			value: SECRET_URL,
+		});
+	});
+
+	it("refuses what is not a web address", () => {
+		for (const raw of [
+			"",
+			"calendar.example/rota.ics",
+			"ftp://calendar.example/rota.ics",
+			"file:///etc/passwd",
+			"https://user:secret@calendar.example/rota.ics",
+		]) {
+			const url = readSubscriptionUrl(raw);
+			assert.equal(url.ok, false, raw);
+			if (!url.ok) assert.equal(url.error.code, "InvalidSubscriptionUrl");
+		}
+	});
+});
+
+describe("fetchCalendarFeed", () => {
+	it("answers the feed's text", async () => {
+		const fetched = await fetchCalendarFeed(
+			SECRET_URL,
+			answering(GOOGLE_FEED, { status: 200 }),
+		);
+		assert.deepEqual(fetched, { ok: true, value: GOOGLE_FEED });
+	});
+
+	it("names the status of a refusal and never the address", async () => {
+		const fetched = await fetchCalendarFeed(
+			SECRET_URL,
+			answering("gone", { status: 404 }),
+		);
+		assert.deepEqual(fetched, {
+			ok: false,
+			reason: "the feed answered HTTP 404",
+		});
+	});
+
+	it("names why an address could not be reached, without the address", async () => {
+		const fetched = await fetchCalendarFeed(SECRET_URL, async (url) => {
+			throw new TypeError("fetch failed", {
+				cause: Object.assign(new Error(`connect ECONNREFUSED ${url}`), {
+					code: "ECONNREFUSED",
+				}),
+			});
+		});
+		assert.deepEqual(fetched, {
+			ok: false,
+			reason: "the feed could not be reached (ECONNREFUSED)",
+		});
+	});
+
+	it("says so when the feed does not answer in time", async () => {
+		const fetched = await fetchCalendarFeed(SECRET_URL, async () => {
+			throw new DOMException("timed out", "TimeoutError");
+		});
+		assert.deepEqual(fetched, {
+			ok: false,
+			reason: "the feed did not answer within 30 seconds",
+		});
+	});
+
+	it("stops reading a chunked feed once it passes the cap", async () => {
+		let pulled = 0;
+		let cancelled = false;
+		const chunk = new Uint8Array(1024 * 1024).fill(0x41);
+		const endless = new ReadableStream<Uint8Array>({
+			pull(controller) {
+				pulled += 1;
+				controller.enqueue(chunk);
+			},
+			cancel() {
+				cancelled = true;
+			},
+		});
+
+		const fetched = await fetchCalendarFeed(SECRET_URL, async () => {
+			const response = new Response(endless, { status: 200 });
+			assert.equal(response.headers.get("content-length"), null);
+			return response;
+		});
+
+		assert.deepEqual(fetched, {
+			ok: false,
+			reason: "the feed is larger than 10 MB",
+		});
+		assert.equal(cancelled, true);
+		assert.ok(pulled <= 12, `read ${pulled} MB of a feed capped at 10`);
+	});
+
+	it("refuses a feed larger than it will store", async () => {
+		const fetched = await fetchCalendarFeed(
+			SECRET_URL,
+			answering("x", {
+				status: 200,
+				headers: { "content-length": String(64 * 1024 * 1024) },
+			}),
+		);
+		assert.deepEqual(fetched, {
+			ok: false,
+			reason: "the feed is larger than 10 MB",
+		});
+	});
+});
+
+describe("splitCalendarFeed", () => {
+	it("cuts a feed into one resource per UID, each one the write path accepts", async () => {
+		const split = await splitCalendarFeed(GOOGLE_FEED);
+		assert.ok(split.ok);
+		assert.equal(split.value.unreadable, 0);
+		assert.deepEqual(
+			split.value.resources.map((resource) => resource.uid),
+			[
+				"pilot-standup@google.com",
+				"quay-offsite@google.com",
+				"tide-review@google.com",
+			],
+		);
+
+		for (const resource of split.value.resources) {
+			assert.match(resource.resourceName, /^[0-9a-f]{40}\.ics$/);
+			const parsed = await parseCalendar(resource.icalData);
+			assert.ok(parsed.ok, resource.uid);
+			assert.equal(parsed.value.uid, resource.uid);
+		}
+	});
+
+	it("keeps a series with its overrides and only the zones it names", async () => {
+		const split = await splitCalendarFeed(GOOGLE_FEED);
+		assert.ok(split.ok);
+		const standup = split.value.resources[0];
+		assert.ok(standup);
+
+		const parsed = await parseCalendar(standup.icalData);
+		assert.ok(parsed.ok);
+		assert.equal(parsed.value.overrides.length, 2);
+		assert.deepEqual(
+			parsed.value.component
+				.getAllSubcomponents("vtimezone")
+				.map((zone) => zone.getFirstPropertyValue("tzid")),
+			["Europe/Amsterdam"],
+		);
+		assert.equal(parsed.value.component.hasProperty("method"), false);
+		assert.equal(
+			parsed.value.component.getFirstPropertyValue("x-wr-calname"),
+			"Harbour rota",
+		);
+
+		const offsite = split.value.resources[1];
+		assert.ok(offsite);
+		assert.doesNotMatch(offsite.icalData, /BEGIN:VTIMEZONE/);
+	});
+
+	it("names the same resource on every read of the same feed", async () => {
+		const first = await splitCalendarFeed(GOOGLE_FEED);
+		const second = await splitCalendarFeed(GOOGLE_FEED);
+		assert.ok(first.ok && second.ok);
+		assert.deepEqual(first.value.resources, second.value.resources);
+	});
+
+	it("counts an event with no UID instead of storing it", async () => {
+		const split = await splitCalendarFeed(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"PRODID:-//Example//Feed//EN",
+				"BEGIN:VEVENT",
+				"DTSTART:20261008T140000Z",
+				"SUMMARY:Nobody's event",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+		assert.ok(split.ok);
+		assert.equal(split.value.resources.length, 0);
+		assert.equal(split.value.unreadable, 1);
+	});
+
+	it("refuses bytes that are not a calendar", async () => {
+		const split = await splitCalendarFeed(
+			"<!doctype html><title>Sign in</title>",
+		);
+		assert.equal(split.ok, false);
+	});
+});
+
+describe("writeCalendarFeed", () => {
+	it("keeps recurrence, a moved and a cancelled instance, all-day and zoned times", async () => {
+		const { store, collection } = await subscribed();
+
+		const write = await writeFeed(store, collection, GOOGLE_FEED, 5_000);
+
+		assert.deepEqual(write, {
+			paused: false,
+			written: 3,
+			unchanged: 0,
+			removed: 0,
+			skipped: 0,
+		});
+		assert.deepEqual(await drawn(store, collection), [
+			{
+				summary: "Pilot standup",
+				startAt: "2026-10-05T07:00:00Z",
+				allDay: false,
+				status: "Confirmed",
+			},
+			{
+				summary: "Quay offsite",
+				startAt: "2026-10-07T00:00:00Z",
+				allDay: true,
+				status: "Confirmed",
+			},
+			{
+				summary: "Tide table review",
+				startAt: "2026-10-08T14:00:00Z",
+				allDay: false,
+				status: "Confirmed",
+			},
+			{
+				summary: "Pilot standup (moved)",
+				startAt: "2026-10-12T08:00:00Z",
+				allDay: false,
+				status: "Confirmed",
+			},
+			{
+				summary: "Pilot standup",
+				startAt: "2026-10-26T08:00:00Z",
+				allDay: false,
+				status: "Confirmed",
+			},
+			{
+				summary: "Pilot standup",
+				startAt: "2026-11-02T08:00:00Z",
+				allDay: false,
+				status: "Cancelled",
+			},
+			{
+				summary: "Pilot standup",
+				startAt: "2026-11-09T08:00:00Z",
+				allDay: false,
+				status: "Confirmed",
+			},
+		]);
+
+		const stored = await store.transaction((repos) =>
+			repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+		);
+		assert.equal(stored.subscriptionCheckedAt, 5_000);
+		assert.equal(stored.subscriptionFetchedAt, 5_000);
+		assert.equal(stored.subscriptionError, "");
+	});
+
+	it("leaves unchanged events alone and removes what the feed dropped", async () => {
+		const { store, collection } = await subscribed();
+		await writeFeed(store, collection, GOOGLE_FEED, 5_000);
+		const sequenceBefore = (
+			await store.transaction((repos) =>
+				repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+			)
+		).syncSequence;
+
+		const dropped = GOOGLE_FEED.replace(
+			/BEGIN:VEVENT\r\nDTSTART:20261008T140000Z[\s\S]*?END:VEVENT\r\n/,
+			"",
+		);
+		const write = await writeFeed(store, collection, dropped, 9_000);
+
+		assert.deepEqual(write, {
+			paused: false,
+			written: 0,
+			unchanged: 2,
+			removed: 1,
+			skipped: 0,
+		});
+		const summaries = (await drawn(store, collection)).map(
+			(instance) => instance.summary,
+		);
+		assert.equal(summaries.includes("Tide table review"), false);
+		assert.equal(summaries.length, 6);
+		const after = await store.transaction((repos) =>
+			repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+		);
+		assert.equal(after.syncSequence, sequenceBefore + 1);
+	});
+
+	it("writes nothing when a second fetch differs only in its export stamps", async () => {
+		const { store, collection } = await subscribed();
+		await writeFeed(store, collection, GOOGLE_FEED, 5_000);
+		const before = await store.transaction((repos) =>
+			repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+		);
+
+		const restamped = GOOGLE_FEED.replaceAll(
+			"DTSTAMP:20260925T120000Z",
+			"DTSTAMP:20260926T081500Z",
+		);
+		const write = await writeFeed(store, collection, restamped, 9_000);
+
+		assert.deepEqual(write, {
+			paused: false,
+			written: 0,
+			unchanged: 3,
+			removed: 0,
+			skipped: 0,
+		});
+		const after = await store.transaction((repos) =>
+			repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+		);
+		assert.equal(after.syncSequence, before.syncSequence);
+		assert.equal(after.subscriptionFetchedAt, 9_000);
+	});
+
+	it("writes nothing for a subscription paused while its feed was read", async () => {
+		const { store, collection } = await subscribed();
+		await store.transaction((repos) =>
+			repos.calendarCollection.update(
+				ACCOUNT_CONFIG_ID,
+				collection.calendarId,
+				{ subscriptionEnabled: false },
+			),
+		);
+
+		const write = await writeFeed(store, collection, GOOGLE_FEED, 5_000);
+
+		assert.deepEqual(write, {
+			paused: true,
+			written: 0,
+			unchanged: 0,
+			removed: 0,
+			skipped: 0,
+		});
+		assert.deepEqual(await drawn(store, collection), []);
+		const stored = await store.transaction((repos) =>
+			repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+		);
+		assert.equal(stored.subscriptionFetchedAt, 0);
+	});
+
+	it("records the events it could not store and keeps the rest", async () => {
+		const { store, collection } = await subscribed();
+
+		const write = await writeFeed(
+			store,
+			collection,
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"PRODID:-//Example//Feed//EN",
+				"BEGIN:VEVENT",
+				"UID:kept@example.com",
+				"DTSTART:20261008T140000Z",
+				"DTEND:20261008T150000Z",
+				"SUMMARY:Kept",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"UID:backwards@example.com",
+				"DTSTART:20261008T140000Z",
+				"DTEND:20261008T130000Z",
+				"SUMMARY:Backwards",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"DTSTART:20261009T140000Z",
+				"SUMMARY:No UID",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+			7_000,
+		);
+
+		assert.equal(write.written, 1);
+		assert.equal(write.skipped, 2);
+		const stored = await store.transaction((repos) =>
+			repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+		);
+		assert.equal(
+			stored.subscriptionError,
+			"2 events in the feed could not be stored",
+		);
+		assert.deepEqual(
+			(await drawn(store, collection)).map((instance) => instance.summary),
+			["Kept"],
+		);
+	});
+});
+
+describe("refreshCalendarSubscription", () => {
+	it("records a failed fetch on the collection and keeps every event", async () => {
+		const { store, collection } = await subscribed();
+		await writeFeed(store, collection, GOOGLE_FEED, 5_000);
+
+		const refreshed = await refreshCalendarSubscription(
+			store,
+			collection,
+			9_000,
+			answering("unavailable", { status: 503 }),
+		);
+
+		assert.deepEqual(refreshed, {
+			ok: false,
+			reason: "the feed answered HTTP 503",
+		});
+		const stored = await store.transaction((repos) =>
+			repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+		);
+		assert.equal(stored.subscriptionCheckedAt, 9_000);
+		assert.equal(stored.subscriptionFetchedAt, 5_000);
+		assert.equal(stored.subscriptionError, "the feed answered HTTP 503");
+		assert.equal(stored.subscriptionError.includes(SECRET_URL), false);
+		assert.equal((await drawn(store, collection)).length, 7);
+	});
+
+	it("states that a page which is not a calendar is not one", async () => {
+		const { store, collection } = await subscribed();
+
+		const refreshed = await refreshCalendarSubscription(
+			store,
+			collection,
+			9_000,
+			answering("<!doctype html><title>Sign in</title>", { status: 200 }),
+		);
+
+		assert.equal(refreshed.ok, false);
+		if (!refreshed.ok) {
+			assert.match(refreshed.reason, /^the feed is not a calendar: /);
+		}
+	});
+
+	it("fetches the collection's own address and clears an earlier failure", async () => {
+		const { store, collection } = await subscribed();
+		await refreshCalendarSubscription(
+			store,
+			collection,
+			3_000,
+			answering("", { status: 500 }),
+		);
+		const asked: string[] = [];
+
+		const refreshed = await refreshCalendarSubscription(
+			store,
+			collection,
+			6_000,
+			async (url) => {
+				asked.push(url);
+				return new Response(GOOGLE_FEED, { status: 200 });
+			},
+		);
+
+		assert.deepEqual(asked, [SECRET_URL]);
+		assert.ok(refreshed.ok);
+		const stored = await store.transaction((repos) =>
+			repos.calendarCollection.get(ACCOUNT_CONFIG_ID, collection.calendarId),
+		);
+		assert.equal(stored.subscriptionError, "");
+		assert.equal(stored.subscriptionFetchedAt, 6_000);
+	});
+});
+
+describe("isSubscriptionDue", () => {
+	it("is due once the last fetch is an interval old, failed or not", async () => {
+		const { collection } = await subscribed();
+		const checked = { ...collection, subscriptionCheckedAt: 10_000 };
+
+		assert.equal(isSubscriptionDue(checked, 10_000 + 899, 900), false);
+		assert.equal(isSubscriptionDue(checked, 10_000 + 900, 900), true);
+		assert.equal(isSubscriptionDue(collection, 1, 900), false);
+		assert.equal(isSubscriptionDue(collection, 900, 900), true);
+	});
+});

package/src/subscribe.ts

@@ -0,0 +1,420 @@
+import { createHash } from "node:crypto";
+import type {
+	CalendarCollectionItem,
+	ICalendarUnitOfWork,
+} from "@remit/data-ports";
+import ICAL from "ical.js";
+import { type CalendarResult, calendarFailure } from "./errors.js";
+import { readCalendarComponent, serializeCalendar } from "./parse.js";
+import { deleteCalendarObject, putCalendarObject } from "./put.js";
+
+export const CALENDAR_SUBSCRIPTION_TIMEOUT_MS = 30_000;
+
+export const CALENDAR_SUBSCRIPTION_MAX_BYTES = 10 * 1024 * 1024;
+
+const SUBSCRIPTION_ERROR_MAX_LENGTH = 512;
+
+const SCHEMES: Record<string, string> = {
+	"http:": "http:",
+	"https:": "https:",
+	"webcal:": "https:",
+	"webcals:": "https:",
+};
+
+export type CalendarFeedFetcher = (
+	url: string,
+	init: RequestInit,
+) => Promise<Response>;
+
+export type CalendarFeedFetch =
+	| { ok: true; value: string }
+	| { ok: false; reason: string };
+
+export interface CalendarFeedResource {
+	uid: string;
+	resourceName: string;
+	icalData: string;
+}
+
+export interface CalendarFeedSplit {
+	resources: CalendarFeedResource[];
+	unreadable: number;
+}
+
+export interface CalendarFeedWrite {
+	/** The subscription was paused while its feed was being read, so nothing was written. */
+	paused: boolean;
+	written: number;
+	unchanged: number;
+	removed: number;
+	skipped: number;
+}
+
+export interface CalendarSubscriptionTarget {
+	accountConfigId: string;
+	calendarId: string;
+}
+
+export type CalendarSubscriptionRefresh =
+	| { ok: true; value: CalendarFeedWrite }
+	| { ok: false; reason: string };
+
+/**
+ * The URL a subscription is fetched from. `webcal:` is what calendar products
+ * hand out for "subscribe", and means the same address over HTTPS.
+ */
+export const readSubscriptionUrl = (raw: string): CalendarResult<string> => {
+	const trimmed = raw.trim();
+	if (!URL.canParse(trimmed)) {
+		return calendarFailure(
+			"InvalidSubscriptionUrl",
+			"the subscription address is not a URL",
+		);
+	}
+	const url = new URL(trimmed);
+	const scheme = SCHEMES[url.protocol];
+	if (!scheme) {
+		return calendarFailure(
+			"InvalidSubscriptionUrl",
+			`a subscription address starts with http, https or webcal, not ${url.protocol.replace(/:$/, "")}`,
+		);
+	}
+	if (url.username !== "" || url.password !== "") {
+		return calendarFailure(
+			"InvalidSubscriptionUrl",
+			"a subscription address carries no user name or password",
+		);
+	}
+	const address = new URL(`${scheme}${trimmed.slice(url.protocol.length)}`);
+	return { ok: true, value: address.toString() };
+};
+
+const truncate = (reason: string): string =>
+	reason.length <= SUBSCRIPTION_ERROR_MAX_LENGTH
+		? reason
+		: `${reason.slice(0, SUBSCRIPTION_ERROR_MAX_LENGTH - 1)}…`;
+
+const unreachableReason = (error: unknown): string => {
+	if (error instanceof Error && error.name === "TimeoutError") {
+		return `the feed did not answer within ${CALENDAR_SUBSCRIPTION_TIMEOUT_MS / 1000} seconds`;
+	}
+	const cause =
+		error instanceof Error && error.cause instanceof Error
+			? error.cause
+			: undefined;
+	const code =
+		cause && "code" in cause && typeof cause.code === "string"
+			? cause.code
+			: undefined;
+	return code
+		? `the feed could not be reached (${code})`
+		: "the feed could not be reached";
+};
+
+/**
+ * Reads a subscription's feed. Every failure is a returned reason that a
+ * person can act on and that never repeats the URL: for a Google secret
+ * address the URL is the whole credential, and the reason is stored on the
+ * collection and drawn in the calendar view.
+ */
+export const fetchCalendarFeed = async (
+	url: string,
+	fetcher: CalendarFeedFetcher = fetch,
+): Promise<CalendarFeedFetch> => {
+	const response = await fetcher(url, {
+		headers: { accept: "text/calendar, */*;q=0.5" },
+		redirect: "follow",
+		signal: AbortSignal.timeout(CALENDAR_SUBSCRIPTION_TIMEOUT_MS),
+	}).then(
+		(value) => ({ ok: true, value }) as const,
+		(error: unknown) =>
+			({ ok: false, reason: unreachableReason(error) }) as const,
+	);
+	if (!response.ok) return response;
+
+	const { status } = response.value;
+	if (status < 200 || status > 299) {
+		await response.value.body?.cancel();
+		return { ok: false, reason: `the feed answered HTTP ${status}` };
+	}
+
+	const declared = Number(response.value.headers.get("content-length") ?? "0");
+	if (declared > CALENDAR_SUBSCRIPTION_MAX_BYTES) {
+		await response.value.body?.cancel();
+		return { ok: false, reason: TOO_LARGE };
+	}
+
+	const { body } = response.value;
+	if (!body) return { ok: true, value: "" };
+	return readCapped(body).then(
+		(read) => read,
+		(error: unknown) => ({ ok: false, reason: unreachableReason(error) }),
+	);
+};
+
+const TOO_LARGE = "the feed is larger than 10 MB";
+
+/**
+ * Reads a body a chunk at a time and stops at the cap. A feed sent chunked
+ * carries no length to refuse up front, so counting as it arrives is the only
+ * thing that keeps an endless body out of memory.
+ */
+const readCapped = async (
+	body: ReadableStream<Uint8Array>,
+): Promise<CalendarFeedFetch> => {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let received = 0;
+	let text = "";
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		received += value.byteLength;
+		if (received > CALENDAR_SUBSCRIPTION_MAX_BYTES) {
+			await reader.cancel();
+			return { ok: false, reason: TOO_LARGE };
+		}
+		text += decoder.decode(value, { stream: true });
+	}
+	return { ok: true, value: text + decoder.decode() };
+};
+
+/**
+ * A resource as it would compare across two fetches. DTSTAMP is when the
+ * provider exported the feed, not when the event changed — Google restamps it
+ * on every fetch — so it is left out, or every refresh would rewrite every
+ * event.
+ */
+const comparable = (icalData: string): string =>
+	icalData.replace(/^DTSTAMP[;:][^\r\n]*\r?\n/gim, "");
+
+const resourceNameOf = (uid: string): string =>
+	`${createHash("sha256").update(uid, "utf8").digest("hex").slice(0, 40)}.ics`;
+
+const zonesReferencedBy = (events: ICAL.Component[]): Set<string> => {
+	const zones = new Set<string>();
+	for (const event of events) {
+		for (const property of event.getAllProperties()) {
+			const tzid = property.getParameter("tzid");
+			if (typeof tzid === "string") zones.add(tzid);
+		}
+	}
+	return zones;
+};
+
+/**
+ * Cuts a whole feed into one resource per UID, the shape the calendar write
+ * path stores: a series and its RECURRENCE-ID overrides travel together, with
+ * the VTIMEZONEs they name, so a DST-crossing series resolves against the zone
+ * the provider published.
+ *
+ * The feed's calendar-level properties are kept on every resource except
+ * METHOD, which a stored resource never carries. A VEVENT with no UID has
+ * nothing to key it by across refreshes, so it is counted and left out.
+ */
+export const splitCalendarFeed = async (
+	icalData: string,
+): Promise<CalendarResult<CalendarFeedSplit>> => {
+	const read = await readCalendarComponent(icalData);
+	if (!read.ok) return read;
+	const feed = read.value;
+	if (feed.name !== "vcalendar") {
+		return calendarFailure(
+			"NotACalendar",
+			feed.name
+				? `expected a VCALENDAR, found ${feed.name.toUpperCase()}`
+				: "expected a VCALENDAR, found nothing",
+		);
+	}
+
+	const timezones = feed.getAllSubcomponents("vtimezone");
+	const byUid = new Map<string, ICAL.Component[]>();
+	let unreadable = 0;
+	for (const event of feed.getAllSubcomponents("vevent")) {
+		const uid = event.getFirstPropertyValue("uid");
+		if (typeof uid !== "string" || uid === "") {
+			unreadable += 1;
+			continue;
+		}
+		byUid.set(uid, [...(byUid.get(uid) ?? []), event]);
+	}
+
+	const resources = [...byUid].map(([uid, events]) => {
+		const calendar = new ICAL.Component("vcalendar");
+		for (const property of feed.getAllProperties()) {
+			if (property.name === "method") continue;
+			calendar.addProperty(new ICAL.Property(property.toJSON()));
+		}
+		const zones = zonesReferencedBy(events);
+		for (const timezone of timezones) {
+			const tzid = timezone.getFirstPropertyValue("tzid");
+			if (typeof tzid === "string" && zones.has(tzid)) {
+				calendar.addSubcomponent(new ICAL.Component(timezone.toJSON()));
+			}
+		}
+		for (const event of events) {
+			calendar.addSubcomponent(new ICAL.Component(event.toJSON()));
+		}
+		return {
+			uid,
+			resourceName: resourceNameOf(uid),
+			icalData: serializeCalendar(calendar),
+		};
+	});
+
+	return { ok: true, value: { resources, unreadable } };
+};
+
+const feedErrorOf = (write: CalendarFeedWrite): string =>
+	write.skipped === 0
+		? ""
+		: `${write.skipped} ${write.skipped === 1 ? "event" : "events"} in the feed could not be stored`;
+
+/**
+ * Makes a subscribed collection hold what the feed holds, in one unit.
+ *
+ * Every resource goes through `putCalendarObject`, the one write path, so a
+ * subscribed event is stored, projected and expanded the way any other event
+ * is. A resource whose bytes have not changed is left alone, and one the feed
+ * no longer carries is removed. A resource the write path refuses is counted
+ * and recorded on the collection rather than failing the whole refresh.
+ */
+export const writeCalendarFeed = async (
+	unitOfWork: ICalendarUnitOfWork,
+	target: CalendarSubscriptionTarget,
+	split: CalendarFeedSplit,
+	now: number,
+): Promise<CalendarFeedWrite> =>
+	unitOfWork.transaction(async (repos) => {
+		const current = await repos.calendarCollection.get(
+			target.accountConfigId,
+			target.calendarId,
+		);
+		if (!current.subscriptionEnabled) {
+			return { paused: true, written: 0, unchanged: 0, removed: 0, skipped: 0 };
+		}
+		const stored = await repos.calendarObject.listByCalendar(target.calendarId);
+		const storedByName = new Map(
+			stored.map((object) => [object.resourceName, object]),
+		);
+		const kept = new Set<string>();
+		const write: CalendarFeedWrite = {
+			paused: false,
+			written: 0,
+			unchanged: 0,
+			removed: 0,
+			skipped: split.unreadable,
+		};
+
+		for (const resource of split.resources) {
+			const existing = storedByName.get(resource.resourceName);
+			if (
+				existing &&
+				comparable(existing.icalData) === comparable(resource.icalData)
+			) {
+				kept.add(resource.resourceName);
+				write.unchanged += 1;
+				continue;
+			}
+			const put = await putCalendarObject(unitOfWork, {
+				accountConfigId: target.accountConfigId,
+				calendarId: target.calendarId,
+				resourceName: resource.resourceName,
+				icalData: resource.icalData,
+			});
+			if (!put.ok) {
+				write.skipped += 1;
+				continue;
+			}
+			kept.add(resource.resourceName);
+			write.written += 1;
+		}
+
+		for (const object of stored) {
+			if (kept.has(object.resourceName)) continue;
+			await deleteCalendarObject(unitOfWork, {
+				accountConfigId: target.accountConfigId,
+				calendarId: target.calendarId,
+				calendarObjectId: object.calendarObjectId,
+			});
+			write.removed += 1;
+		}
+
+		await repos.calendarCollection.update(
+			target.accountConfigId,
+			target.calendarId,
+			{
+				subscriptionCheckedAt: now,
+				subscriptionFetchedAt: now,
+				subscriptionError: truncate(feedErrorOf(write)),
+			},
+		);
+		return write;
+	});
+
+/** Records a refresh that stored nothing, and why. Every stored event stays. */
+export const recordCalendarFeedFailure = async (
+	unitOfWork: ICalendarUnitOfWork,
+	target: CalendarSubscriptionTarget,
+	reason: string,
+	now: number,
+): Promise<void> => {
+	await unitOfWork.transaction((repos) =>
+		repos.calendarCollection.update(target.accountConfigId, target.calendarId, {
+			subscriptionCheckedAt: now,
+			subscriptionError: truncate(reason),
+		}),
+	);
+};
+
+/** Fetches and cuts a feed, or answers why it cannot be stored. */
+export const readCalendarFeed = async (
+	url: string,
+	fetcher: CalendarFeedFetcher = fetch,
+): Promise<
+	{ ok: true; value: CalendarFeedSplit } | { ok: false; reason: string }
+> => {
+	const fetched = await fetchCalendarFeed(url, fetcher);
+	if (!fetched.ok) return fetched;
+	const split = await splitCalendarFeed(fetched.value);
+	if (!split.ok) {
+		return {
+			ok: false,
+			reason: `the feed is not a calendar: ${split.error.message}`,
+		};
+	}
+	return split;
+};
+
+/**
+ * One scheduled refresh of one subscription. A feed that cannot be read
+ * records its reason on the collection and removes nothing.
+ */
+export const refreshCalendarSubscription = async (
+	unitOfWork: ICalendarUnitOfWork,
+	collection: CalendarCollectionItem,
+	now: number,
+	fetcher: CalendarFeedFetcher = fetch,
+): Promise<CalendarSubscriptionRefresh> => {
+	const target = {
+		accountConfigId: collection.accountConfigId,
+		calendarId: collection.calendarId,
+	};
+	const feed = await readCalendarFeed(collection.subscriptionUrl, fetcher);
+	if (!feed.ok) {
+		await recordCalendarFeedFailure(unitOfWork, target, feed.reason, now);
+		return feed;
+	}
+	const write = await writeCalendarFeed(unitOfWork, target, feed.value, now);
+	return { ok: true, value: write };
+};
+
+/**
+ * Whether a subscription is due a refresh: its last fetch, successful or not,
+ * is at least `intervalMs` old.
+ */
+export const isSubscriptionDue = (
+	collection: CalendarCollectionItem,
+	now: number,
+	intervalMs: number,
+): boolean => now - collection.subscriptionCheckedAt >= intervalMs;

package/src/window.test.ts

@@ -36,6 +36,11 @@ const collection = (
 	source: CalendarSource.Default,
 	timezone: "",
 	syncSequence: 1,
+	subscriptionUrl: "",
+	subscriptionEnabled: false,
+	subscriptionCheckedAt: 0,
+	subscriptionFetchedAt: 0,
+	subscriptionError: "",
 	createdAt: 0,
 	updatedAt: 0,
 	...overrides,