@rapidmx/web-client 0.30.0 → 0.31.0

package/dist/lib/auth/session.js

@@ -23,9 +23,31 @@ export const SESSION_REFRESH_AFTER_MS = 45 * 60 * 1000;
 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;
+/** A refresh answered with a refusal is asked once more after this long, in case the cookies were rotated by another tab or the server's session save lagged. */
+export const SESSION_REFRESH_RETRY_MS = 1500;
+/** A forced refresh (a request was refused, or the page has no session) does nothing when a refresh succeeded within this long: the refusal came from the old cookies. */
+export const SESSION_REFRESH_MIN_GAP_MS = 10 * 1000;
+/** How many entries `rapidmx.session.log` keeps. */
+export const SESSION_LOG_MAX = 40;
 const LOCK_NAME = "rapidmx-session-refresh";
 const REFRESHED_AT_KEY = "rapidmx.session.refreshedAt";
 const RELOADED_AT_KEY = "rapidmx.session.reloadedAt";
+const LOG_KEY = "rapidmx.session.log";
+/**
+ * How long a refresh request may go unanswered before it is given up on (not aborted - see `postRefresh()`). A refresh runs inside a cross-tab Web Lock, so one that hangs would hold the lock - and
+ * with it every tab's refresh, and every request waiting on a recovery - for good.
+ */
+export const SESSION_REFRESH_TIMEOUT_MS = 15 * 1000;
+let retryDelayMs = SESSION_REFRESH_RETRY_MS;
+let refreshTimeoutMs = SESSION_REFRESH_TIMEOUT_MS;
+/** Sets how long a refresh request may go unanswered (for tests); `resetSessionRecovery()` restores the default. */
+export function setSessionRefreshTimeout(ms) {
+    refreshTimeoutMs = ms;
+}
+/** Sets how long a refused refresh waits before its one retry (for tests); `resetSessionRecovery()` restores the default. */
+export function setSessionRefreshRetryDelay(ms) {
+    retryDelayMs = ms;
+}
 function readTimestamp(storage, key) {
     try {
         const value = Number(storage().getItem(key));
@@ -43,42 +65,175 @@ function writeTimestamp(storage, key, value) {
         // Storage can be blocked or full; the timestamp only avoids redundant refreshes.
     }
 }
+/** Whether a refresh succeeded within the last `ms`, in this tab or another (they share `localStorage`). A cleared or future-dated record counts as no. */
+export function refreshedRecently(ms) {
+    const at = readTimestamp(() => localStorage, REFRESHED_AT_KEY);
+    const age = Date.now() - at;
+    return at > 0 && age >= 0 && age < ms;
+}
+/** The session log: the last `SESSION_LOG_MAX` things the silent refresh did, oldest first, kept in `localStorage['rapidmx.session.log']` so the cause of an unexpected sign-in can be read afterward. */
+export function getSessionLog() {
+    try {
+        const value = JSON.parse(localStorage.getItem(LOG_KEY) ?? "[]");
+        return Array.isArray(value) ? value : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Appends to the session log, dropping the oldest entries past `SESSION_LOG_MAX`. Best effort: blocked storage loses the entry. */
+export function logSessionEvent(e, d) {
+    try {
+        const entries = getSessionLog();
+        entries.push(d === undefined ? { t: new Date().toISOString(), e } : { t: new Date().toISOString(), e, d });
+        localStorage.setItem(LOG_KEY, JSON.stringify(entries.slice(-SESSION_LOG_MAX)));
+    }
+    catch {
+        // The log is evidence only; it must never get in the way of the session.
+    }
+}
+/** How long ago the last successful refresh was, for log entries: `12s`, or `never` when this browser has no record. */
+function sinceLastRefresh() {
+    const at = readTimestamp(() => localStorage, REFRESHED_AT_KEY);
+    return at > 0 ? `${Math.round((Date.now() - at) / 1000)}s` : "never";
+}
 /** 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)}`;
 }
+/** Sends the browser to auth-server's sign-in page, first writing why to the session log and printing the log to the console. */
+function goToSignIn(authServerUrl, reason) {
+    logSessionEvent("leave", `${reason} sinceOk=${sinceLastRefresh()}`);
+    console.info("[rapidmx] Going to sign-in. Session log:", getSessionLog());
+    window.location.href = signInUrl(authServerUrl);
+}
+/** 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);
+}
+function describeFailure(err) {
+    if (err instanceof ApiRequestError) {
+        return `status=${err.status}${err.code ? ` code=${err.code}` : ""} sinceOk=${sinceLastRefresh()}`;
+    }
+    return `${err instanceof Error ? err.message : "unknown"}`.slice(0, 80);
+}
+/** Counts the refresh requests made, so a request that answers after it was given up on can tell whether a newer one has started since. */
+let refreshSeq = 0;
+/**
+ * One `POST /auth/refresh`, recording when it succeeded. Given up on after `SESSION_REFRESH_TIMEOUT_MS`, which is a failure worth retrying, not a rejection.
+ * Giving up only stops waiting: the request is NOT aborted. Auth-server rotates the single-use refresh token as it answers, and a browser that aborts before the
+ * response headers arrive never stores the rotated cookie, leaving the consumed token behind - the next refresh would be refused and the user signed out.
+ * A late answer is still logged, and a late success still recorded unless a newer refresh has started since.
+ */
+async function postRefresh(authServerUrl) {
+    const seq = ++refreshSeq;
+    const request = authApiFetch(authServerUrl, "/auth/refresh", { method: "POST" });
+    let timedOut = false;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            reject(new Error(`refresh timed out after ${refreshTimeoutMs}ms`));
+        }, refreshTimeoutMs);
+    });
+    // Handles the request's own outcome whenever it comes, so a rejection after the timeout is never unhandled.
+    request.then(() => {
+        if (!timedOut) {
+            return;
+        }
+        if (seq === refreshSeq) {
+            writeTimestamp(() => localStorage, REFRESHED_AT_KEY, Date.now());
+            logSessionEvent("refresh:late-ok");
+        }
+        else {
+            logSessionEvent("refresh:late-superseded");
+        }
+    }, (err) => {
+        if (timedOut) {
+            logSessionEvent("refresh:late-error", describeFailure(err));
+        }
+    });
+    try {
+        await Promise.race([request, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    writeTimestamp(() => localStorage, REFRESHED_AT_KEY, Date.now());
+}
+let refreshing;
 /**
  * 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.
+ * A refresh token is single-use and bound to the session, and auth-server saves the rotated token a moment after it
+ * answers, so refreshing twice in quick succession makes the second look like a dead session. Refreshes are therefore
+ * shared by every caller in the tab (one in flight at a time), serialised across tabs (Web Locks, where the browser has
+ * them), and each tab records when the last one succeeded, so a caller that gets its turn right after a refresh does
+ * nothing. A refresh that is refused is asked once more after `SESSION_REFRESH_RETRY_MS` (the cookies may have been
+ * rotated meanwhile) before it counts as a rejection.
  *
- * @param force Refresh even when the last refresh, by this tab or another, was recent.
+ * @param force Refresh even when the last refresh, by this tab or another, was `SESSION_REFRESH_AFTER_MS` ago or less. Even forced, a refresh made within `SESSION_REFRESH_MIN_GAP_MS` is not repeated.
+ * @param reason Why, for the session log.
  * @returns `true` when a refresh was made, `false` when one was not needed.
  */
-export async function refreshSession(authServerUrl, force = false) {
+export function refreshSession(authServerUrl, force = false, reason = force ? "recovery" : "check") {
+    if (refreshing) {
+        // A forced caller must not take the outcome of a refresh that may have been skipped as not due: ask again once it is over (which the minimum gap keeps from being a second POST when it did refresh).
+        return force && !refreshing.forced ? refreshing.promise.then(() => refreshSession(authServerUrl, true, reason)) : refreshing.promise;
+    }
     const run = async () => {
-        if (!force && Date.now() - readTimestamp(() => localStorage, REFRESHED_AT_KEY) < SESSION_REFRESH_AFTER_MS) {
+        if (refreshedRecently(force ? SESSION_REFRESH_MIN_GAP_MS : SESSION_REFRESH_AFTER_MS)) {
+            if (force) {
+                logSessionEvent("refresh:skip", `recent sinceOk=${sinceLastRefresh()} reason=${reason}`);
+            }
             return false;
         }
-        await authApiFetch(authServerUrl, "/auth/refresh", { method: "POST" });
-        writeTimestamp(() => localStorage, REFRESHED_AT_KEY, Date.now());
+        logSessionEvent("refresh:start", `reason=${reason} sinceOk=${sinceLastRefresh()}`);
+        try {
+            await postRefresh(authServerUrl);
+        }
+        catch (err) {
+            if (!isAuthRejection(err)) {
+                logSessionEvent("refresh:error", describeFailure(err));
+                throw err;
+            }
+            logSessionEvent("refresh:rejected", `${describeFailure(err)} attempt=1`);
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+            if (refreshedRecently(SESSION_REFRESH_MIN_GAP_MS)) {
+                // Another tab renewed the session while this one waited.
+                logSessionEvent("refresh:skip", `recent-after-retry-wait reason=${reason}`);
+                return false;
+            }
+            logSessionEvent("refresh:retry", `reason=${reason}`);
+            try {
+                await postRefresh(authServerUrl);
+            }
+            catch (err2) {
+                logSessionEvent(isAuthRejection(err2) ? "refresh:rejected" : "refresh:error", `${describeFailure(err2)} attempt=2`);
+                throw err2;
+            }
+        }
+        logSessionEvent("refresh:ok", `reason=${reason}`);
         return true;
     };
     const locks = typeof navigator === "undefined" ? undefined : navigator.locks;
-    return locks ? locks.request(LOCK_NAME, run) : run();
+    const promise = (locks ? locks.request(LOCK_NAME, run) : run()).finally(() => {
+        refreshing = undefined;
+    });
+    refreshing = { promise, forced: force };
+    return promise;
 }
 /** How long the outcome of a recovery is reused for: requests that fail together share one refresh, and a session that will not come back is not asked again at once. */
 export const SESSION_RECOVERY_COOLDOWN_MS = 10 * 1000;
 let recovery;
 let lastRecovery;
 /**
- * Renews the session because a request was refused for lack of one, whatever this browser's record of the last refresh says. Every request
- * refused at about the same time shares one refresh, and its outcome is reused for `SESSION_RECOVERY_COOLDOWN_MS`. A refusal also clears the record of
- * the last refresh, so the next regular check asks again (and sends the browser to sign-in if the refresh token is truly gone).
+ * Renews the session because a request was refused for lack of one, whatever this browser's record of the last refresh says - except that a refresh that
+ * succeeded within `SESSION_REFRESH_MIN_GAP_MS` (by this tab or another) is not repeated: the request was refused with the cookies from before it, so it is
+ * simply sent again with the new ones. Every request refused at about the same time shares one refresh, and its outcome is reused for `SESSION_RECOVERY_COOLDOWN_MS`.
+ * A refusal also clears the record of the last refresh, so the next regular check asks again (and sends the browser to sign-in if the refresh token is truly gone).
  *
  * @returns Whether the session was renewed.
  */
@@ -86,7 +241,7 @@ export function recoverSession(authServerUrl) {
     if (lastRecovery && Date.now() - lastRecovery.at < SESSION_RECOVERY_COOLDOWN_MS) {
         return Promise.resolve(lastRecovery.renewed);
     }
-    recovery ?? (recovery = refreshSession(authServerUrl, true)
+    recovery ?? (recovery = refreshSession(authServerUrl, true, "recovery")
         .then(() => true, () => {
         writeTimestamp(() => localStorage, REFRESHED_AT_KEY, 0);
         return false;
@@ -98,14 +253,13 @@ export function recoverSession(authServerUrl) {
     }));
     return recovery;
 }
-/** Forgets what recoveries have done (for tests). */
+/** Forgets what recoveries and refreshes have done, and restores the retry delay and timeout (for tests). */
 export function resetSessionRecovery() {
     recovery = undefined;
     lastRecovery = undefined;
-}
-/** 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);
+    refreshing = undefined;
+    retryDelayMs = SESSION_REFRESH_RETRY_MS;
+    refreshTimeoutMs = SESSION_REFRESH_TIMEOUT_MS;
 }
 /**
  * Redirects the browser to auth-server's sign-in page when `userUid` is absent, carrying the current URL as
@@ -127,7 +281,7 @@ export function useRedirectIfUnauthenticated(userUid, authServerUrl) {
             console.error("Cannot redirect to sign-in: mail:auth_server_url is not configured.");
             return;
         }
-        window.location.href = signInUrl(authServerUrl);
+        goToSignIn(authServerUrl, "no-session");
     }, [userUid, authServerUrl, explicitClient]);
 }
 /**
@@ -141,9 +295,11 @@ export function useRedirectIfUnauthenticated(userUid, authServerUrl) {
  * - `userUid` set: also renews the session when a request is refused for lack of one (`apiFetch()` asks `recoverSession()` and sends the request
  * again), so a token that ran out while timers were stopped costs nothing. 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.
+ * whenever the tab becomes visible or focused or the network returns, because a sleeping laptop stops timers (a tab that wakes after the
+ * token's hour checks first, and a request refused meanwhile waits for that same refresh rather than starting its own). A failure that is
+ * not a rejection is simply retried at the next check. A rejection (`401`/`403` twice running, `SESSION_REFRESH_RETRY_MS` apart: 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.
+ * Everything it does is recorded in the session log (`getSessionLog()`), which is also printed to the console when the browser goes to sign-in.
  *
  * **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
@@ -172,21 +328,26 @@ export function useSessionRefresh(userUid, authServerUrl, options = {}) {
         }
         let cancelled = false;
         if (!userUid) {
-            if (paused || Date.now() - readTimestamp(() => sessionStorage, RELOADED_AT_KEY) < SESSION_RELOAD_GUARD_MS) {
-                window.location.href = signInUrl(authServerUrl);
+            if (paused) {
+                goToSignIn(authServerUrl, "no-session paused");
+                return;
+            }
+            if (Date.now() - readTimestamp(() => sessionStorage, RELOADED_AT_KEY) < SESSION_RELOAD_GUARD_MS) {
+                goToSignIn(authServerUrl, "no-session after-reload");
                 return;
             }
-            // Forced: the page has no session, so what this browser remembers of the last refresh says nothing about whether one is due.
-            refreshSession(authServerUrl, true)
+            // Forced: the page has no session, so what this browser remembers of the last refresh says nothing about whether one is due (but one made seconds ago is not repeated).
+            refreshSession(authServerUrl, true, "nouser")
                 .then(() => {
                 if (!cancelled) {
+                    logSessionEvent("reload-after-refresh");
                     writeTimestamp(() => sessionStorage, RELOADED_AT_KEY, Date.now());
                     window.location.reload();
                 }
             })
                 .catch(() => {
                 if (!cancelled) {
-                    window.location.href = signInUrl(authServerUrl);
+                    goToSignIn(authServerUrl, "no-session refresh-rejected");
                 }
             });
             return () => {
@@ -200,8 +361,10 @@ export function useSessionRefresh(userUid, authServerUrl, options = {}) {
         setApiSessionRecovery(() => recoverSession(authServerUrl));
         let leaving = false;
         let inFlight = false;
-        const leave = async () => {
+        let hiddenAt;
+        const leave = async (reason) => {
             leaving = true;
+            logSessionEvent("leave:pending", reason);
             try {
                 await beforeRedirectRef.current?.();
             }
@@ -209,18 +372,22 @@ export function useSessionRefresh(userUid, authServerUrl, options = {}) {
                 // Saving what can be saved is best effort; the session is over either way.
             }
             if (!cancelled) {
-                window.location.href = signInUrl(authServerUrl);
+                goToSignIn(authServerUrl, reason);
             }
         };
-        const check = () => {
+        // `trigger` names what woke the check, for the log; the periodic tick passes none, so it logs only when it actually refreshes.
+        const check = (trigger) => {
             if (cancelled || leaving || inFlight) {
                 return;
             }
+            if (trigger) {
+                logSessionEvent("check", trigger);
+            }
             inFlight = true;
-            refreshSession(authServerUrl)
+            refreshSession(authServerUrl, false, "check")
                 .catch((err) => {
                 if (isAuthRejection(err)) {
-                    void leave();
+                    void leave("refresh-rejected");
                 }
             })
                 .finally(() => {
@@ -228,20 +395,29 @@ export function useSessionRefresh(userUid, authServerUrl, options = {}) {
             });
         };
         const onVisible = () => {
-            if (document.visibilityState === "visible") {
-                check();
+            if (document.visibilityState === "hidden") {
+                hiddenAt = Date.now();
+                return;
             }
+            logSessionEvent("visible", hiddenAt === undefined ? "hiddenFor=unknown" : `hiddenFor=${Date.now() - hiddenAt}ms`);
+            hiddenAt = undefined;
+            check("visible");
         };
-        check();
-        const interval = window.setInterval(check, SESSION_REFRESH_CHECK_MS);
+        const onFocus = () => check("focus");
+        const onOnline = () => check("online");
+        const onTick = () => check();
+        check("mount");
+        const interval = window.setInterval(onTick, SESSION_REFRESH_CHECK_MS);
         document.addEventListener("visibilitychange", onVisible);
-        window.addEventListener("online", check);
+        window.addEventListener("focus", onFocus);
+        window.addEventListener("online", onOnline);
         return () => {
             cancelled = true;
             setApiSessionRecovery(undefined);
             window.clearInterval(interval);
             document.removeEventListener("visibilitychange", onVisible);
-            window.removeEventListener("online", check);
+            window.removeEventListener("focus", onFocus);
+            window.removeEventListener("online", onOnline);
         };
     }, [userUid, authServerUrl, paused, explicitClient]);
 }

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

@@ -38,10 +38,10 @@ export declare function updateBranding(input: UpdateBrandingInput, client?: ApiC
 /** 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>;
+export declare function uploadBrandingLogo(file: File, client?: ApiClient): 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 uploadBrandingIcon(file: File, client?: ApiClient): Promise<Branding>;
+export declare function uploadBrandingStylesheet(file: File, client?: ApiClient): 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

@@ -8,7 +8,7 @@
  * `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";
+import { withClient, withClientRaw } 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
@@ -22,33 +22,21 @@ export function updateBranding(input, client) {
         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;
+function uploadBrandingAsset(path, file, client) {
+    return withClientRaw(client, path, "POST", file, file.type || "application/octet-stream");
 }
 /** 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);
+export function uploadBrandingLogo(file, client) {
+    return uploadBrandingAsset("/system/branding/logo", file, client);
 }
 /** 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 uploadBrandingIcon(file, client) {
+    return uploadBrandingAsset("/system/branding/icon", file, client);
 }
-export function uploadBrandingStylesheet(file) {
-    return uploadBrandingAsset("/system/branding/stylesheet", file);
+export function uploadBrandingStylesheet(file, client) {
+    return uploadBrandingAsset("/system/branding/stylesheet", file, client);
 }
 export function deleteBrandingLogo(client) {
     return withClient(client, "/system/branding/logo", { method: "DELETE" });

package/dist/lib/calendar/calendarApi.js

@@ -24,6 +24,8 @@ export function visibilityOf(event) {
 }
 const LIST_PAGE_SIZE = 500;
 const LIST_CALENDAR_EVENTS_MAX_PAGES = 100;
+/** Without an order, a page boundary can skip or repeat an event: the `uid` is a fixed one. */
+const EVENT_SORT = JSON.stringify({ uid: "ASC" });
 /**
  * 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
@@ -43,7 +45,7 @@ const LIST_CALENDAR_EVENTS_MAX_PAGES = 100;
 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 })}`);
+        const batch = await withClient(client, `/mail/calendar-events?${buildQuery({ limit: LIST_PAGE_SIZE, page }, { folderUid, sort: EVENT_SORT })}`);
         events.push(...batch);
         if (batch.length < LIST_PAGE_SIZE) {
             break;

package/dist/lib/calendar/eventSearch.js

@@ -64,6 +64,38 @@ export function searchOccurrences(events, query, now = new Date()) {
 export function allOccurrences(events, now = new Date()) {
     return occurrencesOf(events, () => true, now);
 }
+/**
+ * The `count` occurrences of `chronological` (a series, in order of start, as `expandOccurrences()` returns it) that start nearest `now`, still in order. They
+ * are the run around `now`, so that is grown from it a side at a time (the nearer side first, the earlier one on a tie) rather than sorting the whole series.
+ */
+function nearest(chronological, now, count) {
+    const startOf = (o) => new Date(o.startDate).getTime();
+    // The first that starts at or after now.
+    let low = 0;
+    let high = chronological.length;
+    while (low < high) {
+        const middle = (low + high) >> 1;
+        if (startOf(chronological[middle]) < now) {
+            low = middle + 1;
+        }
+        else {
+            high = middle;
+        }
+    }
+    let from = low;
+    let to = low;
+    while (to - from < count) {
+        const before = from > 0 ? now - startOf(chronological[from - 1]) : Infinity;
+        const after = to < chronological.length ? startOf(chronological[to]) - now : Infinity;
+        if (before <= after) {
+            from--;
+        }
+        else {
+            to++;
+        }
+    }
+    return chronological.slice(from, to);
+}
 /** The chronological occurrences of the `events` that `include` accepts (see `searchOccurrences()` for how a series is bounded). */
 function occurrencesOf(events, include, now) {
     const from = addYears(now, -SEARCH_WINDOW_YEARS);
@@ -73,16 +105,21 @@ function occurrencesOf(events, include, now) {
         if (!include(event)) {
             continue;
         }
+        const once = () => expandOccurrences({ ...event, recurrenceRule: undefined }, new Date(new Date(event.startDate).getTime() - 1), new Date(new Date(event.endDate).getTime() + 1));
         if (!event.recurrenceRule) {
-            found.push(...expandOccurrences(event, new Date(new Date(event.startDate).getTime() - 1), new Date(new Date(event.endDate).getTime() + 1)));
+            found.push(...once());
             continue;
         }
-        const occurrences = expandOccurrences(event, from, to);
-        if (occurrences.length > SEARCH_MAX_OCCURRENCES_PER_SERIES) {
-            const distance = (o) => Math.abs(new Date(o.startDate).getTime() - now.getTime());
-            occurrences.sort((a, b) => distance(a) - distance(b)).length = SEARCH_MAX_OCCURRENCES_PER_SERIES;
+        let occurrences;
+        try {
+            occurrences = expandOccurrences(event, from, to);
+        }
+        catch {
+            // One event whose rule or dates cannot be expanded must not fail the whole search or agenda: it counts once, as the stored event.
+            found.push(...once());
+            continue;
         }
-        found.push(...occurrences);
+        found.push(...(occurrences.length > SEARCH_MAX_OCCURRENCES_PER_SERIES ? nearest(occurrences, now.getTime(), SEARCH_MAX_OCCURRENCES_PER_SERIES) : occurrences));
     }
     return found.sort(byStart);
 }

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

@@ -54,7 +54,8 @@ export interface PersonAvailability {
 }
 /** 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). */
+/** The response's results with their times as milliseconds (a person who isn't `"available"` has no blocks whatever the server sent). A window
+ * whose start or end can't be read is busy for all time - never silently free, which is what comparing `NaN` would make it. */
 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"`. */

package/dist/lib/calendar/freeBusyApi.js

@@ -32,16 +32,22 @@ export function getFreeBusy(addresses, start, end, client) {
         }),
     });
 }
-/** The response's results with their times as milliseconds (a person who isn't `"available"` has no blocks whatever the server sent). */
+/** The response's results with their times as milliseconds (a person who isn't `"available"` has no blocks whatever the server sent). A window
+ * whose start or end can't be read is busy for all time - never silently free, which is what comparing `NaN` would make it. */
 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 }))
-            : [],
+        busy: result.status === "available" ? result.busy.map(toBusyBlock) : [],
     }));
 }
+function toBusyBlock(window) {
+    const startMs = Date.parse(window.start);
+    const endMs = Date.parse(window.end);
+    return Number.isFinite(startMs) && Number.isFinite(endMs)
+        ? { startMs, endMs, tentative: window.tentative }
+        : { startMs: Number.NEGATIVE_INFINITY, endMs: Number.POSITIVE_INFINITY, 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;
@@ -88,6 +94,8 @@ export function withoutOwnBlock(people, addresses, startMs, endMs) {
         : person);
 }
 const DEFAULT_STEP_MS = 30 * 60000;
+/** The finest step `suggestTimes()` takes: a zero or negative one would never advance, a tiny one would test millions of slots. */
+const MIN_STEP_MS = 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.
@@ -99,7 +107,7 @@ export function suggestTimes(people, options) {
     if (known.length === 0 || options.durationMs <= 0) {
         return [];
     }
-    const step = options.stepMs ?? DEFAULT_STEP_MS;
+    const step = Number.isFinite(options.stepMs) ? Math.max(MIN_STEP_MS, 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)) {