@rapidmx/web-client 0.14.1 → 0.16.0

package/dist/apps/shared/notifications/store.js

@@ -2,29 +2,7 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-/**
- * The app's one notification store: every pop-up - new mail, a failed send, an API error, an expired session - goes through
- * `notify()`. It is deliberately framework-free (no React, no DOM beyond `sessionStorage`/timers), so it can be called from a hook,
- * a plain function or an `apiFetch` error path alike; `NotificationCenter` (the view, mounted once in the app frame) and
- * `useNotifications()` only *read* it.
- *
- * Rules, all enforced here rather than by the view so they hold whoever renders:
- *
- * - **At most `MAX_VISIBLE` (3) are visible**; the rest wait in a queue and appear as room is made. A sticky notification (an error, or
- * anything with actions) that finds the stack full pushes out the oldest one that would have gone by itself, rather than waiting behind
- * it. A queued notification that has waited `QUEUE_STALE_MS` is dropped (it would be news from the past) - it is still in the history.
- * - **Sticky until dismissed or resolved**: errors and notifications with actions never expire (`update()` or `dismiss()` resolve them).
- * Everything else goes by itself after its kind's default time, or `timeoutMs`. `sticky` overrides both ways.
- * - **A clock that stops**: a notification's remaining time stops while it is hovered or focused (`setPaused()`) and while the tab is
- * hidden (`setAllPaused()`), and continues from where it was.
- * - **Deduplicated by `dedupeKey`**: a second notification with a key that is still on screen (or waiting) does not stack - it replaces
- * the first one's content, restarts its clock and raises its `count`, so a flapping error is one pop-up saying "x3".
- * - **Nothing is lost when one goes**: the last `HISTORY_LIMIT` (30, except new-mail pop-ups, which the inbox already holds) are
- * kept, in memory and in `sessionStorage`, with which errors nobody has seen yet.
- *
- * Nothing is stored where there is no `window` (server-side rendering): the module state is shared between requests there, so
- * `notify()` only hands back an id.
- */
+import { getNotificationsEnabled } from "./preferences.js";
 export const MAX_VISIBLE = 3;
 export const MAX_QUEUED = 20;
 export const QUEUE_STALE_MS = 30000;
@@ -254,6 +232,12 @@ export function notify(input) {
         paused: false,
     };
     applyInput(entry, input);
+    if (!getNotificationsEnabled()) {
+        // The user has pop-ups off: nothing is shown, but it is listed in the history like any other.
+        record(entry);
+        emit();
+        return id;
+    }
     const room = visibleCount() < MAX_VISIBLE;
     entries.push(entry);
     if (room) {

package/dist/apps/shared/search/crossMailboxSearch.d.ts

@@ -0,0 +1,72 @@
+import type { SearchResult } from "@rapidmx/react-shared/search/searchApi.js";
+/**
+ * How far a cross-mailbox search fans out. Exported (and mutable) so a test can shrink them instead of building 26 mailboxes or waiting a
+ * minute for a timeout; nothing else writes to it.
+ */
+export declare const SEARCH_LIMITS: {
+    /** How many mailboxes are worked on at once. */
+    concurrency: number;
+    /** The most mailboxes one search covers - the caller's own first, then the shared ones (`orderMailboxes()`); a note says how many were left out. */
+    maxMailboxes: number;
+    /** How long one mailbox's Tier 1 (server) request may take before that mailbox is given up on, so one wedged mailbox cannot hold the search. */
+    tier1TimeoutMs: number;
+    /** The same for a mailbox's Tier 3 pass (fetching and decrypting up to a couple of hundred candidates, so much longer). */
+    tier3TimeoutMs: number;
+    /** The most result rows a search keeps on screen (the page's own cap for a list, `MAX_LOADED_ROWS`, applies to a search too). */
+    maxRows: number;
+};
+/**
+ * How many results each mailbox contributes to one page. One mailbox gives the whole page; with several the page is shared out between them
+ * (never below `MIN_MAILBOX_PAGE_SIZE`), so the merged first page stays about one page long instead of growing by the number of mailboxes.
+ */
+export declare function searchPageSize(mailboxCount: number, pageSize: number): number;
+/** A search hit that remembers which mailbox it was found in. */
+export interface MailboxHit extends SearchResult {
+    mailboxUid: string;
+}
+export declare function tagHits(mailboxUid: string, hits: SearchResult[]): MailboxHit[];
+/** One hit's identity across mailboxes: the same entity uid found in two mailboxes is two hits. */
+export declare function hitKey(hit: {
+    mailboxUid: string;
+    entityUid: string;
+}): string;
+/**
+ * Merges Tier 1 (server, possibly `metadataOnly` for an encrypted message), Tier 2 (local index, fully decrypted and re-scored) and Tier 3
+ * (server-narrowed candidates, decrypted and re-scored) results into one ranked list, per `specs/search.md` §7's "client MUST re-score all
+ * results it can see... normalise into the same space rather than interleaving raw scores": each tier is normalized independently via
+ * `normalizeServerScores()` before merging, since a Postgres/OpenSearch score, a local `bm25()` score, and Tier 3's own term-count score all
+ * occupy unrelated ranges. A hit present in more than one list keeps only the last-inserted entry (Tier 2 wins over Tier 3 wins over Tier 1) -
+ * Tier 2 and Tier 3 both represent genuine, content-verified scores for the same message, so which one "wins" on overlap doesn't change
+ * correctness, only which of two equally-valid scores is shown; either supersedes Tier 1's metadata-only guess for the same message.
+ *
+ * Each tier's list is pooled across every mailbox searched before it is normalized, so one mailbox's best hit is not automatically "1.0"
+ * next to another's: the ranking is the same rule as for one mailbox, applied to the merged lists. A hit's identity is its mailbox and its
+ * entity uid (`hitKey()`), so the same uid can only collapse within a mailbox. Ties keep the order the lists were given in (a stable sort), which
+ * the caller makes the mailboxes' display order.
+ *
+ * Called progressively - each time with whatever tiers have reported so far (an empty array for the rest). Pure and stateless.
+ */
+export declare function mergeSearchResults(tier1: MailboxHit[], tier2: MailboxHit[], tier3: MailboxHit[]): MailboxHit[];
+/** Raised by `withTimeout()`. */
+export declare class SearchTimeoutError extends Error {
+    constructor();
+}
+/** `promise`, or a rejection with `SearchTimeoutError` if it has not settled after `ms` (never, for a non-finite `ms`). The work is not aborted - a late answer is just dropped. */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+/**
+ * Runs `task` for every item, at most `concurrency` at a time, starting them in order. Stops starting new ones once `isCancelled()` (the search
+ * was superseded) or once one has rejected - which is then this function's own rejection, after the ones already running have settled.
+ */
+export declare function runLimited<T>(items: readonly T[], concurrency: number, task: (item: T) => Promise<void>, isCancelled: () => boolean): Promise<void>;
+/** Why one mailbox's search failed, as a short phrase for the notice: the class of failure, never the server's own text. */
+export declare function classifyFailure(err: unknown): string;
+/** A mailbox that could not be (fully) searched. `encrypted` is set when only its Tier 3 pass (the encrypted mail) failed - its other results are in. */
+export interface MailboxFailure {
+    mailboxUid: string;
+    /** The mailbox's display name, as it was when the search ran. */
+    mailboxName: string;
+    encrypted: boolean;
+    reason: string;
+}
+/** The body of the "Some results may be missing" notice: which mailboxes, and why each. */
+export declare function describeFailures(failures: readonly MailboxFailure[]): string;

package/dist/apps/shared/search/crossMailboxSearch.js

@@ -0,0 +1,136 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The pieces of searching several mailboxes at once (Mail's "All mailboxes" views, and a search widened from one mailbox's folder to every
+ * mailbox the reader can read). Nothing here talks to the server: `apps/www/index.tsx` fans its own per-mailbox pipeline (Tier 1 server search,
+ * Tier 2 local index, Tier 3 server-narrowed encrypted candidates) out across mailboxes and uses these to bound that fan-out, to merge what
+ * comes back into one ranked list and to say, in words, which mailbox could not be searched and why.
+ *
+ * A search of one mailbox is the same code with a list of one: nothing here changes what that returns.
+ */
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { normalizeServerScores } from "@rapidmx/react-shared/search/searchScoring.js";
+/**
+ * How far a cross-mailbox search fans out. Exported (and mutable) so a test can shrink them instead of building 26 mailboxes or waiting a
+ * minute for a timeout; nothing else writes to it.
+ */
+export const SEARCH_LIMITS = {
+    /** How many mailboxes are worked on at once. */
+    concurrency: 4,
+    /** The most mailboxes one search covers - the caller's own first, then the shared ones (`orderMailboxes()`); a note says how many were left out. */
+    maxMailboxes: 25,
+    /** How long one mailbox's Tier 1 (server) request may take before that mailbox is given up on, so one wedged mailbox cannot hold the search. */
+    tier1TimeoutMs: 15000,
+    /** The same for a mailbox's Tier 3 pass (fetching and decrypting up to a couple of hundred candidates, so much longer). */
+    tier3TimeoutMs: 60000,
+    /** The most result rows a search keeps on screen (the page's own cap for a list, `MAX_LOADED_ROWS`, applies to a search too). */
+    maxRows: 500,
+};
+/** The least a mailbox is asked for on one page while several are searched, so a search over many mailboxes still moves at a sensible pace. */
+const MIN_MAILBOX_PAGE_SIZE = 10;
+/**
+ * How many results each mailbox contributes to one page. One mailbox gives the whole page; with several the page is shared out between them
+ * (never below `MIN_MAILBOX_PAGE_SIZE`), so the merged first page stays about one page long instead of growing by the number of mailboxes.
+ */
+export function searchPageSize(mailboxCount, pageSize) {
+    return Math.max(MIN_MAILBOX_PAGE_SIZE, Math.ceil(pageSize / Math.max(1, mailboxCount)));
+}
+export function tagHits(mailboxUid, hits) {
+    return hits.map((hit) => ({ ...hit, mailboxUid }));
+}
+/** One hit's identity across mailboxes: the same entity uid found in two mailboxes is two hits. */
+export function hitKey(hit) {
+    return `${hit.mailboxUid}\u0000${hit.entityUid}`;
+}
+/**
+ * Merges Tier 1 (server, possibly `metadataOnly` for an encrypted message), Tier 2 (local index, fully decrypted and re-scored) and Tier 3
+ * (server-narrowed candidates, decrypted and re-scored) results into one ranked list, per `specs/search.md` §7's "client MUST re-score all
+ * results it can see... normalise into the same space rather than interleaving raw scores": each tier is normalized independently via
+ * `normalizeServerScores()` before merging, since a Postgres/OpenSearch score, a local `bm25()` score, and Tier 3's own term-count score all
+ * occupy unrelated ranges. A hit present in more than one list keeps only the last-inserted entry (Tier 2 wins over Tier 3 wins over Tier 1) -
+ * Tier 2 and Tier 3 both represent genuine, content-verified scores for the same message, so which one "wins" on overlap doesn't change
+ * correctness, only which of two equally-valid scores is shown; either supersedes Tier 1's metadata-only guess for the same message.
+ *
+ * Each tier's list is pooled across every mailbox searched before it is normalized, so one mailbox's best hit is not automatically "1.0"
+ * next to another's: the ranking is the same rule as for one mailbox, applied to the merged lists. A hit's identity is its mailbox and its
+ * entity uid (`hitKey()`), so the same uid can only collapse within a mailbox. Ties keep the order the lists were given in (a stable sort), which
+ * the caller makes the mailboxes' display order.
+ *
+ * Called progressively - each time with whatever tiers have reported so far (an empty array for the rest). Pure and stateless.
+ */
+export function mergeSearchResults(tier1, tier2, tier3) {
+    const merged = new Map();
+    for (const tier of [tier1, tier3, tier2]) {
+        for (const entry of normalizeServerScores(tier)) {
+            merged.set(hitKey(entry.result), entry);
+        }
+    }
+    return Array.from(merged.values())
+        .sort((a, b) => b.normalizedScore - a.normalizedScore)
+        .map((entry) => entry.result);
+}
+/** Raised by `withTimeout()`. */
+export class SearchTimeoutError extends Error {
+    constructor() {
+        super("The search took too long.");
+        this.name = "SearchTimeoutError";
+    }
+}
+/** `promise`, or a rejection with `SearchTimeoutError` if it has not settled after `ms` (never, for a non-finite `ms`). The work is not aborted - a late answer is just dropped. */
+export function withTimeout(promise, ms) {
+    if (!Number.isFinite(ms)) {
+        return promise;
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new SearchTimeoutError()), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (reason) => {
+            clearTimeout(timer);
+            reject(reason);
+        });
+    });
+}
+/**
+ * Runs `task` for every item, at most `concurrency` at a time, starting them in order. Stops starting new ones once `isCancelled()` (the search
+ * was superseded) or once one has rejected - which is then this function's own rejection, after the ones already running have settled.
+ */
+export async function runLimited(items, concurrency, task, isCancelled) {
+    let next = 0;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && !isCancelled() && next < items.length) {
+            const item = items[next++];
+            try {
+                await task(item);
+            }
+            catch (err) {
+                failed = true;
+                throw err;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+}
+/** Why one mailbox's search failed, as a short phrase for the notice: the class of failure, never the server's own text. */
+export function classifyFailure(err) {
+    if (err instanceof SearchTimeoutError) {
+        return "timed out";
+    }
+    if (err instanceof ApiRequestError) {
+        if (err.status === 401 || err.status === 403) {
+            return "access denied";
+        }
+        return err.status >= 500 ? "server error" : "rejected by the server";
+    }
+    return "network error";
+}
+/** The body of the "Some results may be missing" notice: which mailboxes, and why each. */
+export function describeFailures(failures) {
+    return `${failures
+        .map((failure) => `${failure.mailboxName} (${failure.encrypted ? "encrypted mail: " : ""}${failure.reason})`)
+        .join(", ")} could not be searched.`;
+}