@remit/calendar-service 0.0.2 → 0.0.4

package/src/suggest.test.ts

@@ -0,0 +1,329 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { CalendarSuggestionItem } from "@remit/data-ports";
+import { deriveCalendarSuggestionId } from "@remit/data-ports/id";
+import {
+	CalendarInviteMethod,
+	CalendarSuggestionSource,
+	CalendarSuggestionState,
+} from "@remit/domain-enums";
+import { AMSTERDAM_VTIMEZONE, ical } from "./fixtures.js";
+import { MemoryCalendarStore } from "./memory-store.js";
+import { projectSuggestion, recordCalendarSuggestion } from "./suggest.js";
+
+const ACCOUNT_CONFIG_ID = "account-config-1";
+const UID = "invite-4711@example.test";
+
+const invitation = ({
+	method = "REQUEST",
+	sequence = 0,
+	summary = "Quarterly review",
+	uid = UID,
+	extra = [] as string[],
+}): string =>
+	ical(
+		"BEGIN:VCALENDAR",
+		"VERSION:2.0",
+		"PRODID:-//Example Corp//Scheduler//EN",
+		`METHOD:${method}`,
+		...AMSTERDAM_VTIMEZONE,
+		"BEGIN:VEVENT",
+		`UID:${uid}`,
+		"DTSTAMP:20260801T090000Z",
+		`SEQUENCE:${sequence}`,
+		"DTSTART;TZID=Europe/Amsterdam:20260901T100000",
+		"DTEND;TZID=Europe/Amsterdam:20260901T110000",
+		`SUMMARY:${summary}`,
+		"LOCATION:Room 4",
+		"ORGANIZER;CN=Ada:mailto:organizer@example.test",
+		"ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:user@example.test",
+		...extra,
+		"END:VEVENT",
+		"END:VCALENDAR",
+	);
+
+const record = (
+	store: MemoryCalendarStore,
+	icalData: string,
+	messageId: string,
+) =>
+	recordCalendarSuggestion(store.calendarSuggestion, {
+		accountConfigId: ACCOUNT_CONFIG_ID,
+		messageId,
+		bodyPartId: "body-part-1",
+		source: CalendarSuggestionSource.IcalendarPart,
+		icalData,
+		timezone: "Europe/Amsterdam",
+	});
+
+describe("projectSuggestion", () => {
+	it("reads the facts a card is drawn from", async () => {
+		const projected = await projectSuggestion(
+			invitation({}),
+			"Europe/Amsterdam",
+		);
+
+		assert.ok(projected.ok);
+		assert.equal(projected.value.icalUid, UID);
+		assert.equal(projected.value.method, CalendarInviteMethod.Request);
+		assert.equal(projected.value.summary, "Quarterly review");
+		assert.equal(projected.value.location, "Room 4");
+		assert.equal(projected.value.organizer, "organizer@example.test");
+		assert.equal(projected.value.dtStart, "2026-09-01T10:00:00+02:00");
+		assert.equal(projected.value.dtEnd, "2026-09-01T11:00:00+02:00");
+		assert.equal(projected.value.allDay, false);
+	});
+
+	it("reads a cancellation as a cancellation", async () => {
+		const projected = await projectSuggestion(
+			invitation({ method: "CANCEL", sequence: 2 }),
+			"Europe/Amsterdam",
+		);
+
+		assert.ok(projected.ok);
+		assert.equal(projected.value.method, CalendarInviteMethod.Cancel);
+		assert.equal(projected.value.sequence, 2);
+	});
+
+	it("reads a bare .ics as carrying no method", async () => {
+		const bare = ical(
+			"BEGIN:VCALENDAR",
+			"VERSION:2.0",
+			"PRODID:-//Example//EN",
+			"BEGIN:VEVENT",
+			`UID:${UID}`,
+			"DTSTAMP:20260801T090000Z",
+			"DTSTART:20260901T080000Z",
+			"DTEND:20260901T090000Z",
+			"SUMMARY:Lunch",
+			"END:VEVENT",
+			"END:VCALENDAR",
+		);
+
+		const projected = await projectSuggestion(bare, "Europe/Amsterdam");
+
+		assert.ok(projected.ok);
+		assert.equal(projected.value.method, CalendarInviteMethod.None);
+		assert.equal(projected.value.organizer, "");
+		assert.equal(projected.value.location, "");
+	});
+
+	it("refuses unreadable iCalendar as a value, not a throw", async () => {
+		const projected = await projectSuggestion("not a calendar", "UTC");
+
+		assert.equal(projected.ok, false);
+		assert.ok(!projected.ok && projected.error.code);
+	});
+});
+
+describe("recordCalendarSuggestion", () => {
+	it("writes a fixture invitation as one Pending suggestion", async () => {
+		const store = new MemoryCalendarStore();
+
+		const recorded = await record(store, invitation({}), "message-1");
+
+		assert.ok(recorded.ok);
+		assert.equal(
+			recorded.value.suggestion.state,
+			CalendarSuggestionState.Pending,
+		);
+		assert.equal(recorded.value.suggestion.icalUid, UID);
+		assert.equal(
+			recorded.value.suggestion.suggestionId,
+			deriveCalendarSuggestionId("message-1", "body-part-1", UID),
+		);
+		assert.equal(recorded.value.suggestion.acceptedCalendarObjectId, "");
+		assert.deepEqual(recorded.value.superseded, []);
+	});
+
+	it("stores the invitation's bytes unchanged", async () => {
+		const store = new MemoryCalendarStore();
+		const bytes = invitation({});
+
+		const recorded = await record(store, bytes, "message-1");
+
+		assert.ok(recorded.ok);
+		assert.equal(recorded.value.suggestion.icalData, bytes);
+	});
+
+	it("re-reading the same message rewrites the one row", async () => {
+		const store = new MemoryCalendarStore();
+
+		await record(store, invitation({}), "message-1");
+		await record(store, invitation({}), "message-1");
+
+		assert.equal(store.suggestions.size, 1);
+	});
+
+	it("supersedes the earlier revision and offers the new one", async () => {
+		const store = new MemoryCalendarStore();
+
+		const first = await record(store, invitation({ sequence: 0 }), "message-1");
+		const second = await record(
+			store,
+			invitation({ sequence: 1, summary: "Quarterly review, moved" }),
+			"message-2",
+		);
+
+		assert.ok(first.ok);
+		assert.ok(second.ok);
+		assert.equal(
+			second.value.suggestion.state,
+			CalendarSuggestionState.Pending,
+		);
+		assert.deepEqual(
+			second.value.superseded.map((row) => row.suggestionId),
+			[first.value.suggestion.suggestionId],
+		);
+		const superseded = await store.calendarSuggestion.get(
+			ACCOUNT_CONFIG_ID,
+			first.value.suggestion.suggestionId,
+		);
+		assert.equal(superseded.state, CalendarSuggestionState.Superseded);
+	});
+
+	it("leaves the earlier revision alone when the sequence did not move", async () => {
+		// SEQUENCE is the organizer's revision counter. A resend of the same
+		// revision — a redelivery, a second copy filed elsewhere — is not a new
+		// revision, and retiring the card the user is looking at would be a lie.
+		const store = new MemoryCalendarStore();
+
+		const first = await record(store, invitation({ sequence: 3 }), "message-1");
+		const second = await record(
+			store,
+			invitation({ sequence: 3 }),
+			"message-2",
+		);
+
+		assert.ok(first.ok);
+		assert.ok(second.ok);
+		assert.deepEqual(second.value.superseded, []);
+		const earlier = await store.calendarSuggestion.get(
+			ACCOUNT_CONFIG_ID,
+			first.value.suggestion.suggestionId,
+		);
+		assert.equal(earlier.state, CalendarSuggestionState.Pending);
+	});
+
+	it("leaves another event's card alone", async () => {
+		const store = new MemoryCalendarStore();
+
+		const other = await record(
+			store,
+			invitation({ uid: "other@example.test" }),
+			"message-1",
+		);
+		const mine = await record(store, invitation({ sequence: 4 }), "message-2");
+
+		assert.ok(other.ok);
+		assert.ok(mine.ok);
+		assert.deepEqual(mine.value.superseded, []);
+	});
+
+	it("never retires a suggestion the user already answered", async () => {
+		// A decision is the user's. A later revision arriving does not erase the
+		// event they added; a cancellation reaches the calendar only when they
+		// accept the cancellation card.
+		const store = new MemoryCalendarStore();
+
+		const first = await record(store, invitation({ sequence: 0 }), "message-1");
+		assert.ok(first.ok);
+		await store.calendarSuggestion.settle(
+			ACCOUNT_CONFIG_ID,
+			first.value.suggestion.suggestionId,
+			{
+				state: CalendarSuggestionState.Accepted,
+				acceptedCalendarObjectId: "cal-object-1",
+			},
+		);
+
+		const second = await record(
+			store,
+			invitation({ sequence: 1 }),
+			"message-2",
+		);
+
+		assert.ok(second.ok);
+		assert.deepEqual(second.value.superseded, []);
+		const answered = await store.calendarSuggestion.get(
+			ACCOUNT_CONFIG_ID,
+			first.value.suggestion.suggestionId,
+		);
+		assert.equal(answered.state, CalendarSuggestionState.Accepted);
+	});
+
+	it("keeps an acceptance that lands between the read and the retire", async () => {
+		// The producer reads the pending set, then retires what it found. A
+		// person pressing Add to calendar in that gap must keep their event: an
+		// unconditional write here would mark the card Superseded and blank the
+		// id of the resource it just put in their calendar, orphaning it.
+		const store = new MemoryCalendarStore();
+		const first = await record(store, invitation({ sequence: 0 }), "message-1");
+		assert.ok(first.ok);
+		const target = first.value.suggestion.suggestionId;
+
+		const racing = {
+			...store.calendarSuggestion,
+			listByState: async (
+				accountConfigId: string,
+				state: CalendarSuggestionItem["state"],
+			) => {
+				const page = await store.calendarSuggestion.listByState(
+					accountConfigId,
+					state,
+				);
+				// The user accepts, right here.
+				await store.calendarSuggestion.settle(ACCOUNT_CONFIG_ID, target, {
+					state: CalendarSuggestionState.Accepted,
+					acceptedCalendarObjectId: "cal-object-3",
+				});
+				return page;
+			},
+		};
+
+		const second = await recordCalendarSuggestion(racing, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			messageId: "message-2",
+			bodyPartId: "body-part-1",
+			source: CalendarSuggestionSource.IcalendarPart,
+			icalData: invitation({ sequence: 1 }),
+			timezone: "Europe/Amsterdam",
+		});
+
+		assert.ok(second.ok);
+		assert.deepEqual(second.value.superseded, []);
+		const answered = await store.calendarSuggestion.get(
+			ACCOUNT_CONFIG_ID,
+			target,
+		);
+		assert.equal(answered.state, CalendarSuggestionState.Accepted);
+		assert.equal(answered.acceptedCalendarObjectId, "cal-object-3");
+	});
+
+	it("records a cancellation as a card of its own, touching nothing", async () => {
+		const store = new MemoryCalendarStore();
+
+		const cancel = await record(
+			store,
+			invitation({ method: "CANCEL", sequence: 5 }),
+			"message-3",
+		);
+
+		assert.ok(cancel.ok);
+		assert.equal(cancel.value.suggestion.method, CalendarInviteMethod.Cancel);
+		assert.equal(
+			cancel.value.suggestion.state,
+			CalendarSuggestionState.Pending,
+		);
+		assert.equal(store.objects.size, 0);
+	});
+
+	it("writes nothing when the iCalendar will not parse", async () => {
+		const store = new MemoryCalendarStore();
+
+		const recorded = await record(store, "BEGIN:VCALENDAR", "message-1");
+
+		assert.equal(recorded.ok, false);
+		assert.equal(store.suggestions.size, 0);
+	});
+});

package/src/suggest.ts

@@ -0,0 +1,199 @@
+import type {
+	CalendarSuggestionItem,
+	ICalendarSuggestionRepository,
+	PutCalendarSuggestionInput,
+} from "@remit/data-ports";
+import {
+	CalendarInviteMethod,
+	CalendarSuggestionState,
+} from "@remit/domain-enums";
+import type ICAL from "ical.js";
+import type { CalendarResult } from "./errors.js";
+import { parseCalendar } from "./parse.js";
+import { projectCalendar } from "./project.js";
+
+const METHOD_BY_ICAL: Record<string, CalendarSuggestionItem["method"]> = {
+	REQUEST: CalendarInviteMethod.Request,
+	REPLY: CalendarInviteMethod.Reply,
+	CANCEL: CalendarInviteMethod.Cancel,
+	COUNTER: CalendarInviteMethod.Counter,
+	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.
+ */
+export const mailAddressOf = (calAddress: string): string =>
+	calAddress.replace(/^mailto:/i, "");
+
+/** The iTIP method a VCALENDAR declared, `None` when it declared no METHOD. */
+export const inviteMethodOf = (
+	component: ICAL.Component,
+): CalendarSuggestionItem["method"] =>
+	METHOD_BY_ICAL[readString(component, "method").toUpperCase()] ??
+	CalendarInviteMethod.None;
+
+/**
+ * The facts a suggestion carries beside its bytes, read out of the message's
+ * iCalendar and nowhere else. Shares `projectCalendar` with the stored
+ * resource, so a card and the event it becomes cannot disagree about when the
+ * meeting is.
+ */
+export type CalendarSuggestionProjection = Pick<
+	PutCalendarSuggestionInput,
+	| "icalUid"
+	| "sequence"
+	| "method"
+	| "summary"
+	| "dtStart"
+	| "dtEnd"
+	| "allDay"
+	| "location"
+	| "organizer"
+	| "zoneCertainty"
+>;
+
+/**
+ * Reads a message's `text/calendar` bytes into the facts a card is drawn from.
+ *
+ * Refusal is a returned value, as everywhere else in this package: the bytes
+ * come from whatever client the organizer uses, and a mail carrying broken
+ * iCalendar is an ordinary thing that must not fail the message's body sync.
+ */
+export const projectSuggestion = async (
+	icalData: string,
+	timezone: string,
+): Promise<CalendarResult<CalendarSuggestionProjection>> => {
+	const parsed = await parseCalendar(icalData);
+	if (!parsed.ok) return parsed;
+
+	const projection = projectCalendar(parsed.value, timezone);
+	if (!projection.ok) return projection;
+
+	return {
+		ok: true,
+		value: {
+			icalUid: projection.value.icalUid,
+			sequence: projection.value.sequence,
+			method: inviteMethodOf(parsed.value.component),
+			summary: projection.value.summary,
+			dtStart: projection.value.dtStart,
+			dtEnd: projection.value.dtEnd,
+			allDay: projection.value.allDay,
+			location: readString(parsed.value.master, "location"),
+			organizer: mailAddressOf(readString(parsed.value.master, "organizer")),
+			zoneCertainty: projection.value.zoneCertainty,
+		},
+	};
+};
+
+export interface RecordCalendarSuggestionInput {
+	accountConfigId: string;
+	messageId: string;
+	bodyPartId: string;
+	source: CalendarSuggestionItem["source"];
+	/** The VCALENDAR text as it arrived in the message. */
+	icalData: string;
+	/**
+	 * IANA zone a floating time in the invitation is read in — the zone of the
+	 * collection the event would land in. An invitation whose DTSTART names no
+	 * zone is RFC 5545 floating time, and reading it anywhere but where the
+	 * user's calendar lives puts the meeting at the wrong hour.
+	 */
+	timezone: string;
+}
+
+export interface RecordedCalendarSuggestion {
+	suggestion: CalendarSuggestionItem;
+	/** The revisions this one replaced, already marked `Superseded`. */
+	superseded: CalendarSuggestionItem[];
+}
+
+/**
+ * Every pending suggestion the account holds. Drained rather than read as one
+ * page: the page size is a repository detail, and a supersession that missed
+ * the older revision because it sat on page two would leave two live cards for
+ * one event.
+ */
+const listPending = async (
+	repo: ICalendarSuggestionRepository,
+	accountConfigId: string,
+): Promise<CalendarSuggestionItem[]> => {
+	const items: CalendarSuggestionItem[] = [];
+	let continuationToken: string | undefined;
+	do {
+		const page = await repo.listByState(
+			accountConfigId,
+			CalendarSuggestionState.Pending,
+			{ continuationToken },
+		);
+		items.push(...page.items);
+		continuationToken = page.continuationToken;
+	} while (continuationToken);
+	return items;
+};
+
+/**
+ * Records what one message offers, and retires the revision it replaces.
+ *
+ * A revision is a new row, never an edit. The organizer's `SEQUENCE` is what
+ * orders them (RFC 5545 3.8.7.4): a later message carrying the same `UID` with
+ * a higher value leaves the earlier card in place as `Superseded` and writes a
+ * new `Pending` one, so the message the old card came from still has its card
+ * and the user can see which revision they are being asked about.
+ *
+ * Only a `Pending` suggestion is superseded. An answered one is a decision the
+ * user already took, and a later message does not get to erase it — a
+ * cancellation of an accepted event arrives as its own `Cancel` suggestion and
+ * waits for the user like everything else.
+ *
+ * The new row is written before the old ones are retired. A failure between
+ * the two leaves two live cards, which a person can see and act on; the other
+ * order would leave the event with none.
+ *
+ * Retiring is a compare-and-set for the same reason the read and the write are
+ * two steps: a person can accept a card between them, and an unconditional
+ * write would replace their acceptance with `Superseded` and blank the id of
+ * the event it put in their calendar. A card answered in the gap keeps its
+ * answer and is simply not reported as superseded.
+ */
+export const recordCalendarSuggestion = async (
+	repo: ICalendarSuggestionRepository,
+	input: RecordCalendarSuggestionInput,
+): Promise<CalendarResult<RecordedCalendarSuggestion>> => {
+	const projection = await projectSuggestion(input.icalData, input.timezone);
+	if (!projection.ok) return projection;
+
+	const suggestion = await repo.put({
+		accountConfigId: input.accountConfigId,
+		messageId: input.messageId,
+		bodyPartId: input.bodyPartId,
+		source: input.source,
+		icalData: input.icalData,
+		...projection.value,
+	});
+
+	const stale = (await listPending(repo, input.accountConfigId)).filter(
+		(candidate) =>
+			candidate.icalUid === suggestion.icalUid &&
+			candidate.suggestionId !== suggestion.suggestionId &&
+			candidate.sequence < suggestion.sequence,
+	);
+
+	const superseded: CalendarSuggestionItem[] = [];
+	for (const candidate of stale) {
+		const retired = await repo.supersedeIfPending(
+			input.accountConfigId,
+			candidate.suggestionId,
+		);
+		if (retired) superseded.push(retired);
+	}
+
+	return { ok: true, value: { suggestion, superseded } };
+};