@rapidmx/web-client 0.21.0 → 0.22.0

package/lib/calendar/calendarMutations.ts

@@ -0,0 +1,236 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Higher-level calendar mutations shared by the event modal (edit/delete) and the grid views'
+ * drag-and-drop handlers (move/resize) — both need the exact same "this occurrence vs. the entire
+ * series" logic for a recurring event, so it lives here once rather than being duplicated.
+ *
+ * A recurring event has no per-occurrence record server-side — `@rapidmx/restapi` stores only the
+ * master `CalendarEvent` plus its `RecurrenceRule` (see `recurrence.ts`'s header comment). Changing
+ * (or deleting) a single occurrence is therefore always a two-part operation: add that occurrence's
+ * original start to the master's `recurrenceRule.exceptions` (so it stops being generated), and, for
+ * an edit (not a delete), separately create a new standalone `CalendarEvent` carrying the edited
+ * fields, with `recurrenceId` set to that original occurrence's start for traceability — mirroring
+ * how `CalendarEvent.recurrenceId` is documented to work.
+ */
+
+import {
+    CalendarEvent,
+    CalendarEventInput,
+    UpdateCalendarEventInput,
+    createCalendarEvent,
+    deleteCalendarEvent,
+    getCalendarEvent,
+    listCalendarEvents,
+    updateCalendarEvent,
+} from "./calendarApi.js";
+import { CalendarOccurrence, fromEventWallClock, toEventWallClock } from "./recurrence.js";
+import { ApiClient } from "../util/api.js";
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before,
+ * and threads the same `client` through to every `calendarApi.ts` call it makes internally. */
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+function positiveModulo(value: number, modulus: number): number {
+    return ((value % modulus) + modulus) % modulus;
+}
+
+function addException(event: CalendarEvent, occurrenceStart: string, client?: ApiClient): Promise<CalendarEvent> {
+    const rule = event.recurrenceRule!;
+    return updateCalendarEvent(
+        {
+            uid: event.uid,
+            version: event.version,
+            recurrenceRule: { ...rule, exceptions: [...rule.exceptions, occurrenceStart] },
+        },
+        client,
+    );
+}
+
+/** `saveEventSeries()`'s result: the saved master, plus whether its detached occurrences could be kept in
+ * step with a rescheduled series. */
+export type SeriesSaveResult = CalendarEvent & {
+    /** `true` when the series' start moved but at least one detached occurrence (a separate event sharing
+     * the master's `icalUid`, with a `recurrenceId`) couldn't be re-pointed at its occurrence's new start -
+     * that occurrence may then show up twice (the detached copy plus a regenerated one). The master itself
+     * was saved. Absent when nothing needed re-pointing or every update succeeded. */
+    detachedOccurrenceSyncFailed?: boolean;
+};
+
+/**
+ * Applies edited `fields` to every occurrence of a recurring event's series (the master record).
+ *
+ * `fields.startDate` must be the *master's* new start (web-client's `toSeriesFields()` computes it). When
+ * it moves the series (or changes its `timezone`/`allDay`), every occurrence moves by the same wall-clock
+ * delta, so everything that identifies an occurrence by its original start moves with it: the rule's
+ * `exceptions` (else a deleted occurrence reappears and a different one vanishes) and the `recurrenceId` of
+ * each detached occurrence in the master's folder (else the server-side reminder/iTIP logic, which matches
+ * overrides by `recurrenceId`, no longer pairs them). Detached occurrences keep their own edited times. The
+ * master is saved first; re-pointing detached occurrences is best-effort, reported through
+ * `detachedOccurrenceSyncFailed` rather than thrown. Series edits that don't move the start make one PUT.
+ */
+export async function saveEventSeries(
+    occurrence: CalendarOccurrence,
+    fields: Partial<CalendarEventInput>,
+    client?: ApiClient,
+): Promise<SeriesSaveResult> {
+    const update: UpdateCalendarEventInput = { uid: occurrence.uid, version: occurrence.version, ...fields };
+    // A shift can be needed even without an explicit startDate: changing timezone or allDay reinterprets the
+    // master's existing (unchanged) instant onto a different wall clock, exactly as the doc comment above
+    // promises - so all three fields, not just startDate, gate entry into the shift path below.
+    if (fields.startDate === undefined && fields.timezone === undefined && fields.allDay === undefined) {
+        return updateCalendarEvent(update, client);
+    }
+    const master = await getCalendarEvent(occurrence.uid, client);
+    const newTimezone = fields.timezone ?? master.timezone;
+    const newAllDay = fields.allDay ?? master.allDay;
+    const oldStartWall = toEventWallClock(Date.parse(master.startDate), master.timezone, master.allDay);
+    const newStartInstant = Date.parse(fields.startDate ?? master.startDate);
+    const deltaWallMs = toEventWallClock(newStartInstant, newTimezone, newAllDay) - oldStartWall;
+    if (deltaWallMs === 0 && newTimezone === master.timezone && newAllDay === master.allDay) {
+        return updateCalendarEvent(update, client);
+    }
+    // An occurrence is identified by its nominal wall-clock start (the rule's date + the master's time of day),
+    // not by the instant's own wall time: one that fell in a DST gap was pushed forward (02:30 -> 03:30 EDT),
+    // so shifting that pushed wall time would miss the occurrence the moved rule generates on that date.
+    const masterTimeOfDay = positiveModulo(oldStartWall, MS_PER_DAY);
+    const nominalWall = (instantMs: number): number => {
+        const wall = toEventWallClock(instantMs, master.timezone, master.allDay);
+        const dayStart = wall - positiveModulo(wall, MS_PER_DAY);
+        const candidates = [dayStart + masterTimeOfDay, dayStart - MS_PER_DAY + masterTimeOfDay];
+        // An instant the rule couldn't have generated (e.g. a hand-edited exception) shifts by its own wall time.
+        return candidates.find((candidate) => fromEventWallClock(candidate, master.timezone, master.allDay) === instantMs) ?? wall;
+    };
+    const shift = (instant: string) => new Date(fromEventWallClock(nominalWall(Date.parse(instant)) + deltaWallMs, newTimezone, newAllDay)).toISOString();
+
+    const rule = fields.recurrenceRule ?? master.recurrenceRule;
+    if (rule) {
+        update.recurrenceRule = { ...rule, exceptions: rule.exceptions.map(shift) };
+    }
+    const saved = await updateCalendarEvent(update, client);
+
+    let detachedOccurrenceSyncFailed = false;
+    try {
+        const detached = (await listCalendarEvents(master.folderUid, client)).filter(
+            (event) => event.icalUid === master.icalUid && event.uid !== master.uid && event.recurrenceId,
+        );
+        for (const event of detached) {
+            try {
+                // `recurrenceId` isn't part of `CalendarEventInput`, but restapi's update accepts it (the same
+                // way `detachOccurrence()` sends it on create).
+                await updateCalendarEvent(
+                    { uid: event.uid, version: event.version, recurrenceId: shift(event.recurrenceId!) } as UpdateCalendarEventInput,
+                    client,
+                );
+            } catch {
+                detachedOccurrenceSyncFailed = true;
+            }
+        }
+    } catch {
+        detachedOccurrenceSyncFailed = true;
+    }
+    return detachedOccurrenceSyncFailed ? { ...saved, detachedOccurrenceSyncFailed } : saved;
+}
+
+/**
+ * Applies edited `fields` to just this one occurrence of a recurring event, detaching it into its own
+ * standalone (non-recurring) event and excluding the original occurrence from the series.
+ *
+ * The detached event is created *first*, and only then is the original occurrence excluded from the
+ * master — so a failure part-way never makes the occurrence silently disappear. If adding the
+ * exception fails, the just-created detached event is deleted again (best-effort) and the original
+ * error is rethrown. The detached event keeps the master's `icalUid` and records the occurrence's
+ * original start as its `recurrenceId` (the RFC5545 way of identifying a modified instance), and never
+ * carries the series' `recurrenceRule` — even if `fields` includes one (e.g. the event modal's full
+ * field set).
+ */
+export async function detachOccurrence(
+    occurrence: CalendarOccurrence,
+    fields: Partial<CalendarEventInput>,
+    client?: ApiClient,
+): Promise<CalendarEvent> {
+    const originalStart = occurrence.recurrenceId!;
+    // `icalUid`/`recurrenceId` aren't part of `CalendarEventInput`, but `@rapidmx/restapi`'s
+    // `CalendarEvent` model accepts both on create (and `createCalendarEvent` already sends `icalUid`).
+    const input: CalendarEventInput & { icalUid: string; recurrenceId: string } = {
+        mailboxUid: occurrence.mailboxUid,
+        folderUid: occurrence.folderUid,
+        title: occurrence.title,
+        location: occurrence.location,
+        startDate: occurrence.startDate,
+        endDate: occurrence.endDate,
+        allDay: occurrence.allDay,
+        timezone: occurrence.timezone,
+        organizer: occurrence.organizer,
+        attendees: occurrence.attendees,
+        status: occurrence.status,
+        busyStatus: occurrence.busyStatus,
+        reminderMinutesBeforeStart: occurrence.reminderMinutesBeforeStart,
+        autoReplyEnabled: occurrence.autoReplyEnabled,
+        autoReplyMessage: occurrence.autoReplyMessage,
+        // A detached occurrence keeps what the series says about its description, visibility and guests (an absent value is the default).
+        description: occurrence.description ?? undefined,
+        descriptionHtml: occurrence.descriptionHtml ?? undefined,
+        visibility: occurrence.visibility ?? undefined,
+        guestsCanModify: occurrence.guestsCanModify ?? undefined,
+        guestsCanInviteOthers: occurrence.guestsCanInviteOthers ?? undefined,
+        guestsCanSeeGuestList: occurrence.guestsCanSeeGuestList ?? undefined,
+        ...fields,
+        recurrenceRule: undefined,
+        icalUid: occurrence.icalUid,
+        recurrenceId: originalStart,
+    };
+    const created = await createCalendarEvent(input, client);
+    try {
+        await addException(occurrence, originalStart, client);
+    } catch (err) {
+        await deleteCalendarEvent(created.uid, created.version, client).catch(() => undefined);
+        throw err;
+    }
+    return created;
+}
+
+/** Deletes an entire recurring series (or a genuinely non-recurring event) outright. */
+export function deleteEventSeries(occurrence: CalendarOccurrence, client?: ApiClient): Promise<void> {
+    return deleteCalendarEvent(occurrence.uid, occurrence.version, client);
+}
+
+/** Removes just this one occurrence from a recurring series, leaving the rest of the series intact. */
+export function deleteEventOccurrence(occurrence: CalendarOccurrence, client?: ApiClient): Promise<CalendarEvent> {
+    return addException(occurrence, occurrence.recurrenceId!, client);
+}
+
+/**
+ * Moves `occurrence` by `deltaMs` (drag-to-move on a grid), preserving its original duration. A
+ * recurring occurrence is always detached into its own standalone event — matching Outlook's own
+ * drag behavior, which never silently reschedules an entire series from a single dragged instance;
+ * moving the whole series is only ever done explicitly, via the event modal's "entire series" option.
+ */
+export function moveOccurrence(occurrence: CalendarOccurrence, deltaMs: number, client?: ApiClient): Promise<CalendarEvent> {
+    const fields = {
+        startDate: new Date(new Date(occurrence.startDate).getTime() + deltaMs).toISOString(),
+        endDate: new Date(new Date(occurrence.endDate).getTime() + deltaMs).toISOString(),
+    };
+    return occurrence.isRecurringOccurrence
+        ? detachOccurrence(occurrence, fields, client)
+        : updateCalendarEvent({ uid: occurrence.uid, version: occurrence.version, ...fields }, client);
+}
+
+/**
+ * Resizes `occurrence`'s end time (drag-to-resize on a week/day grid), keeping its start fixed and
+ * clamping to a 15-minute minimum duration so a resize can never invert start/end. Same
+ * always-detaches-a-recurring-occurrence reasoning as `moveOccurrence` above.
+ */
+export function resizeOccurrenceEnd(occurrence: CalendarOccurrence, newEndDate: Date, client?: ApiClient): Promise<CalendarEvent> {
+    const start = new Date(occurrence.startDate);
+    const minEnd = new Date(start.getTime() + 15 * 60_000);
+    const endDate = (newEndDate.getTime() > minEnd.getTime() ? newEndDate : minEnd).toISOString();
+    return occurrence.isRecurringOccurrence
+        ? detachOccurrence(occurrence, { endDate }, client)
+        : updateCalendarEvent({ uid: occurrence.uid, version: occurrence.version, endDate }, client);
+}

package/lib/calendar/eventDescription.ts

@@ -0,0 +1,211 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * An event's description as a client handles it. `@rapidmx/restapi` stores the rich text as HTML it has sanitized to a handful of tags
+ * (`b`/`strong`, `i`/`em`, `u`, `br`, `p`, `ul`/`ol`/`li`, and `a` with an `http`, `https` or `mailto` `href`), and a client must still never trust it: a
+ * description can also arrive in an invitation from anyone. So the HTML is never put in the page as it is. `parseEventDescription()` reads it into a small
+ * tree of only those elements - built from what the browser's own parser found, by copying text and one attribute across, so nothing else can survive - and
+ * everything a client shows or sends is made from that tree: `renderable` by React elements (no `dangerouslySetInnerHTML`), written back out as canonical
+ * HTML (`sanitizeEventDescriptionHtml()`) or as plain text (`htmlToPlainText()`, the same text the server derives).
+ *
+ * Reading needs a DOM (`DOMParser`); without one (server-side rendering) the tree is empty, never the input.
+ */
+
+/** The longest plain-text description the server takes, in characters (it allows a little more; this is the bound the dialog holds itself to). */
+export const MAX_EVENT_DESCRIPTION_LENGTH = 32_000;
+/** The longest description HTML the server takes, in characters. */
+export const MAX_EVENT_DESCRIPTION_HTML_LENGTH = 64_000;
+
+/** The elements a description may hold (`b`/`i` are kept as `strong`/`em`). */
+export type DescriptionTag = "strong" | "em" | "u" | "br" | "p" | "ul" | "ol" | "li" | "a";
+
+export type DescriptionNode = { text: string } | { tag: DescriptionTag; href?: string; children: DescriptionNode[] };
+
+const TAG_OF: Record<string, DescriptionTag> = {
+    b: "strong",
+    strong: "strong",
+    i: "em",
+    em: "em",
+    u: "u",
+    br: "br",
+    p: "p",
+    ul: "ul",
+    ol: "ol",
+    li: "li",
+    a: "a",
+};
+
+/** Elements that run or embed something: dropped with everything in them (any other element outside the list keeps its text but not its tags). */
+const DROPPED = new Set(["script", "style", "iframe", "frame", "frameset", "object", "embed", "applet", "svg", "math", "template", "noscript", "noembed", "noframes", "textarea", "select", "option", "title", "head", "xmp"]);
+
+/**
+ * `href` as a link a description may carry - an absolute `http`, `https` or `mailto` URL, in its canonical form - or `undefined` for anything else
+ * (`javascript:`, `data:`, a relative link, a URL with a control character in it). Whitespace and control characters are removed first, since a browser
+ * ignores them inside a scheme (`java\tscript:`).
+ */
+export function safeDescriptionHref(href: string | null | undefined): string | undefined {
+    const compact = (href ?? "").replace(/[\p{Cc}\s]+/gu, "");
+    let url: URL;
+    try {
+        url = new URL(compact);
+    } catch {
+        return undefined;
+    }
+    return ["http:", "https:", "mailto:"].includes(url.protocol) ? url.href : undefined;
+}
+
+function convert(node: Node): DescriptionNode[] {
+    if (node.nodeType === 3) {
+        return [{ text: node.textContent as string }];
+    }
+    if (node.nodeType !== 1) {
+        return [];
+    }
+    const element = node as Element;
+    const name = element.tagName.toLowerCase();
+    if (DROPPED.has(name)) {
+        return [];
+    }
+    const tag = TAG_OF[name];
+    if (tag === "br") {
+        return [{ tag, children: [] }];
+    }
+    const children = Array.from(element.childNodes).flatMap(convert);
+    if (!tag) {
+        return children;
+    }
+    if (tag === "a") {
+        const href = safeDescriptionHref(element.getAttribute("href"));
+        return href ? [{ tag, href, children }] : children;
+    }
+    if (tag === "p" && element.parentElement?.tagName.toLowerCase() === "li") {
+        // A list item written `<li><p>text</p></li>` (what a rich-text editor writes) is `<li>text</li>`: a paragraph inside an item would otherwise
+        // break the line after its bullet. A second paragraph in the same item stays on its own line.
+        return element.previousElementSibling ? [{ tag: "br", children: [] }, ...children] : children;
+    }
+    return [{ tag, children }];
+}
+
+/** The elements and text of `html` a description may hold, and nothing else. `[]` without a DOM. */
+export function parseEventDescription(html: string | null | undefined): DescriptionNode[] {
+    if (!html || typeof DOMParser === "undefined") {
+        return [];
+    }
+    const document = new DOMParser().parseFromString(html, "text/html");
+    return Array.from(document.body.childNodes).flatMap(convert);
+}
+
+function escapeText(text: string): string {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function escapeAttribute(text: string): string {
+    return escapeText(text).replace(/"/g, "&quot;");
+}
+
+function serialize(nodes: DescriptionNode[]): string {
+    return nodes
+        .map((node) => {
+            if ("text" in node) {
+                return escapeText(node.text);
+            }
+            if (node.tag === "br") {
+                return "<br>";
+            }
+            const open = node.tag === "a" ? `<a href="${escapeAttribute(node.href as string)}" rel="noopener noreferrer">` : `<${node.tag}>`;
+            return `${open}${serialize(node.children)}</${node.tag}>`;
+        })
+        .join("");
+}
+
+/** Nothing but white space: text of spaces, a line break, or a paragraph or line break holding only such (what an editor writes for an empty line). */
+function isBlank(node: DescriptionNode): boolean {
+    return "text" in node ? node.text.trim() === "" : (node.tag === "p" || node.tag === "br") && node.children.every(isBlank);
+}
+
+/**
+ * `html` reduced to what a description may hold, written as canonical HTML (a link with `rel="noopener noreferrer"`, text and attribute values escaped,
+ * every tag closed) and without the empty paragraphs an editor leaves before and after the text - a description with no text in it is `""`. Idempotent.
+ * This is what the dialog sends; the server sanitizes it again. `""` without a DOM.
+ */
+export function sanitizeEventDescriptionHtml(html: string | null | undefined): string {
+    const nodes = parseEventDescription(html);
+    let first = 0;
+    let last = nodes.length;
+    while (first < last && isBlank(nodes[first])) {
+        first++;
+    }
+    while (last > first && isBlank(nodes[last - 1])) {
+        last--;
+    }
+    return serialize(nodes.slice(first, last));
+}
+
+interface TextState {
+    text: string;
+    lists: { ordered: boolean; count: number }[];
+}
+
+function startLine(state: TextState): void {
+    if (state.text !== "" && !state.text.endsWith("\n")) {
+        state.text += "\n";
+    }
+}
+
+function writeText(nodes: DescriptionNode[], state: TextState): void {
+    for (const node of nodes) {
+        if ("text" in node) {
+            const collapsed = node.text.replace(/(?![\t\n\r])\p{Cc}/gu, "").replace(/[ \t\r\n]+/g, " ");
+            state.text += state.text === "" || state.text.endsWith("\n") ? collapsed.replace(/^ /, "") : collapsed;
+        } else if (node.tag === "br") {
+            state.text += "\n";
+        } else if (node.tag === "p") {
+            startLine(state);
+            writeText(node.children, state);
+            startLine(state);
+        } else if (node.tag === "ul" || node.tag === "ol") {
+            startLine(state);
+            state.lists.push({ ordered: node.tag === "ol", count: 0 });
+            writeText(node.children, state);
+            state.lists.pop();
+            startLine(state);
+        } else if (node.tag === "li") {
+            startLine(state);
+            const list = state.lists[state.lists.length - 1];
+            if (list?.ordered) {
+                list.count++;
+                state.text += `${list.count}. `;
+            } else {
+                state.text += "- ";
+            }
+            writeText(node.children, state);
+            startLine(state);
+        } else if (node.tag === "a") {
+            const start = state.text.length;
+            writeText(node.children, state);
+            const shown = state.text.slice(start).trim();
+            const href = node.href as string;
+            if (shown !== href && shown !== href.replace(/^mailto:/i, "")) {
+                state.text += ` (${href})`;
+            }
+        } else {
+            writeText(node.children, state);
+        }
+    }
+}
+
+/**
+ * The plain text of `html`, as the server derives it: a line break for each `<br>`, paragraph and list item (`- ` before a bulleted item, `1. ` before a
+ * numbered one), a link's URL in parentheses after its text when the text is not the URL already, every other tag dropped, whitespace collapsed and runs of
+ * blank lines shortened. `""` for a description with no text in it, and without a DOM.
+ */
+export function htmlToPlainText(html: string | null | undefined): string {
+    const state: TextState = { text: "", lists: [] };
+    writeText(parseEventDescription(html), state);
+    return state.text
+        .replace(/[ \t]+\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}

package/lib/calendar/freeBusyApi.ts

@@ -0,0 +1,197 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** The client of `@rapidmx/restapi`'s `POST /mail/calendar-events/free-busy` - when other people are busy, for an event dialog's "Find a time" - and the
+ * small pure helpers that turn its answer into what a grid and a list of suggested times need.
+ *
+ * What the server tells about a person is only ever when they are busy, never why: no title, place, guest or id. And for some people it tells nothing at
+ * all, which is not the same as telling they are free: `"unknown"` is a person the server has no calendar for (an external address, or a calendar too big
+ * to read) and `"restricted"` is one who chose not to share their free/busy with the caller (`Mailbox.freeBusyVisibility`). Every helper here treats both
+ * as *not known to be free* - they are never counted as available, and never make a time "free for everyone". */
+
+import { ApiClient, withClient } from "../util/api.js";
+
+/** The most addresses one request may ask about. */
+export const FREE_BUSY_MAX_ADDRESSES = 50;
+/** The longest window one request may ask about, in days. */
+export const FREE_BUSY_MAX_DAYS = 31;
+
+/** `"available"`: the server read the person's calendar (`busy` is what it found). `"unknown"`: it has no information. `"restricted"`: they hide it from you. */
+export type FreeBusyStatus = "available" | "unknown" | "restricted";
+
+/** One stretch of busy time, as the server sends it (UTC ISO 8601, sorted, merged and clipped to the window). */
+export interface FreeBusyWindow {
+    start: string;
+    end: string;
+    /** Only tentatively busy (a tentative event, or an invitation not yet answered firmly). */
+    tentative: boolean;
+}
+
+export interface FreeBusyResult {
+    address: string;
+    status: FreeBusyStatus;
+    /** Empty unless `status` is `"available"`. */
+    busy: FreeBusyWindow[];
+}
+
+export interface FreeBusyResponse {
+    start: string;
+    end: string;
+    /** One result per address asked, in the order asked. */
+    results: FreeBusyResult[];
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+/**
+ * When the people at `addresses` (1 to `FREE_BUSY_MAX_ADDRESSES`) are busy between `start` and `end` (at most `FREE_BUSY_MAX_DAYS` days). The caller's own
+ * mailboxes are always answered as available with their real busy time. Rejects with an `ApiRequestError`: 400 for a bad request, 401 when signed out,
+ * 429 when asked too often (60 a minute).
+ */
+export function getFreeBusy(addresses: string[], start: Date | string, end: Date | string, client?: ApiClient): Promise<FreeBusyResponse> {
+    return withClient(client, "/mail/calendar-events/free-busy", {
+        method: "POST",
+        body: JSON.stringify({
+            addresses,
+            start: typeof start === "string" ? start : start.toISOString(),
+            end: typeof end === "string" ? end : end.toISOString(),
+        }),
+    });
+}
+
+/** A stretch of busy time as milliseconds since the epoch. */
+export interface BusyBlock {
+    startMs: number;
+    endMs: number;
+    tentative: boolean;
+}
+
+/** What is known about one person's time. */
+export interface PersonAvailability {
+    address: string;
+    status: FreeBusyStatus;
+    busy: BusyBlock[];
+}
+
+/** What a person's calendar says about a stretch of time. `"unknown"` is any person the server did not (or would not) tell about - never free. */
+export type AvailabilityState = "free" | "tentative" | "busy" | "unknown";
+
+/** The response's results with their times as milliseconds (a person who isn't `"available"` has no blocks whatever the server sent). */
+export function availabilityOf(response: FreeBusyResponse): PersonAvailability[] {
+    return response.results.map((result) => ({
+        address: result.address,
+        status: result.status,
+        busy:
+            result.status === "available"
+                ? result.busy.map((window) => ({ startMs: Date.parse(window.start), endMs: Date.parse(window.end), tentative: window.tentative }))
+                : [],
+    }));
+}
+
+/** Whether a block overlaps the stretch from `startMs` to `endMs` (touching ends do not overlap). */
+function overlaps(block: BusyBlock, startMs: number, endMs: number): boolean {
+    return block.startMs < endMs && block.endMs > startMs;
+}
+
+/** What `person` is between `startMs` and `endMs`: `"busy"` when a firm block overlaps, else `"tentative"` when a tentative one does, else `"free"` - and
+ * `"unknown"`, whatever the blocks, for a person who isn't `"available"`. */
+export function availabilityDuring(person: PersonAvailability, startMs: number, endMs: number): AvailabilityState {
+    if (person.status !== "available") {
+        return "unknown";
+    }
+    const overlapping = person.busy.filter((block) => overlaps(block, startMs, endMs));
+    if (overlapping.some((block) => !block.tentative)) {
+        return "busy";
+    }
+    return overlapping.length > 0 ? "tentative" : "free";
+}
+
+/** How a stretch of time stands for a group. */
+export interface AvailabilitySummary {
+    /** People known to be busy for some of it (firm or tentative). */
+    conflicts: number;
+    /** Of those, the ones only tentatively busy. */
+    tentative: number;
+    /** People nothing is known about (external, too big, or hiding their calendar): not counted as free, not counted as conflicts. */
+    unknown: number;
+    /** People known to be free for all of it. */
+    free: number;
+}
+
+export function summarizeAvailability(people: PersonAvailability[], startMs: number, endMs: number): AvailabilitySummary {
+    const summary: AvailabilitySummary = { conflicts: 0, tentative: 0, unknown: 0, free: 0 };
+    for (const person of people) {
+        const state = availabilityDuring(person, startMs, endMs);
+        if (state === "unknown") {
+            summary.unknown++;
+        } else if (state === "free") {
+            summary.free++;
+        } else {
+            summary.conflicts++;
+            if (state === "tentative") {
+                summary.tentative++;
+            }
+        }
+    }
+    return summary;
+}
+
+/**
+ * `people` without the blocks that are exactly the stretch from `startMs` to `endMs`, for the addresses in `addresses` (lower case): what an event that is
+ * being rescheduled takes up on the calendars of the people already invited to it - which would otherwise show as everyone's conflict with itself. Only an
+ * exact match goes, so a block that the server merged with a neighbouring or overlapping event stays (a conflict shown, never one hidden).
+ */
+export function withoutOwnBlock(people: PersonAvailability[], addresses: Set<string>, startMs: number, endMs: number): PersonAvailability[] {
+    return people.map((person) =>
+        addresses.has(person.address.toLowerCase())
+            ? { ...person, busy: person.busy.filter((block) => block.startMs !== startMs || block.endMs !== endMs) }
+            : person,
+    );
+}
+
+export interface SuggestTimesOptions {
+    /** The stretches a meeting may fall in (e.g. each day's 8:00 to 18:00), in any order. A slot lies wholly inside one. */
+    windows: { startMs: number; endMs: number }[];
+    /** How long the meeting is. */
+    durationMs: number;
+    /** How far apart slots start, from a window's start (default 30 minutes). */
+    stepMs?: number;
+    /** How many to find (default 5). */
+    limit?: number;
+    /** No slot starts before this (e.g. now). */
+    notBeforeMs?: number;
+}
+
+const DEFAULT_STEP_MS = 30 * 60_000;
+const DEFAULT_SUGGESTIONS = 5;
+
+/**
+ * The start times (ms) of the first `limit` slots of `durationMs` inside `windows` where everyone known is free - no firm or tentative block overlaps it.
+ * People who are `"unknown"` or `"restricted"` cannot be checked and so do not constrain the answer (a caller says so next to the suggestions); with nobody
+ * known at all there is nothing to base a suggestion on and the answer is empty.
+ */
+export function suggestTimes(people: PersonAvailability[], options: SuggestTimesOptions): number[] {
+    const known = people.filter((person) => person.status === "available");
+    if (known.length === 0 || options.durationMs <= 0) {
+        return [];
+    }
+    const step = options.stepMs ?? DEFAULT_STEP_MS;
+    const limit = options.limit ?? DEFAULT_SUGGESTIONS;
+    const found: number[] = [];
+    for (const window of [...options.windows].sort((a, b) => a.startMs - b.startMs)) {
+        for (let start = window.startMs; start + options.durationMs <= window.endMs; start += step) {
+            if (start < (options.notBeforeMs ?? Number.NEGATIVE_INFINITY)) {
+                continue;
+            }
+            if (known.every((person) => availabilityDuring(person, start, start + options.durationMs) === "free")) {
+                found.push(start);
+                if (found.length >= limit) {
+                    return found;
+                }
+            }
+        }
+    }
+    return found;
+}