@rapidmx/web-client 0.9.0 → 0.11.0

package/apps/shared/mail/newMailNotifications.ts

@@ -0,0 +1,183 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { Folder, Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { formatMailAddress, splitMailAddress } from "@rapidmx/react-shared/mail/mailAddress.js";
+
+/**
+ * What decides whether a new message is announced, what the announcement says, and the two settings behind it (both per
+ * browser, in `localStorage`): whether new-mail pop-ups are on at all, and what the user told the "turn on desktop
+ * notifications" offer.
+ *
+ * The announcement is built only from what the push event carries - the whole `Message`, including `bodyPreview` - and only
+ * ever as text: React escapes it on screen and the Notifications API takes plain strings, so nothing here is HTML.
+ */
+
+/** `localStorage` key of the pop-ups switch. Absent means on; `"off"` means the user turned them off. */
+export const NEW_MAIL_POPUPS_KEY = "rapidmx-new-mail-popups";
+
+/** `localStorage` key of the answer to the desktop-notifications offer: `"later"` (not now) or `"asked"` (they were asked). */
+export const DESKTOP_OFFER_KEY = "rapidmx-desktop-notifications-offer";
+
+/** How much of the body an announcement quotes. */
+export const PREVIEW_MAX_LENGTH = 140;
+
+/** A message received longer ago than this is not "new": mail imported or migrated in bulk arrives as `create` events too. */
+export const MAX_NEW_AGE_MS = 6 * 60 * 60 * 1000;
+
+/** The subject the server stores for an encrypted message (the real one is inside the ciphertext). */
+const ENCRYPTED_SUBJECT_PLACEHOLDER = "[...]";
+
+function readStorage(key: string): string | null {
+    try {
+        return localStorage.getItem(key);
+    } catch {
+        return null;
+    }
+}
+
+function writeStorage(key: string, value: string | null): void {
+    try {
+        if (value === null) {
+            localStorage.removeItem(key);
+        } else {
+            localStorage.setItem(key, value);
+        }
+    } catch {
+        // Storage blocked or full: the choice lasts until the page is reloaded, no longer.
+    }
+}
+
+/** Whether new-mail pop-ups are on (the default). */
+export function getNewMailPopupsEnabled(): boolean {
+    return readStorage(NEW_MAIL_POPUPS_KEY) !== "off";
+}
+
+export function setNewMailPopupsEnabled(enabled: boolean): void {
+    writeStorage(NEW_MAIL_POPUPS_KEY, enabled ? null : "off");
+}
+
+/** Whether the "turn on desktop notifications" offer has been put away with "Not now" (or answered). */
+export function getDesktopOfferDismissed(): boolean {
+    return readStorage(DESKTOP_OFFER_KEY) !== null;
+}
+
+export function setDesktopOfferDismissed(dismissed: boolean): void {
+    writeStorage(DESKTOP_OFFER_KEY, dismissed ? "later" : null);
+}
+
+/** The browser's notification permission, or `"unsupported"` where there is no Notifications API. */
+export type DesktopPermission = NotificationPermission | "unsupported";
+
+export function desktopPermission(): DesktopPermission {
+    return typeof Notification === "undefined" ? "unsupported" : Notification.permission;
+}
+
+/** Asks the browser for permission - call it from a click. Resolves the answer; never rejects. */
+export async function requestDesktopPermission(): Promise<DesktopPermission> {
+    if (typeof Notification === "undefined") {
+        return "unsupported";
+    }
+    try {
+        return await Notification.requestPermission();
+    } catch {
+        return desktopPermission();
+    }
+}
+
+/** What an announcement shows. */
+export interface NewMailNotice {
+    /** The message's uid: the announcement's identity (and the desktop notification's `tag`). */
+    uid: string;
+    mailboxUid: string;
+    folderUid: string;
+    /** The sender's display name, `""` when there is none. */
+    senderName: string;
+    /** The sender's address - always shown, so a name can't stand in for who really sent it. */
+    senderAddress: string;
+    subject: string;
+    /** About `PREVIEW_MAX_LENGTH` characters of the body as plain text; `Encrypted message` for an encrypted one. */
+    preview: string;
+    /** Where opening it goes. */
+    href: string;
+}
+
+/** Control characters, and the invisible or bidirectional-override characters that can make text read as something else, as code point ranges. */
+const UNWANTED_RANGES: [number, number][] = [
+    [0x0000, 0x001f],
+    [0x007f, 0x009f],
+    [0x200b, 0x200f],
+    [0x2028, 0x202e],
+    [0x2060, 0x2064],
+    [0x2066, 0x2069],
+    [0xfeff, 0xfeff],
+];
+const hex = (code: number) => "\\u" + code.toString(16).padStart(4, "0");
+const UNWANTED = new RegExp("[" + UNWANTED_RANGES.map(([from, to]) => hex(from) + "-" + hex(to)).join("") + "]+", "g");
+
+/** `text` with those characters replaced by spaces, whitespace folded, and cut to `max` characters (with an ellipsis). */
+export function cleanPreview(text: string, max: number = PREVIEW_MAX_LENGTH): string {
+    const cleaned = text.replace(UNWANTED, " ").replace(/\s+/g, " ").trim();
+    return cleaned.length > max ? cleaned.slice(0, max - 1).trimEnd() + String.fromCharCode(0x2026) : cleaned;
+}
+
+/** The text of an announcement of `message`. */
+export function noticeFor(message: Message): NewMailNotice {
+    const { name, address } = splitMailAddress(message.from);
+    const encrypted = message.encrypted === true;
+    const rawSubject = cleanPreview(message.subject ?? "", 200);
+    const subject =
+        !rawSubject || rawSubject === ENCRYPTED_SUBJECT_PLACEHOLDER ? (encrypted ? "(encrypted subject)" : "(no subject)") : rawSubject;
+    return {
+        uid: message.uid,
+        mailboxUid: message.mailboxUid,
+        folderUid: message.folderUid,
+        // `splitMailAddress()` has already taken control and bidirectional-override characters out of both.
+        senderName: name ?? "",
+        senderAddress: address,
+        subject,
+        preview: encrypted ? "Encrypted message" : cleanPreview(message.bodyPreview ?? ""),
+        href: `/messages/${encodeURIComponent(message.uid)}`,
+    };
+}
+
+/** Every address that is this user's own, lowercased - a message from one of them is not new mail worth announcing. */
+export function ownAddressesOf(mailboxes: Mailbox[]): Set<string> {
+    const own = new Set<string>();
+    for (const mailbox of mailboxes) {
+        for (const address of [mailbox.primarySmtpAddress, ...(mailbox.aliasAddresses ?? [])]) {
+            if (address) {
+                own.add(address.trim().toLowerCase());
+            }
+        }
+    }
+    return own;
+}
+
+/**
+ * Whether the arrival of `message` is worth announcing: unread mail in an Inbox (not Drafts, Sent Items, Outbox, Deleted Items,
+ * Junk Email or quarantine, which are other folders), that Focused Inbox did not put under Other, that its own user did not
+ * send, and that is not old (a bulk import).
+ */
+export function shouldAnnounce(
+    message: Message,
+    context: { folders: Folder[]; ownAddresses: Set<string>; now?: number },
+): boolean {
+    if (context.folders.find((folder) => folder.uid === message.folderUid)?.type !== "inbox") {
+        return false;
+    }
+    if (message.flags.read === true || message.inferenceClassification === "other") {
+        return false;
+    }
+    if (context.ownAddresses.has((message.from?.address ?? "").trim().toLowerCase())) {
+        return false;
+    }
+    const received = Date.parse(message.receivedDate);
+    return Number.isNaN(received) || (context.now ?? Date.now()) - received < MAX_NEW_AGE_MS;
+}
+
+/** `Name <address>`, or the address alone - the desktop notification's title. */
+export function noticeSender(notice: Pick<NewMailNotice, "senderName" | "senderAddress">): string {
+    return formatMailAddress({ address: notice.senderAddress, displayName: notice.senderName || undefined });
+}

package/apps/shared/mail/outbox/UnlockBridge.tsx

@@ -0,0 +1,23 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect } from "react";
+import { useUnlockPrompt } from "../../components/layout/UnlockPromptProvider.js";
+import { registerUnlockOpener } from "./composeBridge.js";
+
+/**
+ * Lets code with no React context - a pop-up's "Unlock" action - open the app's one unlock prompt (`UnlockPromptProvider`). Renders nothing;
+ * mounted once, inside the provider it reaches.
+ */
+export default function UnlockBridge(): null {
+    const { requestUnlock } = useUnlockPrompt();
+    useEffect(
+        () =>
+            registerUnlockOpener(async (mailboxUid, keys) => {
+                await requestUnlock(mailboxUid, keys);
+            }),
+        [requestUnlock],
+    );
+    return null;
+}

package/apps/shared/mail/outbox/composeBridge.ts

@@ -0,0 +1,69 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { Attachment, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+
+/**
+ * A compose window to re-open around a message that was already composed: a failed send's "Open draft". The message keeps its uid - the
+ * server draft it was assembled into - and everything the sender had typed comes back exactly as it was, including what could not have
+ * been read back from the server (the plain text of a message that was encrypted before it was stored).
+ */
+export interface ResumeCompose {
+    /** The server draft the window continues - it must be in Drafts (a message that is in Outbox is moved back first). */
+    draft: Message;
+    mailboxUid: string;
+    to: string;
+    cc: string;
+    bcc: string;
+    subject: string;
+    html: string;
+    attachments: Attachment[];
+    requestReceipt: boolean;
+    signEnabled: boolean;
+    encryptRequested: boolean;
+}
+
+/** What the app frame's compose provider offers to code that has no React context (a pop-up's action, a push-event handler). */
+export interface ComposeOpenerInput {
+    mailboxUid?: string;
+    resume?: ResumeCompose;
+}
+
+let opener: ((input: ComposeOpenerInput) => void) | undefined;
+let unlocker: ((mailboxUid: string, keys: PublicKey[]) => Promise<void>) | undefined;
+
+/** Registered by `ComposeProvider`; returns the function that unregisters it. */
+export function registerComposeOpener(open: (input: ComposeOpenerInput) => void): () => void {
+    opener = open;
+    return () => {
+        if (opener === open) {
+            opener = undefined;
+        }
+    };
+}
+
+/** Opens a compose window from outside React. `false` when no compose provider is mounted (nothing was opened). */
+export function openComposeFromOutside(input: ComposeOpenerInput): boolean {
+    if (!opener) {
+        return false;
+    }
+    opener(input);
+    return true;
+}
+
+/** Registered by the unlock prompt's owner; returns the function that unregisters it. */
+export function registerUnlockOpener(unlock: (mailboxUid: string, keys: PublicKey[]) => Promise<void>): () => void {
+    unlocker = unlock;
+    return () => {
+        if (unlocker === unlock) {
+            unlocker = undefined;
+        }
+    };
+}
+
+/** Opens the existing unlock prompt from outside React. Resolves once the keys are unlocked; rejects when the user dismissed it (or there is no prompt). */
+export function requestUnlockFromOutside(mailboxUid: string, keys: PublicKey[]): Promise<void> {
+    return unlocker ? unlocker(mailboxUid, keys) : Promise.reject(new Error("No unlock prompt is available."));
+}

package/apps/shared/mail/outbox/outboxState.ts

@@ -0,0 +1,88 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+
+/**
+ * What a message in Outbox is doing, read from the fields the server keeps on it (`scheduledSend*`):
+ *
+ * These are the server's own definitions (`@rapidmx/restapi`'s background send):
+ *
+ * - `sending`: a lease (`scheduledSendLeaseExpiresAt`) is running, or a *due* `scheduledSendTime` with no failed attempts yet - a message
+ * queued for the server's worker (a background send is queued as an ordinary due message, `scheduledSendTime` = when it was queued);
+ * - `retrying`: `scheduledSendAttempts > 0` with a later `scheduledSendTime` (or a lease on one): a delivery attempt failed and the server
+ * will try again;
+ * - `failed`: `scheduledSendError` set and no `scheduledSendTime` - the server gave up; it stays in Outbox, waiting for the user to retry
+ * (the same send call again) or to open it (back to Drafts is allowed, it is not in flight);
+ * - `scheduled`: a send-later message whose time has not come.
+ *
+ * "Due" is judged against the message's own `dateModified` as well as the clock: a background send's `scheduledSendTime` is set by the server
+ * at the moment it queued the message, so a browser whose clock runs behind must not read it as a send scheduled for the future.
+ */
+export type OutboxItemState = "sending" | "retrying" | "failed" | "scheduled";
+
+export interface OutboxItemStatus {
+    state: OutboxItemState;
+    /** Failed delivery attempts so far (`retrying`). */
+    attempts: number;
+    /** Why it failed (`failed`). */
+    error?: string;
+    /** When it will be sent or tried again (`scheduled`, `retrying`), epoch ms. */
+    at?: number;
+}
+
+/** A `scheduledSendTime` this close to the message's last modification was set by the server as "now": a due message, not a scheduled one. */
+export const DUE_SLACK_MS = 2_000;
+
+export function outboxItemStatus(message: Message, now: number = Date.now()): OutboxItemStatus {
+    const attempts = message.scheduledSendAttempts ?? 0;
+    const lease = message.scheduledSendLeaseExpiresAt ? Date.parse(message.scheduledSendLeaseExpiresAt) : NaN;
+    const at = message.scheduledSendTime ? Date.parse(message.scheduledSendTime) : NaN;
+    if (message.scheduledSendError && !message.scheduledSendTime && !(lease > now)) {
+        return { state: "failed", attempts, error: message.scheduledSendError };
+    }
+    if (lease > now) {
+        return { state: attempts > 0 ? "retrying" : "sending", attempts };
+    }
+    if (attempts > 0) {
+        return { state: "retrying", attempts, at: Number.isNaN(at) ? undefined : at };
+    }
+    const modified = message.dateModified ? Date.parse(message.dateModified) : NaN;
+    const dueWhenModified = at - modified <= DUE_SLACK_MS;
+    if (at > now && !dueWhenModified) {
+        return { state: "scheduled", attempts, at };
+    }
+    return { state: "sending", attempts };
+}
+
+/** How many messages of each kind an Outbox folder holds. */
+export interface OutboxFolderStatus {
+    sending: number;
+    retrying: number;
+    failed: number;
+    scheduled: number;
+}
+
+export const EMPTY_OUTBOX_STATUS: OutboxFolderStatus = { sending: 0, retrying: 0, failed: 0, scheduled: 0 };
+
+export function summarizeOutbox(messages: Message[], now: number = Date.now()): OutboxFolderStatus {
+    const status = { ...EMPTY_OUTBOX_STATUS };
+    for (const message of messages) {
+        status[outboxItemStatus(message, now).state] += 1;
+    }
+    return status;
+}
+
+/** The text a screen reader gets for an Outbox count, and the tooltip: "2 messages sending", "3 messages, 1 failed". */
+export function outboxLabel(total: number, status: OutboxFolderStatus | undefined, pendingHere: number): string {
+    const noun = `${total} ${total === 1 ? "message" : "messages"}`;
+    if (status && status.failed > 0) {
+        return `${noun}, ${status.failed} failed`;
+    }
+    const inFlight = (status ? status.sending + status.retrying : 0) + pendingHere;
+    if (inFlight > 0) {
+        return `${noun} sending`;
+    }
+    return status && status.scheduled > 0 && status.scheduled === total ? `${noun} scheduled` : noun;
+}

package/apps/shared/mail/outbox/pendingSends.ts

@@ -0,0 +1,146 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useSyncExternalStore } from "react";
+import { registerComposeFlush } from "../../components/mail/compose/composeFlushRegistry.js";
+
+/**
+ * The messages this tab has been asked to send whose *client-side* work is not finished: assembling (and encrypting/signing, which takes
+ * a moment) and the request that hands them to the server. Once the server has answered `202 queued` a message is safe - the server
+ * owns it, and the Outbox folder's own count, list and push events say the rest - so it leaves this set.
+ *
+ * What this is for: the Outbox indicator counts these at once (before the server has heard of the message), a message in this set is
+ * why the tab asks "Leave site?" (`beforeunload`) and why Sign Out waits a moment before ending the session, and a second Send of the same
+ * draft is refused while it is here.
+ */
+export type PendingStage = "preparing" | "queuing";
+
+export interface PendingSend {
+    /** The draft's uid: one send per draft at a time. */
+    draftUid: string;
+    mailboxUid: string;
+    subject: string;
+    /** Every recipient's address. */
+    recipients: string[];
+    stage: PendingStage;
+    /** A send-later message: it goes to Outbox and waits for its time, rather than being relayed. */
+    scheduled: boolean;
+    startedAt: number;
+}
+
+const NO_SENDS: readonly PendingSend[] = [];
+let pending: PendingSend[] = [];
+let snapshot: readonly PendingSend[] = pending;
+const listeners = new Set<() => void>();
+let stopFlush: (() => void) | undefined;
+let waiters: (() => void)[] = [];
+
+function emit(): void {
+    snapshot = [...pending];
+    for (const listener of [...listeners]) {
+        listener();
+    }
+}
+
+/** `beforeunload`: leaving now would lose a message the server has not received. */
+function handleBeforeUnload(event: BeforeUnloadEvent): void {
+    // Only installed while something is pending (see `syncGuards()`).
+    event.preventDefault();
+    event.returnValue = "";
+}
+
+/** Installs the `beforeunload` prompt and the sign-out wait while a send is pending, and takes them away when none is. Only ever called from a browser. */
+function syncGuards(): void {
+    if (pending.length > 0 && !stopFlush) {
+        window.addEventListener("beforeunload", handleBeforeUnload);
+        // Sign Out flushes compose windows before it ends the session; a message still being prepared is waited for there too.
+        stopFlush = registerComposeFlush(() => whenSettled(20_000));
+    } else if (pending.length === 0 && stopFlush) {
+        window.removeEventListener("beforeunload", handleBeforeUnload);
+        stopFlush();
+        stopFlush = undefined;
+    }
+    if (pending.length === 0) {
+        const done = waiters;
+        waiters = [];
+        for (const resolve of done) {
+            resolve();
+        }
+    }
+}
+
+/** Whether a send of this draft is under way in this tab. */
+export function isSendPending(draftUid: string): boolean {
+    return pending.some((entry) => entry.draftUid === draftUid);
+}
+
+/** Starts tracking a send. `false` (and nothing tracked) when this draft is already being sent - the caller must not send it again. */
+export function beginPendingSend(entry: Omit<PendingSend, "stage" | "startedAt">): boolean {
+    if (isSendPending(entry.draftUid)) {
+        return false;
+    }
+    pending.push({ ...entry, stage: "preparing", startedAt: Date.now() });
+    syncGuards();
+    emit();
+    return true;
+}
+
+export function setPendingStage(draftUid: string, stage: PendingStage): void {
+    pending = pending.map((entry) => (entry.draftUid === draftUid ? { ...entry, stage } : entry));
+    emit();
+}
+
+/** The server has the message (or the attempt failed and is now the user's to resolve): it is no longer this tab's work. */
+export function finishPendingSend(draftUid: string): void {
+    pending = pending.filter((entry) => entry.draftUid !== draftUid);
+    syncGuards();
+    emit();
+}
+
+export function getPendingSends(): readonly PendingSend[] {
+    return snapshot;
+}
+
+export function subscribePendingSends(listener: () => void): () => void {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+
+/** How many messages of `mailboxUid` are still being handed to the server: what the Outbox pill adds to its server count at once. */
+export function pendingCountFor(mailboxUid: string, sends: readonly PendingSend[] = snapshot): number {
+    return sends.filter((entry) => entry.mailboxUid === mailboxUid).length;
+}
+
+/** Resolves (to whether everything settled) when no send is pending, or after `timeoutMs`. */
+export function whenSettled(timeoutMs: number): Promise<boolean> {
+    if (pending.length === 0) {
+        return Promise.resolve(true);
+    }
+    return new Promise<boolean>((resolve) => {
+        const timer = setTimeout(() => {
+            waiters = waiters.filter((waiter) => waiter !== done);
+            resolve(false);
+        }, timeoutMs);
+        function done() {
+            clearTimeout(timer);
+            resolve(true);
+        }
+        waiters.push(done);
+    });
+}
+
+/** The messages being sent, for a component. */
+export function usePendingSends(): readonly PendingSend[] {
+    return useSyncExternalStore(subscribePendingSends, getPendingSends, () => NO_SENDS);
+}
+
+/** Forgets everything - for a test. */
+export function resetPendingSends(): void {
+    pending = [];
+    waiters = [];
+    syncGuards();
+    emit();
+}