@rapidmx/web-client 0.20.0 → 0.22.0

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

@@ -1,155 +1,160 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import { Message, cancelScheduledSend, getMessage, listAttachments, listFolders, queueMessageSend } from "@rapidmx/react-shared/mail/mailApi.js";
-import { SendEvent, describeSendEventError } from "@rapidmx/react-shared/mail/sendEvents.js";
-import { formatRecipient } from "../../components/mail/compose/recipients.js";
-import { loadOriginalMessage } from "../../components/mail/compose/quotedBody.js";
-import { notifyApiError } from "../../notifications/apiErrors.js";
-import { dismiss, notify } from "../../notifications/store.js";
-import { beginPendingSend, finishPendingSend, setPendingStage } from "./pendingSends.js";
-import { failOutgoing, forgetOutgoing, markOutgoingSending, markOutgoingSent } from "./outgoingReplies.js";
-import { openComposeFromOutside } from "./composeBridge.js";
-import { describeMessage, forgetRetainedRequest, notifySent, openDraftFromRequest, retainedRequest } from "./sendJob.js";
-
-/**
- * What the user is told when the server reports how a queued message went (`send-succeeded`, `send-failed`, `send-retrying` push events,
- * see `@rapidmx/react-shared`'s `parseSendEvent()`): a quiet, single "Message sent" for a message this tab sent (several close together are
- * one pop-up counting up), an info pop-up when a delivery is retried, and - only when it finally failed - the sticky "This message wasn't sent" with the
- * server's reason, its technical details and what to do about it. The Outbox count, list and pill update themselves from the same events
- * (`useMailLiveUpdates()` refreshes on them).
- */
-
-const retryId = (uid: string) => `send-retry:${uid}`;
-const failedId = (uid: string) => `send-failed:${uid}`;
-
-function summary(recipients: string[]): string {
-    return recipients.length <= 2 ? recipients.join(" and ") : `${recipients[0]} and ${recipients.length - 1} others`;
-}
-
-/** Moves a message the server failed to relay back into Drafts (the only place it can be edited or sent again), and returns it as it is there. */
-async function moveBackToDrafts(uid: string, mailboxUid: string): Promise<Message> {
-    const message = await getMessage(uid);
-    const drafts = (await listFolders(mailboxUid)).find((folder) => folder.type === "drafts");
-    if (!drafts || message.folderUid === drafts.uid) {
-        return message;
-    }
-    return cancelScheduledSend(message, drafts.uid);
-}
-
-function escapeHtml(text: string): string {
-    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-
-/** "Open draft" for a message the server failed to relay: back into Drafts, and into a compose window with what was written. */
-async function openFailedDraft(event: SendEvent): Promise<void> {
-    try {
-        const moved = await moveBackToDrafts(event.uid, event.mailboxUid ?? "");
-        // Back in Drafts it is no longer a message on its way in its conversation.
-        forgetOutgoing(event.uid);
-        const request = retainedRequest(event.uid);
-        if (request) {
-            openDraftFromRequest({ ...request, draft: moved });
-            return;
-        }
-        if (moved.encrypted) {
-            notify({
-                id: `open-draft:${event.uid}`,
-                kind: "info",
-                title: "This message is encrypted",
-                message: "It was moved back to Drafts, but it can only be edited in the tab that wrote it. Open it from Drafts to send it again.",
-                timeoutMs: 8_000,
-            });
-            return;
-        }
-        const original = await loadOriginalMessage(moved, null);
-        const attachments = await listAttachments(moved.folderUid, moved.uid).catch(() => []);
-        const byType = (type: "to" | "cc" | "bcc") => moved.recipients.filter((recipient) => recipient.type === type).map(formatRecipient).join(", ");
-        openComposeFromOutside({
-            mailboxUid: moved.mailboxUid,
-            resume: {
-                draft: moved,
-                mailboxUid: moved.mailboxUid,
-                to: byType("to"),
-                cc: byType("cc"),
-                bcc: byType("bcc"),
-                subject: moved.subject ?? event.subject,
-                html: original.body.html ?? (original.body.text ? `<p>${escapeHtml(original.body.text).replace(/\r?\n/g, "<br>")}</p>` : ""),
-                attachments,
-                requestReceipt: !!moved.requestReceipt,
-                signEnabled: true,
-                encryptRequested: false,
-            },
-        });
-    } catch (err) {
-        notifyApiError(err, "Couldn't open this draft");
-    }
-}
-
-/** "Retry" for a message the server failed to relay: the same send call again - a failed message stays in Outbox and the server queues it afresh (with a new retry budget). */
-async function retryFailed(event: SendEvent): Promise<void> {
-    if (!beginPendingSend({ draftUid: event.uid, mailboxUid: event.mailboxUid ?? "", subject: event.subject, recipients: event.recipients, scheduled: false })) {
-        return;
-    }
-    dismiss(failedId(event.uid));
-    markOutgoingSending(event.uid);
-    try {
-        setPendingStage(event.uid, "queuing");
-        const result = await queueMessageSend(event.uid);
-        if (!result.queued) {
-            notifySent();
-        }
-    } catch (err) {
-        notifyApiError(err, "This message wasn't sent", { dedupeKey: failedId(event.uid) });
-    } finally {
-        finishPendingSend(event.uid);
-    }
-}
-
-/** Shows what a send event means to the user. */
-export function handleSendEvent(event: SendEvent): void {
-    if (event.action === "send-succeeded") {
-        dismiss(retryId(event.uid));
-        dismiss(failedId(event.uid));
-        // The conversation on screen swaps the message it drew for the Sent Items copy (a message this tab did not send has nothing drawn).
-        markOutgoingSent(event.uid);
-        // The server reports every message it relays, scheduled ones from long ago included: only a message this tab queued in the background is
-        // worth a confirmation (several are one pop-up counting up). Anything else - a send-later message going out, another tab's send - is quiet.
-        if (retainedRequest(event.uid)) {
-            forgetRetainedRequest(event.uid);
-            notifySent();
-        }
-        return;
-    }
-    const failure = describeSendEventError(event.error, event.action === "send-failed" ? "The server couldn't send this message." : "The server couldn't send this message yet.");
-    const what = describeMessage(event.subject, summary(event.recipients));
-    if (event.action === "send-retrying") {
-        const next = event.nextAttemptAt ? Date.parse(event.nextAttemptAt) : NaN;
-        notify({
-            id: retryId(event.uid),
-            kind: "info",
-            title: "Retrying to send",
-            message: `${what} (attempt ${event.attempt + 1}${Number.isNaN(next) ? "" : `, at ${new Date(next).toLocaleTimeString()}`}). ${failure.message}`,
-            details: failure.lines,
-            sticky: false,
-            timeoutMs: 8_000,
-        });
-        return;
-    }
-    dismiss(retryId(event.uid));
-    const actions = [
-        { label: "Retry", onClick: () => void retryFailed(event) },
-        { label: "Open draft", onClick: () => void openFailedDraft(event) },
-    ];
-    notify({
-        id: failedId(event.uid),
-        kind: "error",
-        title: "This message wasn't sent",
-        message: `${what}: ${failure.message}`,
-        details: failure.lines,
-        actions,
-    });
-    // The conversation on screen shows the same failure under the message, with the same ways out.
-    failOutgoing(event.uid, failure.message, actions);
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { Message, cancelScheduledSend, getMessage, listAttachments, listFolders, queueMessageSend } from "../../../../lib/mail/mailApi.js";
+import { SendEvent, describeSendEventError } from "../../../../lib/mail/sendEvents.js";
+import type { ApiClient } from "../../../../lib/util/api.js";
+import { formatRecipient } from "../../components/mail/compose/recipients.js";
+import { loadOriginalMessage } from "../../components/mail/compose/quotedBody.js";
+import { notifyApiError } from "../../notifications/apiErrors.js";
+import { dismiss, notify } from "../../notifications/store.js";
+import { beginPendingSend, finishPendingSend, setPendingStage } from "./pendingSends.js";
+import { failOutgoing, forgetOutgoing, markOutgoingSending, markOutgoingSent } from "./outgoingReplies.js";
+import { openComposeFromOutside } from "./composeBridge.js";
+import { describeMessage, forgetRetainedRequest, notifySent, openDraftFromRequest, retainedRequest } from "./sendJob.js";
+
+/**
+ * What the user is told when the server reports how a queued message went (`send-succeeded`, `send-failed`, `send-retrying` push events,
+ * see `@rapidmx/react-shared`'s `parseSendEvent()`): a quiet, single "Message sent" for a message this tab sent (several close together are
+ * one pop-up counting up), an info pop-up when a delivery is retried, and - only when it finally failed - the sticky "This message wasn't sent" with the
+ * server's reason, its technical details and what to do about it. The Outbox count, list and pill update themselves from the same events
+ * (`useMailLiveUpdates()` refreshes on them).
+ */
+
+const retryId = (uid: string) => `send-retry:${uid}`;
+const failedId = (uid: string) => `send-failed:${uid}`;
+
+function summary(recipients: string[]): string {
+    return recipients.length <= 2 ? recipients.join(" and ") : `${recipients[0]} and ${recipients.length - 1} others`;
+}
+
+/** Moves a message the server failed to relay back into Drafts (the only place it can be edited or sent again), and returns it as it is there. */
+async function moveBackToDrafts(uid: string, mailboxUid: string, client: ApiClient | undefined): Promise<Message> {
+    const message = await getMessage(uid, client);
+    const drafts = (await listFolders(mailboxUid, client)).find((folder) => folder.type === "drafts");
+    if (!drafts || message.folderUid === drafts.uid) {
+        return message;
+    }
+    return cancelScheduledSend(message, drafts.uid, client);
+}
+
+function escapeHtml(text: string): string {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** "Open draft" for a message the server failed to relay: back into Drafts, and into a compose window with what was written. */
+async function openFailedDraft(event: SendEvent, client: ApiClient | undefined): Promise<void> {
+    try {
+        const moved = await moveBackToDrafts(event.uid, event.mailboxUid ?? "", client);
+        // Back in Drafts it is no longer a message on its way in its conversation.
+        forgetOutgoing(event.uid);
+        const request = retainedRequest(event.uid);
+        if (request) {
+            openDraftFromRequest({ ...request, draft: moved });
+            return;
+        }
+        if (moved.encrypted) {
+            notify({
+                id: `open-draft:${event.uid}`,
+                kind: "info",
+                title: "This message is encrypted",
+                message: "It was moved back to Drafts, but it can only be edited in the tab that wrote it. Open it from Drafts to send it again.",
+                timeoutMs: 8_000,
+            });
+            return;
+        }
+        // loadOriginalMessage() (quotedBody.ts) does not yet accept an explicit ApiClient itself - out of scope here (that module is not one of
+        // this task's files); it still falls back to the default global session even under an ApiClientContext.Provider.
+        const original = await loadOriginalMessage(moved, null);
+        const attachments = await listAttachments(moved.folderUid, moved.uid, client).catch(() => []);
+        const byType = (type: "to" | "cc" | "bcc") => moved.recipients.filter((recipient) => recipient.type === type).map(formatRecipient).join(", ");
+        openComposeFromOutside({
+            mailboxUid: moved.mailboxUid,
+            resume: {
+                draft: moved,
+                mailboxUid: moved.mailboxUid,
+                to: byType("to"),
+                cc: byType("cc"),
+                bcc: byType("bcc"),
+                subject: moved.subject ?? event.subject,
+                html: original.body.html ?? (original.body.text ? `<p>${escapeHtml(original.body.text).replace(/\r?\n/g, "<br>")}</p>` : ""),
+                attachments,
+                requestReceipt: !!moved.requestReceipt,
+                signEnabled: true,
+                encryptRequested: false,
+            },
+        });
+    } catch (err) {
+        notifyApiError(err, "Couldn't open this draft");
+    }
+}
+
+/** "Retry" for a message the server failed to relay: the same send call again - a failed message stays in Outbox and the server queues it afresh (with a new retry budget). */
+async function retryFailed(event: SendEvent, client: ApiClient | undefined): Promise<void> {
+    if (!beginPendingSend({ draftUid: event.uid, mailboxUid: event.mailboxUid ?? "", subject: event.subject, recipients: event.recipients, scheduled: false })) {
+        return;
+    }
+    dismiss(failedId(event.uid));
+    markOutgoingSending(event.uid);
+    try {
+        setPendingStage(event.uid, "queuing");
+        const result = await queueMessageSend(event.uid, client);
+        if (!result.queued) {
+            notifySent();
+        }
+    } catch (err) {
+        notifyApiError(err, "This message wasn't sent", { dedupeKey: failedId(event.uid) });
+    } finally {
+        finishPendingSend(event.uid);
+    }
+}
+
+/** Shows what a send event means to the user. `client` is the explicit `ApiClient` (from `useApiClient()`) whichever code observed this push
+ * event was rendered under - `undefined` (the default) for every existing caller, which keeps using the default global cookie-based session
+ * exactly as before. */
+export function handleSendEvent(event: SendEvent, client?: ApiClient): void {
+    if (event.action === "send-succeeded") {
+        dismiss(retryId(event.uid));
+        dismiss(failedId(event.uid));
+        // The conversation on screen swaps the message it drew for the Sent Items copy (a message this tab did not send has nothing drawn).
+        markOutgoingSent(event.uid);
+        // The server reports every message it relays, scheduled ones from long ago included: only a message this tab queued in the background is
+        // worth a confirmation (several are one pop-up counting up). Anything else - a send-later message going out, another tab's send - is quiet.
+        if (retainedRequest(event.uid)) {
+            forgetRetainedRequest(event.uid);
+            notifySent();
+        }
+        return;
+    }
+    const failure = describeSendEventError(event.error, event.action === "send-failed" ? "The server couldn't send this message." : "The server couldn't send this message yet.");
+    const what = describeMessage(event.subject, summary(event.recipients));
+    if (event.action === "send-retrying") {
+        const next = event.nextAttemptAt ? Date.parse(event.nextAttemptAt) : NaN;
+        notify({
+            id: retryId(event.uid),
+            kind: "info",
+            title: "Retrying to send",
+            message: `${what} (attempt ${event.attempt + 1}${Number.isNaN(next) ? "" : `, at ${new Date(next).toLocaleTimeString()}`}). ${failure.message}`,
+            details: failure.lines,
+            sticky: false,
+            timeoutMs: 8_000,
+        });
+        return;
+    }
+    dismiss(retryId(event.uid));
+    const actions = [
+        { label: "Retry", onClick: () => void retryFailed(event, client) },
+        { label: "Open draft", onClick: () => void openFailedDraft(event, client) },
+    ];
+    notify({
+        id: failedId(event.uid),
+        kind: "error",
+        title: "This message wasn't sent",
+        message: `${what}: ${failure.message}`,
+        details: failure.lines,
+        actions,
+    });
+    // The conversation on screen shows the same failure under the message, with the same ways out.
+    failOutgoing(event.uid, failure.message, actions);
+}

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

@@ -3,7 +3,8 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { useEffect, useMemo, useState } from "react";
-import { listMessages } from "@rapidmx/react-shared/mail/mailApi.js";
+import { listMessages } from "../../../../lib/mail/mailApi.js";
+import { useApiClient } from "../../../../lib/util/apiClientContext.js";
 import type { MailboxFolders } from "../../components/mail/layout/MailShell.js";
 import { FolderCount, countOfFolder } from "../folderCounts.js";
 import { OutboxFolderStatus, summarizeOutbox } from "./outboxState.js";
@@ -17,6 +18,7 @@ export const OUTBOX_STATUS_LIMIT = 50;
  * whenever that count or the live updates change, so an empty Outbox - almost always - is free. A failed read keeps what was known.
  */
 export function useOutboxStatus(mailboxFolders: MailboxFolders[], counts: Record<string, FolderCount>, liveTick: number, enabled: boolean): Record<string, OutboxFolderStatus> {
+    const client = useApiClient();
     const [statuses, setStatuses] = useState<Record<string, OutboxFolderStatus>>({});
     const outboxes = useMemo(
         () =>
@@ -43,7 +45,7 @@ export function useOutboxStatus(mailboxFolders: MailboxFolders[], counts: Record
         });
         let cancelled = false;
         for (const outbox of occupied) {
-            listMessages(outbox.uid, { limit: OUTBOX_STATUS_LIMIT }).then(
+            listMessages(outbox.uid, { limit: OUTBOX_STATUS_LIMIT }, client).then(
                 (messages) => {
                     if (!cancelled) {
                         setStatuses((previous) => ({ ...previous, [outbox.uid]: summarizeOutbox(messages) }));
@@ -55,7 +57,7 @@ export function useOutboxStatus(mailboxFolders: MailboxFolders[], counts: Record
         return () => {
             cancelled = true;
         };
-    }, [enabled, key, liveTick]);
+    }, [enabled, key, liveTick, client]);
 
     return statuses;
 }

package/apps/shared/mail/permanentDelete.ts

@@ -2,8 +2,8 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { Message, emptyFolder, listMessages, purgeMessage } from "@rapidmx/react-shared/mail/mailApi.js";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { Message, emptyFolder, listMessages, purgeMessage } from "../../../lib/mail/mailApi.js";
+import { ApiClient, ApiRequestError } from "../../../lib/util/api.js";
 import { displaySubject } from "../components/mail/reading/EncryptedPreview.js";
 import { notifySessionExpired } from "../notifications/apiErrors.js";
 import { notify } from "../notifications/store.js";
@@ -64,14 +64,14 @@ export function messageCount(count: number): string {
  * to delete, a message that is already gone) is recorded against its message and the rest carry on. `deleted` and `failed` keep the order of
  * `messages`.
  */
-export async function purgeMessages(messages: Message[]): Promise<PurgeOutcome> {
+export async function purgeMessages(messages: Message[], client?: ApiClient): Promise<PurgeOutcome> {
     const failures: (PurgeFailure | null)[] = new Array(messages.length).fill(null);
     let next = 0;
     async function worker(): Promise<void> {
         while (next < messages.length) {
             const index = next++;
             try {
-                await purgeMessage(messages[index].uid);
+                await purgeMessage(messages[index].uid, client);
             } catch (err) {
                 failures[index] = { message: messages[index], ...describeFailure(err) };
             }
@@ -93,17 +93,18 @@ export async function purgeMessages(messages: Message[]): Promise<PurgeOutcome>
 export async function purgeFolder(
     folderUid: string,
     paging: { pageSize: number; maxPages: number } = { pageSize: LIST_PAGE_SIZE, maxPages: MAX_LIST_PAGES },
+    client?: ApiClient,
 ): Promise<EmptyFolderOutcome> {
     try {
-        await emptyFolder(folderUid);
+        await emptyFolder(folderUid, client);
         return { emptied: true, deleted: [], failed: [] };
     } catch (err) {
         if (!(err instanceof ApiRequestError) || (err.status !== 403 && err.status !== 409)) {
             throw err;
         }
     }
-    const listed = await listAllPages((page) => listMessages(folderUid, { limit: paging.pageSize, page }), paging.pageSize, paging.maxPages);
-    const outcome = await purgeMessages(listed.items);
+    const listed = await listAllPages((page) => listMessages(folderUid, { limit: paging.pageSize, page }, client), paging.pageSize, paging.maxPages);
+    const outcome = await purgeMessages(listed.items, client);
     return { ...outcome, emptied: outcome.failed.length === 0 && !listed.truncated };
 }
 

package/apps/shared/mail/primaryMailbox.ts

@@ -17,7 +17,7 @@
  *
  * `orderMailboxes()` puts the primary mailbox first, then the caller's other mailboxes, then the shared ones, each group alphabetical.
  */
-import { isSharedWithMe, type Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { isSharedWithMe, type Mailbox } from "../../../lib/mail/mailApi.js";
 
 /** Whether `mailbox` is the signed-in user's own. */
 export function isOwnMailbox(mailbox: Mailbox, userUid: string | undefined): boolean {

package/apps/shared/mail/reportNotices.ts

@@ -1,66 +1,66 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import type { MessageReportKind, MessageReportResult } from "@rapidmx/react-shared/mail/mailApi.js";
-
-/** Where a notification's "Manage blocked senders" goes: the Blocked and safe senders page of the mailbox. */
-export function senderListsHref(mailboxUid: string): string {
-    return `/settings/blocked-senders?mailboxUid=${encodeURIComponent(mailboxUid)}`;
-}
-
-/** What a pop-up says about reporting `kind`: the title, and the folder the message goes to. */
-const KINDS: Record<MessageReportKind, { title: string; noun: string; folder: string }> = {
-    junk: { title: "Reported as junk", noun: "junk", folder: "Junk Email" },
-    phishing: { title: "Reported as phishing", noun: "phishing", folder: "Junk Email" },
-    not_junk: { title: "Marked as not junk", noun: "not junk", folder: "the Inbox" },
-};
-
-/** The noun of `kind` for a failure's title ("Couldn't report this message as phishing"). */
-export function reportNoun(kind: MessageReportKind): string {
-    return KINDS[kind].noun;
-}
-
-/** The title of a pop-up for a report of `kind`. */
-export function reportTitle(kind: MessageReportKind): string {
-    return KINDS[kind].title;
-}
-
-/** The name of the folder a report of `kind` files the message in. */
-export function reportFolderName(kind: MessageReportKind): string {
-    return KINDS[kind].folder;
-}
-
-/** What a pop-up for a report says. `hint` is the small muted line: only for the two things a reader may want to know about (the filter could not be
- * taught, or the message is encrypted so it was not), never for the ones that are simply how the server is set up. */
-export interface ReportNotice {
-    title: string;
-    message: string;
-    hint?: string;
-}
-
-/**
- * The words for what the server did with a report (`reportMessage()`'s answer): where the message went, whether the spam filter learned from it, and - for
- * a report of phishing - that the server recorded it. `subject` names the message. `alwaysTrust` says the reader asked for the sender to be trusted.
- */
-export function reportNotice(result: MessageReportResult, subject: string, alwaysTrust: boolean): ReportNotice {
-    const kind = KINDS[result.kind];
-    const where = result.moved ? `was moved to ${kind.folder}` : `is already in ${kind.folder}`;
-    const learned = result.learned ? " and used to train the spam filter" : "";
-    const parts = [`“${subject}” ${where}${learned}.`];
-    if (result.kind === "phishing") {
-        parts.push("The report was recorded in the audit log.");
-    }
-    if (result.safeSender) {
-        parts.push(`Mail from ${result.safeSender} that passes authentication is no longer sent to Junk Email.`);
-    } else if (alwaysTrust) {
-        parts.push("The message names no address that could be trusted.");
-    }
-    const hint =
-        result.learnSkipped === "failed"
-            ? "The spam filter could not be trained from this report."
-            : result.learnSkipped === "encrypted"
-              ? "Not used to train the spam filter: the message is encrypted."
-              : undefined;
-    return { title: kind.title, message: parts.join(" "), hint };
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { MessageReportKind, MessageReportResult } from "../../../lib/mail/mailApi.js";
+
+/** Where a notification's "Manage blocked senders" goes: the Blocked and safe senders page of the mailbox. */
+export function senderListsHref(mailboxUid: string): string {
+    return `/settings/blocked-senders?mailboxUid=${encodeURIComponent(mailboxUid)}`;
+}
+
+/** What a pop-up says about reporting `kind`: the title, and the folder the message goes to. */
+const KINDS: Record<MessageReportKind, { title: string; noun: string; folder: string }> = {
+    junk: { title: "Reported as junk", noun: "junk", folder: "Junk Email" },
+    phishing: { title: "Reported as phishing", noun: "phishing", folder: "Junk Email" },
+    not_junk: { title: "Marked as not junk", noun: "not junk", folder: "the Inbox" },
+};
+
+/** The noun of `kind` for a failure's title ("Couldn't report this message as phishing"). */
+export function reportNoun(kind: MessageReportKind): string {
+    return KINDS[kind].noun;
+}
+
+/** The title of a pop-up for a report of `kind`. */
+export function reportTitle(kind: MessageReportKind): string {
+    return KINDS[kind].title;
+}
+
+/** The name of the folder a report of `kind` files the message in. */
+export function reportFolderName(kind: MessageReportKind): string {
+    return KINDS[kind].folder;
+}
+
+/** What a pop-up for a report says. `hint` is the small muted line: only for the two things a reader may want to know about (the filter could not be
+ * taught, or the message is encrypted so it was not), never for the ones that are simply how the server is set up. */
+export interface ReportNotice {
+    title: string;
+    message: string;
+    hint?: string;
+}
+
+/**
+ * The words for what the server did with a report (`reportMessage()`'s answer): where the message went, whether the spam filter learned from it, and - for
+ * a report of phishing - that the server recorded it. `subject` names the message. `alwaysTrust` says the reader asked for the sender to be trusted.
+ */
+export function reportNotice(result: MessageReportResult, subject: string, alwaysTrust: boolean): ReportNotice {
+    const kind = KINDS[result.kind];
+    const where = result.moved ? `was moved to ${kind.folder}` : `is already in ${kind.folder}`;
+    const learned = result.learned ? " and used to train the spam filter" : "";
+    const parts = [`“${subject}” ${where}${learned}.`];
+    if (result.kind === "phishing") {
+        parts.push("The report was recorded in the audit log.");
+    }
+    if (result.safeSender) {
+        parts.push(`Mail from ${result.safeSender} that passes authentication is no longer sent to Junk Email.`);
+    } else if (alwaysTrust) {
+        parts.push("The message names no address that could be trusted.");
+    }
+    const hint =
+        result.learnSkipped === "failed"
+            ? "The spam filter could not be trained from this report."
+            : result.learnSkipped === "encrypted"
+              ? "Not used to train the spam filter: the message is encrypted."
+              : undefined;
+    return { title: kind.title, message: parts.join(" "), hint };
+}