@remit/calendar-service 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/calendar-service",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "iCalendar (RFC 5545) parsing, projection and recurrence expansion over the calendar store",
   "type": "module",
   "main": "src/index.ts",
@@ -9,11 +9,15 @@
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./memory-store": {
+      "types": "./src/memory-store.ts",
+      "default": "./src/memory-store.ts"
     }
   },
   "scripts": {
     "test:typecheck": "tsgo --noEmit",
-    "test:run": "node $NODE_TEST_FLAGS --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-lines=90 --test 'src/**/*.test.ts'"
+    "test:run": "node $NODE_TEST_FLAGS --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/memory-store.ts' --test-coverage-lines=90 --test 'src/**/*.test.ts'"
   },
   "dependencies": {
     "@remit/data-ports": "*",

package/src/accept.test.ts

@@ -0,0 +1,357 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { CalendarSuggestionItem } from "@remit/data-ports";
+import {
+	CalendarSuggestionSource,
+	CalendarSuggestionState,
+} from "@remit/domain-enums";
+import { acceptCalendarSuggestion, buildAcceptedCalendar } from "./accept.js";
+import { ical } from "./fixtures.js";
+import { MemoryCalendarStore } from "./memory-store.js";
+import { provisionDefaultCalendar } from "./put.js";
+import { recordCalendarSuggestion } from "./suggest.js";
+
+const ACCOUNT_CONFIG_ID = "account-config-1";
+const ATTENDEE = "user@example.test";
+const UID = "invite-4711@example.test";
+
+const invitation = ({
+	method = "REQUEST",
+	sequence = 0,
+	attendees = ["ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:user@example.test"],
+	extra = [] as string[],
+}): string =>
+	ical(
+		"BEGIN:VCALENDAR",
+		"VERSION:2.0",
+		"PRODID:-//Example Corp//Scheduler//EN",
+		`METHOD:${method}`,
+		"BEGIN:VEVENT",
+		`UID:${UID}`,
+		"DTSTAMP:20260801T090000Z",
+		`SEQUENCE:${sequence}`,
+		"DTSTART:20260901T080000Z",
+		"DTEND:20260901T090000Z",
+		"SUMMARY:Quarterly review",
+		"ORGANIZER:mailto:organizer@example.test",
+		...attendees,
+		"X-EXAMPLE-TICKET:AB-4711",
+		...extra,
+		"END:VEVENT",
+		"END:VCALENDAR",
+	);
+
+const suggestionOf = (
+	icalData: string,
+	overrides: Partial<CalendarSuggestionItem> = {},
+): CalendarSuggestionItem => ({
+	suggestionId: "suggestion-1",
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	messageId: "message-1",
+	bodyPartId: "body-part-1",
+	icalUid: UID,
+	sequence: 0,
+	method: "Request",
+	source: CalendarSuggestionSource.IcalendarPart,
+	state: CalendarSuggestionState.Pending,
+	summary: "Quarterly review",
+	dtStart: "2026-09-01T08:00:00+00:00",
+	dtEnd: "2026-09-01T09:00:00+00:00",
+	allDay: false,
+	location: "",
+	organizer: "organizer@example.test",
+	zoneCertainty: "Explicit",
+	icalData,
+	acceptedCalendarObjectId: "",
+	createdAt: 0,
+	updatedAt: 0,
+	...overrides,
+});
+
+const provisioned = async (): Promise<{
+	store: MemoryCalendarStore;
+	calendarId: string;
+}> => {
+	const store = new MemoryCalendarStore();
+	const collection = await provisionDefaultCalendar(store, ACCOUNT_CONFIG_ID);
+	return { store, calendarId: collection.calendarId };
+};
+
+const recorded = async (
+	store: MemoryCalendarStore,
+	icalData: string,
+	messageId: string,
+): Promise<CalendarSuggestionItem> => {
+	const result = await recordCalendarSuggestion(store.calendarSuggestion, {
+		accountConfigId: ACCOUNT_CONFIG_ID,
+		messageId,
+		bodyPartId: "body-part-1",
+		source: CalendarSuggestionSource.IcalendarPart,
+		icalData,
+		timezone: "UTC",
+	});
+	assert.ok(result.ok);
+	return result.value.suggestion;
+};
+
+describe("buildAcceptedCalendar", () => {
+	it("keeps the UID and the SEQUENCE the organizer sent", async () => {
+		const built = await buildAcceptedCalendar(
+			suggestionOf(invitation({ sequence: 3 })),
+			ATTENDEE,
+		);
+
+		assert.ok(built.ok);
+		assert.match(built.value, /UID:invite-4711@example\.test/);
+		assert.match(built.value, /SEQUENCE:3/);
+	});
+
+	it("marks the user accepted on the line already naming them", async () => {
+		const built = await buildAcceptedCalendar(
+			suggestionOf(invitation({})),
+			ATTENDEE,
+		);
+
+		assert.ok(built.ok);
+		assert.match(built.value, /PARTSTAT=ACCEPTED/);
+		assert.doesNotMatch(built.value, /NEEDS-ACTION/);
+		assert.equal(built.value.match(/ATTENDEE/g)?.length, 1);
+	});
+
+	it("adds the user as an attendee when the invitation never named them", async () => {
+		const built = await buildAcceptedCalendar(
+			suggestionOf(invitation({ attendees: [] })),
+			ATTENDEE,
+		);
+
+		assert.ok(built.ok);
+		assert.match(built.value, /ATTENDEE/);
+		assert.match(built.value, /PARTSTAT=ACCEPTED/);
+		assert.match(built.value, /mailto:user@example\.test/);
+	});
+
+	it("drops the METHOD, which a stored resource must not carry", async () => {
+		// RFC 4791 4.1: a calendar object resource is not a scheduling message.
+		// Leaving METHOD in makes every client read the user's own entry as an
+		// unanswered invitation.
+		const built = await buildAcceptedCalendar(
+			suggestionOf(invitation({})),
+			ATTENDEE,
+		);
+
+		assert.ok(built.ok);
+		assert.doesNotMatch(built.value, /^METHOD:/m);
+	});
+
+	it("carries through a property nobody modelled", async () => {
+		const built = await buildAcceptedCalendar(
+			suggestionOf(invitation({})),
+			ATTENDEE,
+		);
+
+		assert.ok(built.ok);
+		assert.match(built.value, /X-EXAMPLE-TICKET:AB-4711/);
+	});
+
+	it("cancels the event when the card is a cancellation", async () => {
+		const built = await buildAcceptedCalendar(
+			suggestionOf(invitation({ method: "CANCEL" }), { method: "Cancel" }),
+			ATTENDEE,
+		);
+
+		assert.ok(built.ok);
+		assert.match(built.value, /STATUS:CANCELLED/);
+	});
+
+	it("refuses a suggestion with no iCalendar behind it", async () => {
+		const built = await buildAcceptedCalendar(
+			suggestionOf("", { source: CalendarSuggestionSource.TextHeuristic }),
+			ATTENDEE,
+		);
+
+		assert.equal(built.ok, false);
+	});
+});
+
+describe("acceptCalendarSuggestion", () => {
+	it("writes the resource and settles the card in one unit", async () => {
+		const { store, calendarId } = await provisioned();
+		const suggestion = await recorded(store, invitation({}), "message-1");
+
+		const accepted = await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion,
+			attendee: ATTENDEE,
+		});
+
+		assert.ok(accepted.ok);
+		assert.equal(
+			accepted.value.suggestion.state,
+			CalendarSuggestionState.Accepted,
+		);
+		assert.equal(
+			accepted.value.suggestion.acceptedCalendarObjectId,
+			accepted.value.object?.calendarObjectId,
+		);
+		assert.equal(accepted.value.object?.icalUid, UID);
+		assert.equal(store.objects.size, 1);
+	});
+
+	it("expands the accepted event into the occurrence index", async () => {
+		const { store, calendarId } = await provisioned();
+		const suggestion = await recorded(store, invitation({}), "message-1");
+
+		const accepted = await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion,
+			attendee: ATTENDEE,
+		});
+
+		assert.ok(accepted.ok);
+		assert.equal(
+			store.occurrences.get(accepted.value.object?.calendarObjectId ?? "")
+				?.length,
+			1,
+		);
+	});
+
+	it("accepting twice leaves one event in the calendar", async () => {
+		const { store, calendarId } = await provisioned();
+		const suggestion = await recorded(store, invitation({}), "message-1");
+
+		const first = await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion,
+			attendee: ATTENDEE,
+		});
+		const second = await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion,
+			attendee: ATTENDEE,
+		});
+
+		assert.ok(first.ok);
+		assert.ok(second.ok);
+		assert.equal(store.objects.size, 1);
+		assert.equal(
+			second.value.object?.calendarObjectId,
+			first.value.object?.calendarObjectId,
+		);
+	});
+
+	it("accepting a later revision rewrites the event, never a second copy", async () => {
+		const { store, calendarId } = await provisioned();
+		const first = await recorded(
+			store,
+			invitation({ sequence: 0 }),
+			"message-1",
+		);
+		await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion: first,
+			attendee: ATTENDEE,
+		});
+
+		const revision = await recorded(
+			store,
+			invitation({ sequence: 1 }),
+			"message-2",
+		);
+		const accepted = await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion: revision,
+			attendee: ATTENDEE,
+		});
+
+		assert.ok(accepted.ok);
+		assert.equal(store.objects.size, 1);
+		assert.equal(accepted.value.object?.sequence, 1);
+	});
+
+	it("never invents an event just to mark it cancelled", async () => {
+		// The user left the invitation Pending, so nothing is in their calendar.
+		// Accepting the cancellation must clear the card and write nothing —
+		// writing a resource here would put a meeting they never had into their
+		// calendar for the sole purpose of saying it was called off.
+		const { store, calendarId } = await provisioned();
+		const request = await recorded(store, invitation({}), "message-1");
+		const cancel = await recorded(
+			store,
+			invitation({ method: "CANCEL", sequence: 1 }),
+			"message-2",
+		);
+
+		const accepted = await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion: cancel,
+			attendee: ATTENDEE,
+		});
+
+		assert.ok(accepted.ok);
+		assert.equal(accepted.value.outcome, "NothingToCancel");
+		assert.equal(accepted.value.object, null);
+		assert.equal(store.objects.size, 0);
+		assert.equal(
+			accepted.value.suggestion.state,
+			CalendarSuggestionState.Dismissed,
+		);
+		assert.equal(accepted.value.suggestion.acceptedCalendarObjectId, "");
+		// The request it superseded is left exactly as the producer left it.
+		const superseded = await store.calendarSuggestion.get(
+			ACCOUNT_CONFIG_ID,
+			request.suggestionId,
+		);
+		assert.equal(superseded.state, CalendarSuggestionState.Superseded);
+	});
+
+	it("a cancellation touches the calendar only once it is accepted", async () => {
+		const { store, calendarId } = await provisioned();
+		const request = await recorded(store, invitation({}), "message-1");
+		await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion: request,
+			attendee: ATTENDEE,
+		});
+
+		const cancel = await recorded(
+			store,
+			invitation({ method: "CANCEL", sequence: 1 }),
+			"message-2",
+		);
+		const before = [...store.objects.values()][0];
+		assert.equal(before?.status, "Confirmed");
+
+		const accepted = await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion: cancel,
+			attendee: ATTENDEE,
+		});
+
+		assert.ok(accepted.ok);
+		assert.equal(accepted.value.object?.status, "Cancelled");
+		assert.equal(store.objects.size, 1);
+	});
+
+	it("writes nothing when the invitation's bytes will not parse", async () => {
+		const { store, calendarId } = await provisioned();
+
+		const accepted = await acceptCalendarSuggestion(store, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			calendarId,
+			suggestion: suggestionOf("BEGIN:VCALENDAR"),
+			attendee: ATTENDEE,
+		});
+
+		assert.equal(accepted.ok, false);
+		assert.equal(store.objects.size, 0);
+	});
+});

package/src/accept.ts

@@ -0,0 +1,207 @@
+import type {
+	CalendarObjectItem,
+	CalendarSuggestionItem,
+	ICalendarUnitOfWork,
+} from "@remit/data-ports";
+import {
+	CalendarInviteMethod,
+	CalendarSuggestionState,
+} from "@remit/domain-enums";
+import ICAL from "ical.js";
+import type { CalendarResult } from "./errors.js";
+import { parseCalendar, serializeCalendar } from "./parse.js";
+import { putCalendarObject } from "./put.js";
+import { mailAddressOf } from "./suggest.js";
+
+const eventsOf = (component: ICAL.Component): ICAL.Component[] =>
+	component.getAllSubcomponents("vevent");
+
+/**
+ * Marks one address as having accepted, on every VEVENT of the resource — the
+ * master and each override alike, since an attendee's answer is to the series.
+ *
+ * An ATTENDEE line already naming the user has its PARTSTAT rewritten rather
+ * than a second one appended: two ATTENDEE lines for one person is a resource
+ * every other client reads as two people.
+ */
+const markAccepted = (component: ICAL.Component, attendee: string): void => {
+	const wanted = attendee.toLowerCase();
+	for (const event of eventsOf(component)) {
+		const existing = event
+			.getAllProperties("attendee")
+			.find(
+				(property) =>
+					mailAddressOf(String(property.getFirstValue())).toLowerCase() ===
+					wanted,
+			);
+		const property =
+			existing ?? new ICAL.Property("attendee", event as ICAL.Component);
+		property.setParameter("partstat", "ACCEPTED");
+		if (!existing) {
+			property.setValue(`mailto:${attendee}`);
+			event.addProperty(property);
+		}
+	}
+};
+
+const markCancelled = (component: ICAL.Component): void => {
+	for (const event of eventsOf(component)) {
+		event.removeAllProperties("status");
+		event.addPropertyWithValue("status", "CANCELLED");
+	}
+};
+
+/**
+ * The VCALENDAR a stored resource is made of, built from the invitation's own
+ * bytes.
+ *
+ * Built by editing what arrived rather than by composing a fresh event: the
+ * UID, the SEQUENCE, the recurrence rule, the overrides and every X- property
+ * the organizer's client wrote survive into the calendar, which is what makes
+ * the stored resource answer to the same event a later revision or a
+ * cancellation names.
+ *
+ * The METHOD goes. A scheduling message carries one (RFC 5546); a stored
+ * calendar object resource must not (RFC 4791 4.1), and leaving it in makes
+ * every CalDAV client treat the user's own calendar entry as an unanswered
+ * invitation.
+ */
+export const buildAcceptedCalendar = async (
+	suggestion: Pick<CalendarSuggestionItem, "icalData" | "method">,
+	attendee: string,
+): Promise<CalendarResult<string>> => {
+	const parsed = await parseCalendar(suggestion.icalData);
+	if (!parsed.ok) return parsed;
+
+	const { component } = parsed.value;
+	component.removeAllProperties("method");
+	markAccepted(component, attendee);
+	if (suggestion.method === CalendarInviteMethod.Cancel) {
+		markCancelled(component);
+	}
+
+	return { ok: true, value: serializeCalendar(component) };
+};
+
+export interface AcceptCalendarSuggestionInput {
+	accountConfigId: string;
+	calendarId: string;
+	suggestion: CalendarSuggestionItem;
+	/** Mail address of the person accepting — the account the message arrived on. */
+	attendee: string;
+}
+
+/**
+ * What accepting did.
+ *
+ * `Written` is the ordinary case: a resource is in the calendar and `object`
+ * names it. `NothingToCancel` is a cancellation for a meeting this calendar
+ * never held — the user never accepted the invitation, or accepted it
+ * somewhere else — where the only honest act is to clear the card. Writing a
+ * resource there would put an event in the calendar that exists solely to say
+ * it was cancelled, which is worse than the meeting the user never had.
+ */
+export type AcceptOutcome = "Written" | "NothingToCancel";
+
+export interface AcceptedCalendarSuggestion {
+	suggestion: CalendarSuggestionItem;
+	outcome: AcceptOutcome;
+	/** The resource that was written, `null` for `NothingToCancel`. */
+	object: CalendarObjectItem | null;
+}
+
+/**
+ * Adds a suggested event to a calendar, as one unit.
+ *
+ * The resource is written through `putCalendarObject`, the same function every
+ * other calendar write goes through, so an event added from a mail and one
+ * added from the week grid are the same kind of row — and a native client
+ * editing it afterwards edits the same bytes. The suggestion's own state is
+ * settled inside that transaction: a suggestion marked `Accepted` with no
+ * resource behind it, or a resource with the card still asking, is a state
+ * nothing later can repair.
+ *
+ * Accepting a `Cancel` suggestion writes `STATUS:CANCELLED` through that same
+ * path, but only onto a resource that is already there. Nothing withdraws an
+ * event on its own — a cancellation reaches the calendar only because a person
+ * pressed the button, and only when the calendar holds the meeting being
+ * withdrawn.
+ *
+ * No mail is sent. There is no iMIP reply here and none anywhere on this path;
+ * the organizer learns nothing from the user accepting.
+ *
+ * Idempotent. The resource is addressed by the event's UID within the
+ * collection, so accepting the same suggestion twice — or accepting a later
+ * revision of an event already added — rewrites the one resource rather than
+ * leaving the calendar showing the meeting twice.
+ */
+export const acceptCalendarSuggestion = async (
+	unitOfWork: ICalendarUnitOfWork,
+	input: AcceptCalendarSuggestionInput,
+): Promise<CalendarResult<AcceptedCalendarSuggestion>> => {
+	const icalData = await buildAcceptedCalendar(
+		input.suggestion,
+		input.attendee,
+	);
+	if (!icalData.ok) return icalData;
+
+	return unitOfWork.transaction(async (repos) => {
+		const existing = await repos.calendarObject.findByUid(
+			input.calendarId,
+			input.suggestion.icalUid,
+		);
+
+		// A cancellation cancels something. With no resource carrying this UID
+		// there is nothing in the calendar to withdraw, and writing one would
+		// invent a meeting the user never had purely to mark it cancelled. Clear
+		// the card and leave the calendar untouched.
+		if (
+			input.suggestion.method === CalendarInviteMethod.Cancel &&
+			existing === null
+		) {
+			const cleared = await repos.calendarSuggestion.settle(
+				input.accountConfigId,
+				input.suggestion.suggestionId,
+				{
+					state: CalendarSuggestionState.Dismissed,
+					acceptedCalendarObjectId: "",
+				},
+			);
+			return {
+				ok: true,
+				value: {
+					suggestion: cleared,
+					outcome: "NothingToCancel",
+					object: null,
+				},
+			};
+		}
+
+		const written = await putCalendarObject(unitOfWork, {
+			accountConfigId: input.accountConfigId,
+			calendarId: input.calendarId,
+			resourceName:
+				existing?.resourceName ?? `${input.suggestion.suggestionId}.ics`,
+			icalData: icalData.value,
+		});
+		if (!written.ok) return written;
+
+		const settled = await repos.calendarSuggestion.settle(
+			input.accountConfigId,
+			input.suggestion.suggestionId,
+			{
+				state: CalendarSuggestionState.Accepted,
+				acceptedCalendarObjectId: written.value.calendarObjectId,
+			},
+		);
+
+		return {
+			ok: true,
+			value: {
+				suggestion: settled,
+				outcome: "Written",
+				object: written.value,
+			},
+		};
+	});
+};