@remit/calendar-service 0.0.7 → 0.0.9

package/package.json

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

package/src/feed.test.ts

@@ -9,7 +9,6 @@ import {
 	CALENDAR_FEED_TOKEN_BYTES,
 	calendarFeedIsUnchanged,
 	calendarFeedIsUnmodifiedSince,
-	calendarFeedPath,
 	hashCalendarFeedToken,
 	isCalendarFeedToken,
 	mintCalendarFeedToken,
@@ -99,7 +98,7 @@ describe("a feed address", () => {
 		const minted = mintCalendarFeedToken();
 
 		assert.equal(
-			readCalendarFeedToken(calendarFeedPath(minted.token)),
+			readCalendarFeedToken(`/feeds/calendar/${minted.token}.ics`),
 			minted.token,
 		);
 	});
@@ -279,7 +278,9 @@ describe("a feed path in a log line", () => {
 	it("keeps the route and drops the token", () => {
 		const minted = mintCalendarFeedToken();
 
-		const redacted = redactCalendarFeedPath(calendarFeedPath(minted.token));
+		const redacted = redactCalendarFeedPath(
+			`/feeds/calendar/${minted.token}.ics`,
+		);
 
 		assert.equal(redacted.includes(minted.token), false);
 		assert.equal(redacted, "/feeds/calendar/<redacted>.ics");

package/src/feed.ts

@@ -50,9 +50,6 @@ export const mintCalendarFeedToken = (): CalendarFeedSecret => {
 export const isCalendarFeedToken = (token: string): boolean =>
 	TOKEN_SHAPE.test(token);
 
-export const calendarFeedPath = (token: string): string =>
-	`${CALENDAR_FEED_PATH_PREFIX}${token}${CALENDAR_FEED_PATH_SUFFIX}`;
-
 /**
  * The token a request path carries, or `null` when the path is not a feed
  * address. One segment only: a slash inside it would name a different route.

package/src/index.ts

@@ -37,7 +37,6 @@ export {
 	type CalendarFeedSecret,
 	calendarFeedIsUnchanged,
 	calendarFeedIsUnmodifiedSince,
-	calendarFeedPath,
 	hashCalendarFeedToken,
 	isCalendarFeedToken,
 	mintCalendarFeedToken,

package/src/project.ts

@@ -36,18 +36,11 @@ const TRANSPARENCY_BY_ICAL: Record<string, CalendarObjectItem["transparency"]> =
 		TRANSPARENT: CalendarTransparency.Transparent,
 	};
 
-const readString = (component: ICAL.Component, name: string): string => {
+export const readString = (component: ICAL.Component, name: string): string => {
 	const value = component.getFirstPropertyValue(name);
 	return typeof value === "string" ? value : "";
 };
 
-/**
- * Whether the resource expands to more than its master instance — an RRULE, an
- * RDATE, or an override VEVENT. The overrides count: a client that edits one
- * instance of a series and then deletes the rule leaves a resource with nothing
- * but a master and its exceptions, and every one of those is still an
- * occurrence somebody has to see.
- */
 /**
  * The fields that describe one VEVENT rather than the series it belongs to.
  *
@@ -73,6 +66,13 @@ export const projectEventDisplay = (
 		CalendarTransparency.Opaque,
 });
 
+/**
+ * Whether the resource expands to more than its master instance — an RRULE, an
+ * RDATE, or an override VEVENT. The overrides count: a client that edits one
+ * instance of a series and then deletes the rule leaves a resource with nothing
+ * but a master and its exceptions, and every one of those is still an
+ * occurrence somebody has to see.
+ */
 export const hasRecurrence = (calendar: ParsedCalendar): boolean =>
 	calendar.master.hasProperty("rrule") ||
 	calendar.master.hasProperty("rdate") ||

package/src/scope.test.ts

@@ -98,6 +98,222 @@ describe("applyScopedUpdate", () => {
 		assert.ok(master?.includes("DTSTART:20260907T090000Z"));
 	});
 
+	it("moves the series by what changed on the occurrence a scope=All edit was made from", async () => {
+		const calendar = await read(WEEKLY);
+
+		const write = await applyScopedUpdate(
+			calendar,
+			"",
+			input(RecurrenceScope.All, "2026-09-21T09:00:00Z"),
+			{ start: "2026-09-21T14:00:00Z", end: "2026-09-21T15:30:00Z" },
+		);
+
+		assert.ok(write.ok);
+		assert.ok(write.value.kind === "Replace");
+		const [master, ...rest] = events(write.value.icalData);
+		assert.deepEqual(rest, []);
+		assert.ok(
+			master?.includes("DTSTART:20260907T140000Z"),
+			`the series still starts on its first occurrence: ${master?.join(" | ")}`,
+		);
+		assert.ok(master?.includes("DTEND:20260907T153000Z"));
+		assert.ok(master?.includes("RRULE:FREQ=WEEKLY;COUNT=5"));
+	});
+
+	it("keeps a zoned series on its own first day when a scope=All edit crosses a clock change", async () => {
+		const calendar = await read(AMSTERDAM_WEEKLY);
+
+		const write = await applyScopedUpdate(
+			calendar,
+			"Europe/Amsterdam",
+			input(RecurrenceScope.All, "2026-10-29T08:00:00Z"),
+			{
+				start: "2026-10-29T10:00:00+01:00",
+				end: "2026-10-29T11:00:00+01:00",
+				timeZone: "Europe/Amsterdam",
+			},
+		);
+
+		assert.ok(write.ok);
+		assert.ok(write.value.kind === "Replace");
+		const [master] = events(write.value.icalData);
+		assert.ok(
+			master?.includes("DTSTART;TZID=Europe/Amsterdam:20261015T100000"),
+			`the series moves on its own wall clock: ${master?.join(" | ")}`,
+		);
+		assert.ok(master?.includes("DTEND;TZID=Europe/Amsterdam:20261015T110000"));
+	});
+
+	it("keeps a series on its weekday when a scope=All edit is made from an occurrence moved on its own", async () => {
+		const calendar = await read(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"UID:weekly@example.com",
+				"DTSTART:20260907T090000Z",
+				"DTEND:20260907T100000Z",
+				"SUMMARY:Stand-up",
+				"RRULE:FREQ=WEEKLY;COUNT=5",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"UID:weekly@example.com",
+				"RECURRENCE-ID:20260921T090000Z",
+				"DTSTART:20260923T090000Z",
+				"DTEND:20260923T100000Z",
+				"SUMMARY:Stand-up",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		const write = await applyScopedUpdate(
+			calendar,
+			"",
+			input(RecurrenceScope.All, "2026-09-21T09:00:00Z"),
+			{ start: "2026-09-23T10:00:00Z", end: "2026-09-23T11:00:00Z" },
+		);
+
+		assert.ok(write.ok);
+		assert.ok(write.value.kind === "Replace");
+		const [master, override] = events(write.value.icalData);
+		assert.ok(
+			master?.includes("DTSTART:20260907T100000Z"),
+			`the series stays on Mondays: ${master?.join(" | ")}`,
+		);
+		assert.ok(master?.includes("DTEND:20260907T110000Z"));
+		assert.ok(
+			override?.includes("RECURRENCE-ID:20260921T100000Z"),
+			`the moved occurrence still replaces its own slot: ${override?.join(" | ")}`,
+		);
+		assert.ok(override?.includes("DTSTART:20260923T090000Z"));
+
+		const expanded = expandCalendar(await read(write.value.icalData), "");
+		assert.deepEqual(
+			expanded.occurrences.map((occurrence) => occurrence.startAt),
+			[
+				"2026-09-07T10:00:00Z",
+				"2026-09-14T10:00:00Z",
+				"2026-09-23T09:00:00Z",
+				"2026-09-28T10:00:00Z",
+				"2026-10-05T10:00:00Z",
+			],
+		);
+	});
+
+	it("keeps an excluded occurrence excluded when a scope=All edit moves the series' time", async () => {
+		const calendar = await read(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"UID:weekly@example.com",
+				"DTSTART:20260907T090000Z",
+				"DTEND:20260907T100000Z",
+				"SUMMARY:Stand-up",
+				"RRULE:FREQ=WEEKLY;COUNT=5",
+				"EXDATE:20260914T090000Z",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		const write = await applyScopedUpdate(
+			calendar,
+			"",
+			input(RecurrenceScope.All, "2026-09-21T09:00:00Z"),
+			{ start: "2026-09-21T10:00:00Z", end: "2026-09-21T11:00:00Z" },
+		);
+
+		assert.ok(write.ok);
+		assert.ok(write.value.kind === "Replace");
+		const expanded = expandCalendar(await read(write.value.icalData), "");
+		assert.deepEqual(
+			expanded.occurrences.map((occurrence) => occurrence.startAt),
+			[
+				"2026-09-07T10:00:00Z",
+				"2026-09-21T10:00:00Z",
+				"2026-09-28T10:00:00Z",
+				"2026-10-05T10:00:00Z",
+			],
+		);
+	});
+
+	it("moves only the end when a scope=All edit changes only the end", async () => {
+		const calendar = await read(WEEKLY);
+
+		const write = await applyScopedUpdate(
+			calendar,
+			"",
+			input(RecurrenceScope.All, "2026-09-21T09:00:00Z"),
+			{ end: "2026-09-21T11:00:00Z" },
+		);
+
+		assert.ok(write.ok);
+		assert.ok(write.value.kind === "Replace");
+		const [master] = events(write.value.icalData);
+		assert.ok(
+			master?.includes("DTSTART:20260907T090000Z"),
+			`the start is untouched: ${master?.join(" | ")}`,
+		);
+		assert.ok(
+			master?.includes("DTEND:20260907T110000Z"),
+			`the end lands on the series' first day: ${master?.join(" | ")}`,
+		);
+	});
+
+	it("keeps the series' first day when a scope=All edit changes only the zone", async () => {
+		const calendar = await read(WEEKLY);
+
+		const write = await applyScopedUpdate(
+			calendar,
+			"",
+			input(RecurrenceScope.All, "2026-09-21T09:00:00Z"),
+			{ timeZone: "Europe/Amsterdam" },
+		);
+
+		assert.ok(write.ok);
+		assert.ok(write.value.kind === "Replace");
+		const [master] = events(write.value.icalData);
+		assert.ok(
+			master?.includes("DTSTART;TZID=Europe/Amsterdam:20260907T110000"),
+			`the same instant, read in the new zone: ${master?.join(" | ")}`,
+		);
+		assert.ok(master?.includes("DTEND;TZID=Europe/Amsterdam:20260907T120000"));
+	});
+
+	it("keeps the series' first day when a scope=All edit changes only all-day", async () => {
+		const calendar = await read(WEEKLY);
+
+		const write = await applyScopedUpdate(
+			calendar,
+			"",
+			input(RecurrenceScope.All, "2026-09-21T09:00:00Z"),
+			{ allDay: true },
+		);
+
+		assert.ok(write.ok);
+		assert.ok(write.value.kind === "Replace");
+		const [master] = events(write.value.icalData);
+		assert.ok(
+			master?.includes("DTSTART;VALUE=DATE:20260907"),
+			`the series still starts on its first day: ${master?.join(" | ")}`,
+		);
+	});
+
+	it("refuses a scope=All time change made from an occurrence the series does not have", async () => {
+		const calendar = await read(WEEKLY);
+
+		const write = await applyScopedUpdate(
+			calendar,
+			"",
+			input(RecurrenceScope.All, "2026-09-22T09:00:00Z"),
+			{ start: "2026-09-22T14:00:00Z", end: "2026-09-22T15:00:00Z" },
+		);
+
+		assert.equal(write.ok, false);
+	});
+
 	it("writes a RECURRENCE-ID override for one occurrence under scope=This", async () => {
 		const calendar = await read(WEEKLY);
 

package/src/scope.ts

@@ -29,7 +29,7 @@ export type ScopedWrite =
 
 export interface ScopedWriteInput {
 	scope: RecurrenceScopeValue;
-	/** ISO 8601 UTC instant naming the occurrence; `""` outside `This`/`Following`. */
+	/** ISO 8601 UTC instant naming the occurrence the write was made from, or `""`. */
 	recurrenceId: string;
 	/** UID the resource a `Following` split creates is written under. */
 	followingUid: string;
@@ -286,6 +286,138 @@ const applyToMaster = async (
 	return { ok: true, value: replaceWith(calendar) };
 };
 
+const touchesTime = (patch: Partial<CalendarEventFields>): boolean =>
+	patch.start !== undefined ||
+	patch.end !== undefined ||
+	patch.allDay !== undefined ||
+	patch.timeZone !== undefined;
+
+const civilDay = (time: ICAL.Time): number =>
+	Date.UTC(time.year, time.month - 1, time.day) / 86_400_000;
+
+const shiftProperty = (
+	component: ICAL.Component,
+	name: string,
+	days: number,
+): void => {
+	const property = component.getFirstProperty(name);
+	const value = property?.getFirstValue();
+	if (!property || !(value instanceof ICAL.Time)) return;
+	const shifted = value.clone();
+	shifted.adjust(days, 0, 0, 0);
+	property.setValue(shifted);
+};
+
+/** Where an occurrence is drawn, which a moved one no longer shares with its slot. */
+const shownStart = (occurrence: FoundOccurrence): ICAL.Time | null => {
+	if (occurrence.details) return occurrence.details.startDate;
+	const start = occurrence.override?.getFirstPropertyValue("dtstart");
+	return start instanceof ICAL.Time ? start : null;
+};
+
+/**
+ * The slot a value named under the old DTSTART, named under the new one: the
+ * same day of the series, at the series' new time and in its new zone.
+ */
+const reslot = (
+	value: ICAL.Time,
+	before: ICAL.Time,
+	after: ICAL.Time,
+): ICAL.Time => {
+	const moved = after.clone();
+	moved.adjust(civilDay(value) - civilDay(before), 0, 0, 0);
+	return moved;
+};
+
+/**
+ * Keeps every override and excluded date on the slot it was written for once
+ * the series' own start has moved. A RECURRENCE-ID or an EXDATE matches a slot
+ * by its exact time, so leaving them behind would detach a moved occurrence
+ * from the one it replaces and bring a deleted one back.
+ */
+const followSlots = (
+	calendar: ParsedCalendar,
+	before: ICAL.Time,
+	after: ICAL.Time,
+): void => {
+	if (before.isDate !== after.isDate) return;
+	const tzid = dtStartTzid(calendar.master);
+	for (const override of calendar.overrides) {
+		const recurrenceId = override.getFirstPropertyValue("recurrence-id");
+		if (!(recurrenceId instanceof ICAL.Time)) continue;
+		override.removeAllProperties("recurrence-id");
+		override.addProperty(
+			timeProperty("recurrence-id", reslot(recurrenceId, before, after), tzid),
+		);
+	}
+	for (const name of ["exdate", "rdate"]) {
+		for (const property of calendar.master.getAllProperties(name)) {
+			const values = property.getValues();
+			if (!values.every((value: unknown) => value instanceof ICAL.Time)) {
+				continue;
+			}
+			calendar.master.removeProperty(property);
+			for (const value of values as ICAL.Time[]) {
+				calendar.master.addProperty(
+					timeProperty(name, reslot(value, before, after), tzid),
+				);
+			}
+		}
+	}
+};
+
+/**
+ * A whole-series edit made from one occurrence of it.
+ *
+ * A start or end in the patch is that occurrence's new time, so each is moved
+ * back by the days between where that occurrence is drawn and where the series
+ * begins. The series keeps its first day and its weekday, and only what was
+ * edited changes.
+ */
+const applyToSeriesFrom = async (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+	recurrenceId: string,
+	patch: Partial<CalendarEventFields>,
+): Promise<CalendarResult<ScopedWrite>> => {
+	const found = findOccurrence(calendar, collectionTimezone, recurrenceId);
+	if (!found.ok) return found;
+	const seriesStart = calendar.master.getFirstPropertyValue("dtstart");
+	const shown = shownStart(found.value);
+	if (!(seriesStart instanceof ICAL.Time) || !shown) {
+		return calendarFailure(
+			"UnknownOccurrence",
+			`${recurrenceId} has no start to move the series from`,
+		);
+	}
+	const before = seriesStart.clone();
+	const beforeTzid = dtStartTzid(calendar.master);
+	const daysIn = civilDay(shown) - civilDay(before);
+
+	const applied = await applyEventFields(
+		calendar.master,
+		patch,
+		collectionTimezone,
+	);
+	if (!applied.ok) return applied;
+	if (patch.start !== undefined) {
+		shiftProperty(calendar.master, "dtstart", -daysIn);
+	}
+	if (patch.end !== undefined) {
+		shiftProperty(calendar.master, "dtend", -daysIn);
+	}
+
+	const after = calendar.master.getFirstPropertyValue("dtstart");
+	if (
+		after instanceof ICAL.Time &&
+		(after.toString() !== before.toString() ||
+			dtStartTzid(calendar.master) !== beforeTzid)
+	) {
+		followSlots(calendar, before, after);
+	}
+	return { ok: true, value: replaceWith(calendar) };
+};
+
 /**
  * The occurrence a `This` or `Following` write names, or `null` when the scope
  * collapses to the whole series — which is what "everything from the first
@@ -362,7 +494,8 @@ const overrideFor = async (
 /**
  * Turns an edit of one drawing of a series into the resource writes it means.
  *
- * `All` rewrites the master. `This` writes a RECURRENCE-ID override, which is
+ * `All` rewrites the master, moved from the occurrence it names when it names
+ * one. `This` writes a RECURRENCE-ID override, which is
  * the only thing iCalendar has for "this one is different". `Following` splits,
  * because a rule cannot change halfway through.
  */
@@ -373,7 +506,19 @@ export const applyScopedUpdate = async (
 	patch: Partial<CalendarEventFields>,
 ): Promise<CalendarResult<ScopedWrite>> => {
 	if (input.scope === RecurrenceScope.All) {
-		return applyToMaster(calendar, collectionTimezone, patch);
+		if (
+			input.recurrenceId === "" ||
+			!hasRecurrence(calendar) ||
+			!touchesTime(patch)
+		) {
+			return applyToMaster(calendar, collectionTimezone, patch);
+		}
+		return applyToSeriesFrom(
+			calendar,
+			collectionTimezone,
+			input.recurrenceId,
+			patch,
+		);
 	}
 
 	const anchored = anchorOf(calendar, collectionTimezone, input);

package/src/suggest.ts

@@ -10,7 +10,7 @@ import {
 import type ICAL from "ical.js";
 import type { CalendarResult } from "./errors.js";
 import { parseCalendar } from "./parse.js";
-import { projectCalendar } from "./project.js";
+import { projectCalendar, readString } from "./project.js";
 
 const METHOD_BY_ICAL: Record<string, CalendarSuggestionItem["method"]> = {
 	REQUEST: CalendarInviteMethod.Request,
@@ -20,11 +20,6 @@ const METHOD_BY_ICAL: Record<string, CalendarSuggestionItem["method"]> = {
 	PUBLISH: CalendarInviteMethod.Publish,
 };
 
-const readString = (component: ICAL.Component, name: string): string => {
-	const value = component.getFirstPropertyValue(name);
-	return typeof value === "string" ? value : "";
-};
-
 /**
  * A `CAL-ADDRESS` as a plain mail address. RFC 5545 3.3.3 writes one as a URI,
  * which in practice is always `mailto:`; a card shows a person, not a URI.