@rapidmx/web-client 0.20.0 → 0.22.0

package/dist/lib/calendar/eventDescription.js

@@ -0,0 +1,195 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 = 32000;
+/** The longest description HTML the server takes, in characters. */
+export const MAX_EVENT_DESCRIPTION_HTML_LENGTH = 64000;
+const TAG_OF = {
+    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) {
+    const compact = (href ?? "").replace(/[\p{Cc}\s]+/gu, "");
+    let url;
+    try {
+        url = new URL(compact);
+    }
+    catch {
+        return undefined;
+    }
+    return ["http:", "https:", "mailto:"].includes(url.protocol) ? url.href : undefined;
+}
+function convert(node) {
+    if (node.nodeType === 3) {
+        return [{ text: node.textContent }];
+    }
+    if (node.nodeType !== 1) {
+        return [];
+    }
+    const element = node;
+    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) {
+    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) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttribute(text) {
+    return escapeText(text).replace(/"/g, "&quot;");
+}
+function serialize(nodes) {
+    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)}" 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) {
+    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) {
+    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));
+}
+function startLine(state) {
+    if (state.text !== "" && !state.text.endsWith("\n")) {
+        state.text += "\n";
+    }
+}
+function writeText(nodes, state) {
+    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;
+            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) {
+    const state = { text: "", lists: [] };
+    writeText(parseEventDescription(html), state);
+    return state.text
+        .replace(/[ \t]+\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}

package/dist/lib/calendar/freeBusyApi.d.ts

@@ -0,0 +1,100 @@
+/** 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 } from "../util/api.js";
+/** The most addresses one request may ask about. */
+export declare const FREE_BUSY_MAX_ADDRESSES = 50;
+/** The longest window one request may ask about, in days. */
+export declare 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 declare function getFreeBusy(addresses: string[], start: Date | string, end: Date | string, client?: ApiClient): Promise<FreeBusyResponse>;
+/** 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 declare function availabilityOf(response: FreeBusyResponse): PersonAvailability[];
+/** 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 declare function availabilityDuring(person: PersonAvailability, startMs: number, endMs: number): AvailabilityState;
+/** 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 declare function summarizeAvailability(people: PersonAvailability[], startMs: number, endMs: number): AvailabilitySummary;
+/**
+ * `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 declare function withoutOwnBlock(people: PersonAvailability[], addresses: Set<string>, startMs: number, endMs: number): PersonAvailability[];
+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;
+}
+/**
+ * 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 declare function suggestTimes(people: PersonAvailability[], options: SuggestTimesOptions): number[];

package/dist/lib/calendar/freeBusyApi.js

@@ -0,0 +1,119 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { 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;
+/** `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, start, end, client) {
+    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(),
+        }),
+    });
+}
+/** 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) {
+    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, startMs, endMs) {
+    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, startMs, endMs) {
+    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";
+}
+export function summarizeAvailability(people, startMs, endMs) {
+    const summary = { 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, addresses, startMs, endMs) {
+    return people.map((person) => addresses.has(person.address.toLowerCase())
+        ? { ...person, busy: person.busy.filter((block) => block.startMs !== startMs || block.endMs !== endMs) }
+        : person);
+}
+const DEFAULT_STEP_MS = 30 * 60000;
+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, options) {
+    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 = [];
+    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;
+}

package/dist/lib/calendar/inviteApi.d.ts

@@ -0,0 +1,121 @@
+/** Typed wrappers over `@rapidmx/restapi`'s `/mail/calendar-events/invite` surface - the calendar invitation (iMIP: an
+ * `.ics` attachment carrying an iTIP `METHOD`) a mail message may hold, read for the reading pane's invitation card. The
+ * server does all the work of an answer: it puts the meeting on the reader's calendar (or takes it off), and sends the
+ * iTIP REPLY to the organizer. The client only reads the state and asks for a change; every call returns the invitation as
+ * it now stands, ready to draw. */
+import { ApiClient } from "../util/api.js";
+import type { EventVisibility, GuestPermissions } from "./calendarApi.js";
+/** What the reader can answer an invitation with. */
+export type InviteResponse = "accepted" | "tentative" | "declined";
+export interface InviteParticipant {
+    address: string;
+    displayName?: string;
+    responseStatus?: "accepted" | "tentative" | "declined" | "needs-action";
+}
+/** One of the reader's own events near an invitation, as the server lists it for the RSVP day view and its conflict check. */
+export interface InviteScheduleEntry {
+    uid: string;
+    title: string;
+    /** ISO 8601 instants. */
+    startDate: string;
+    endDate: string;
+    allDay: boolean;
+    /** The event blocks the reader's time (it is not marked free). */
+    busy: boolean;
+    tentative: boolean;
+}
+/** The calendar invitation a message carries, together with what the reader's own calendar says about it. */
+export interface MessageInvite {
+    /** The iTIP `METHOD` as sent: `"REQUEST"`, `"CANCEL"`, `"REPLY"`, `"PUBLISH"` or `"COUNTER"`, or `""` when the file names none. */
+    method: string;
+    /** The iCalendar `UID`. */
+    uid: string;
+    sequence: number;
+    summary?: string;
+    location?: string;
+    /** ISO 8601 instant. */
+    startDate?: string;
+    endDate?: string;
+    allDay: boolean;
+    /** The IANA zone the organizer used. */
+    timezone?: string;
+    organizer?: {
+        address: string;
+        displayName?: string;
+    };
+    attendees: InviteParticipant[];
+    recurring: boolean;
+    /** The reader's mailbox is the organizer. */
+    isOrganizer: boolean;
+    /** What the reader answered, if anything. */
+    response?: InviteResponse;
+    /** An event for it is on the reader's calendar now. */
+    onCalendar: boolean;
+    /** That event's uid (for a link into the calendar). */
+    calendarEventUid?: string;
+    /** The calendar already holds a newer revision than this message. */
+    outdated: boolean;
+    /** A `REQUEST` addressed to the reader: offer Accept / Tentative / Decline. */
+    canRespond: boolean;
+    /** A `PUBLISH`, or no method at all: offer "Add to calendar". */
+    canAdd: boolean;
+    /** A `CANCEL` whose meeting is on the calendar: offer "Remove from calendar". */
+    canRemove: boolean;
+    /** A `REQUEST` the reader can answer with a different time: offer "Propose new time". */
+    canPropose: boolean;
+    /** A `COUNTER` for a meeting the reader organizes: offer "Accept proposal". */
+    canAcceptProposal: boolean;
+    /** For a `REPLY` or `COUNTER`: the attendee who sent it and what they answered or proposed. For a `COUNTER`,
+     * `startDate`/`endDate` are the proposed time. */
+    reply?: InviteParticipant;
+    /** The reader's busy events that overlap the invitation's time. */
+    conflicts: InviteScheduleEntry[];
+    /** The reader's other events from 12 hours before the invitation's start to 12 hours after its end (recurrences
+     * expanded, this meeting left out) - what the RSVP day view draws around the invitation. */
+    schedule: InviteScheduleEntry[];
+    /** The description as plain text, if the organizer wrote one. */
+    description?: string;
+    /** The description as HTML the server sanitized - still rendered through `sanitizeEventDescriptionHtml()`, never trusted as it stands. */
+    descriptionHtml?: string;
+    /** Who may see the event's details, as the organizer sent it. */
+    visibility?: EventVisibility;
+    /** What the organizer allows the guests to do. Every field is present when the server says any (all optional here so an older server, which says none, reads
+     * as the defaults - see `guestPermissionsOf()`). */
+    guestPermissions?: Partial<GuestPermissions>;
+    /** A guest's copy that allows a change of the title, location, description or time: offer "Request a change" (`requestEventChange()` on `calendarEventUid`). */
+    canRequestChange?: boolean;
+    /** A guest's copy that allows adding guests: offer "Add guests" (`requestEventChange()` with `addAttendees` on `calendarEventUid`). */
+    canRequestInvite?: boolean;
+    /** On a `COUNTER` that is a guest's change request (rather than a proposed time) received by the organizer: whether it was applied automatically. */
+    changeRequest?: {
+        applied: boolean;
+    };
+}
+/** `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. */
+/**
+ * Reads the invitation a message carries. Resolves `null` when the message has none the server can read (a `404`) - the
+ * common, expected answer for a message that merely has an attachment - and rejects for any other failure.
+ */
+export declare function getMessageInvite(messageUid: string, client?: ApiClient): Promise<MessageInvite | null>;
+/**
+ * Answers an invitation. The server puts the meeting on the reader's calendar for `"accepted"`/`"tentative"` (or takes it
+ * off for `"declined"`) and sends the organizer the matching iTIP REPLY; for a `PUBLISH`ed event (which has no organizer to
+ * answer) `"accepted"` only adds it to the calendar. Resolves with the invitation as it now stands.
+ */
+export declare function respondToMessageInvite(messageUid: string, responseStatus: InviteResponse, client?: ApiClient): Promise<MessageInvite>;
+/** Takes a canceled meeting off the reader's calendar. Resolves with the invitation as it now stands. */
+export declare function removeMessageInvite(messageUid: string, client?: ApiClient): Promise<MessageInvite>;
+/** A different time to suggest to the organizer. */
+export interface ProposedTime {
+    /** ISO 8601 instants. */
+    startDate: string;
+    endDate: string;
+    /** A note to the organizer, sent with the proposal. */
+    comment?: string;
+}
+/** Proposes a different time to the organizer of a `REQUEST` (an iTIP `COUNTER` sent by the server). Resolves with the invitation as it now stands. */
+export declare function proposeNewTime(messageUid: string, proposal: ProposedTime, client?: ApiClient): Promise<MessageInvite>;
+/** Accepts an attendee's proposed time (a `COUNTER`) for a meeting the reader organizes: the server moves the event and sends the attendees the update. Resolves with the invitation as it now stands. */
+export declare function acceptProposal(messageUid: string, client?: ApiClient): Promise<MessageInvite>;

package/dist/lib/calendar/inviteApi.js

@@ -0,0 +1,54 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Typed wrappers over `@rapidmx/restapi`'s `/mail/calendar-events/invite` surface - the calendar invitation (iMIP: an
+ * `.ics` attachment carrying an iTIP `METHOD`) a mail message may hold, read for the reading pane's invitation card. The
+ * server does all the work of an answer: it puts the meeting on the reader's calendar (or takes it off), and sends the
+ * iTIP REPLY to the organizer. The client only reads the state and asks for a change; every call returns the invitation as
+ * it now stands, ready to draw. */
+import { ApiRequestError, withClient } 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. */
+/**
+ * Reads the invitation a message carries. Resolves `null` when the message has none the server can read (a `404`) - the
+ * common, expected answer for a message that merely has an attachment - and rejects for any other failure.
+ */
+export async function getMessageInvite(messageUid, client) {
+    try {
+        return await withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}`);
+    }
+    catch (err) {
+        if (err instanceof ApiRequestError && err.status === 404) {
+            return null;
+        }
+        throw err;
+    }
+}
+/**
+ * Answers an invitation. The server puts the meeting on the reader's calendar for `"accepted"`/`"tentative"` (or takes it
+ * off for `"declined"`) and sends the organizer the matching iTIP REPLY; for a `PUBLISH`ed event (which has no organizer to
+ * answer) `"accepted"` only adds it to the calendar. Resolves with the invitation as it now stands.
+ */
+export function respondToMessageInvite(messageUid, responseStatus, client) {
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/respond`, {
+        method: "POST",
+        body: JSON.stringify({ responseStatus }),
+    });
+}
+/** Takes a canceled meeting off the reader's calendar. Resolves with the invitation as it now stands. */
+export function removeMessageInvite(messageUid, client) {
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/remove`, { method: "POST" });
+}
+/** Proposes a different time to the organizer of a `REQUEST` (an iTIP `COUNTER` sent by the server). Resolves with the invitation as it now stands. */
+export function proposeNewTime(messageUid, proposal, client) {
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/propose`, {
+        method: "POST",
+        body: JSON.stringify(proposal),
+    });
+}
+/** Accepts an attendee's proposed time (a `COUNTER`) for a meeting the reader organizes: the server moves the event and sends the attendees the update. Resolves with the invitation as it now stands. */
+export function acceptProposal(messageUid, client) {
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/accept-proposal`, { method: "POST" });
+}

package/dist/lib/calendar/recurrence.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RFC5545 recurrence expansion, entirely client-side — `@rapidmx/restapi` stores/returns
+ * `RecurrenceRule` as-is and does no expansion of its own (see `calendarApi.ts`'s own header
+ * comment). Built on the `rrule` package.
+ */
+import * as RRuleNS from "rrule";
+import { CalendarEvent, RecurrenceRule, WeekdayCode } from "./calendarApi.js";
+/** Extracted so the CJS-interop fallback branch can be exercised directly with a plain object,
+ * without needing to fight a module mock into reproducing Node's exact interop shape. */
+export declare function resolveRRuleExport(ns: typeof RRuleNS): typeof RRuleNS.RRule;
+/**
+ * Builds an `RRule` instance from this app's `RecurrenceRule` shape, anchored at `dtstart`. Pass the
+ * event's IANA `tzid` so the rule carries it (e.g. `DTSTART;TZID=America/New_York:...` from
+ * `.toString()`) — note that, per `rrule`'s own convention, a rule with a non-UTC `tzid` expects
+ * `dtstart` to be a "floating" wall-clock time expressed as a UTC `Date` and rezones its generated
+ * dates using the *runtime's* local zone, which is why `expandOccurrences()` below does its own
+ * timezone conversion instead of relying on this.
+ */
+export declare function buildRRule(rule: RecurrenceRule, dtstart: Date, tzid?: string): RRuleNS.RRule;
+/** A single expanded occurrence of a (possibly recurring) `CalendarEvent`, ready to render on a grid. */
+export interface CalendarOccurrence extends CalendarEvent {
+    /** A key unique per occurrence (`${event.uid}::${occurrence start}`) — use this for React `key`s and
+     * drag-and-drop ids, since a recurring event's `uid` alone isn't unique across its occurrences. */
+    occurrenceKey: string;
+    /** `true` for a generated occurrence of a recurring event (as opposed to the stored master record, or
+     * a genuinely non-recurring event) — moving/resizing one calls `updateCalendarEvent` differently (see
+     * the calendar page's own drag handlers) since it must detach into its own standalone event. */
+    isRecurringOccurrence: boolean;
+}
+/**
+ * Converts an instant to the "wall-clock as UTC" milliseconds recurrence expansion works in for an event
+ * with this `timezone`/`allDay` - UTC for an all-day event (stored as UTC-midnight dates), the event's IANA
+ * zone otherwise (the runtime's local zone when empty or unrecognized). Exported for `calendarMutations.ts`,
+ * which shifts a series' exception dates by the same wall-clock delta as its start.
+ */
+export declare function toEventWallClock(instantMs: number, timezone: string | undefined, allDay: boolean | undefined): number;
+/** Inverse of `toEventWallClock()` (DST gaps/overlaps resolved per RFC 5545 - see `ianaZone()`). */
+export declare function fromEventWallClock(wallMs: number, timezone: string | undefined, allDay: boolean | undefined): number;
+/**
+ * Expands `event` into every occurrence whose interval overlaps `[rangeStart, rangeEnd]`. A
+ * non-recurring event yields itself (in a one-element array) if it overlaps, or `[]` otherwise —
+ * callers don't need to special-case recurring vs. not.
+ *
+ * Recurrence is expanded in the event's own `timezone` (an IANA zone id; an empty or unrecognized
+ * value falls back to the runtime's local zone, i.e. floating time), so every occurrence keeps the
+ * master's local wall-clock start/end time and local weekday — a weekly Monday 23:00
+ * America/New_York event stays on Monday 23:00 New York time across DST changes, rather than being
+ * expanded on the UTC weekday/time of its first instance. An all-day event is the exception: its dates are
+ * UTC-midnight date-only values, so it expands in UTC regardless of `timezone` - expanding a
+ * `2026-09-14T00:00Z` Monday in America/New_York would otherwise see a Sunday-evening start and put every
+ * occurrence on the wrong date. A timed occurrence that falls in a DST gap starts at the pre-transition
+ * offset (RFC 5545) and keeps its wall-clock duration.
+ */
+export declare function expandOccurrences(event: CalendarEvent, rangeStart: Date, rangeEnd: Date): CalendarOccurrence[];
+/** Expands every event in `events` and flattens the result — the usual entry point for a grid view. */
+export declare function expandAllOccurrences(events: CalendarEvent[], rangeStart: Date, rangeEnd: Date): CalendarOccurrence[];
+/** A human-readable summary of `rule` (e.g. "every 2 weeks on Monday, Wednesday until Jan 1, 2027"). */
+export declare function describeRecurrence(rule: RecurrenceRule): string;
+export declare const WEEKDAY_CODES: WeekdayCode[];
+export declare const WEEKDAY_LABELS: Record<WeekdayCode, string>;