@remit/calendar-service 0.0.20 → 1.0.0

package/dist/participation.d.ts

@@ -0,0 +1,36 @@
+import type { CalendarAttendee, CalendarAttendeeCounts, CalendarInviteAnswer as CalendarInviteAnswerValue, CalendarParticipation as CalendarParticipationValue } from "@remit/api-openapi-types";
+import type ICAL from "ical.js";
+import type { ParsedCalendar } from "./parse.js";
+/** The PARTSTAT each answer a guest gives is written as. */
+export declare const PARTSTAT_OF_ANSWER: Record<CalendarInviteAnswerValue, string>;
+/** A CAL-ADDRESS as the lower-cased mail address it names. */
+export declare const calendarAddressOf: (value: unknown) => string;
+/** The addresses that are the reader, lower-cased once for every comparison. */
+export declare const selfAddressSet: (addresses: readonly string[]) => Set<string>;
+/** A PARTSTAT as an answer. Anything that is not a yes, no or maybe is still owed one. */
+export declare const attendeeStatusOf: (property: ICAL.Property) => CalendarAttendee["status"];
+export declare const organizerOf: (component: ICAL.Component) => string;
+/** The ATTENDEE line naming an address, if the component carries one. */
+export declare const attendeeLineOf: (component: ICAL.Component, address: string) => ICAL.Property | undefined;
+/**
+ * Where the reader stands on one VEVENT.
+ *
+ * An event with no ATTENDEE line has nobody to schedule, whoever it names as
+ * ORGANIZER. One the reader organizes is theirs. Otherwise the reader's own
+ * ATTENDEE line carries their answer, and an event that lists other people
+ * but not the reader has nothing for the reader to answer.
+ */
+export declare const participationOf: (component: ICAL.Component, self: ReadonlySet<string>) => CalendarParticipationValue;
+/**
+ * Where the reader stands on one occurrence of a stored resource: on the
+ * override for its slot when the series has one, which carries its own
+ * PARTSTAT, and on the master otherwise. Read from the bytes on every read, so
+ * nothing stored can disagree with them.
+ */
+export declare const participationAtSlot: (calendar: ParsedCalendar, collectionTimezone: string, recurrenceId: string, self: ReadonlySet<string>) => CalendarParticipationValue;
+/**
+ * The guest list of one VEVENT, organizer first. The organizer counts as a
+ * yes and appears once, even when an ATTENDEE line names them too.
+ */
+export declare const attendeesOf: (component: ICAL.Component) => CalendarAttendee[];
+export declare const countAttendees: (attendees: readonly CalendarAttendee[]) => CalendarAttendeeCounts;

package/dist/participation.js

@@ -0,0 +1,104 @@
+import { CalendarAttendeeRole, CalendarAttendeeStatus, CalendarParticipation, } from "@remit/domain-enums";
+import { overridesBySlot } from "./expand.js";
+import { mailAddressOf } from "./suggest.js";
+/** The PARTSTAT each answer a guest gives is written as. */
+export const PARTSTAT_OF_ANSWER = {
+    Accepted: "ACCEPTED",
+    Tentative: "TENTATIVE",
+    Declined: "DECLINED",
+};
+/** A CAL-ADDRESS as the lower-cased mail address it names. */
+export const calendarAddressOf = (value) => mailAddressOf(String(value ?? ""))
+    .trim()
+    .toLowerCase();
+/** The addresses that are the reader, lower-cased once for every comparison. */
+export const selfAddressSet = (addresses) => new Set(addresses.map((address) => address.trim().toLowerCase()));
+const STATUS_BY_PARTSTAT = {
+    ACCEPTED: CalendarAttendeeStatus.Accepted,
+    TENTATIVE: CalendarAttendeeStatus.Tentative,
+    DECLINED: CalendarAttendeeStatus.Declined,
+};
+const PARTICIPATION_BY_STATUS = {
+    [CalendarAttendeeStatus.NeedsAction]: CalendarParticipation.NeedsAction,
+    [CalendarAttendeeStatus.Accepted]: CalendarParticipation.Accepted,
+    [CalendarAttendeeStatus.Tentative]: CalendarParticipation.Tentative,
+    [CalendarAttendeeStatus.Declined]: CalendarParticipation.Declined,
+};
+/** A PARTSTAT as an answer. Anything that is not a yes, no or maybe is still owed one. */
+export const attendeeStatusOf = (property) => STATUS_BY_PARTSTAT[String(property.getParameter("partstat") ?? "").toUpperCase()] ?? CalendarAttendeeStatus.NeedsAction;
+export const organizerOf = (component) => calendarAddressOf(component.getFirstPropertyValue("organizer"));
+/** The ATTENDEE line naming an address, if the component carries one. */
+export const attendeeLineOf = (component, address) => component
+    .getAllProperties("attendee")
+    .find((property) => calendarAddressOf(property.getFirstValue()) === address);
+/**
+ * Where the reader stands on one VEVENT.
+ *
+ * An event with no ATTENDEE line has nobody to schedule, whoever it names as
+ * ORGANIZER. One the reader organizes is theirs. Otherwise the reader's own
+ * ATTENDEE line carries their answer, and an event that lists other people
+ * but not the reader has nothing for the reader to answer.
+ */
+export const participationOf = (component, self) => {
+    const attendees = component.getAllProperties("attendee");
+    if (attendees.length === 0)
+        return CalendarParticipation.Unscheduled;
+    if (self.has(organizerOf(component)))
+        return CalendarParticipation.Organizer;
+    const own = attendees.find((property) => self.has(calendarAddressOf(property.getFirstValue())));
+    if (!own)
+        return CalendarParticipation.Unscheduled;
+    return PARTICIPATION_BY_STATUS[attendeeStatusOf(own)];
+};
+/**
+ * Where the reader stands on one occurrence of a stored resource: on the
+ * override for its slot when the series has one, which carries its own
+ * PARTSTAT, and on the master otherwise. Read from the bytes on every read, so
+ * nothing stored can disagree with them.
+ */
+export const participationAtSlot = (calendar, collectionTimezone, recurrenceId, self) => {
+    const override = recurrenceId === ""
+        ? undefined
+        : overridesBySlot(calendar, collectionTimezone).get(recurrenceId);
+    return participationOf(override ?? calendar.master, self);
+};
+const textParameter = (property, name) => {
+    const value = property.getParameter(name);
+    return typeof value === "string" ? value : "";
+};
+/**
+ * The guest list of one VEVENT, organizer first. The organizer counts as a
+ * yes and appears once, even when an ATTENDEE line names them too.
+ */
+export const attendeesOf = (component) => {
+    const lines = component.getAllProperties("attendee");
+    if (lines.length === 0)
+        return [];
+    const organizerProperty = component.getFirstProperty("organizer");
+    const organizer = organizerOf(component);
+    const guests = lines
+        .map((property) => ({
+        email: calendarAddressOf(property.getFirstValue()),
+        displayName: textParameter(property, "cn"),
+        role: CalendarAttendeeRole.Guest,
+        status: attendeeStatusOf(property),
+    }))
+        .filter((guest) => guest.email !== "" && guest.email !== organizer);
+    if (organizer === "" || !organizerProperty)
+        return guests;
+    return [
+        {
+            email: organizer,
+            displayName: textParameter(organizerProperty, "cn"),
+            role: CalendarAttendeeRole.Organizer,
+            status: CalendarAttendeeStatus.Accepted,
+        },
+        ...guests,
+    ];
+};
+export const countAttendees = (attendees) => ({
+    accepted: attendees.filter((attendee) => attendee.status === CalendarAttendeeStatus.Accepted).length,
+    declined: attendees.filter((attendee) => attendee.status === CalendarAttendeeStatus.Declined).length,
+    tentative: attendees.filter((attendee) => attendee.status === CalendarAttendeeStatus.Tentative).length,
+    needsAction: attendees.filter((attendee) => attendee.status === CalendarAttendeeStatus.NeedsAction).length,
+});

package/dist/put.d.ts

@@ -1,5 +1,7 @@
 import type { CalendarCollectionItem, CalendarObjectItem, DeleteCalendarObjectWrite, ICalendarStore, PutCalendarObjectWrite } from "@remit/data-ports";
 import type { CalendarResult } from "./errors.js";
+/** URL segment of the task collection every account config is provisioned with. */
+export declare const TASK_CALENDAR_URL_SEGMENT = "tasks";
 /** URL segment of the collection every account config is provisioned with. */
 export declare const DEFAULT_CALENDAR_URL_SEGMENT = "default";
 export interface PutCalendarObjectInput {
@@ -50,3 +52,8 @@ export declare const deleteCalendarObject: (store: ICalendarStore, input: {
  * the collection the first one made rather than a rival copy of it.
  */
 export declare const provisionDefaultCalendar: (store: ICalendarStore, accountConfigId: string, displayName?: string) => Promise<CalendarCollectionItem>;
+/**
+ * The collection an account config keeps its tasks in. Provisioned beside the
+ * default event collection, idempotently, for the same reason.
+ */
+export declare const provisionTaskCalendar: (store: ICalendarStore, accountConfigId: string, displayName?: string) => Promise<CalendarCollectionItem>;

package/dist/put.js

@@ -1,9 +1,11 @@
 import { deriveCalendarObjectId } from "@remit/data-ports/id";
-import { CalendarSource } from "@remit/domain-enums";
+import { CalendarComponentSet, CalendarSource } from "@remit/domain-enums";
 import { computeEtag } from "./etag.js";
 import { expandCalendar } from "./expand.js";
 import { parseCalendar } from "./parse.js";
 import { projectCalendar } from "./project.js";
+/** URL segment of the task collection every account config is provisioned with. */
+export const TASK_CALENDAR_URL_SEGMENT = "tasks";
 /** URL segment of the collection every account config is provisioned with. */
 export const DEFAULT_CALENDAR_URL_SEGMENT = "default";
 /**
@@ -76,3 +78,14 @@ export const provisionDefaultCalendar = (store, accountConfigId, displayName = "
     displayName,
     source: CalendarSource.Default,
 });
+/**
+ * The collection an account config keeps its tasks in. Provisioned beside the
+ * default event collection, idempotently, for the same reason.
+ */
+export const provisionTaskCalendar = (store, accountConfigId, displayName = "Tasks") => store.repos.calendarCollection.create({
+    accountConfigId,
+    urlSegment: TASK_CALENDAR_URL_SEGMENT,
+    displayName,
+    componentSet: CalendarComponentSet.VtodoOnly,
+    source: CalendarSource.Default,
+});

package/dist/reply.d.ts

@@ -0,0 +1,30 @@
+import type { ICalendarStore } from "@remit/data-ports";
+/** A reply's place in the order replies are applied in. */
+export interface ReplyRevision {
+    sequence: number;
+    /** The reply's DTSTAMP, UTC basic form (`20261103T120000Z`), or `""`. */
+    stamp: string;
+}
+/**
+ * Whether a reply overtakes the answer the organizer's copy already holds
+ * (RFC 5546 2.1.5): a reply to an older revision of the event is stale, and of
+ * two replies to the same revision the later DTSTAMP wins.
+ */
+export declare const replyOvertakes: (stored: ReplyRevision, reply: ReplyRevision) => boolean;
+export type RecordCalendarReplyOutcome = "Recorded" | "NotAReply" | "Unreadable" | "NotOrganized" | "Stale";
+export interface RecordCalendarReplyInput {
+    accountConfigId: string;
+    /** The `text/calendar` part as it arrived. */
+    icalData: string;
+    /** The addresses of the account config's accounts. */
+    selfAddresses: readonly string[];
+}
+/**
+ * Applies a guest's `METHOD:REPLY` to the event the reader organizes.
+ *
+ * The write is local: the organizer's copy is the calendar row, and it goes
+ * through the single write path so the guest's answer reaches the occurrence
+ * index too. Nothing is sent back. A reply the reader does not organize, or
+ * one older than the answer already held, changes nothing.
+ */
+export declare const recordCalendarReply: (store: ICalendarStore, input: RecordCalendarReplyInput) => Promise<RecordCalendarReplyOutcome>;

package/dist/reply.js

@@ -0,0 +1,154 @@
+import { CalendarInviteMethod, RecurrenceScope } from "@remit/domain-enums";
+import ICAL from "ical.js";
+import { overridesBySlot } from "./expand.js";
+import { parseCalendar, serializeCalendar, } from "./parse.js";
+import { attendeeLineOf, calendarAddressOf, organizerOf, selfAddressSet, } from "./participation.js";
+/**
+ * Where the organizer's copy keeps the DTSTAMP of the reply it last applied for
+ * a guest, so a reply that arrives late cannot undo a newer one.
+ */
+const APPLIED_REPLY_STAMP = "x-remit-reply-stamp";
+import { prepareCalendarObject } from "./put.js";
+import { applyScopedUpdate } from "./scope.js";
+import { inviteMethodOf } from "./suggest.js";
+import { resolveTime, tzidOf } from "./time.js";
+/**
+ * Whether a reply overtakes the answer the organizer's copy already holds
+ * (RFC 5546 2.1.5): a reply to an older revision of the event is stale, and of
+ * two replies to the same revision the later DTSTAMP wins.
+ */
+export const replyOvertakes = (stored, reply) => {
+    if (reply.sequence < stored.sequence)
+        return false;
+    if (stored.stamp === "")
+        return true;
+    return reply.stamp > stored.stamp;
+};
+const sequenceOf = (component) => {
+    const value = component.getFirstPropertyValue("sequence");
+    return typeof value === "number" ? value : 0;
+};
+const stampOf = (component) => {
+    const value = component.getFirstPropertyValue("dtstamp");
+    return value instanceof ICAL.Time
+        ? value.convertToZone(ICAL.Timezone.utcTimezone).toICALString()
+        : "";
+};
+const recurrenceSlotOf = (component, collectionTimezone) => {
+    const value = component.getFirstPropertyValue("recurrence-id");
+    if (!(value instanceof ICAL.Time))
+        return "";
+    return resolveTime(value, tzidOf(component.getFirstProperty("recurrence-id")), collectionTimezone).isoUtc;
+};
+/**
+ * The organizer's VEVENTs one reply VEVENT answers: the override for its
+ * RECURRENCE-ID, made when the series has none yet, or every VEVENT when the
+ * reply answers the series.
+ */
+const targetsOf = async (stored, collectionTimezone, slot) => {
+    if (slot === "") {
+        return { calendar: stored, targets: [stored.master, ...stored.overrides] };
+    }
+    const existing = overridesBySlot(stored, collectionTimezone).get(slot);
+    if (existing)
+        return { calendar: stored, targets: [existing] };
+    const written = await applyScopedUpdate(stored, collectionTimezone, { scope: RecurrenceScope.This, recurrenceId: slot, followingUid: "" }, {});
+    if (!written.ok) {
+        throw new Error(`a reply to ${slot} could not be given an override of its own: ${written.error.message}`);
+    }
+    if (written.value.kind !== "Replace") {
+        throw new Error(`a reply to ${slot} resolved to a ${written.value.kind} rather than an override`);
+    }
+    const reparsed = await parseCalendar(written.value.icalData);
+    if (!reparsed.ok) {
+        throw new Error(`an override this server wrote no longer parses: ${reparsed.error.message}`);
+    }
+    const override = overridesBySlot(reparsed.value, collectionTimezone).get(slot);
+    return { calendar: reparsed.value, targets: override ? [override] : [] };
+};
+/**
+ * Applies a guest's `METHOD:REPLY` to the event the reader organizes.
+ *
+ * The write is local: the organizer's copy is the calendar row, and it goes
+ * through the single write path so the guest's answer reaches the occurrence
+ * index too. Nothing is sent back. A reply the reader does not organize, or
+ * one older than the answer already held, changes nothing.
+ */
+export const recordCalendarReply = async (store, input) => {
+    const reply = await parseCalendar(input.icalData);
+    if (!reply.ok)
+        return "Unreadable";
+    if (inviteMethodOf(reply.value.component) !== CalendarInviteMethod.Reply) {
+        return "NotAReply";
+    }
+    const self = selfAddressSet(input.selfAddresses);
+    const collections = await store.repos.calendarCollection.listByAccountConfig(input.accountConfigId);
+    for (const collection of collections) {
+        const object = await store.repos.calendarObject.findByUid(collection.calendarId, reply.value.uid);
+        if (!object)
+            continue;
+        const stored = await parseCalendar(object.icalData);
+        if (!stored.ok) {
+            throw new Error(`stored calendar object ${object.calendarObjectId} no longer parses: ${stored.error.message}`);
+        }
+        if (!self.has(organizerOf(stored.value.master)))
+            return "NotOrganized";
+        let calendar = stored.value;
+        let changed = false;
+        for (const answered of [reply.value.master, ...reply.value.overrides]) {
+            const revision = {
+                sequence: sequenceOf(answered),
+                stamp: stampOf(answered),
+            };
+            const found = await targetsOf(calendar, collection.timezone, recurrenceSlotOf(answered, collection.timezone));
+            calendar = found.calendar;
+            for (const line of answered.getAllProperties("attendee")) {
+                const guest = calendarAddressOf(line.getFirstValue());
+                const partstat = line.getParameter("partstat");
+                if (typeof partstat !== "string")
+                    continue;
+                for (const target of found.targets) {
+                    const own = attendeeLineOf(target, guest);
+                    if (!own)
+                        continue;
+                    const heldStamp = own.getParameter(APPLIED_REPLY_STAMP);
+                    const held = {
+                        sequence: sequenceOf(target),
+                        stamp: typeof heldStamp === "string" ? heldStamp : "",
+                    };
+                    if (!replyOvertakes(held, revision))
+                        continue;
+                    own.setParameter("partstat", partstat.toUpperCase());
+                    own.removeParameter("rsvp");
+                    if (revision.stamp !== "") {
+                        own.setParameter(APPLIED_REPLY_STAMP, revision.stamp);
+                    }
+                    changed = true;
+                }
+            }
+        }
+        if (!changed)
+            return "Stale";
+        const write = await prepareCalendarObject(collection, {
+            accountConfigId: input.accountConfigId,
+            calendarId: collection.calendarId,
+            resourceName: object.resourceName,
+            icalData: serializeCalendar(calendar.component),
+        });
+        if (!write.ok) {
+            throw new Error(`a reply applied to ${object.calendarObjectId} was refused by the write path: ${write.error.message}`);
+        }
+        // Conditional on the version the reply was applied to. An edit that
+        // landed meanwhile is a conflict: the write is refused loudly, the
+        // body-sync job fails, and the queue's redelivery applies the reply to
+        // the event as it now stands.
+        const report = await store.commit([
+            { ...write.value, kind: "ReprojectObject", readEtag: object.etag },
+        ]);
+        if (report.staleReprojections.length > 0) {
+            throw new Error(`${object.calendarObjectId} changed while a guest's reply was applied to it`);
+        }
+        return "Recorded";
+    }
+    return "NotOrganized";
+};

package/dist/scheduling.d.ts

@@ -0,0 +1,67 @@
+import type { CalendarInviteAnswer as CalendarInviteAnswerValue } from "@remit/api-openapi-types";
+import { CalendarInviteMethod } from "@remit/domain-enums";
+import { type CalendarResult } from "./errors.js";
+import { type ParsedCalendar } from "./parse.js";
+/** A person as the scheduling lines name them. */
+export interface CalendarPerson {
+    email: string;
+    displayName: string;
+}
+/** The iTIP methods this server sends. */
+export type SchedulingMethod = typeof CalendarInviteMethod.Request | typeof CalendarInviteMethod.Cancel | typeof CalendarInviteMethod.Reply;
+/** The guest addresses of a resource's master, organizer excluded. */
+export declare const guestAddressesOf: (calendar: ParsedCalendar) => string[];
+/**
+ * Two addresses for one guest is one guest. A guest list that names the
+ * organizer drops them: the organizer is on the event as its ORGANIZER.
+ */
+export declare const distinctGuests: (organizer: string, guests: readonly CalendarPerson[]) => CalendarPerson[];
+/** The guest an editor sent that is not a mail address, if there is one. */
+export declare const invalidGuestOf: (guests: readonly CalendarPerson[]) => CalendarPerson | undefined;
+/**
+ * Writes the organizer and the guest list onto every VEVENT of a resource.
+ *
+ * A guest already on the list keeps their ATTENDEE line as it stands, answer
+ * included; a new one is owed an answer. The organizer is never an ATTENDEE of their own event here: they are
+ * the ORGANIZER, and every client reads that as a yes.
+ */
+export declare const applyGuestList: (icalData: string, organizer: CalendarPerson, guests: readonly CalendarPerson[]) => Promise<string>;
+/**
+ * Moves SEQUENCE past every value the resource carries, on every VEVENT. A
+ * recipient keeps the highest revision it has seen, so a reschedule has to
+ * outrank the invitation it replaces.
+ */
+export declare const bumpSequence: (icalData: string) => Promise<string>;
+/**
+ * Writes the reader's PARTSTAT. `recurrenceId` names the one occurrence
+ * answered, or `""` for the series. Answered DTSTAMP is the organizer's
+ * ordering key when two replies cross, so the reply is stamped, not the event.
+ */
+export declare const applyAnswer: (icalData: string, collectionTimezone: string, attendee: string, answer: CalendarInviteAnswerValue, recurrenceId: string) => Promise<CalendarResult<string>>;
+export interface SchedulingMessageInput {
+    method: SchedulingMethod;
+    /** When the message is built; written as every VEVENT's DTSTAMP. */
+    now: Date;
+    /**
+     * A REQUEST or CANCEL: the guest it goes to, so a cancellation to a
+     * removed guest still names them. A REPLY: the guest answering, the only
+     * ATTENDEE it carries.
+     */
+    attendee: CalendarPerson;
+    /** A REPLY to one occurrence names it here; `""` answers the series. */
+    recurrenceId: string;
+    collectionTimezone: string;
+}
+export interface SchedulingMessage {
+    icalData: string;
+    sequence: number;
+    summary: string;
+}
+/**
+ * The VCALENDAR one scheduling message carries (RFC 5546), built from the
+ * stored resource it is about. The stored resource never carries METHOD
+ * (RFC 4791 4.1); the message always does.
+ */
+export declare const buildSchedulingMessage: (icalData: string, input: SchedulingMessageInput) => Promise<SchedulingMessage>;
+/** The subject line a scheduling message goes out under. */
+export declare const schedulingSubject: (method: SchedulingMethod, summary: string, answer?: CalendarInviteAnswerValue) => string;

package/dist/scheduling.js

@@ -0,0 +1,208 @@
+import { CalendarInviteAnswer, CalendarInviteMethod, } from "@remit/domain-enums";
+import ICAL from "ical.js";
+import { calendarFailure } from "./errors.js";
+import { overridesBySlot } from "./expand.js";
+import { parseCalendar, serializeCalendar, } from "./parse.js";
+import { attendeeLineOf, calendarAddressOf, organizerOf, PARTSTAT_OF_ANSWER, } from "./participation.js";
+import { readString } from "./project.js";
+const ICAL_METHOD = {
+    [CalendarInviteMethod.Request]: "REQUEST",
+    [CalendarInviteMethod.Cancel]: "CANCEL",
+    [CalendarInviteMethod.Reply]: "REPLY",
+};
+const eventsOf = (calendar) => [
+    calendar.master,
+    ...calendar.overrides,
+];
+const normalized = (email) => email.trim().toLowerCase();
+const personProperty = (name, person) => {
+    const property = new ICAL.Property(name);
+    property.setValue(`mailto:${normalized(person.email)}`);
+    if (person.displayName !== "")
+        property.setParameter("cn", person.displayName);
+    return property;
+};
+const parsedOrThrow = async (icalData) => {
+    const parsed = await parseCalendar(icalData);
+    if (!parsed.ok) {
+        throw new Error(`a calendar resource this server wrote no longer parses: ${parsed.error.message}`);
+    }
+    return parsed.value;
+};
+/** The guest addresses of a resource's master, organizer excluded. */
+export const guestAddressesOf = (calendar) => {
+    const organizer = organizerOf(calendar.master);
+    return calendar.master
+        .getAllProperties("attendee")
+        .map((property) => calendarAddressOf(property.getFirstValue()))
+        .filter((email) => email !== "" && email !== organizer);
+};
+/**
+ * Two addresses for one guest is one guest. A guest list that names the
+ * organizer drops them: the organizer is on the event as its ORGANIZER.
+ */
+export const distinctGuests = (organizer, guests) => {
+    const seen = new Set([normalized(organizer)]);
+    const distinct = [];
+    for (const guest of guests) {
+        const email = normalized(guest.email);
+        if (email === "" || seen.has(email))
+            continue;
+        seen.add(email);
+        distinct.push({ email, displayName: guest.displayName });
+    }
+    return distinct;
+};
+const EMAIL_SHAPE = /^[^\s@<>"]+@[^\s@<>"]+\.[^\s@<>"]+$/;
+/** The guest an editor sent that is not a mail address, if there is one. */
+export const invalidGuestOf = (guests) => guests.find((guest) => !EMAIL_SHAPE.test(guest.email.trim()));
+/**
+ * Writes the organizer and the guest list onto every VEVENT of a resource.
+ *
+ * A guest already on the list keeps their ATTENDEE line as it stands, answer
+ * included; a new one is owed an answer. The organizer is never an ATTENDEE of their own event here: they are
+ * the ORGANIZER, and every client reads that as a yes.
+ */
+export const applyGuestList = async (icalData, organizer, guests) => {
+    const calendar = await parsedOrThrow(icalData);
+    const listed = distinctGuests(organizer.email, guests);
+    for (const event of eventsOf(calendar)) {
+        const previous = new Map(event
+            .getAllProperties("attendee")
+            .map((property) => [
+            calendarAddressOf(property.getFirstValue()),
+            property,
+        ]));
+        event.removeAllProperties("organizer");
+        event.removeAllProperties("attendee");
+        if (listed.length === 0)
+            continue;
+        event.addProperty(personProperty("organizer", organizer));
+        for (const guest of listed) {
+            const kept = previous.get(guest.email);
+            if (kept) {
+                if (guest.displayName !== "")
+                    kept.setParameter("cn", guest.displayName);
+                event.addProperty(kept);
+                continue;
+            }
+            const property = personProperty("attendee", guest);
+            property.setParameter("role", "REQ-PARTICIPANT");
+            property.setParameter("partstat", "NEEDS-ACTION");
+            property.setParameter("rsvp", "TRUE");
+            event.addProperty(property);
+        }
+    }
+    return serializeCalendar(calendar.component);
+};
+/**
+ * Moves SEQUENCE past every value the resource carries, on every VEVENT. A
+ * recipient keeps the highest revision it has seen, so a reschedule has to
+ * outrank the invitation it replaces.
+ */
+export const bumpSequence = async (icalData) => {
+    const calendar = await parsedOrThrow(icalData);
+    const events = eventsOf(calendar);
+    const highest = Math.max(...events.map((event) => {
+        const value = event.getFirstPropertyValue("sequence");
+        return typeof value === "number" ? value : 0;
+    }));
+    for (const event of events) {
+        event.removeAllProperties("sequence");
+        event.addPropertyWithValue("sequence", highest + 1);
+    }
+    return serializeCalendar(calendar.component);
+};
+/**
+ * The VEVENTs an answer is written on: the override for one occurrence, or
+ * every VEVENT for the series. The override is the one `applyScopedUpdate`
+ * made or found for that slot, so it is already in the resource.
+ */
+const answeredEvents = (calendar, collectionTimezone, recurrenceId) => {
+    if (recurrenceId === "")
+        return eventsOf(calendar);
+    const override = overridesBySlot(calendar, collectionTimezone).get(recurrenceId);
+    return override ? [override] : [];
+};
+/**
+ * Writes the reader's PARTSTAT. `recurrenceId` names the one occurrence
+ * answered, or `""` for the series. Answered DTSTAMP is the organizer's
+ * ordering key when two replies cross, so the reply is stamped, not the event.
+ */
+export const applyAnswer = async (icalData, collectionTimezone, attendee, answer, recurrenceId) => {
+    const calendar = await parsedOrThrow(icalData);
+    const events = answeredEvents(calendar, collectionTimezone, recurrenceId);
+    const lines = events.flatMap((event) => {
+        const line = attendeeLineOf(event, attendee);
+        return line ? [line] : [];
+    });
+    if (lines.length === 0) {
+        return calendarFailure("UnknownOccurrence", `${attendee} is not on the guest list of that occurrence`);
+    }
+    for (const line of lines) {
+        line.setParameter("partstat", PARTSTAT_OF_ANSWER[answer]);
+        line.removeParameter("rsvp");
+    }
+    return { ok: true, value: serializeCalendar(calendar.component) };
+};
+/**
+ * The VCALENDAR one scheduling message carries (RFC 5546), built from the
+ * stored resource it is about. The stored resource never carries METHOD
+ * (RFC 4791 4.1); the message always does.
+ */
+export const buildSchedulingMessage = async (icalData, input) => {
+    const calendar = await parsedOrThrow(icalData);
+    const { component } = calendar;
+    component.removeAllProperties("method");
+    component.addPropertyWithValue("method", ICAL_METHOD[input.method]);
+    const stamp = ICAL.Time.fromJSDate(input.now, true);
+    const attendee = normalized(input.attendee.email);
+    let events = eventsOf(calendar);
+    if (input.method === CalendarInviteMethod.Reply &&
+        input.recurrenceId !== "") {
+        events = answeredEvents(calendar, input.collectionTimezone, input.recurrenceId);
+        for (const event of eventsOf(calendar)) {
+            if (!events.includes(event))
+                component.removeSubcomponent(event);
+        }
+    }
+    for (const event of events) {
+        event.removeAllProperties("dtstamp");
+        event.addPropertyWithValue("dtstamp", stamp);
+        if (input.method === CalendarInviteMethod.Cancel) {
+            event.removeAllProperties("status");
+            event.addPropertyWithValue("status", "CANCELLED");
+            if (!attendeeLineOf(event, attendee)) {
+                event.addProperty(personProperty("attendee", input.attendee));
+            }
+        }
+        if (input.method === CalendarInviteMethod.Reply) {
+            for (const line of event.getAllProperties("attendee")) {
+                if (calendarAddressOf(line.getFirstValue()) !== attendee) {
+                    event.removeProperty(line);
+                }
+            }
+        }
+    }
+    const sequence = calendar.master.getFirstPropertyValue("sequence");
+    return {
+        icalData: serializeCalendar(component),
+        sequence: typeof sequence === "number" ? sequence : 0,
+        summary: readString(calendar.master, "summary"),
+    };
+};
+/** The subject line a scheduling message goes out under. */
+export const schedulingSubject = (method, summary, answer) => {
+    const title = summary === "" ? "(no title)" : summary;
+    if (method === CalendarInviteMethod.Cancel)
+        return `Cancelled: ${title}`;
+    if (method === CalendarInviteMethod.Reply) {
+        const word = answer === CalendarInviteAnswer.Declined
+            ? "Declined"
+            : answer === CalendarInviteAnswer.Tentative
+                ? "Tentative"
+                : "Accepted";
+        return `${word}: ${title}`;
+    }
+    return `Invitation: ${title}`;
+};