@rapidmx/web-client 0.21.0 → 0.23.0

package/dist/lib/calendar/calendarApi.js

@@ -0,0 +1,106 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Typed wrappers over `@rapidmx/restapi`'s `/mail/calendar-events` REST surface — see `mailApi.ts`'s own
+ * header comment for the shared ACL/authorization model every wrapper file here follows. Recurrence
+ * expansion happens entirely client-side (see `apps/shared/lib/recurrence.ts`) — the backend stores/returns
+ * `RecurrenceRule` as-is and does no RFC5545 expansion of its own. */
+import { withClient } from "../util/api.js";
+import { buildQuery } from "../util/apiQuery.js";
+/** The guest permissions an event has when none were chosen (Google Calendar's own defaults). */
+export const DEFAULT_GUEST_PERMISSIONS = { guestsCanModify: false, guestsCanInviteOthers: true, guestsCanSeeGuestList: true };
+/** The guest permissions `source` says, a missing (or `null`) flag reading as its default - an event stored before they existed carries none. */
+export function guestPermissionsOf(source) {
+    return {
+        guestsCanModify: source.guestsCanModify ?? DEFAULT_GUEST_PERMISSIONS.guestsCanModify,
+        guestsCanInviteOthers: source.guestsCanInviteOthers ?? DEFAULT_GUEST_PERMISSIONS.guestsCanInviteOthers,
+        guestsCanSeeGuestList: source.guestsCanSeeGuestList ?? DEFAULT_GUEST_PERMISSIONS.guestsCanSeeGuestList,
+    };
+}
+/** The visibility an event has, `"default"` when it says none. */
+export function visibilityOf(event) {
+    return event.visibility ?? "default";
+}
+const LIST_PAGE_SIZE = 500;
+const LIST_CALENDAR_EVENTS_MAX_PAGES = 100;
+/**
+ * Lists every event in a folder (same "fetch the flat list, filter client-side" contract as
+ * `contactsApi.ts`'s `listContacts`/`tasksApi.ts`'s `listTasks`), for the caller to expand and filter
+ * to a visible range itself (see `recurrence.ts`'s `expandAllOccurrences`). This deliberately does
+ * *not* push `startDate`/`endDate` range filtering down to the server via `@rapidmx/restapi`'s
+ * `field=lte(v)`/`gte(v)` query-operator DSL — confirmed directly against a running instance that
+ * `CalendarEventMongo`'s `startDate`/`endDate` are persisted as plain strings despite being typed
+ * `Date`, so a Mongo `$lte`/`$gte` comparison against them (a real `Date` operand) matches nothing at
+ * all, silently returning zero events for *any* date-bounded query. Client-side filtering sidesteps
+ * that entirely and needs no fix to land here.
+ *
+ * Pages through the whole folder (`limit=500`, the server's own page-size cap) until a short page comes
+ * back, so a calendar with more than one page of events isn't silently truncated. A hard cap of
+ * `LIST_CALENDAR_EVENTS_MAX_PAGES` pages guards against looping forever should a server ever ignore
+ * `page` and keep returning full pages.
+ */
+export async function listCalendarEvents(folderUid, client) {
+    const events = [];
+    for (let page = 0; page < LIST_CALENDAR_EVENTS_MAX_PAGES; page++) {
+        const batch = await withClient(client, `/mail/calendar-events?${buildQuery({ limit: LIST_PAGE_SIZE, page }, { folderUid })}`);
+        events.push(...batch);
+        if (batch.length < LIST_PAGE_SIZE) {
+            break;
+        }
+    }
+    return events;
+}
+export function getCalendarEvent(uid, client) {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(uid)}`);
+}
+export function createCalendarEvent(input, client) {
+    return withClient(client, "/mail/calendar-events", {
+        method: "POST",
+        body: JSON.stringify({
+            allDay: false,
+            attendees: [],
+            status: "confirmed",
+            busyStatus: "busy",
+            icalUid: crypto.randomUUID(),
+            sequence: 0,
+            ...input,
+        }),
+    });
+}
+export function updateCalendarEvent(input, client) {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+export function deleteCalendarEvent(uid, version, client) {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}
+/**
+ * Responds to a meeting invite as the calling mailbox's own attendee entry. Synchronous — unlike
+ * `recallMessage()` in `mailApi.ts`, this immediately mutates and persists the response (the iTIP
+ * REPLY email send is best-effort server-side and never affects this call's outcome). On
+ * `"accepted"`/`"tentative"` the whole updated `CalendarEvent` comes back, with only the calling
+ * attendee's own `responseStatus` changed. On `"declined"`, the backend instead soft-deletes the
+ * mailbox's own copy of the event and returns only `{ uid }` — the caller should treat a decline the
+ * same as a delete rather than expecting an updated event back.
+ */
+export function respondToEvent(uid, responseStatus, client) {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(uid)}/respond`, {
+        method: "POST",
+        body: JSON.stringify({ responseStatus }),
+    });
+}
+/**
+ * Asks the organizer to change an event, as a guest (not the organizer) whose copy allows it: the title, location, description or time need
+ * `guestsCanModify`, added guests need `guestsCanInviteOthers` (403 otherwise; 400 when nothing differs from what the event has, or a value is invalid).
+ * Nothing changes on this mailbox's own copy - the request is mailed to the organizer, and when the change is allowed it is applied there and
+ * arrives back later as an ordinary update of the invitation.
+ */
+export function requestEventChange(uid, request, client) {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(uid)}/request-change`, {
+        method: "POST",
+        body: JSON.stringify(request),
+    });
+}

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

@@ -0,0 +1,18 @@
+/** A fixed client-side color palette for calendars, matching the plan's "no new `Category`-style
+ * backend entity" approach already used for Contacts' categories: `Folder.color` just stores one of
+ * these hex values (or, in principle, any string — an unrecognized one still works fine as a raw CSS
+ * color), the palette itself never needs to round-trip through the backend. */
+import { Folder } from "../mail/mailApi.js";
+export declare const CALENDAR_COLOR_PALETTE: string[];
+/** The color a mailbox's original auto-provisioned calendar effectively had before this field
+ * existed — kept as the fallback so every pre-existing calendar keeps looking the same. */
+export declare const DEFAULT_CALENDAR_COLOR: string;
+/** `fallback` replaces `DEFAULT_CALENDAR_COLOR` for a folder with no color of its own - e.g. a shared
+ * mailbox's calendar falling back to that mailbox's `accentColorForMailbox()`, so it doesn't render in
+ * the same default blue as the caller's own calendar. An explicit `Folder.color` always wins. */
+export declare function colorForFolder(folder: Pick<Folder, "color">, fallback?: string): string;
+/** A stable per-mailbox color for grouping one mailbox's calendars together (sidebar section accent, and
+ * the fallback color for its uncolored calendars). Deterministic hash of `mailboxUid` into the palette
+ * minus `DEFAULT_CALENDAR_COLOR`, so another mailbox never collides with the default a caller's own
+ * calendar already uses. Client-side only - nothing is persisted. */
+export declare function accentColorForMailbox(mailboxUid: string): string;

package/dist/lib/calendar/calendarColors.js

@@ -0,0 +1,39 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** A fixed client-side color palette for calendars, matching the plan's "no new `Category`-style
+ * backend entity" approach already used for Contacts' categories: `Folder.color` just stores one of
+ * these hex values (or, in principle, any string — an unrecognized one still works fine as a raw CSS
+ * color), the palette itself never needs to round-trip through the backend. */
+export const CALENDAR_COLOR_PALETTE = [
+    "#2563eb", // blue
+    "#7c3aed", // violet
+    "#db2777", // pink
+    "#dc2626", // red
+    "#ea580c", // orange
+    "#ca8a04", // amber
+    "#16a34a", // green
+    "#0d9488", // teal
+];
+/** The color a mailbox's original auto-provisioned calendar effectively had before this field
+ * existed — kept as the fallback so every pre-existing calendar keeps looking the same. */
+export const DEFAULT_CALENDAR_COLOR = CALENDAR_COLOR_PALETTE[0];
+/** `fallback` replaces `DEFAULT_CALENDAR_COLOR` for a folder with no color of its own - e.g. a shared
+ * mailbox's calendar falling back to that mailbox's `accentColorForMailbox()`, so it doesn't render in
+ * the same default blue as the caller's own calendar. An explicit `Folder.color` always wins. */
+export function colorForFolder(folder, fallback = DEFAULT_CALENDAR_COLOR) {
+    return folder.color || fallback;
+}
+/** A stable per-mailbox color for grouping one mailbox's calendars together (sidebar section accent, and
+ * the fallback color for its uncolored calendars). Deterministic hash of `mailboxUid` into the palette
+ * minus `DEFAULT_CALENDAR_COLOR`, so another mailbox never collides with the default a caller's own
+ * calendar already uses. Client-side only - nothing is persisted. */
+export function accentColorForMailbox(mailboxUid) {
+    const choices = CALENDAR_COLOR_PALETTE.slice(1);
+    let hash = 0;
+    for (let i = 0; i < mailboxUid.length; i++) {
+        hash = (hash * 31 + mailboxUid.charCodeAt(i)) >>> 0;
+    }
+    return choices[hash % choices.length];
+}

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

@@ -0,0 +1,42 @@
+/**
+ * `@dnd-kit/core` identifies draggables/droppables purely by string id — this module owns the
+ * encoding scheme for calendar drag ids and, more importantly, `resolveDragAction()`: a pure
+ * function turning a drag-end's (active id, over id) pair into "move this occurrence by N ms" or
+ * "resize this occurrence's end to this instant", *without* touching `@dnd-kit` itself. Kept pure and
+ * dependency-free from the grid components on purpose: `@dnd-kit`'s pointer-based drag sensors are
+ * awkward to drive from jsdom in tests (they need real `PointerEvent`/`getBoundingClientRect`
+ * behavior a headless DOM doesn't fully provide), but the *decision* a drag-end makes is ordinary
+ * data-in-data-out logic that's trivial to unit test directly — see `calendarDragIds.test.ts`. The
+ * grid views (`MonthView`/`TimeGridView`) only need to tag their draggable/droppable elements with
+ * these ids correctly; the calendar page's `onDragEnd` calls `resolveDragAction` and then one of
+ * `calendarMutations.ts`'s `moveOccurrence`/`resizeOccurrenceEnd`.
+ */
+import { CalendarOccurrence } from "./recurrence.js";
+/**
+ * A month-view day cell's droppable id, for the given day (any time-of-day on that calendar date) —
+ * encoded as the runtime's *local* `yyyy-MM-dd`, matching the local-midnight day dates the grid views
+ * build via `date-fns`.
+ */
+export declare function dayDropId(date: Date): string;
+/** A week/day-view time slot's droppable id, rounded to the given date-time instant. */
+export declare function slotDropId(date: Date): string;
+/** An event chip/block's draggable id (drag-to-move). */
+export declare function eventDragId(occurrence: CalendarOccurrence): string;
+/** An event block's resize-handle draggable id (drag-to-resize, week/day view only). */
+export declare function resizeDragId(occurrence: CalendarOccurrence): string;
+export type DragAction = {
+    type: "move";
+    occurrence: CalendarOccurrence;
+    deltaMs: number;
+} | {
+    type: "resize";
+    occurrence: CalendarOccurrence;
+    newEnd: Date;
+};
+/**
+ * Resolves a `@dnd-kit` drag-end's `active`/`over` ids into the action it represents, or `null` if
+ * the drop doesn't correspond to anything actionable (dropped outside any droppable, or the dragged
+ * id doesn't match any occurrence currently on the grid — e.g. it was removed by an in-flight reload
+ * mid-drag).
+ */
+export declare function resolveDragAction(activeId: string, overId: string | undefined, occurrences: CalendarOccurrence[]): DragAction | null;

package/dist/lib/calendar/calendarDragIds.js

@@ -0,0 +1,92 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * `@dnd-kit/core` identifies draggables/droppables purely by string id — this module owns the
+ * encoding scheme for calendar drag ids and, more importantly, `resolveDragAction()`: a pure
+ * function turning a drag-end's (active id, over id) pair into "move this occurrence by N ms" or
+ * "resize this occurrence's end to this instant", *without* touching `@dnd-kit` itself. Kept pure and
+ * dependency-free from the grid components on purpose: `@dnd-kit`'s pointer-based drag sensors are
+ * awkward to drive from jsdom in tests (they need real `PointerEvent`/`getBoundingClientRect`
+ * behavior a headless DOM doesn't fully provide), but the *decision* a drag-end makes is ordinary
+ * data-in-data-out logic that's trivial to unit test directly — see `calendarDragIds.test.ts`. The
+ * grid views (`MonthView`/`TimeGridView`) only need to tag their draggable/droppable elements with
+ * these ids correctly; the calendar page's `onDragEnd` calls `resolveDragAction` and then one of
+ * `calendarMutations.ts`'s `moveOccurrence`/`resizeOccurrenceEnd`.
+ */
+const DAY_ID_PREFIX = "day:";
+const SLOT_ID_PREFIX = "slot:";
+const RESIZE_ID_PREFIX = "resize:";
+/**
+ * A month-view day cell's droppable id, for the given day (any time-of-day on that calendar date) —
+ * encoded as the runtime's *local* `yyyy-MM-dd`, matching the local-midnight day dates the grid views
+ * build via `date-fns`.
+ */
+export function dayDropId(date) {
+    const yyyy = String(date.getFullYear()).padStart(4, "0");
+    const mm = String(date.getMonth() + 1).padStart(2, "0");
+    const dd = String(date.getDate()).padStart(2, "0");
+    return `${DAY_ID_PREFIX}${yyyy}-${mm}-${dd}`;
+}
+/** A week/day-view time slot's droppable id, rounded to the given date-time instant. */
+export function slotDropId(date) {
+    return `${SLOT_ID_PREFIX}${date.toISOString()}`;
+}
+/** An event chip/block's draggable id (drag-to-move). */
+export function eventDragId(occurrence) {
+    return occurrence.occurrenceKey;
+}
+/** An event block's resize-handle draggable id (drag-to-resize, week/day view only). */
+export function resizeDragId(occurrence) {
+    return `${RESIZE_ID_PREFIX}${occurrence.occurrenceKey}`;
+}
+/**
+ * Resolves a `@dnd-kit` drag-end's `active`/`over` ids into the action it represents, or `null` if
+ * the drop doesn't correspond to anything actionable (dropped outside any droppable, or the dragged
+ * id doesn't match any occurrence currently on the grid — e.g. it was removed by an in-flight reload
+ * mid-drag).
+ */
+export function resolveDragAction(activeId, overId, occurrences) {
+    if (!overId) {
+        return null;
+    }
+    const isResize = activeId.startsWith(RESIZE_ID_PREFIX);
+    const occurrenceKey = isResize ? activeId.slice(RESIZE_ID_PREFIX.length) : activeId;
+    const occurrence = occurrences.find((o) => o.occurrenceKey === occurrenceKey);
+    if (!occurrence) {
+        return null;
+    }
+    if (isResize) {
+        if (!overId.startsWith(SLOT_ID_PREFIX)) {
+            return null;
+        }
+        return { type: "resize", occurrence, newEnd: new Date(overId.slice(SLOT_ID_PREFIX.length)) };
+    }
+    if (overId.startsWith(DAY_ID_PREFIX)) {
+        // Moving a timed event to another day keeps the occurrence's local wall-clock start time, so the delta is
+        // "same local time on the target day" minus the original start — a whole number of calendar
+        // days, which is not always a multiple of 24h when the move crosses a DST change.
+        const [year, month, day] = overId.slice(DAY_ID_PREFIX.length).split("-").map(Number);
+        // An all-day event's start is a UTC-midnight date-only value, so its target is that calendar date's
+        // UTC midnight - never "the same local time", which west of UTC reads the stored midnight as the
+        // previous evening and lands the event a day late.
+        const source = new Date(occurrence.startDate);
+        const target = new Date(source.getTime());
+        if (occurrence.allDay) {
+            target.setTime(Date.UTC(year, month - 1, day));
+        }
+        else {
+            target.setFullYear(year, month - 1, day);
+        }
+        if (Number.isNaN(target.getTime())) {
+            return null;
+        }
+        return { type: "move", occurrence, deltaMs: target.getTime() - source.getTime() };
+    }
+    if (overId.startsWith(SLOT_ID_PREFIX)) {
+        const targetSlot = new Date(overId.slice(SLOT_ID_PREFIX.length));
+        return { type: "move", occurrence, deltaMs: targetSlot.getTime() - new Date(occurrence.startDate).getTime() };
+    }
+    return null;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 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 } from "./calendarApi.js";
+import { CalendarOccurrence } from "./recurrence.js";
+import { ApiClient } from "../util/api.js";
+/** `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 declare function saveEventSeries(occurrence: CalendarOccurrence, fields: Partial<CalendarEventInput>, client?: ApiClient): Promise<SeriesSaveResult>;
+/**
+ * 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 declare function detachOccurrence(occurrence: CalendarOccurrence, fields: Partial<CalendarEventInput>, client?: ApiClient): Promise<CalendarEvent>;
+/** Deletes an entire recurring series (or a genuinely non-recurring event) outright. */
+export declare function deleteEventSeries(occurrence: CalendarOccurrence, client?: ApiClient): Promise<void>;
+/** Removes just this one occurrence from a recurring series, leaving the rest of the series intact. */
+export declare function deleteEventOccurrence(occurrence: CalendarOccurrence, client?: ApiClient): Promise<CalendarEvent>;
+/**
+ * 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 declare function moveOccurrence(occurrence: CalendarOccurrence, deltaMs: number, client?: ApiClient): Promise<CalendarEvent>;
+/**
+ * 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 declare function resizeOccurrenceEnd(occurrence: CalendarOccurrence, newEndDate: Date, client?: ApiClient): Promise<CalendarEvent>;

package/dist/lib/calendar/calendarMutations.js

@@ -0,0 +1,190 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { createCalendarEvent, deleteCalendarEvent, getCalendarEvent, listCalendarEvents, updateCalendarEvent, } from "./calendarApi.js";
+import { fromEventWallClock, toEventWallClock } from "./recurrence.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, modulus) {
+    return ((value % modulus) + modulus) % modulus;
+}
+function addException(event, occurrenceStart, client) {
+    const rule = event.recurrenceRule;
+    return updateCalendarEvent({
+        uid: event.uid,
+        version: event.version,
+        recurrenceRule: { ...rule, exceptions: [...rule.exceptions, occurrenceStart] },
+    }, client);
+}
+/**
+ * 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, fields, client) {
+    const update = { 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) => {
+        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) => 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) }, 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, fields, client) {
+    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 = {
+        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, client) {
+    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, client) {
+    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, deltaMs, client) {
+    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, newEndDate, client) {
+    const start = new Date(occurrence.startDate);
+    const minEnd = new Date(start.getTime() + 15 * 60000);
+    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/dist/lib/calendar/eventDescription.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 declare const MAX_EVENT_DESCRIPTION_LENGTH = 32000;
+/** The longest description HTML the server takes, in characters. */
+export declare const MAX_EVENT_DESCRIPTION_HTML_LENGTH = 64000;
+/** 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[];
+};
+/**
+ * `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 declare function safeDescriptionHref(href: string | null | undefined): string | undefined;
+/** The elements and text of `html` a description may hold, and nothing else. `[]` without a DOM. */
+export declare function parseEventDescription(html: string | null | undefined): DescriptionNode[];
+/**
+ * `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 declare function sanitizeEventDescriptionHtml(html: string | null | undefined): string;
+/**
+ * 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 declare function htmlToPlainText(html: string | null | undefined): string;