@rapidmx/web-client 0.20.0 → 0.22.0

package/dist/lib/auth/session.js

@@ -0,0 +1,210 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Session handling for a service that never issues its own JWTs — identity comes entirely from a separate
+ * `auth-server` deployment (see `.claude/NOTES.md`). `userUid` (present when the `jwt` cookie auth-server
+ * set is valid) and `authServerUrl` are both supplied by the page's server-side `fetchProps` (see
+ * `src/{mongo,sql}/routes/{wwwRoute,AdminConsoleRoute}.ts`), not fetched client-side.
+ *
+ * The access token auth-server issues lives an hour, the refresh token two weeks. `useSessionRefresh()` keeps the
+ * first alive for as long as the second is valid by calling auth-server's `POST /api/auth/refresh` cross-origin
+ * (`authApiFetch()`), which reissues both cookies. That works because the deployment scopes both cookies to the shared
+ * parent domain and auth-server's CORS/CSRF origin allow-list includes this app's origin - the same requirements
+ * sign-out already has.
+ */
+import { useEffect, useRef } from "react";
+import { ApiRequestError, authApiFetch } from "../util/api.js";
+import { useApiClient } from "../util/apiClientContext.js";
+/** An access token's age at which it is refreshed. The token lives an hour; the margin leaves time to retry a failed refresh. */
+export const SESSION_REFRESH_AFTER_MS = 45 * 60 * 1000;
+/** How often an open page checks whether its token is due. Also what retries a refresh that failed for a transient reason. */
+export const SESSION_REFRESH_CHECK_MS = 60 * 1000;
+/** A reload that follows a successful recovery refresh but still finds no session is not repeated within this window. */
+export const SESSION_RELOAD_GUARD_MS = 60 * 1000;
+const LOCK_NAME = "rapidmx-session-refresh";
+const REFRESHED_AT_KEY = "rapidmx.session.refreshedAt";
+const RELOADED_AT_KEY = "rapidmx.session.reloadedAt";
+function readTimestamp(storage, key) {
+    try {
+        const value = Number(storage().getItem(key));
+        return Number.isFinite(value) ? value : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function writeTimestamp(storage, key, value) {
+    try {
+        storage().setItem(key, String(value));
+    }
+    catch {
+        // Storage can be blocked or full; the timestamp only avoids redundant refreshes.
+    }
+}
+/** The URL of auth-server's sign-in page, carrying the current URL as `return_to` so it can send the browser back here. */
+function signInUrl(authServerUrl) {
+    return `${authServerUrl}/auth/signin?return_to=${encodeURIComponent(window.location.href)}`;
+}
+/**
+ * Refreshes the signed-in session through auth-server: exchanges the `refresh` cookie for a new access token and
+ * refresh token, both set as cookies on the response. Rejects with the `ApiRequestError` auth-server answered
+ * (`401`/`403` when the refresh token has expired or was revoked).
+ *
+ * A refresh token is single-use and bound to the session, so two tabs refreshing at once would make the second one look
+ * like a dead session. Refreshes are therefore serialised across tabs (Web Locks, where the browser has them) and each
+ * tab records when the last one happened, so a tab that gets its turn right after another tab refreshed does nothing.
+ *
+ * @param force Refresh even when the last refresh, by this tab or another, was recent.
+ * @returns `true` when a refresh was made, `false` when one was not needed.
+ */
+export async function refreshSession(authServerUrl, force = false) {
+    const run = async () => {
+        if (!force && Date.now() - readTimestamp(() => localStorage, REFRESHED_AT_KEY) < SESSION_REFRESH_AFTER_MS) {
+            return false;
+        }
+        await authApiFetch(authServerUrl, "/auth/refresh", { method: "POST" });
+        writeTimestamp(() => localStorage, REFRESHED_AT_KEY, Date.now());
+        return true;
+    };
+    const locks = typeof navigator === "undefined" ? undefined : navigator.locks;
+    return locks ? locks.request(LOCK_NAME, run) : run();
+}
+/** Whether `err` says auth-server rejected the refresh token itself, as opposed to a failure worth retrying. */
+function isAuthRejection(err) {
+    return err instanceof ApiRequestError && (err.status === 401 || err.status === 403);
+}
+/**
+ * Redirects the browser to auth-server's sign-in page when `userUid` is absent, carrying the current URL as
+ * `return_to` so auth-server can send the browser back here afterward. A no-op once `userUid` is present.
+ *
+ * This does not try to recover the session first; `useSessionRefresh()` does, and is what an app frame should call.
+ *
+ * A no-op under an `ApiClientContext.Provider` (see `useSessionRefresh()`'s own doc comment for why) — there is
+ * no `jwt` cookie in that context for `userUid` to ever meaningfully reflect, and redirecting to auth-server's
+ * cookie-based sign-in page would be wrong for a session whose lifecycle a host app's own `ApiClient` manages.
+ */
+export function useRedirectIfUnauthenticated(userUid, authServerUrl) {
+    const explicitClient = useApiClient();
+    useEffect(() => {
+        if (explicitClient || userUid) {
+            return;
+        }
+        if (!authServerUrl) {
+            console.error("Cannot redirect to sign-in: mail:auth_server_url is not configured.");
+            return;
+        }
+        window.location.href = signInUrl(authServerUrl);
+    }, [userUid, authServerUrl, explicitClient]);
+}
+/**
+ * Keeps a page's session alive for as long as auth-server's refresh token is valid, so the user is not sent to sign in
+ * again every time the access token's hour is up:
+ *
+ * - `userUid` unset (the page was rendered without a valid `jwt` cookie - the tab was left open past the token's
+ * lifetime, or reopened later): attempts one silent refresh and reloads so the server renders the page with the new
+ * cookie. If the refresh is refused (the refresh token expired or was revoked, or there was none), or a reload just
+ * made still found no session, redirects to sign-in as `useRedirectIfUnauthenticated()` does.
+ * - `userUid` set: refreshes once the token is `SESSION_REFRESH_AFTER_MS` old (and right away when this browser has no
+ * record of a recent refresh, since the page's token age is unknown), checked every `SESSION_REFRESH_CHECK_MS` and
+ * whenever the tab becomes visible or the network returns, because a sleeping laptop stops timers. A failure that is
+ * not a rejection is simply retried at the next check. A rejection (`401`/`403`: the refresh token expired or was
+ * revoked, so the session cannot be kept) redirects to sign-in with `return_to` after `options.beforeRedirect` has run.
+ *
+ * **A no-op under an `ApiClientContext.Provider`** (see `util/apiClientContext.ts`): everything above assumes a
+ * `jwt`/`refresh` cookie pair this app can renew through auth-server's own `/auth/refresh` - meaningless for a
+ * component whose network calls actually go through an explicit `ApiClient` from `createApiClient()` instead
+ * (e.g. one account of the native, multi-account `tauri-client`), which has no cookie jar for that origin at all
+ * and whose token lifecycle is the host app's own job via a completely different mechanism (its own refresh
+ * flow, keyed to `ApiClient.getAccessToken()`). Detected via `useApiClient()`; when it returns anything other
+ * than `undefined`, this hook does nothing at all - no timer, no listener, no redirect, regardless of `userUid`/
+ * `authServerUrl`/`options`. The default (no `ApiClientContext.Provider` anywhere - every existing browser/SSR/
+ * Electron consumer) is completely unchanged: `useApiClient()` there always returns `undefined`.
+ */
+export function useSessionRefresh(userUid, authServerUrl, options = {}) {
+    const paused = !!options.paused;
+    const explicitClient = useApiClient();
+    const beforeRedirectRef = useRef(options.beforeRedirect);
+    beforeRedirectRef.current = options.beforeRedirect;
+    useEffect(() => {
+        if (explicitClient) {
+            return;
+        }
+        if (!authServerUrl) {
+            if (!userUid) {
+                console.error("Cannot redirect to sign-in: mail:auth_server_url is not configured.");
+            }
+            return;
+        }
+        let cancelled = false;
+        if (!userUid) {
+            if (paused || Date.now() - readTimestamp(() => sessionStorage, RELOADED_AT_KEY) < SESSION_RELOAD_GUARD_MS) {
+                window.location.href = signInUrl(authServerUrl);
+                return;
+            }
+            refreshSession(authServerUrl)
+                .then(() => {
+                if (!cancelled) {
+                    writeTimestamp(() => sessionStorage, RELOADED_AT_KEY, Date.now());
+                    window.location.reload();
+                }
+            })
+                .catch(() => {
+                if (!cancelled) {
+                    window.location.href = signInUrl(authServerUrl);
+                }
+            });
+            return () => {
+                cancelled = true;
+            };
+        }
+        if (paused) {
+            return;
+        }
+        let leaving = false;
+        let inFlight = false;
+        const leave = async () => {
+            leaving = true;
+            try {
+                await beforeRedirectRef.current?.();
+            }
+            catch {
+                // Saving what can be saved is best effort; the session is over either way.
+            }
+            if (!cancelled) {
+                window.location.href = signInUrl(authServerUrl);
+            }
+        };
+        const check = () => {
+            if (cancelled || leaving || inFlight) {
+                return;
+            }
+            inFlight = true;
+            refreshSession(authServerUrl)
+                .catch((err) => {
+                if (isAuthRejection(err)) {
+                    void leave();
+                }
+            })
+                .finally(() => {
+                inFlight = false;
+            });
+        };
+        const onVisible = () => {
+            if (document.visibilityState === "visible") {
+                check();
+            }
+        };
+        check();
+        const interval = window.setInterval(check, SESSION_REFRESH_CHECK_MS);
+        document.addEventListener("visibilitychange", onVisible);
+        window.addEventListener("online", check);
+        return () => {
+            cancelled = true;
+            window.clearInterval(interval);
+            document.removeEventListener("visibilitychange", onVisible);
+            window.removeEventListener("online", check);
+        };
+    }, [userUid, authServerUrl, paused, explicitClient]);
+}

package/dist/lib/branding/brandingApi.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s `Branding` route (`BaseBrandingRoute`) — a single, admin-managed,
+ * publicly-readable row of product chrome (logo, title/company name, custom stylesheet, header/footer HTML).
+ * `GET /system/branding` needs no auth (every viewer, including an anonymous booking-page visitor, can read
+ * it); every write is `@RequiresTrustedRole()` on the backend.
+ */
+import { ApiClient } from "../util/api.js";
+export interface Branding {
+    companyName: string;
+    title: string;
+    /** Already a directly-usable `<img src>` value — either an admin-set external URL, or (once uploaded via
+     * `uploadBrandingLogo()`) this server's own resolved asset URL. Never a bare blob key. */
+    logoUrl?: string;
+    /** The compact mark for navigation headers, independently configurable from `logoUrl`'s full logo -
+     * same directly-usable shape as `logoUrl`. Falls back to `logoUrl`, then a built-in default, when unset
+     * (see `useBranding()`'s `iconSrc`) - no fallback is applied here. */
+    iconUrl?: string;
+    /** Same shape as `logoUrl`, directly usable as a `<link href>`. */
+    stylesheetUrl?: string;
+    headerHtml?: string;
+    footerHtml?: string;
+}
+/** `client`, given by every function below that isn't a raw-bytes upload, 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. */
+export declare function getBranding(client?: ApiClient): Promise<Branding>;
+export interface UpdateBrandingInput {
+    companyName?: string;
+    title?: string;
+    logoUrl?: string;
+    iconUrl?: string;
+    stylesheetUrl?: string;
+    headerHtml?: string;
+    footerHtml?: string;
+}
+export declare function updateBranding(input: UpdateBrandingInput, client?: ApiClient): Promise<Branding>;
+/** Uploads `file` as the logo, self-hosted via `BlobStore` — bypasses `apiFetch` (which always forces
+ * `Content-Type: application/json`) the same way `mailApi.ts`'s `uploadAttachment()` does, since
+ * `BaseBrandingRoute.uploadLogo()` reads the raw request body directly. */
+export declare function uploadBrandingLogo(file: File): Promise<Branding>;
+/** Uploads `file` as the compact nav-header icon, independently of `uploadBrandingLogo()`'s full logo. */
+export declare function uploadBrandingIcon(file: File): Promise<Branding>;
+export declare function uploadBrandingStylesheet(file: File): Promise<Branding>;
+export declare function deleteBrandingLogo(client?: ApiClient): Promise<void>;
+export declare function deleteBrandingIcon(client?: ApiClient): Promise<void>;
+export declare function deleteBrandingStylesheet(client?: ApiClient): Promise<void>;

package/dist/lib/branding/brandingApi.js

@@ -0,0 +1,61 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s `Branding` route (`BaseBrandingRoute`) — a single, admin-managed,
+ * publicly-readable row of product chrome (logo, title/company name, custom stylesheet, header/footer HTML).
+ * `GET /system/branding` needs no auth (every viewer, including an anonymous booking-page visitor, can read
+ * it); every write is `@RequiresTrustedRole()` on the backend.
+ */
+import { ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+/** `client`, given by every function below that isn't a raw-bytes upload, 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. */
+export function getBranding(client) {
+    return withClient(client, "/system/branding");
+}
+export function updateBranding(input, client) {
+    return withClient(client, "/system/branding", {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+async function uploadBrandingAsset(path, file) {
+    const res = await fetch(apiUrl(path), {
+        method: "POST",
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": file.type || "application/octet-stream" }),
+        body: file,
+    });
+    const contentType = res.headers.get("content-type") ?? "";
+    const responseBody = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+    if (!res.ok) {
+        const message = (responseBody && (responseBody.message || responseBody.error)) || res.statusText || "Upload failed.";
+        throw new ApiRequestError(message, res.status, responseBody?.code);
+    }
+    return responseBody;
+}
+/** Uploads `file` as the logo, self-hosted via `BlobStore` — bypasses `apiFetch` (which always forces
+ * `Content-Type: application/json`) the same way `mailApi.ts`'s `uploadAttachment()` does, since
+ * `BaseBrandingRoute.uploadLogo()` reads the raw request body directly. */
+export function uploadBrandingLogo(file) {
+    return uploadBrandingAsset("/system/branding/logo", file);
+}
+/** Uploads `file` as the compact nav-header icon, independently of `uploadBrandingLogo()`'s full logo. */
+export function uploadBrandingIcon(file) {
+    return uploadBrandingAsset("/system/branding/icon", file);
+}
+export function uploadBrandingStylesheet(file) {
+    return uploadBrandingAsset("/system/branding/stylesheet", file);
+}
+export function deleteBrandingLogo(client) {
+    return withClient(client, "/system/branding/logo", { method: "DELETE" });
+}
+export function deleteBrandingIcon(client) {
+    return withClient(client, "/system/branding/icon", { method: "DELETE" });
+}
+export function deleteBrandingStylesheet(client) {
+    return withClient(client, "/system/branding/stylesheet", { method: "DELETE" });
+}

package/dist/lib/branding/useBranding.d.ts

@@ -0,0 +1,23 @@
+import { Branding } from "./brandingApi.js";
+/** `id` of the `<link>` for an uploaded/referenced custom stylesheet — server-rendered directly by
+ * `apps/*​/_layout.tsx` (with this exact id) when one is configured, and kept live by this hook's
+ * background refresh thereafter (matched by this id, rather than always appending a duplicate). */
+export declare const CUSTOM_STYLESHEET_LINK_ID = "branding-stylesheet";
+export interface UseBrandingResult {
+    branding: Branding | null;
+    /** `branding.logoUrl` once loaded, else the built-in default — always a usable `<img src>`. */
+    logoSrc: string;
+    /** `branding.iconUrl` once loaded, falling back to the full logo and then the built-in default — the
+     * compact mark for nav headers (see `Branding.iconUrl`'s doc comment). Always a usable `<img src>`. */
+    iconSrc: string;
+}
+/**
+ * Fetches the admin-configured `Branding` singleton once on mount and applies its cosmetic side effects
+ * (browser-tab title, injected custom stylesheet `<link>`) directly to `document` — the same "resolve real
+ * client state once mounted, no SSR prop threading" convention `useIsMobile`/`MailShell`'s query-param reads
+ * already use. `GET /system/branding` needs no auth and never `404`s (see `BaseBrandingRoute.get()`), so a
+ * fetch failure here can only be a real network/server problem — swallowed rather than surfaced, since
+ * branding is purely decorative and every other part of the shell already depends on the same API being
+ * reachable.
+ */
+export default function useBranding(): UseBrandingResult;

package/dist/lib/branding/useBranding.js

@@ -0,0 +1,65 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { getBranding } from "./brandingApi.js";
+const DEFAULT_LOGO_SRC = "/images/logo.svg";
+/** `id` of the `<link>` for an uploaded/referenced custom stylesheet — server-rendered directly by
+ * `apps/*​/_layout.tsx` (with this exact id) when one is configured, and kept live by this hook's
+ * background refresh thereafter (matched by this id, rather than always appending a duplicate). */
+export const CUSTOM_STYLESHEET_LINK_ID = "branding-stylesheet";
+/**
+ * Fetches the admin-configured `Branding` singleton once on mount and applies its cosmetic side effects
+ * (browser-tab title, injected custom stylesheet `<link>`) directly to `document` — the same "resolve real
+ * client state once mounted, no SSR prop threading" convention `useIsMobile`/`MailShell`'s query-param reads
+ * already use. `GET /system/branding` needs no auth and never `404`s (see `BaseBrandingRoute.get()`), so a
+ * fetch failure here can only be a real network/server problem — swallowed rather than surfaced, since
+ * branding is purely decorative and every other part of the shell already depends on the same API being
+ * reachable.
+ */
+export default function useBranding() {
+    const [branding, setBranding] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        getBranding()
+            .then((result) => {
+            if (!cancelled) {
+                setBranding(result);
+            }
+        })
+            .catch(() => {
+            // Decorative only — leave `branding` at null, which every consumer already treats as
+            // "use the defaults".
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    useEffect(() => {
+        if (branding?.title) {
+            document.title = branding.title;
+        }
+    }, [branding?.title]);
+    useEffect(() => {
+        // Reuses an existing `<link>` (server-rendered by `apps/*​/_layout.tsx` when a stylesheet is already
+        // configured) rather than always appending a duplicate — see `CUSTOM_STYLESHEET_LINK_ID`'s doc comment.
+        let link = document.getElementById(CUSTOM_STYLESHEET_LINK_ID);
+        if (!branding?.stylesheetUrl) {
+            link?.remove();
+            return;
+        }
+        if (!link) {
+            link = document.createElement("link");
+            link.id = CUSTOM_STYLESHEET_LINK_ID;
+            link.rel = "stylesheet";
+            document.head.appendChild(link);
+        }
+        link.href = branding.stylesheetUrl;
+    }, [branding?.stylesheetUrl]);
+    return {
+        branding,
+        logoSrc: branding?.logoUrl || DEFAULT_LOGO_SRC,
+        iconSrc: branding?.iconUrl || branding?.logoUrl || DEFAULT_LOGO_SRC,
+    };
+}

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

@@ -0,0 +1,230 @@
+/** 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 { ApiClient } from "../util/api.js";
+export type AttendeeRole = "required" | "optional" | "resource";
+export type AttendeeResponseStatus = "needsAction" | "accepted" | "declined" | "tentative";
+export interface Attendee {
+    address: string;
+    displayName?: string;
+    role: AttendeeRole;
+    responseStatus: AttendeeResponseStatus;
+    isOrganizer: boolean;
+}
+export type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";
+/** RFC5545 two-letter weekday codes, matching `rrule`'s own `WeekdayStr` type exactly. */
+export type WeekdayCode = "MO" | "TU" | "WE" | "TH" | "FR" | "SA" | "SU";
+export interface RecurrenceRule {
+    freq: RecurrenceFrequency;
+    interval: number;
+    /** Only meaningful for `freq: "weekly"`. */
+    byDay?: WeekdayCode[];
+    byMonthDay?: number[];
+    byMonth?: number[];
+    /** Ends after this many occurrences. Mutually exclusive with `until` — at most one may be set. */
+    count?: number;
+    /** Ends on this date (inclusive). Mutually exclusive with `count`. */
+    until?: string;
+    /** Specific occurrence start dates removed from the recurrence set. */
+    exceptions: string[];
+}
+export type CalendarEventStatus = "tentative" | "confirmed" | "cancelled";
+export type BusyStatus = "free" | "busy" | "tentative" | "oof";
+/** Who may see an event's details (iCalendar `CLASS`). A private or confidential event is shown to a read-only reader of a shared calendar only as a
+ * busy block (`CalendarEvent.redacted`). `"default"` is what an event with none says. */
+export type EventVisibility = "default" | "public" | "private" | "confidential";
+/** What the guests of an event may do (`CalendarEvent.guestsCan*`). */
+export interface GuestPermissions {
+    /** A guest may ask the organizer to change the title, location, description or time. */
+    guestsCanModify: boolean;
+    /** A guest may ask the organizer to add guests. */
+    guestsCanInviteOthers: boolean;
+    /** A guest sees who else was invited. */
+    guestsCanSeeGuestList: boolean;
+}
+/** The guest permissions an event has when none were chosen (Google Calendar's own defaults). */
+export declare const DEFAULT_GUEST_PERMISSIONS: GuestPermissions;
+/** The guest permissions `source` says, a missing (or `null`) flag reading as its default - an event stored before they existed carries none. */
+export declare function guestPermissionsOf(source: {
+    [K in keyof GuestPermissions]?: boolean | null;
+}): GuestPermissions;
+/** The visibility an event has, `"default"` when it says none. */
+export declare function visibilityOf(event: {
+    visibility?: EventVisibility | null;
+}): EventVisibility;
+/**
+ * The organizer's shape is `@rapidmx/restapi`'s general-purpose `Recipient` type (it's reused from the
+ * mail-recipient model), so it requires a `type` field even though a to/cc/bcc distinction is meaningless
+ * for an event organizer — this wrapper always sends `type: "to"` as an inert filler value when building one.
+ */
+export interface CalendarOrganizer {
+    address: string;
+    displayName?: string;
+    type: "to";
+}
+export interface CalendarEvent {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    folderUid: string;
+    mailboxUid: string;
+    title: string;
+    location?: string;
+    startDate: string;
+    endDate: string;
+    allDay: boolean;
+    timezone: string;
+    organizer: CalendarOrganizer;
+    attendees: Attendee[];
+    recurrenceRule?: RecurrenceRule;
+    /** For a single occurrence of a recurring event that has been individually modified, its original start date. */
+    recurrenceId?: string;
+    status: CalendarEventStatus;
+    busyStatus: BusyStatus;
+    reminderMinutesBeforeStart?: number;
+    icalUid: string;
+    sequence: number;
+    /** The `sequence` value invites were last sent for (server-internal iTIP tracking) — read-only
+     * display, never sent back in a `CalendarEventInput`. */
+    inviteSequenceSent?: number;
+    /** Set when an iTIP CANCEL was last sent for this event — read-only display, never sent back. */
+    cancelNoticeSentAt?: string;
+    /** When `true`, this event's own [`startDate`, `endDate`] window independently triggers an
+     * automatic-reply period for the mailbox, in addition to (not instead of) the mailbox-level
+     * `Mailbox.oofEnabled` toggle — e.g. a "Vacation" event configuring its own out-of-office window
+     * without touching the mailbox-wide setting. Takes precedence over `Mailbox.oofEnabled` while both
+     * are active (see `@rapidmx/restapi`'s `resolveActiveOof()`). */
+    autoReplyEnabled?: boolean;
+    /** The automatic-reply body while this event's window is active. Only meaningful when
+     * `autoReplyEnabled` is `true`. */
+    autoReplyMessage?: string;
+    /** The `@rapidmx/meet-plugin` `VideoMeeting` minted for this event, when the organizer turned on
+     * video conferencing (see `videoconf/videoMeetingsApi.ts`). Only the link is stored here — each
+     * attendee's own personal join URL is substituted into their own copy of the invitation server-side,
+     * so this event carries no per-attendee link and the organizer's own link is fetched from the meeting
+     * (`getVideoMeeting()`), never read off the event. */
+    videoMeetingUid?: string;
+    /** The description as plain text (at most 32,000 characters). When `descriptionHtml` is set this is its plain-text form. `null` or absent: none. */
+    description?: string | null;
+    /** The description as HTML the server has sanitized down to `b`/`strong`, `i`/`em`, `u`, `br`, `p`, `ul`/`ol`/`li` and `a` (`href` of `http`, `https` or
+     * `mailto` only). Still to be rendered through `sanitizeEventDescriptionHtml()` (`eventDescription.ts`), never trusted as it stands. `null` or absent:
+     * the description, if any, is plain text. */
+    descriptionHtml?: string | null;
+    /** Who may see the event's details - absent (or `null`, on a row stored before this existed) reads as `"default"`; see `visibilityOf()`. */
+    visibility?: EventVisibility | null;
+    /** Whether the guests may ask for the event to change (default `false`). Absent or `null` reads as the default; see `guestPermissionsOf()`. */
+    guestsCanModify?: boolean | null;
+    /** Whether the guests may ask for guests to be added (default `true`). */
+    guestsCanInviteOthers?: boolean | null;
+    /** Whether a guest sees the other guests (default `true`). When `false` a guest's copy lists only themselves. */
+    guestsCanSeeGuestList?: boolean | null;
+    /** Response-only. This reader (of a shared calendar, without edit access) sees the event only as a busy block: the title is `"Busy"` and there are no
+     * attendees, location, description or guest permissions. Never sent back. A live-update notification for such an event carries it too, and the
+     * owner's client refetches by `uid` instead of using the payload. */
+    redacted?: boolean;
+}
+/**
+ * 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 declare function listCalendarEvents(folderUid: string, client?: ApiClient): Promise<CalendarEvent[]>;
+export declare function getCalendarEvent(uid: string, client?: ApiClient): Promise<CalendarEvent>;
+export interface CalendarEventInput {
+    mailboxUid: string;
+    folderUid: string;
+    title: string;
+    location?: string;
+    startDate: string;
+    endDate: string;
+    allDay?: boolean;
+    timezone: string;
+    organizer: CalendarOrganizer;
+    attendees?: Attendee[];
+    recurrenceRule?: RecurrenceRule;
+    status?: CalendarEventStatus;
+    busyStatus?: BusyStatus;
+    reminderMinutesBeforeStart?: number;
+    autoReplyEnabled?: boolean;
+    autoReplyMessage?: string;
+    /** Set (or, sent as `null` on an update, cleared) when the caller has just minted or cancelled this
+     * event's video meeting — see `CalendarEvent.videoMeetingUid`. */
+    videoMeetingUid?: string;
+    /** Plain-text description (<= 32,000 characters). `null` (or `""`) clears it on an update. Sending only `descriptionHtml` makes the server derive this. */
+    description?: string | null;
+    /** Description HTML (<= 64,000 characters); the server sanitizes it. `null` (or `""`) clears it. Sending only `description` clears the HTML. */
+    descriptionHtml?: string | null;
+    visibility?: EventVisibility;
+    /** Only the organizer's own copy takes these; on a guest's copy they are ignored. Changing any of them, the description or the visibility re-invites. */
+    guestsCanModify?: boolean;
+    guestsCanInviteOthers?: boolean;
+    guestsCanSeeGuestList?: boolean;
+}
+export declare function createCalendarEvent(input: CalendarEventInput, client?: ApiClient): Promise<CalendarEvent>;
+export interface UpdateCalendarEventInput extends Partial<CalendarEventInput> {
+    uid: string;
+    version: number;
+}
+export declare function updateCalendarEvent(input: UpdateCalendarEventInput, client?: ApiClient): Promise<CalendarEvent>;
+export declare function deleteCalendarEvent(uid: string, version: number, client?: ApiClient): Promise<void>;
+/** The subset of `AttendeeResponseStatus` a caller can actually respond with — `"needsAction"` is only
+ * ever a default/initial value, never a valid response. */
+export type AttendeeResponseInput = Exclude<AttendeeResponseStatus, "needsAction">;
+/**
+ * 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 declare function respondToEvent(uid: string, responseStatus: AttendeeResponseInput, client?: ApiClient): Promise<CalendarEvent | {
+    uid: string;
+}>;
+/** A change a guest asks the organizer for (`requestEventChange()`): only what is to differ. */
+export interface EventChangeRequest {
+    /** Non-empty, at most 1,000 characters. A request can set these, not clear them. */
+    title?: string;
+    location?: string;
+    description?: string;
+    descriptionHtml?: string;
+    /** ISO 8601 instants. */
+    startDate?: string;
+    endDate?: string;
+    /** Up to 50 guests to add. */
+    addAttendees?: {
+        address: string;
+        displayName?: string;
+    }[];
+}
+/** What the server made of a change request. */
+export interface EventChangeRequestResult {
+    requested: true;
+    /** Which fields the request changes (as the server named them, e.g. `title`, `startDate`, `addAttendees`). */
+    changes: string[];
+    addAttendees: {
+        address: string;
+        displayName?: string;
+    }[];
+}
+/**
+ * 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 declare function requestEventChange(uid: string, request: EventChangeRequest, client?: ApiClient): Promise<EventChangeRequestResult>;