@remit/calendar-service 0.0.18 → 0.0.19

package/dist/subscribe.d.ts

@@ -0,0 +1,96 @@
+import type { CalendarCollectionItem, ICalendarStore } from "@remit/data-ports";
+import { type CalendarResult } from "./errors.js";
+export declare const CALENDAR_SUBSCRIPTION_TIMEOUT_MS = 30000;
+export declare const CALENDAR_SUBSCRIPTION_MAX_BYTES: number;
+export type CalendarFeedFetcher = (url: string, init: RequestInit) => Promise<Response>;
+export type CalendarFeedFetch = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface CalendarFeedResource {
+    uid: string;
+    resourceName: string;
+    icalData: string;
+}
+export interface CalendarFeedSplit {
+    resources: CalendarFeedResource[];
+    unreadable: number;
+}
+export interface CalendarFeedWrite {
+    /** The subscription was paused while its feed was being read, so nothing was written. */
+    paused: boolean;
+    written: number;
+    unchanged: number;
+    removed: number;
+    skipped: number;
+}
+export interface CalendarSubscriptionTarget {
+    accountConfigId: string;
+    calendarId: string;
+}
+export type CalendarSubscriptionRefresh = {
+    ok: true;
+    value: CalendarFeedWrite;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The URL a subscription is fetched from. `webcal:` is what calendar products
+ * hand out for "subscribe", and means the same address over HTTPS.
+ */
+export declare const readSubscriptionUrl: (raw: string) => CalendarResult<string>;
+/**
+ * Reads a subscription's feed. Every failure is a returned reason that a
+ * person can act on and that never repeats the URL: for a Google secret
+ * address the URL is the whole credential, and the reason is stored on the
+ * collection and drawn in the calendar view.
+ */
+export declare const fetchCalendarFeed: (url: string, fetcher?: CalendarFeedFetcher) => Promise<CalendarFeedFetch>;
+/**
+ * Cuts a whole feed into one resource per UID, the shape the calendar write
+ * path stores: a series and its RECURRENCE-ID overrides travel together, with
+ * the VTIMEZONEs they name, so a DST-crossing series resolves against the zone
+ * the provider published.
+ *
+ * The feed's calendar-level properties are kept on every resource except
+ * METHOD, which a stored resource never carries. A VEVENT with no UID has
+ * nothing to key it by across refreshes, so it is counted and left out.
+ */
+export declare const splitCalendarFeed: (icalData: string) => Promise<CalendarResult<CalendarFeedSplit>>;
+/**
+ * Makes a subscribed collection hold what the feed holds, in one commit.
+ *
+ * Every resource goes through `prepareCalendarObject`, the one write path, so
+ * a subscribed event is stored, projected and expanded the way any other event
+ * is. A resource whose bytes have not changed is left alone, and one the feed
+ * no longer carries is removed. A resource the write path refuses is counted
+ * and recorded on the collection rather than failing the whole refresh.
+ *
+ * Repeating a refresh converges: a resource is keyed by its name, so a second
+ * run over the same feed finds every resource unchanged.
+ */
+export declare const writeCalendarFeed: (store: ICalendarStore, target: CalendarSubscriptionTarget, split: CalendarFeedSplit, now: number) => Promise<CalendarFeedWrite>;
+/** Records a refresh that stored nothing, and why. Every stored event stays. */
+export declare const recordCalendarFeedFailure: (store: ICalendarStore, target: CalendarSubscriptionTarget, reason: string, now: number) => Promise<void>;
+/** Fetches and cuts a feed, or answers why it cannot be stored. */
+export declare const readCalendarFeed: (url: string, fetcher?: CalendarFeedFetcher) => Promise<{
+    ok: true;
+    value: CalendarFeedSplit;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * One scheduled refresh of one subscription. A feed that cannot be read
+ * records its reason on the collection and removes nothing.
+ */
+export declare const refreshCalendarSubscription: (store: ICalendarStore, collection: CalendarCollectionItem, now: number, fetcher?: CalendarFeedFetcher) => Promise<CalendarSubscriptionRefresh>;
+/**
+ * Whether a subscription is due a refresh: its last fetch, successful or not,
+ * is at least `intervalMs` old.
+ */
+export declare const isSubscriptionDue: (collection: CalendarCollectionItem, now: number, intervalMs: number) => boolean;

package/dist/subscribe.js

@@ -0,0 +1,298 @@
+import { createHash } from "node:crypto";
+import ICAL from "ical.js";
+import { calendarFailure } from "./errors.js";
+import { readCalendarComponent, serializeCalendar } from "./parse.js";
+import { deleteCalendarObjectWrite, prepareCalendarObject } from "./put.js";
+export const CALENDAR_SUBSCRIPTION_TIMEOUT_MS = 30_000;
+export const CALENDAR_SUBSCRIPTION_MAX_BYTES = 10 * 1024 * 1024;
+const SUBSCRIPTION_ERROR_MAX_LENGTH = 512;
+const SCHEMES = {
+    "http:": "http:",
+    "https:": "https:",
+    "webcal:": "https:",
+    "webcals:": "https:",
+};
+/**
+ * The URL a subscription is fetched from. `webcal:` is what calendar products
+ * hand out for "subscribe", and means the same address over HTTPS.
+ */
+export const readSubscriptionUrl = (raw) => {
+    const trimmed = raw.trim();
+    if (!URL.canParse(trimmed)) {
+        return calendarFailure("InvalidSubscriptionUrl", "the subscription address is not a URL");
+    }
+    const url = new URL(trimmed);
+    const scheme = SCHEMES[url.protocol];
+    if (!scheme) {
+        return calendarFailure("InvalidSubscriptionUrl", `a subscription address starts with http, https or webcal, not ${url.protocol.replace(/:$/, "")}`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        return calendarFailure("InvalidSubscriptionUrl", "a subscription address carries no user name or password");
+    }
+    const address = new URL(`${scheme}${trimmed.slice(url.protocol.length)}`);
+    return { ok: true, value: address.toString() };
+};
+const truncate = (reason) => reason.length <= SUBSCRIPTION_ERROR_MAX_LENGTH
+    ? reason
+    : `${reason.slice(0, SUBSCRIPTION_ERROR_MAX_LENGTH - 1)}…`;
+const unreachableReason = (error) => {
+    if (error instanceof Error && error.name === "TimeoutError") {
+        return `the feed did not answer within ${CALENDAR_SUBSCRIPTION_TIMEOUT_MS / 1000} seconds`;
+    }
+    const cause = error instanceof Error && error.cause instanceof Error
+        ? error.cause
+        : undefined;
+    const code = cause && "code" in cause && typeof cause.code === "string"
+        ? cause.code
+        : undefined;
+    return code
+        ? `the feed could not be reached (${code})`
+        : "the feed could not be reached";
+};
+/**
+ * Reads a subscription's feed. Every failure is a returned reason that a
+ * person can act on and that never repeats the URL: for a Google secret
+ * address the URL is the whole credential, and the reason is stored on the
+ * collection and drawn in the calendar view.
+ */
+export const fetchCalendarFeed = async (url, fetcher = fetch) => {
+    const response = await fetcher(url, {
+        headers: { accept: "text/calendar, */*;q=0.5" },
+        redirect: "follow",
+        signal: AbortSignal.timeout(CALENDAR_SUBSCRIPTION_TIMEOUT_MS),
+    }).then((value) => ({ ok: true, value }), (error) => ({ ok: false, reason: unreachableReason(error) }));
+    if (!response.ok)
+        return response;
+    const { status } = response.value;
+    if (status < 200 || status > 299) {
+        await response.value.body?.cancel();
+        return { ok: false, reason: `the feed answered HTTP ${status}` };
+    }
+    const declared = Number(response.value.headers.get("content-length") ?? "0");
+    if (declared > CALENDAR_SUBSCRIPTION_MAX_BYTES) {
+        await response.value.body?.cancel();
+        return { ok: false, reason: TOO_LARGE };
+    }
+    const { body } = response.value;
+    if (!body)
+        return { ok: true, value: "" };
+    return readCapped(body).then((read) => read, (error) => ({ ok: false, reason: unreachableReason(error) }));
+};
+const TOO_LARGE = "the feed is larger than 10 MB";
+/**
+ * Reads a body a chunk at a time and stops at the cap. A feed sent chunked
+ * carries no length to refuse up front, so counting as it arrives is the only
+ * thing that keeps an endless body out of memory.
+ */
+const readCapped = async (body) => {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let received = 0;
+    let text = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > CALENDAR_SUBSCRIPTION_MAX_BYTES) {
+            await reader.cancel();
+            return { ok: false, reason: TOO_LARGE };
+        }
+        text += decoder.decode(value, { stream: true });
+    }
+    return { ok: true, value: text + decoder.decode() };
+};
+/**
+ * A resource as it would compare across two fetches. DTSTAMP is when the
+ * provider exported the feed, not when the event changed — Google restamps it
+ * on every fetch — so it is left out, or every refresh would rewrite every
+ * event.
+ */
+const comparable = (icalData) => icalData.replace(/^DTSTAMP[;:][^\r\n]*\r?\n/gim, "");
+const resourceNameOf = (uid) => `${createHash("sha256").update(uid, "utf8").digest("hex").slice(0, 40)}.ics`;
+const zonesReferencedBy = (events) => {
+    const zones = new Set();
+    for (const event of events) {
+        for (const property of event.getAllProperties()) {
+            const tzid = property.getParameter("tzid");
+            if (typeof tzid === "string")
+                zones.add(tzid);
+        }
+    }
+    return zones;
+};
+/**
+ * Cuts a whole feed into one resource per UID, the shape the calendar write
+ * path stores: a series and its RECURRENCE-ID overrides travel together, with
+ * the VTIMEZONEs they name, so a DST-crossing series resolves against the zone
+ * the provider published.
+ *
+ * The feed's calendar-level properties are kept on every resource except
+ * METHOD, which a stored resource never carries. A VEVENT with no UID has
+ * nothing to key it by across refreshes, so it is counted and left out.
+ */
+export const splitCalendarFeed = async (icalData) => {
+    const read = await readCalendarComponent(icalData);
+    if (!read.ok)
+        return read;
+    const feed = read.value;
+    if (feed.name !== "vcalendar") {
+        return calendarFailure("NotACalendar", feed.name
+            ? `expected a VCALENDAR, found ${feed.name.toUpperCase()}`
+            : "expected a VCALENDAR, found nothing");
+    }
+    const timezones = feed.getAllSubcomponents("vtimezone");
+    const byUid = new Map();
+    let unreadable = 0;
+    for (const event of feed.getAllSubcomponents("vevent")) {
+        const uid = event.getFirstPropertyValue("uid");
+        if (typeof uid !== "string" || uid === "") {
+            unreadable += 1;
+            continue;
+        }
+        byUid.set(uid, [...(byUid.get(uid) ?? []), event]);
+    }
+    const resources = [...byUid].map(([uid, events]) => {
+        const calendar = new ICAL.Component("vcalendar");
+        for (const property of feed.getAllProperties()) {
+            if (property.name === "method")
+                continue;
+            calendar.addProperty(new ICAL.Property(property.toJSON()));
+        }
+        const zones = zonesReferencedBy(events);
+        for (const timezone of timezones) {
+            const tzid = timezone.getFirstPropertyValue("tzid");
+            if (typeof tzid === "string" && zones.has(tzid)) {
+                calendar.addSubcomponent(new ICAL.Component(timezone.toJSON()));
+            }
+        }
+        for (const event of events) {
+            calendar.addSubcomponent(new ICAL.Component(event.toJSON()));
+        }
+        return {
+            uid,
+            resourceName: resourceNameOf(uid),
+            icalData: serializeCalendar(calendar),
+        };
+    });
+    return { ok: true, value: { resources, unreadable } };
+};
+const feedErrorOf = (write) => write.skipped === 0
+    ? ""
+    : `${write.skipped} ${write.skipped === 1 ? "event" : "events"} in the feed could not be stored`;
+/**
+ * Makes a subscribed collection hold what the feed holds, in one commit.
+ *
+ * Every resource goes through `prepareCalendarObject`, the one write path, so
+ * a subscribed event is stored, projected and expanded the way any other event
+ * is. A resource whose bytes have not changed is left alone, and one the feed
+ * no longer carries is removed. A resource the write path refuses is counted
+ * and recorded on the collection rather than failing the whole refresh.
+ *
+ * Repeating a refresh converges: a resource is keyed by its name, so a second
+ * run over the same feed finds every resource unchanged.
+ */
+export const writeCalendarFeed = async (store, target, split, now) => {
+    const current = await store.repos.calendarCollection.get(target.accountConfigId, target.calendarId);
+    if (!current.subscriptionEnabled) {
+        return { paused: true, written: 0, unchanged: 0, removed: 0, skipped: 0 };
+    }
+    const stored = await store.repos.calendarObject.listByCalendar(target.calendarId);
+    const storedByName = new Map(stored.map((object) => [object.resourceName, object]));
+    const kept = new Set();
+    const writes = [];
+    const write = {
+        paused: false,
+        written: 0,
+        unchanged: 0,
+        removed: 0,
+        skipped: split.unreadable,
+    };
+    for (const resource of split.resources) {
+        const existing = storedByName.get(resource.resourceName);
+        if (existing &&
+            comparable(existing.icalData) === comparable(resource.icalData)) {
+            kept.add(resource.resourceName);
+            write.unchanged += 1;
+            continue;
+        }
+        const put = await prepareCalendarObject(current, {
+            accountConfigId: target.accountConfigId,
+            calendarId: target.calendarId,
+            resourceName: resource.resourceName,
+            icalData: resource.icalData,
+        });
+        if (!put.ok) {
+            write.skipped += 1;
+            continue;
+        }
+        writes.push(put.value);
+        kept.add(resource.resourceName);
+        write.written += 1;
+    }
+    for (const object of stored) {
+        if (kept.has(object.resourceName))
+            continue;
+        writes.push(deleteCalendarObjectWrite({
+            accountConfigId: target.accountConfigId,
+            calendarId: target.calendarId,
+            calendarObjectId: object.calendarObjectId,
+        }));
+        write.removed += 1;
+    }
+    writes.push({
+        kind: "UpdateCollection",
+        accountConfigId: target.accountConfigId,
+        calendarId: target.calendarId,
+        patch: {
+            subscriptionCheckedAt: now,
+            subscriptionFetchedAt: now,
+            subscriptionError: truncate(feedErrorOf(write)),
+        },
+    });
+    await store.commit(writes);
+    return write;
+};
+/** Records a refresh that stored nothing, and why. Every stored event stays. */
+export const recordCalendarFeedFailure = async (store, target, reason, now) => {
+    await store.repos.calendarCollection.update(target.accountConfigId, target.calendarId, {
+        subscriptionCheckedAt: now,
+        subscriptionError: truncate(reason),
+    });
+};
+/** Fetches and cuts a feed, or answers why it cannot be stored. */
+export const readCalendarFeed = async (url, fetcher = fetch) => {
+    const fetched = await fetchCalendarFeed(url, fetcher);
+    if (!fetched.ok)
+        return fetched;
+    const split = await splitCalendarFeed(fetched.value);
+    if (!split.ok) {
+        return {
+            ok: false,
+            reason: `the feed is not a calendar: ${split.error.message}`,
+        };
+    }
+    return split;
+};
+/**
+ * One scheduled refresh of one subscription. A feed that cannot be read
+ * records its reason on the collection and removes nothing.
+ */
+export const refreshCalendarSubscription = async (store, collection, now, fetcher = fetch) => {
+    const target = {
+        accountConfigId: collection.accountConfigId,
+        calendarId: collection.calendarId,
+    };
+    const feed = await readCalendarFeed(collection.subscriptionUrl, fetcher);
+    if (!feed.ok) {
+        await recordCalendarFeedFailure(store, target, feed.reason, now);
+        return feed;
+    }
+    const write = await writeCalendarFeed(store, target, feed.value, now);
+    return { ok: true, value: write };
+};
+/**
+ * Whether a subscription is due a refresh: its last fetch, successful or not,
+ * is at least `intervalMs` old.
+ */
+export const isSubscriptionDue = (collection, now, intervalMs) => now - collection.subscriptionCheckedAt >= intervalMs;

package/dist/suggest.d.ts

@@ -0,0 +1,74 @@
+import type { CalendarSuggestionItem, ICalendarSuggestionRepository, PutCalendarSuggestionInput } from "@remit/data-ports";
+import type ICAL from "ical.js";
+import type { CalendarResult } from "./errors.js";
+/**
+ * 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 declare const mailAddressOf: (calAddress: string) => string;
+/** The iTIP method a VCALENDAR declared, `None` when it declared no METHOD. */
+export declare const inviteMethodOf: (component: ICAL.Component) => CalendarSuggestionItem["method"];
+/**
+ * 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" | "endsAtUtc" | "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 declare const projectSuggestion: (icalData: string, timezone: string) => Promise<CalendarResult<CalendarSuggestionProjection>>;
+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[];
+}
+/**
+ * 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.
+ *
+ * Every earlier revision already retired is pointed at this one too, so a
+ * card three revisions back opens the newest in one step rather than walking
+ * the chain a revision at a time.
+ */
+export declare const recordCalendarSuggestion: (repo: ICalendarSuggestionRepository, input: RecordCalendarSuggestionInput) => Promise<CalendarResult<RecordedCalendarSuggestion>>;

package/dist/suggest.js

@@ -0,0 +1,138 @@
+import { CalendarInviteMethod, CalendarSuggestionState, } from "@remit/domain-enums";
+import { expandCalendar } from "./expand.js";
+import { parseCalendar } from "./parse.js";
+import { projectCalendar, readString } from "./project.js";
+import { toUtcIso } from "./time.js";
+const OPEN_ENDED_SERIES = "9999-12-31T23:59:59Z";
+const EARLIEST_INSTANT = new Date(0).toISOString();
+const METHOD_BY_ICAL = {
+    REQUEST: CalendarInviteMethod.Request,
+    REPLY: CalendarInviteMethod.Reply,
+    CANCEL: CalendarInviteMethod.Cancel,
+    COUNTER: CalendarInviteMethod.Counter,
+    PUBLISH: CalendarInviteMethod.Publish,
+};
+/**
+ * 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) => calAddress.replace(/^mailto:/i, "");
+/** The iTIP method a VCALENDAR declared, `None` when it declared no METHOD. */
+export const inviteMethodOf = (component) => METHOD_BY_ICAL[readString(component, "method").toUpperCase()] ??
+    CalendarInviteMethod.None;
+const endsAtUtcOf = (calendar, timezone, dtEnd) => {
+    const expansion = expandCalendar(calendar, timezone);
+    if (expansion.expandedThrough !== "")
+        return OPEN_ENDED_SERIES;
+    const ends = expansion.occurrences.map((occurrence) => occurrence.endAt);
+    if (ends.length === 0)
+        return toUtcIso(Date.parse(dtEnd));
+    return ends.reduce((latest, end) => (end > latest ? end : latest));
+};
+/**
+ * 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, timezone) => {
+    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,
+            endsAtUtc: endsAtUtcOf(parsed.value, timezone, projection.value.dtEnd),
+            allDay: projection.value.allDay,
+            location: readString(parsed.value.master, "location"),
+            organizer: mailAddressOf(readString(parsed.value.master, "organizer")),
+            zoneCertainty: projection.value.zoneCertainty,
+        },
+    };
+};
+/**
+ * Every suggestion the account holds in one state. 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 listInState = async (repo, accountConfigId, state) => {
+    const items = [];
+    let continuationToken;
+    do {
+        const page = await repo.listByState(accountConfigId, state, {
+            endsAfter: EARLIEST_INSTANT,
+            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.
+ *
+ * Every earlier revision already retired is pointed at this one too, so a
+ * card three revisions back opens the newest in one step rather than walking
+ * the chain a revision at a time.
+ */
+export const recordCalendarSuggestion = async (repo, input) => {
+    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 olderRevision = (candidate) => candidate.icalUid === suggestion.icalUid &&
+        candidate.suggestionId !== suggestion.suggestionId &&
+        candidate.sequence < suggestion.sequence;
+    const stale = (await listInState(repo, input.accountConfigId, CalendarSuggestionState.Pending)).filter(olderRevision);
+    const superseded = [];
+    for (const candidate of stale) {
+        const retired = await repo.supersedeIfPending(input.accountConfigId, candidate.suggestionId, suggestion.messageId);
+        if (retired)
+            superseded.push(retired);
+    }
+    const retiredEarlier = (await listInState(repo, input.accountConfigId, CalendarSuggestionState.Superseded)).filter((candidate) => olderRevision(candidate) &&
+        candidate.supersededByMessageId !== suggestion.messageId);
+    for (const candidate of retiredEarlier) {
+        await repo.repointSuperseded(input.accountConfigId, candidate.suggestionId, suggestion.messageId);
+    }
+    return { ok: true, value: { suggestion, superseded } };
+};

package/dist/time.d.ts

@@ -0,0 +1,76 @@
+import type { CalendarObjectItem } from "@remit/data-ports";
+import ICAL from "ical.js";
+/**
+ * A resolved iCalendar time, in the two forms the store keeps.
+ *
+ * `isoUtc` is what a sort key holds: fixed width, so lexicographic order is
+ * chronological order. `isoOffset` is what a client displays: the event's own
+ * wall time with the offset it was written in, which `isoUtc` cannot express
+ * for an all-day event without turning a civil date into an instant.
+ *
+ * `certainty` says how much either of them is worth. A zone that could not be
+ * resolved still produces an instant — there is nothing else to produce — and
+ * without this marker that guess is indistinguishable from a fact.
+ */
+export interface ResolvedTime {
+    instantMs: number;
+    isoUtc: string;
+    isoOffset: string;
+    isDate: boolean;
+    certainty: CalendarObjectItem["zoneCertainty"];
+}
+export declare const toUtcIso: (instantMs: number) => string;
+/** Whether this platform can be asked about a zone by name. */
+export declare const isResolvableZone: (timeZone: string) => boolean;
+/**
+ * The wall-clock fields an instant reads as in a zone, with the offset that
+ * zone was at. The zone falls back to UTC when it is one this platform cannot
+ * name, which is the same fallback `resolveTime` takes.
+ */
+export declare const civilInZone: (instantMs: number, timeZone: string) => {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    offsetMinutes: number;
+};
+/**
+ * An instant as the wall time it reads as in a zone, carrying that zone's
+ * offset — the form a client renders.
+ *
+ * The store keeps occurrences as UTC instants because only a fixed-width form
+ * sorts correctly, and a client that was handed those would have to re-derive
+ * the event's own zone to draw it anywhere. This is the other direction, done
+ * once on the server: an occurrence of a 09:00 Amsterdam meeting comes back as
+ * `09:00+02:00` in summer and `09:00+01:00` in winter rather than as two
+ * different times of day.
+ */
+export declare const toOffsetIso: (instantMs: number, timeZone: string) => string;
+/**
+ * Resolves one iCalendar time to an instant and to its own wall-clock form.
+ *
+ * The zone is taken from the value itself when ical.js could bind one — a
+ * VTIMEZONE defined in this very resource, or UTC. A floating value, and a
+ * value whose TZID has no VTIMEZONE, falls back to `tzidHint` (the property's
+ * own TZID parameter) and then to the collection's timezone, so a resource
+ * written by a client that assumes the server knows the zone database still
+ * lands on the right instant.
+ *
+ * Which of those happened is reported, never swallowed: a named zone that no
+ * fallback could resolve comes back `Ambiguous`, so a caller can say the event
+ * may be hours out instead of drawing it in the wrong place in silence.
+ */
+export declare const resolveTime: (time: ICAL.Time, tzidHint: string, collectionTimezone: string) => ResolvedTime;
+/** The TZID a property was written with, or `""` when it names none. */
+export declare const tzidOf: (property: ICAL.Property | null) => string;
+/** The zone a component's DTSTART was written in. */
+export declare const dtStartTzid: (component: ICAL.Component) => string;
+/**
+ * The zone a component's end was written in. DTEND carries its own TZID and
+ * need not match DTSTART's, so an end read with the start's zone silently
+ * changes the event's length. Only a stated DTEND has a zone of its own: an end
+ * derived from a duration is already in the start's zone.
+ */
+export declare const dtEndTzid: (component: ICAL.Component) => string;