nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/MessageHelpers.js

@@ -0,0 +1,573 @@
+import { ApiError } from "./ApiResponses.js";
+import { sameChatId } from "./ChatHelpers.js";
+import { nowUtcDateTime } from "./DateTimeHelpers.js";
+import { markdownToPlainText } from "./MarkdownHelpers.js";
+import { holdPickerItems, pagedPicker } from "./PagedPicker.js";
+/*
+ * The words and small rules a mail thread is drawn with - a role's name, a list of people folded to three names and a
+ * count, the note a person copied unseen reads before replying - and a mailbox kept in memory (`localMessageSource`)
+ * that keeps the rules a backend keeps: who sees whom, a reply that shows a blind copy, archive per person, unread per
+ * person, one thread per retried send.
+ */
+/** A role's name on screen. */
+export const MAIL_ROLE_LABELS = { from: "From", to: "To", cc: "Cc", bcc: "Bcc" };
+/** A list's name on screen. */
+export const MAIL_LIST_LABELS = { inbox: "Inbox", unread: "Unread", sent: "Sent", archived: "Archived" };
+/** What a person copied unseen reads over the reply box: their reply makes them a Cc, seen by everyone. */
+export const MAIL_BCC_NOTE = "You were sent a blind copy. Replying shows you to everyone.";
+/** The most people on one thread together, the sender aside. */
+export const MAIL_PEOPLE_MAX = 50;
+/** The longest subject. */
+export const MAIL_SUBJECT_MAX = 100;
+/** The longest message. */
+export const MAIL_BODY_MAX = 4000;
+/**
+ * The most unread lines `unread()` counts: a backend counts to here and stops (the Message module's `Mail/Unread`), so
+ * a bell writes "99+" from 100 on and says "more than 99".
+ */
+export const MAIL_UNREAD_MAX = 100;
+/** Joins names as a sentence does: "A", "A and B", "A, B and C". */
+function sentence(names) {
+    if (names.length <= 1)
+        return names[0] ?? "";
+    return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+/** Folds a list of people to its first `max` names and a count of the rest: a To line with 50 people stays one line. */
+export function mailPeopleLine(people, max = 3) {
+    const limit = Math.max(1, max);
+    // Two more is "+2" and not one name fewer: a count stands for at least two people, never for one.
+    const shown = people.length <= limit + 1 ? people : people.slice(0, limit);
+    const more = people.length - shown.length;
+    const names = shown.map(person => person.name);
+    return { shown, more, text: more > 0 ? `${names.join(", ")} +${more}` : names.join(", "), full: sentence(people.map(person => person.name)) };
+}
+/** The note a reader of a thread sees over the reply box, or `null`: a person copied unseen who may reply. */
+export function mailBccNote(head) {
+    return head && head.myRole === "bcc" && head.canSend ? MAIL_BCC_NOTE : null;
+}
+/** An id for a new message, made once per form so a retried send writes it once. */
+export function newMailClientId() {
+    const random = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    return `mail-${random}`;
+}
+/**
+ * The people a new message can be sent to, as a dropdown's params: the source's search, paged by the server, every
+ * person named once seen. One for every To, Cc and Bcc box of a page.
+ *
+ * @example
+ * const people = mailPeoplePicker(mail);
+ * { type: EInputTypes.Dropdown, name: "to", label: "To", multiple: true, required: true, ...people }
+ */
+export function mailPeoplePicker(source) {
+    return pagedPicker(request => source.people(request), { valueKey: "id", labelKey: "name", isInactive: person => person.isActive === false });
+}
+/**
+ * A New message form's opening values, from the source's defaults (the reader's supervisor in To, or the people they
+ * chose): a CRUD's `form.createDefaults`. The people are handed to the picker, so the boxes name them at once. Give the
+ * form a `clientId` of its own in `newValues` too: a form whose defaults could not be read opens on those alone.
+ *
+ * @example form={{ newValues: () => ({ clientId: newMailClientId() }), createDefaults: mailComposeDefaults(mail, people) }}
+ */
+export function mailComposeDefaults(source, picker) {
+    return async (signal) => {
+        const defaults = await source.defaults(signal);
+        if (picker)
+            holdPickerItems(picker, [...defaults.to, ...defaults.cc, ...defaults.bcc]);
+        const ids = (people) => people.filter(person => person.isActive !== false).map(person => person.id);
+        return { to: ids(defaults.to), cc: ids(defaults.cc), bcc: ids(defaults.bcc), clientId: newMailClientId() };
+    };
+}
+/**
+ * A data table's loader over one list of a mailbox, paged by the source: `<DataTable paging="server" load={...} />`.
+ * `about` narrows it to the threads about one record.
+ */
+export function mailInboxLoader(source, list, about) {
+    return (query, signal) => source.inbox({ list, search: query.search, skip: (query.page - 1) * query.pageSize, take: query.pageSize, signal, ...about });
+}
+/** A line of an inbox row's preview: the Markdown as text, on one line. */
+export function mailPreviewText(preview) {
+    return markdownToPlainText(preview ?? "").replace(/\s+/g, " ").trim();
+}
+/** Bcc < Cc < To: a role only ever moves to a more visible one, and From never changes. */
+const VISIBILITY = { bcc: 1, cc: 2, to: 3, from: 4 };
+/** A refusal with the status a server would answer, so a page tells "you cannot open this" (404) from a failure. */
+const refuse = (status, message) => new ApiError({ ok: false, status, message });
+/**
+ * A `MessageSource` in memory: a whole mailbox without a backend, for a demo page or a test. It keeps a backend's
+ * rules: a person sees the people copied unseen only on a thread they sent, or their own row; a reply by a person
+ * copied unseen makes them a Cc; Archive is each person's own and a line by someone else brings the thread back; a line
+ * is unread for everyone but its author (a line the system wrote for nobody); a new message or a reply sent again with
+ * the same id is written once. `as(userId)` reads the same mailbox as somebody else.
+ *
+ * The lists: **Inbox** every thread the reader is on and has not archived, **Unread** those with unread lines,
+ * **Sent** the ones they started, **Archived** the ones they put aside; newest line first; the search looks in the
+ * subject and the record's words.
+ */
+export function localMessageSource(options) {
+    const now = options.now ?? nowUtcDateTime;
+    const people = new Map(options.people.map(person => [String(person.id), person]));
+    const failing = new Set();
+    let threadSequence = 0;
+    let lineSequence = 0;
+    const wait = () => (options.delay ? new Promise(resolve => setTimeout(resolve, options.delay)) : Promise.resolve());
+    const fail = (part) => {
+        if (failing.has(part))
+            throw refuse(503, "The server did not answer.");
+    };
+    const nameOf = (id) => (id === null ? "" : (people.get(id)?.name ?? "Unknown"));
+    const personOf = (id) => people.get(id) ?? { id, name: "Unknown", isActive: false };
+    // Kept by their text inside; handed out as the people were given, so a number stays a number.
+    const idOf = (key) => people.get(key)?.id ?? key;
+    const threads = (options.threads ?? []).map(seed => {
+        const id = String(seed.id ?? `mail-${++threadSequence}`);
+        const roles = new Map([[String(seed.from), "from"]]);
+        const add = (ids, role) => {
+            for (const one of ids ?? [])
+                if (!roles.has(String(one)))
+                    roles.set(String(one), role);
+        };
+        add(seed.to, "to");
+        add(seed.cc, "cc");
+        add(seed.bcc, "bcc");
+        const lines = [];
+        seed.lines.forEach((line, index) => {
+            lines.push({
+                id: `${id}-${++lineSequence}`,
+                authorId: line.authorId === null ? null : String(line.authorId),
+                body: line.body,
+                kind: line.kind ?? (index === 0 && !seed.chat ? "mail" : "chat"),
+                createdAt: line.createdAt,
+                replyToId: line.replyTo === undefined ? null : (lines[line.replyTo]?.id ?? null),
+                key: null,
+            });
+        });
+        const readMarks = new Map();
+        for (const person of roles.keys()) {
+            const given = seed.read?.[person];
+            // A person has read their own lines, and whatever the seed says beyond them.
+            let own = -1;
+            lines.forEach((line, index) => {
+                if (line.authorId === person)
+                    own = index;
+            });
+            readMarks.set(person, Math.max(own, given ?? -1));
+        }
+        return {
+            id,
+            subject: seed.subject,
+            chat: seed.chat ?? null,
+            starred: new Set((seed.starredBy ?? []).map(String)),
+            createdTime: lines[0]?.createdAt ?? now(),
+            domain: seed.domain ? { domainType: seed.domain.domainType, id: seed.domain.id ?? null, label: seed.domain.label ?? null } : null,
+            closed: seed.closed === true,
+            roles,
+            lines,
+            readMarks,
+            archived: new Set((seed.archivedBy ?? []).map(String)),
+            key: null,
+        };
+    });
+    const find = (id) => threads.find(thread => thread.id === String(id));
+    /** The thread, when this reader is on it: a stranger learns nothing, as from a server (404). */
+    const open = (id, reader) => {
+        const thread = find(id);
+        if (!thread || !thread.roles.has(reader))
+            throw refuse(404, "This message is not available to you.");
+        return thread;
+    };
+    /** Whether this reader may see a person on this thread: everyone but the people copied unseen, who only the sender and they themselves see. */
+    const sees = (thread, reader, person) => thread.roles.get(person) !== "bcc" || thread.roles.get(reader) === "from" || person === reader;
+    const unreadOf = (thread, reader) => {
+        const mark = thread.readMarks.get(reader) ?? -1;
+        return thread.lines.filter((line, index) => index > mark && line.authorId !== null && line.authorId !== reader).length;
+    };
+    const peopleIn = (thread, reader, role) => [...thread.roles].filter(([person, held]) => held === role && sees(thread, reader, person)).map(([person]) => personOf(person));
+    const lastOf = (thread) => thread.lines[thread.lines.length - 1];
+    const kindOf = (thread) => (thread.chat ? "chat" : thread.domain ? "domain" : "mail");
+    /** A chat's name as this reader sees it: its own, else its other people. */
+    const chatName = (thread, reader) => thread.subject ||
+        [...thread.roles.keys()]
+            .filter(person => person !== reader)
+            .map(nameOf)
+            .join(", ");
+    const rowOf = (thread, reader) => {
+        const last = lastOf(thread);
+        const from = [...thread.roles].find(([, role]) => role === "from")?.[0] ?? "";
+        // A chat's row is named as the reader sees the chat: the other person, or the group.
+        const fromKey = thread.chat === "one-to-one" ? ([...thread.roles.keys()].find(person => person !== reader) ?? from) : from;
+        const avatar = people.get(fromKey)?.avatar;
+        return {
+            id: thread.id,
+            subject: thread.chat ? chatName(thread, reader) : thread.subject,
+            fromId: idOf(fromKey),
+            fromName: thread.chat === "group" ? chatName(thread, reader) : nameOf(fromKey),
+            ...(avatar && { fromAvatar: avatar }),
+            threadKind: kindOf(thread),
+            starred: thread.starred.has(reader),
+            myRole: thread.roles.get(reader) ?? "to",
+            kind: thread.lines[0]?.kind === "notification" ? "notification" : "mail",
+            domainType: thread.domain?.domainType ?? null,
+            domainLabel: thread.domain?.label ?? null,
+            lastMessageTime: last?.createdAt ?? thread.createdTime,
+            lastAuthorName: last ? nameOf(last.authorId) || null : null,
+            lastPreview: (last?.body ?? "").slice(0, 160),
+            messageCount: thread.lines.length,
+            unreadCount: unreadOf(thread, reader),
+            archived: thread.archived.has(reader),
+        };
+    };
+    const headOf = (thread, reader) => {
+        const from = [...thread.roles].find(([, role]) => role === "from")?.[0] ?? "";
+        const role = thread.roles.get(reader) ?? "to";
+        return {
+            id: thread.id,
+            subject: thread.chat ? chatName(thread, reader) : thread.subject,
+            threadKind: kindOf(thread),
+            from: personOf(from),
+            to: peopleIn(thread, reader, "to"),
+            cc: peopleIn(thread, reader, "cc"),
+            bcc: peopleIn(thread, reader, "bcc"),
+            myRole: role,
+            archived: thread.archived.has(reader),
+            canSend: !thread.closed && people.get(reader)?.isActive !== false,
+            createdTime: thread.createdTime,
+            messageCount: thread.lines.length,
+            unreadCount: unreadOf(thread, reader),
+            ...(thread.domain && { domain: thread.domain }),
+        };
+    };
+    const messageOf = (thread, line, reader) => {
+        const index = thread.lines.indexOf(line);
+        // Who has it and who has read it, never naming a person this reader may not see.
+        const others = [...thread.roles.keys()].filter(person => person !== line.authorId && sees(thread, reader, person));
+        return {
+            id: line.id,
+            authorId: line.authorId === null ? "" : idOf(line.authorId),
+            authorName: line.authorId === null ? null : nameOf(line.authorId),
+            body: line.body,
+            createdAt: line.createdAt,
+            status: "sent",
+            kind: line.kind,
+            ...(line.replyToId && { replyToId: line.replyToId }),
+            ...(line.authorId === null && { isSystem: true }),
+            ...(line.authorId !== null && { deliveredTo: others.map(idOf), readBy: others.filter(person => (thread.readMarks.get(person) ?? -1) >= index).map(idOf) }),
+        };
+    };
+    const summaryOf = (thread, reader) => {
+        const last = lastOf(thread);
+        return {
+            messageCount: thread.lines.length,
+            unreadCount: unreadOf(thread, reader),
+            lastMessageAt: last?.createdAt ?? null,
+            lastMessageText: last ? mailPreviewText(last.body) : null,
+            lastMessageBy: last ? nameOf(last.authorId) || null : null,
+        };
+    };
+    const participantsOf = (thread, reader) => [...thread.roles]
+        .filter(([person]) => sees(thread, reader, person))
+        .map(([person, role]) => ({ id: idOf(person), name: nameOf(person), role: MAIL_ROLE_LABELS[role], ...(people.get(person)?.isActive === false && { inactive: true }) }));
+    /** Names a person again on a thread, raising their role and never lowering it; From never changes. */
+    const raise = (thread, person, role) => {
+        const held = thread.roles.get(person);
+        if (!held) {
+            thread.roles.set(person, role);
+            thread.readMarks.set(person, -1);
+        }
+        else if (held !== "from" && VISIBILITY[role] > VISIBILITY[held])
+            thread.roles.set(person, role);
+    };
+    /** A line added: its author has read it, and the thread is back in every other person's inbox. */
+    const append = (thread, line) => {
+        const held = { ...line, id: `${thread.id}-${++lineSequence}` };
+        thread.lines.push(held);
+        if (held.authorId !== null)
+            thread.readMarks.set(held.authorId, thread.lines.length - 1);
+        for (const person of thread.roles.keys())
+            if (person !== held.authorId)
+                thread.archived.delete(person);
+        return held;
+    };
+    const inList = (thread, reader, list) => {
+        if (!thread.roles.has(reader))
+            return false;
+        const archived = thread.archived.has(reader);
+        if (list === "archived")
+            return archived;
+        if (list === "sent")
+            return thread.roles.get(reader) === "from";
+        if (list === "unread")
+            return !archived && unreadOf(thread, reader) > 0;
+        return !archived;
+    };
+    /** The people of a new message, checked as a server checks them: every wrong one at once. */
+    const checkPeople = (draft, reader) => {
+        const problems = [];
+        const chosen = new Map();
+        const take = (ids, role) => {
+            for (const one of ids ?? []) {
+                const key = String(one);
+                const person = people.get(key);
+                if (!person || person.isActive === false)
+                    problems.push(`${MAIL_ROLE_LABELS[role]}: ${person?.name ?? key} cannot be written to.`);
+                else if (key === reader)
+                    problems.push(`${MAIL_ROLE_LABELS[role]}: you are the sender.`);
+                else if (chosen.has(key))
+                    problems.push(`${person.name} is named twice: keep them in one of To, Cc and Bcc.`);
+                else
+                    chosen.set(key, role);
+            }
+        };
+        take(draft.to, "to");
+        take(draft.cc, "cc");
+        take(draft.bcc, "bcc");
+        if ((draft.to ?? []).length === 0)
+            problems.push("To: name at least one person.");
+        if (chosen.size > MAIL_PEOPLE_MAX)
+            problems.push(`At most ${MAIL_PEOPLE_MAX} people together.`);
+        const subject = draft.subject.trim();
+        if (subject.length === 0 || subject.length > MAIL_SUBJECT_MAX)
+            problems.push(`Subject: 1 to ${MAIL_SUBJECT_MAX} characters.`);
+        const body = draft.body.trim();
+        if (body.length === 0 || body.length > MAIL_BODY_MAX)
+            problems.push(`Message: 1 to ${MAIL_BODY_MAX} characters.`);
+        if (problems.length)
+            throw refuse(400, problems.join(" "));
+        return chosen;
+    };
+    function sourceFor(readerId) {
+        const reader = String(readerId);
+        return {
+            async inbox(request) {
+                await wait();
+                fail("inbox");
+                const search = request.search?.trim().toLowerCase() ?? "";
+                const mine = threads.filter(thread => thread.roles.has(reader));
+                const matches = mine
+                    .filter(thread => inList(thread, reader, request.list))
+                    .filter(thread => !search || `${thread.subject} ${thread.domain?.label ?? ""}`.toLowerCase().includes(search))
+                    .filter(thread => request.threadKind === undefined || kindOf(thread) === request.threadKind)
+                    .filter(thread => request.domainType === undefined ||
+                    (thread.domain !== null && String(thread.domain.domainType) === String(request.domainType) && (request.parentId === undefined || String(thread.domain.id) === String(request.parentId))))
+                    .map(thread => rowOf(thread, reader))
+                    .sort((a, b) => b.lastMessageTime.localeCompare(a.lastMessageTime));
+                return { rows: matches.slice(request.skip, request.skip + request.take), total: mine.length, matches: matches.length };
+            },
+            async thread(id) {
+                await wait();
+                fail("thread");
+                return headOf(open(id, reader), reader);
+            },
+            threadSource(id) {
+                return {
+                    async history(request) {
+                        await wait();
+                        fail("history");
+                        const thread = open(id, reader);
+                        const all = thread.lines;
+                        const page = (lines, hasMore) => ({
+                            messages: lines.map(line => messageOf(thread, line, reader)),
+                            hasMore,
+                            summary: summaryOf(thread, reader),
+                            participants: participantsOf(thread, reader),
+                            canSend: headOf(thread, reader).canSend,
+                        });
+                        if (request.after) {
+                            const from = all.findIndex(line => sameChatId(line.id, request.after));
+                            return page(from === -1 ? [] : all.slice(from + 1), false);
+                        }
+                        const end = request.before ? all.findIndex(line => sameChatId(line.id, request.before)) : all.length;
+                        const stop = end === -1 ? all.length : end;
+                        const start = Math.max(0, stop - request.take);
+                        return page(all.slice(start, stop), start > 0);
+                    },
+                    async send(draft) {
+                        await wait();
+                        fail("reply");
+                        const thread = open(id, reader);
+                        if (!headOf(thread, reader).canSend)
+                            throw refuse(403, "This conversation is closed.");
+                        const body = draft.body.trim();
+                        if (body.length === 0 || body.length > MAIL_BODY_MAX)
+                            throw refuse(400, `Message: 1 to ${MAIL_BODY_MAX} characters.`);
+                        const key = `${reader}:${draft.clientId}`;
+                        const sent = thread.lines.find(line => line.key === key);
+                        if (sent)
+                            return messageOf(thread, sent, reader);
+                        // A reply shows its author to everyone: a person copied unseen becomes a Cc.
+                        if (thread.roles.get(reader) === "bcc")
+                            thread.roles.set(reader, "cc");
+                        const line = append(thread, { authorId: reader, body, kind: draft.kind === "mail" && !thread.chat ? "mail" : "chat", createdAt: now(), replyToId: draft.replyToId === undefined || draft.replyToId === null ? null : String(draft.replyToId), key });
+                        return messageOf(thread, line, reader);
+                    },
+                    async markRead(upTo) {
+                        await wait();
+                        const thread = open(id, reader);
+                        const at = thread.lines.findIndex(line => sameChatId(line.id, upTo));
+                        if (at > (thread.readMarks.get(reader) ?? -1))
+                            thread.readMarks.set(reader, at);
+                    },
+                };
+            },
+            async compose(draft) {
+                await wait();
+                fail("compose");
+                const key = `compose:${reader}:${draft.clientId}`;
+                const made = threads.find(thread => thread.key === key);
+                if (made)
+                    return { id: made.id, messageId: made.lines[0].id };
+                const chosen = checkPeople(draft, reader);
+                const thread = {
+                    id: `mail-${++threadSequence}`,
+                    subject: draft.subject.trim(),
+                    chat: null,
+                    starred: new Set(),
+                    createdTime: now(),
+                    domain: null,
+                    closed: false,
+                    roles: new Map([[reader, "from"], ...chosen]),
+                    lines: [],
+                    readMarks: new Map([...chosen.keys()].map(person => [person, -1])),
+                    archived: new Set(),
+                    key,
+                };
+                threads.push(thread);
+                const line = append(thread, { authorId: reader, body: draft.body.trim(), kind: "mail", createdAt: thread.createdTime, replyToId: null, key: null });
+                return { id: thread.id, messageId: line.id };
+            },
+            async archive(ids) {
+                await wait();
+                let changed = 0;
+                for (const id of ids) {
+                    const thread = find(id);
+                    if (thread?.roles.has(reader) && !thread.archived.has(reader)) {
+                        thread.archived.add(reader);
+                        changed++;
+                    }
+                }
+                return changed;
+            },
+            async unarchive(ids) {
+                await wait();
+                let changed = 0;
+                for (const id of ids) {
+                    const thread = find(id);
+                    if (thread?.archived.delete(reader))
+                        changed++;
+                }
+                return changed;
+            },
+            async folders() {
+                await wait();
+                fail("folders");
+                const mine = threads.filter(thread => thread.roles.has(reader));
+                const lists = ["inbox", "unread", "sent", "archived"];
+                const folders = lists.map(list => ({ list, unread: mine.filter(thread => inList(thread, reader, list) && unreadOf(thread, reader) > 0).length }));
+                const kinds = new Map();
+                for (const thread of mine.filter(one => inList(one, reader, "inbox"))) {
+                    const threadKind = kindOf(thread);
+                    const domainType = threadKind === "domain" ? (thread.domain?.domainType ?? null) : null;
+                    const key = `${threadKind}:${String(domainType)}`;
+                    const held = kinds.get(key) ?? { threadKind, domainType, unread: 0, total: 0 };
+                    held.total++;
+                    if (unreadOf(thread, reader) > 0)
+                        held.unread++;
+                    kinds.set(key, held);
+                }
+                return { folders, kinds: [...kinds.values()] };
+            },
+            async markRead(ids) {
+                await wait();
+                fail("marks");
+                let changed = 0;
+                for (const id of ids) {
+                    const thread = find(id);
+                    if (!thread?.roles.has(reader) || unreadOf(thread, reader) === 0)
+                        continue;
+                    thread.readMarks.set(reader, thread.lines.length - 1);
+                    changed++;
+                }
+                return changed;
+            },
+            async markUnread(ids) {
+                await wait();
+                fail("marks");
+                let changed = 0;
+                for (const id of ids) {
+                    const thread = find(id);
+                    if (!thread?.roles.has(reader) || unreadOf(thread, reader) > 0)
+                        continue;
+                    // The newest line somebody else wrote is unread again; a thread of the reader's own lines alone stays read.
+                    let at = -1;
+                    thread.lines.forEach((line, index) => {
+                        if (line.authorId !== null && line.authorId !== reader)
+                            at = index;
+                    });
+                    if (at === -1)
+                        continue;
+                    thread.readMarks.set(reader, at - 1);
+                    changed++;
+                }
+                return changed;
+            },
+            async star(ids, starred) {
+                await wait();
+                fail("marks");
+                let changed = 0;
+                for (const id of ids) {
+                    const thread = find(id);
+                    if (!thread?.roles.has(reader) || thread.starred.has(reader) === starred)
+                        continue;
+                    if (starred)
+                        thread.starred.add(reader);
+                    else
+                        thread.starred.delete(reader);
+                    changed++;
+                }
+                return changed;
+            },
+            async unread() {
+                await wait();
+                fail("unread");
+                const rows = threads
+                    .filter(thread => inList(thread, reader, "unread"))
+                    .map(thread => rowOf(thread, reader))
+                    .sort((a, b) => b.lastMessageTime.localeCompare(a.lastMessageTime));
+                // Counted as a backend counts: to MAIL_UNREAD_MAX, and no further.
+                return { count: Math.min(rows.reduce((total, row) => total + row.unreadCount, 0), MAIL_UNREAD_MAX), newest: rows.slice(0, 8) };
+            },
+            async people(query) {
+                await wait();
+                fail("people");
+                const search = query.search.trim().toLowerCase();
+                const found = options.people.filter(person => String(person.id) !== reader && person.isActive !== false && (!search || person.name.toLowerCase().includes(search)));
+                return { items: found.slice(query.skip, query.skip + query.pageSize), total: found.length, hasMore: query.skip + query.pageSize < found.length };
+            },
+            async defaults() {
+                await wait();
+                fail("defaults");
+                const own = options.defaults?.[reader] ?? {};
+                const list = (ids) => (ids ?? []).map(id => personOf(String(id)));
+                return { to: list(own.to), cc: list(own.cc), bcc: list(own.bcc) };
+            },
+        };
+    }
+    return {
+        ...sourceFor(options.userId),
+        as: sourceFor,
+        post(threadId, given) {
+            const thread = find(threadId);
+            if (!thread)
+                throw refuse(404, "No such thread.");
+            for (const person of given.to ?? [])
+                raise(thread, String(person), "to");
+            for (const person of given.cc ?? [])
+                raise(thread, String(person), "cc");
+            const authorId = given.authorId === null ? null : String(given.authorId);
+            if (authorId !== null && !thread.roles.has(authorId))
+                raise(thread, authorId, "cc");
+            const line = append(thread, { authorId, body: given.body, kind: given.kind ?? "notification", createdAt: now(), replyToId: null, key: null });
+            return messageOf(thread, line, authorId ?? "");
+        },
+        failing,
+    };
+}

package/dist/Helpers/MessageUnread.d.ts

@@ -0,0 +1,95 @@
+import type { MailInboxRow, MessageSource } from "../Interfaces/MailInterfaces.ts";
+/** How often the bell reads, in milliseconds, while the page is in front: a minute (the domain messages spec). */
+export declare const MESSAGE_UNREAD_INTERVAL = 60000;
+/** A wake within this long of the last read reads nothing more: a tab shown again also takes the focus. */
+export declare const MESSAGE_UNREAD_WAKE_GAP = 2000;
+/** What the bell knows. */
+export interface MessageUnreadSnapshot {
+    /** `idle`: never read. `loading`: the first read is on its way. `ready`: a count is known. `failed`: the first read failed. */
+    status: "idle" | "loading" | "ready" | "failed";
+    /** Unread lines, as the source counts them (a backend stops at `MAIL_UNREAD_MAX`). */
+    count: number;
+    /** The newest threads holding them, newest first. */
+    newest: readonly MailInboxRow[];
+    /** The last read failed: the count is the one read before it. */
+    failed: boolean;
+    error?: unknown;
+    /** When the last answer landed (milliseconds since 1970). */
+    checkedAt?: number;
+    /** Words for a screen reader, set when the count went up: `seq` grows with each, so the same words can be said again. */
+    spoken?: {
+        text: string;
+        seq: number;
+    };
+}
+/** The world the poller reads: the clock, a timer, whether the page is in front, and when it comes back. */
+export interface MessageUnreadEnvironment {
+    now(): number;
+    /** Runs `run` once after `ms`; answers how to call it off. */
+    later(run: () => void, ms: number): () => void;
+    /** Whether the page is in front: a hidden tab reads nothing. */
+    visible(): boolean;
+    /** Calls `run` when the window takes the focus or the tab is shown or hidden; answers how to stop. */
+    watch(run: () => void): () => void;
+}
+/** The browser's: `Date.now`, `setTimeout`, `document.visibilityState`, `focus` and `visibilitychange`. */
+export declare function browserUnreadEnvironment(): MessageUnreadEnvironment;
+/** "No unread messages", "1 unread message", "3 unread messages", "More than 99 unread messages". */
+export declare function mailUnreadWords(count: number, max?: number): string;
+/** The badge: "3", "99+" from 100 on (a backend counts to 100 and stops). Empty for none. */
+export declare function mailUnreadBadge(count: number, max?: number): string;
+/** A thread's address in the inbox: `href` with `thread=<id>` added to its query, before any `#`. */
+export declare function mailThreadHref(href: string, id: MailInboxRow["id"]): string;
+/** One bell's place in the poller: how often it wants a read, and how it leaves. */
+export interface MessageUnreadMembership {
+    leave(): void;
+    /** Whether this bell is the one that speaks: the first still drawn, so two bells never say the same thing twice. */
+    speaks(): boolean;
+}
+/** One mailbox's unread count for the whole page. Every bell of the page on the same source shares it. */
+export declare class MessageUnreadPoller {
+    private source;
+    private env;
+    private snapshot;
+    private listeners;
+    private members;
+    private controller;
+    private cancelTimer;
+    private stopWatching;
+    private startedAt;
+    private endedAt;
+    private known;
+    private seq;
+    /** A refresh was asked while a read was on its way: one more read follows it. */
+    private again;
+    /** Reads started, for a page that shows how many calls it made, and for tests. */
+    reads: number;
+    constructor(source: Pick<MessageSource, "unread">, env?: MessageUnreadEnvironment);
+    readonly getSnapshot: () => MessageUnreadSnapshot;
+    /** Hears every change. Joining is separate: a bell that only shows a count need not make the page read. */
+    readonly subscribe: (listener: () => void) => (() => void);
+    private set;
+    /** How often the members want a read: the shortest any of them asked for. */
+    private get interval();
+    /** A bell drawn: the first starts the reads. Reads at once unless an answer younger than the interval is held. */
+    join(interval?: number): MessageUnreadMembership;
+    /**
+     * Reads now: a page that just read a thread, archived some, or a bell opened. With a read on its way - which may have
+     * counted before the change - one more read follows it, however many refreshes are asked meanwhile; never two at once.
+     * While the page is hidden nothing is read: the read asked for waits for the page to be shown.
+     */
+    refresh(): void;
+    /** A read ended: the one asked for meanwhile, now, while the page is in front; else the next one, a minute on. */
+    private settle;
+    /** The window took the focus, or the tab was shown or hidden. */
+    private wake;
+    private read;
+    /** The next read, an interval after the last one ended: only while a bell is drawn and the page is in front. */
+    private schedule;
+    /** The last bell went: no timer, no watching, the read on its way called off. What was read stays for the next bell. */
+    private stop;
+}
+/** The page's poller for a mailbox: one per source object, however many bells draw it. */
+export declare function messageUnreadPoller(source: Pick<MessageSource, "unread">): MessageUnreadPoller;
+/** Reads the count again now, for every bell on `source`: after the page read a thread or archived some. */
+export declare function refreshMessageUnread(source: Pick<MessageSource, "unread">): void;