@remit/calendar-service 0.0.18 → 0.0.19

package/dist/accept.d.ts

@@ -0,0 +1,71 @@
+import type { CalendarInviteAnswer as CalendarInviteAnswerValue } from "@remit/api-openapi-types";
+import type { CalendarObjectItem, CalendarSuggestionItem, ICalendarStore } from "@remit/data-ports";
+import type { CalendarResult } from "./errors.js";
+/**
+ * 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 declare const buildAcceptedCalendar: (suggestion: Pick<CalendarSuggestionItem, "icalData" | "method">, attendee: string, answer: CalendarInviteAnswerValue) => Promise<CalendarResult<string>>;
+export interface AcceptCalendarSuggestionInput {
+    accountConfigId: string;
+    calendarId: string;
+    suggestion: CalendarSuggestionItem;
+    /** Mail address of the person accepting — the account the message arrived on. */
+    attendee: string;
+    answer: CalendarInviteAnswerValue;
+}
+/**
+ * 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, then settles the suggestion.
+ *
+ * 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 event and the suggestion
+ * live in different databases, so the commit writes the event first and
+ * settles the card second. A failure between the two leaves the card still
+ * asking with the event in the calendar, and accepting again repairs it: the
+ * event write lands on the same resource and the settle follows.
+ *
+ * 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 declare const acceptCalendarSuggestion: (store: ICalendarStore, input: AcceptCalendarSuggestionInput) => Promise<CalendarResult<AcceptedCalendarSuggestion>>;

package/dist/accept.js

@@ -0,0 +1,159 @@
+import { deriveCalendarObjectId } from "@remit/data-ports/id";
+import { CalendarInviteAnswer, CalendarInviteMethod, CalendarSuggestionState, } from "@remit/domain-enums";
+import ICAL from "ical.js";
+import { parseCalendar, serializeCalendar } from "./parse.js";
+import { prepareCalendarObject, readWrittenObject } from "./put.js";
+import { mailAddressOf } from "./suggest.js";
+const eventsOf = (component) => component.getAllSubcomponents("vevent");
+const partstatOf = {
+    [CalendarInviteAnswer.Accepted]: "ACCEPTED",
+    [CalendarInviteAnswer.Tentative]: "TENTATIVE",
+};
+const stateOf = {
+    [CalendarInviteAnswer.Accepted]: CalendarSuggestionState.Accepted,
+    [CalendarInviteAnswer.Tentative]: CalendarSuggestionState.Tentative,
+};
+/**
+ * Marks one address with its answer, 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 markAnswered = (component, attendee, answer) => {
+    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);
+        property.setParameter("partstat", partstatOf[answer]);
+        if (!existing) {
+            property.setValue(`mailto:${attendee}`);
+            event.addProperty(property);
+        }
+    }
+};
+const markCancelled = (component) => {
+    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, attendee, answer) => {
+    const parsed = await parseCalendar(suggestion.icalData);
+    if (!parsed.ok)
+        return parsed;
+    const { component } = parsed.value;
+    component.removeAllProperties("method");
+    markAnswered(component, attendee, answer);
+    if (suggestion.method === CalendarInviteMethod.Cancel) {
+        markCancelled(component);
+    }
+    return { ok: true, value: serializeCalendar(component) };
+};
+/**
+ * Adds a suggested event to a calendar, then settles the suggestion.
+ *
+ * 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 event and the suggestion
+ * live in different databases, so the commit writes the event first and
+ * settles the card second. A failure between the two leaves the card still
+ * asking with the event in the calendar, and accepting again repairs it: the
+ * event write lands on the same resource and the settle follows.
+ *
+ * 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 (store, input) => {
+    const icalData = await buildAcceptedCalendar(input.suggestion, input.attendee, input.answer);
+    if (!icalData.ok)
+        return icalData;
+    const existing = await store.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) {
+        await store.commit([
+            {
+                kind: "SettleSuggestion",
+                accountConfigId: input.accountConfigId,
+                suggestionId: input.suggestion.suggestionId,
+                settle: {
+                    state: CalendarSuggestionState.Dismissed,
+                    acceptedCalendarObjectId: "",
+                },
+            },
+        ]);
+        return {
+            ok: true,
+            value: {
+                suggestion: await store.repos.calendarSuggestion.get(input.accountConfigId, input.suggestion.suggestionId),
+                outcome: "NothingToCancel",
+                object: null,
+            },
+        };
+    }
+    const collection = await store.repos.calendarCollection.get(input.accountConfigId, input.calendarId);
+    const write = await prepareCalendarObject(collection, {
+        accountConfigId: input.accountConfigId,
+        calendarId: input.calendarId,
+        resourceName: existing?.resourceName ?? `${input.suggestion.suggestionId}.ics`,
+        icalData: icalData.value,
+    });
+    if (!write.ok)
+        return write;
+    const calendarObjectId = deriveCalendarObjectId(write.value.object.calendarId, write.value.object.resourceName);
+    await store.commit([
+        write.value,
+        {
+            kind: "SettleSuggestion",
+            accountConfigId: input.accountConfigId,
+            suggestionId: input.suggestion.suggestionId,
+            settle: {
+                state: stateOf[input.answer],
+                acceptedCalendarObjectId: calendarObjectId,
+            },
+        },
+    ]);
+    return {
+        ok: true,
+        value: {
+            suggestion: await store.repos.calendarSuggestion.get(input.accountConfigId, input.suggestion.suggestionId),
+            outcome: "Written",
+            object: await readWrittenObject(store, write.value),
+        },
+    };
+};

package/dist/build.d.ts

@@ -0,0 +1,79 @@
+import type { CalendarObjectItem } from "@remit/data-ports";
+import ICAL from "ical.js";
+import { type CalendarResult } from "./errors.js";
+/** Identifies this server in the PRODID of every VCALENDAR it writes. */
+export declare const CALENDAR_PRODID = "-//Remit//Reader Calendar//EN";
+/**
+ * An event as a person describes it, before it is iCalendar.
+ *
+ * Deliberately not a subset of a VEVENT: a client should not have to know that
+ * an all-day end is exclusive, that a duration and an end are the same fact
+ * written twice, or that a zone lives in a parameter rather than in the value.
+ * The server owns iCalendar; this is the shape the API takes and the shape a
+ * patch is expressed in.
+ */
+export interface CalendarEventFields {
+    summary: string;
+    description: string;
+    location: string;
+    /** ISO 8601 with a zone offset, or `YYYY-MM-DD` when `allDay`. */
+    start: string;
+    /** Same form as `start`. Exclusive for an all-day event. */
+    end: string;
+    allDay: boolean;
+    /** IANA zone the event is anchored in. `""` anchors it in UTC. */
+    timeZone: string;
+    status: CalendarObjectItem["status"];
+    transparency: CalendarObjectItem["transparency"];
+    /** RRULE value without the property name. `""` for a single event. */
+    recurrenceRule: string;
+}
+/**
+ * An offset is required on a date-time. A wall time with no offset names no
+ * instant — a client sending `2026-03-29T02:30:00` on the morning the clocks
+ * move is asking for a time that happens twice, or not at all — and guessing
+ * one is how a calendar quietly puts an event an hour out.
+ */
+export declare const OFFSET_BEARING: RegExp;
+/**
+ * Reads one API date-time into the iCalendar time the resource will carry.
+ *
+ * An all-day value becomes a DATE, which is a civil date and has no zone at
+ * all. A timed value becomes the wall time it reads as in `timeZone`, so the
+ * resource records the zone the event is anchored in rather than the offset
+ * that zone happened to be at — which is the whole difference between a weekly
+ * 09:00 meeting and a meeting that moves to 08:00 every autumn.
+ */
+export declare const readEventTime: (value: string, allDay: boolean, timeZone: string) => CalendarResult<ICAL.Time>;
+/** The time fields a stored VEVENT already carries, in the API's own form. */
+export declare const eventTimeFields: (component: ICAL.Component, collectionTimezone: string) => Pick<CalendarEventFields, "start" | "end" | "allDay" | "timeZone">;
+/**
+ * ical.js's recurrence parser in a promise, so an unreadable rule arrives as a
+ * value to branch on rather than a synchronous throw.
+ *
+ * A rule with no FREQ is refused rather than stored. ical.js reads text it
+ * finds no parts in as a rule with a null frequency instead of failing, and
+ * storing that would give somebody an event marked as recurring that produces
+ * nothing — the failure a client cannot see and cannot fix.
+ */
+export declare const readRecurrenceRule: (recurrenceRule: string) => Promise<CalendarResult<ICAL.Recur>>;
+/**
+ * Writes a patch onto a VEVENT.
+ *
+ * A field the patch does not carry is untouched, so renaming an event moves
+ * nothing. The time fields are the exception: zone, all-day-ness, start and end
+ * are one fact between them, so touching any of them rewrites DTSTART and DTEND
+ * together from the values the event would then have. Rewriting only the one
+ * the caller named is what produces an event that starts in one zone and ends
+ * in another.
+ */
+export declare const applyEventFields: (component: ICAL.Component, patch: Partial<CalendarEventFields>, collectionTimezone: string) => Promise<CalendarResult<null>>;
+/**
+ * Builds the VCALENDAR text for a new event.
+ *
+ * The output goes straight to the single write path, which parses it again to
+ * validate and project it. That second read is not waste: it is the same gate
+ * every other writer passes, so an event this function got wrong is refused
+ * here rather than stored.
+ */
+export declare const buildEventCalendar: (fields: CalendarEventFields, uid: string, now?: Date) => Promise<CalendarResult<string>>;

package/dist/build.js

@@ -0,0 +1,196 @@
+import { CalendarEventStatus, CalendarTransparency } from "@remit/domain-enums";
+import ICAL from "ical.js";
+import { calendarFailure } from "./errors.js";
+import { serializeCalendar } from "./parse.js";
+import { civilInZone, dtEndTzid, dtStartTzid, isResolvableZone, resolveTime, } from "./time.js";
+/** Identifies this server in the PRODID of every VCALENDAR it writes. */
+export const CALENDAR_PRODID = "-//Remit//Reader Calendar//EN";
+const STATUS_TO_ICAL = {
+    [CalendarEventStatus.Confirmed]: "CONFIRMED",
+    [CalendarEventStatus.Tentative]: "TENTATIVE",
+    [CalendarEventStatus.Cancelled]: "CANCELLED",
+};
+const TRANSPARENCY_TO_ICAL = {
+    [CalendarTransparency.Opaque]: "OPAQUE",
+    [CalendarTransparency.Transparent]: "TRANSPARENT",
+};
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}/;
+/**
+ * An offset is required on a date-time. A wall time with no offset names no
+ * instant — a client sending `2026-03-29T02:30:00` on the morning the clocks
+ * move is asking for a time that happens twice, or not at all — and guessing
+ * one is how a calendar quietly puts an event an hour out.
+ */
+export const OFFSET_BEARING = /(Z|[+-]\d{2}:\d{2})$/;
+/**
+ * Reads one API date-time into the iCalendar time the resource will carry.
+ *
+ * An all-day value becomes a DATE, which is a civil date and has no zone at
+ * all. A timed value becomes the wall time it reads as in `timeZone`, so the
+ * resource records the zone the event is anchored in rather than the offset
+ * that zone happened to be at — which is the whole difference between a weekly
+ * 09:00 meeting and a meeting that moves to 08:00 every autumn.
+ */
+export const readEventTime = (value, allDay, timeZone) => {
+    if (allDay) {
+        const date = DATE_ONLY.exec(value)?.[0];
+        if (!date) {
+            return calendarFailure("InvalidDateTime", `an all-day event needs a YYYY-MM-DD date, and this one carries "${value}"`);
+        }
+        const [year, month, day] = date.split("-").map(Number);
+        return {
+            ok: true,
+            value: ICAL.Time.fromData({ year, month, day, isDate: true }),
+        };
+    }
+    if (!OFFSET_BEARING.test(value)) {
+        return calendarFailure("InvalidDateTime", `a date-time needs an explicit zone offset, and this one carries "${value}"`);
+    }
+    const instantMs = Date.parse(value);
+    if (Number.isNaN(instantMs)) {
+        return calendarFailure("InvalidDateTime", `"${value}" is not a date-time this server can read`);
+    }
+    if (timeZone !== "" && !isResolvableZone(timeZone)) {
+        return calendarFailure("UnknownTimeZone", `"${timeZone}" is not a time zone this server can resolve`);
+    }
+    const civil = civilInZone(instantMs, timeZone === "" ? "UTC" : timeZone);
+    return {
+        ok: true,
+        value: ICAL.Time.fromData({
+            year: civil.year,
+            month: civil.month,
+            day: civil.day,
+            hour: civil.hour,
+            minute: civil.minute,
+            second: civil.second,
+            isDate: false,
+        }, timeZone === "" ? ICAL.Timezone.utcTimezone : ICAL.Timezone.localTimezone),
+    };
+};
+const setTimeProperty = (event, name, time, timeZone) => {
+    event.removeAllProperties(name);
+    const property = new ICAL.Property(name);
+    event.addProperty(property);
+    property.setValue(time);
+    if (!time.isDate && timeZone !== "") {
+        property.setParameter("tzid", timeZone);
+    }
+};
+const setTextProperty = (event, name, value) => {
+    event.removeAllProperties(name);
+    if (value === "")
+        return;
+    event.addPropertyWithValue(name, value);
+};
+/** The time fields a stored VEVENT already carries, in the API's own form. */
+export const eventTimeFields = (component, collectionTimezone) => {
+    const event = new ICAL.Event(component);
+    const startTzid = dtStartTzid(component);
+    const start = resolveTime(event.startDate, startTzid, collectionTimezone);
+    const end = resolveTime(event.endDate, dtEndTzid(component), collectionTimezone);
+    return {
+        start: start.isoOffset,
+        end: end.isoOffset,
+        allDay: start.isDate,
+        timeZone: startTzid,
+    };
+};
+/**
+ * ical.js's recurrence parser in a promise, so an unreadable rule arrives as a
+ * value to branch on rather than a synchronous throw.
+ *
+ * A rule with no FREQ is refused rather than stored. ical.js reads text it
+ * finds no parts in as a rule with a null frequency instead of failing, and
+ * storing that would give somebody an event marked as recurring that produces
+ * nothing — the failure a client cannot see and cannot fix.
+ */
+export const readRecurrenceRule = (recurrenceRule) => new Promise((resolve) => {
+    resolve(ICAL.Recur.fromString(recurrenceRule));
+}).then((value) => value.freq
+    ? { ok: true, value }
+    : calendarFailure("InvalidRecurrenceRule", `"${recurrenceRule}" names no FREQ, so it is not a recurrence rule`), (error) => calendarFailure("InvalidRecurrenceRule", error instanceof Error
+    ? error.message
+    : `"${recurrenceRule}" is not a recurrence rule this server can read`));
+/**
+ * Writes a patch onto a VEVENT.
+ *
+ * A field the patch does not carry is untouched, so renaming an event moves
+ * nothing. The time fields are the exception: zone, all-day-ness, start and end
+ * are one fact between them, so touching any of them rewrites DTSTART and DTEND
+ * together from the values the event would then have. Rewriting only the one
+ * the caller named is what produces an event that starts in one zone and ends
+ * in another.
+ */
+export const applyEventFields = async (component, patch, collectionTimezone) => {
+    if (patch.summary !== undefined) {
+        setTextProperty(component, "summary", patch.summary);
+    }
+    if (patch.description !== undefined) {
+        setTextProperty(component, "description", patch.description);
+    }
+    if (patch.location !== undefined) {
+        setTextProperty(component, "location", patch.location);
+    }
+    if (patch.status !== undefined) {
+        setTextProperty(component, "status", STATUS_TO_ICAL[patch.status]);
+    }
+    if (patch.transparency !== undefined) {
+        setTextProperty(component, "transp", TRANSPARENCY_TO_ICAL[patch.transparency]);
+    }
+    if (patch.recurrenceRule !== undefined) {
+        component.removeAllProperties("rrule");
+        if (patch.recurrenceRule !== "") {
+            const rule = await readRecurrenceRule(patch.recurrenceRule);
+            if (!rule.ok)
+                return rule;
+            component.addPropertyWithValue("rrule", rule.value);
+        }
+    }
+    const touchesTime = patch.start !== undefined ||
+        patch.end !== undefined ||
+        patch.allDay !== undefined ||
+        patch.timeZone !== undefined;
+    if (!touchesTime)
+        return { ok: true, value: null };
+    // A VEVENT being built from nothing has no times to read back, and every one
+    // of them is in the patch. The empty start then refuses a create that left
+    // one out, which is the same answer reading it back would have given.
+    const current = component.hasProperty("dtstart")
+        ? eventTimeFields(component, collectionTimezone)
+        : { start: "", end: "", allDay: false, timeZone: "" };
+    const allDay = patch.allDay ?? current.allDay;
+    const timeZone = patch.timeZone ?? current.timeZone;
+    const start = readEventTime(patch.start ?? current.start, allDay, timeZone);
+    if (!start.ok)
+        return start;
+    const end = readEventTime(patch.end ?? current.end, allDay, timeZone);
+    if (!end.ok)
+        return end;
+    // A duration says the same thing DTEND does, and leaving one behind beside a
+    // rewritten DTEND leaves two answers to how long the event is.
+    component.removeAllProperties("duration");
+    setTimeProperty(component, "dtstart", start.value, timeZone);
+    setTimeProperty(component, "dtend", end.value, timeZone);
+    return { ok: true, value: null };
+};
+/**
+ * Builds the VCALENDAR text for a new event.
+ *
+ * The output goes straight to the single write path, which parses it again to
+ * validate and project it. That second read is not waste: it is the same gate
+ * every other writer passes, so an event this function got wrong is refused
+ * here rather than stored.
+ */
+export const buildEventCalendar = async (fields, uid, now = new Date()) => {
+    const calendar = new ICAL.Component("vcalendar");
+    calendar.addPropertyWithValue("version", "2.0");
+    calendar.addPropertyWithValue("prodid", CALENDAR_PRODID);
+    const event = new ICAL.Component("vevent");
+    calendar.addSubcomponent(event);
+    event.addPropertyWithValue("uid", uid);
+    event.addPropertyWithValue("dtstamp", ICAL.Time.fromJSDate(now, true));
+    const applied = await applyEventFields(event, fields, fields.timeZone);
+    if (!applied.ok)
+        return applied;
+    return { ok: true, value: serializeCalendar(calendar) };
+};

package/dist/correct.d.ts

@@ -0,0 +1,4 @@
+import type { CalendarSuggestionItem } from "@remit/data-ports";
+import type { CalendarEventFields } from "./build.js";
+import { type CalendarResult } from "./errors.js";
+export declare const correctCalendarSuggestion: (suggestion: CalendarSuggestionItem, patch: Partial<CalendarEventFields>, collectionTimezone: string) => Promise<CalendarResult<CalendarSuggestionItem>>;

package/dist/correct.js

@@ -0,0 +1,22 @@
+import { CalendarInviteMethod, RecurrenceScope } from "@remit/domain-enums";
+import { calendarFailure } from "./errors.js";
+import { parseCalendar } from "./parse.js";
+import { applyScopedUpdate } from "./scope.js";
+export const correctCalendarSuggestion = async (suggestion, patch, collectionTimezone) => {
+    if (suggestion.method === CalendarInviteMethod.Cancel) {
+        return calendarFailure("UneditableCancellation", "a cancellation names no event to correct — add it or dismiss it as it is");
+    }
+    const parsed = await parseCalendar(suggestion.icalData);
+    if (!parsed.ok)
+        return parsed;
+    const edited = await applyScopedUpdate(parsed.value, collectionTimezone, { scope: RecurrenceScope.All, recurrenceId: "", followingUid: "" }, patch);
+    if (!edited.ok)
+        return edited;
+    if (edited.value.kind !== "Replace") {
+        throw new Error(`an edit to the whole invitation resolved to a ${edited.value.kind}`);
+    }
+    return {
+        ok: true,
+        value: { ...suggestion, icalData: edited.value.icalData },
+    };
+};

package/dist/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Why a VCALENDAR was refused. Every value names something the writer can act
+ * on — a caller maps these to a 4xx and repeats the message.
+ */
+export type CalendarValidationCode = 
+/** The bytes are not parseable iCalendar at all. */
+"MalformedIcalendar"
+/** The document's root is not a VCALENDAR. */
+ | "NotACalendar"
+/** A component this collection does not store, e.g. VTODO or VJOURNAL. */
+ | "UnsupportedComponent"
+/** A VCALENDAR with no VEVENT in it. */
+ | "NoEvent"
+/** No VEVENT without a RECURRENCE-ID: overrides with nothing to override. */
+ | "NoMasterEvent"
+/** More than one VEVENT without a RECURRENCE-ID. */
+ | "MultipleMasterEvents"
+/** A VEVENT with no UID, or an empty one. */
+ | "MissingUid"
+/** VEVENTs in one resource declaring different UIDs. */
+ | "MismatchedUid"
+/** A VEVENT with no DTSTART. */
+ | "MissingDtStart"
+/** A VEVENT whose end precedes its start. */
+ | "BackwardsEnd"
+/** A start or end that is not a date-time this server can read. */
+ | "InvalidDateTime"
+/** A time zone name nothing on this platform resolves. */
+ | "UnknownTimeZone"
+/** An RRULE value ical.js could not read. */
+ | "InvalidRecurrenceRule"
+/** A scoped write that names one occurrence without saying which. */
+ | "MissingRecurrenceId"
+/** A per-occurrence scope against an event that has one occurrence. */
+ | "NotRecurring"
+/** A RECURRENCE-ID naming no occurrence this series produces. */
+ | "UnknownOccurrence" | "UnmovableRecurrenceRule" | "UneditableCancellation"
+/** A subscription address that is not an http, https or webcal URL. */
+ | "InvalidSubscriptionUrl" | "NotReopenable" | "AnswerOvertaken";
+export interface CalendarValidationError {
+    code: CalendarValidationCode;
+    message: string;
+}
+/**
+ * The outcome of reading a VCALENDAR. A refusal is a value, not a throw:
+ * malformed input from a client is an expected outcome of this boundary, and
+ * every caller has to render it rather than crash on it.
+ */
+export type CalendarResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: CalendarValidationError;
+};
+export declare const calendarFailure: <T>(code: CalendarValidationCode, message: string) => CalendarResult<T>;

package/dist/errors.js

@@ -0,0 +1 @@
+export const calendarFailure = (code, message) => ({ ok: false, error: { code, message } });

package/dist/etag.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Strong entity tag over the resource's stored bytes.
+ *
+ * Computed over the bytes exactly as they are stored — CRLF and all — rather
+ * than over a reparse of them, so the tag of an untouched resource never moves.
+ * Unquoted: HTTP's quoting is the transport's business, and a stored tag that
+ * carried the quotes would have to be stripped by everything that compares it.
+ */
+export declare const computeEtag: (icalData: string) => string;

package/{src/etag.ts → dist/etag.js}

@@ -1,5 +1,4 @@
 import { createHash } from "node:crypto";
-
 /**
  * Strong entity tag over the resource's stored bytes.
  *
@@ -8,5 +7,4 @@ import { createHash } from "node:crypto";
  * Unquoted: HTTP's quoting is the transport's business, and a stored tag that
  * carried the quotes would have to be stripped by everything that compares it.
  */
-export const computeEtag = (icalData: string): string =>
-	createHash("sha256").update(icalData, "utf8").digest("hex");
+export const computeEtag = (icalData) => createHash("sha256").update(icalData, "utf8").digest("hex");