nexus-shared 4.0.0 → 4.1.0

package/dist/Helpers/MessageBackend.js

@@ -0,0 +1,329 @@
+import { NexusModule } from "../Interfaces/ApiInterfaces.js";
+import { apiEndpoint } from "./ApiRoutes.js";
+import { NexusChatBackend } from "./ChatBackend.js";
+/*
+ * How a mailbox talks to a backend: which endpoint serves each action, what each request sends, and how each answer is
+ * read. `MessageBackend` is what an app implements for its own backend; `NexusMessageBackend` is the Nexus Message
+ * module's `Mail` controller, and runs when nothing is registered. Nothing here calls anything - `apiMessageSource` does
+ * that - so this file is pure and can be checked without a server.
+ *
+ * A thread's lines are the chat's: the history and a reply answer with the chat's own rows, read by the chat's backend,
+ * so a mail thread is drawn by the chat's thread unchanged.
+ */
+/** The actions a mailbox needs from a backend. */
+export const MAIL_ACTIONS = {
+    /** A page of one list: inbox, unread, sent, archived. */
+    inbox: "Inbox",
+    /** A thread's head: its subject and its people. */
+    thread: "Thread",
+    /** A page of a thread's lines. */
+    history: "History",
+    /** A new message. */
+    compose: "Create",
+    /** A reply in a thread. */
+    reply: "Reply",
+    /** How far the reader has read a thread. */
+    read: "Read",
+    /** Threads put aside. */
+    archive: "Archive",
+    /** Threads brought back. */
+    unarchive: "Unarchive",
+    /** How much is unread, and the newest of it. */
+    unread: "Unread",
+    /** The people a message can be sent to. */
+    people: "People",
+    /** Who a new message goes to by default. */
+    defaults: "Defaults",
+    /** The counts beside a mail client's folders and types. */
+    folders: "Folders",
+    /** Whole conversations marked read. */
+    markRead: "MarkRead",
+    /** Conversations marked unread again. */
+    markUnread: "MarkUnread",
+    /** Conversations starred. */
+    star: "Star",
+    /** Stars taken away. */
+    unstar: "Unstar",
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value) => (typeof value === "string" && value.trim() !== "" ? value : null);
+const count = (value) => {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : 0;
+};
+const idOf = (value) => (typeof value === "string" || typeof value === "number" ? value : null);
+/** Rows of an answer: an array, or the `results` of a page. */
+function rowsOf(result) {
+    const list = Array.isArray(result) ? result : isRecord(result) && Array.isArray(result.results) ? result.results : [];
+    return list.filter(isRecord);
+}
+/**
+ * What a mailbox needs from a backend. Extend `NexusMessageBackend` for an app whose mail API differs, and register it
+ * once beside the app's API modules:
+ *
+ * @example
+ * class AppMessageBackend extends NexusMessageBackend {
+ *   override readonly module = AppModule.Messages;
+ * }
+ * defineMessageBackend(new AppMessageBackend());
+ */
+export class MessageBackend {
+    /** What opening a thread sends, as the call's `params`: its id in the path. */
+    threadParams(threadId) {
+        return { id: typeof threadId === "number" ? threadId : String(threadId) };
+    }
+    /** The optional doors this backend has: a mail client offers Mark read, Mark unread and stars only where they are. */
+    supports(action) {
+        return action === "folders" ? typeof this.readFolders === "function" : false;
+    }
+}
+/** The Nexus numbers of a conversation's kind (`Mail/Inbox`'s and `Mail/Folders`' `kind`). */
+const NEXUS_THREAD_KINDS = { mail: 1, chat: 2, domain: 3 };
+/** The Nexus numbers of a person's role on a thread (`EChatParticipantRoles`): 0 is a plain member of a chat. */
+const NEXUS_ROLES = { 1: "from", 2: "to", 3: "cc", 4: "bcc" };
+/** The Nexus numbers of the lists (`Mail/Inbox`'s `list`). */
+const NEXUS_LISTS = { inbox: 1, unread: 2, sent: 3, archived: 4 };
+/**
+ * The Nexus Message module's `Mail` controller (`App/Api/Mail/...`): POST `Inbox`, `History`, `Create`, `Reply` and
+ * `People`; GET `Thread/{id}`, `Unread` and `Defaults`; PUT `Read`, `Archive` and `Unarchive`. Pages answer
+ * `{ results, totalCount, filterCount }`; a person's role and a message's kind come as the backend's numbers and are
+ * read as this package's words. Override `module` or `controller` for another place, or any reader for another shape.
+ */
+export class NexusMessageBackend extends MessageBackend {
+    /** The module the mail endpoints live in. `NexusModule.Message`. */
+    module = NexusModule.Message;
+    /** The controller the actions hang off. */
+    controller = "Mail";
+    /** A thread's lines are the chat's rows, read as the chat reads them. */
+    chat = new NexusChatBackend();
+    endpoint(action) {
+        // The Nexus module's value, as `NexusChatBackend` takes it: an app on modules of its own registers its own backend.
+        const module = this.module;
+        const path = `${this.controller}/${MAIL_ACTIONS[action]}`;
+        // `subject` words the failure toasts; the thread shows its own messages, so its calls send `toast: false`.
+        switch (action) {
+            case "thread":
+                return apiEndpoint.get(module, `${path}/{id}`, { action: "load", subject: "message" });
+            case "unread":
+            case "defaults":
+                return apiEndpoint.get(module, path, { action: "load", subject: "messages" });
+            case "read":
+                return apiEndpoint.put(module, path, { action: "update", subject: "message" });
+            case "folders":
+                return apiEndpoint.get(module, path, { action: "load", subject: "messages" });
+            case "archive":
+            case "unarchive":
+            case "markRead":
+            case "markUnread":
+            case "star":
+            case "unstar":
+                return apiEndpoint.put(module, path, { action: "update", subject: "messages" });
+            case "compose":
+                return apiEndpoint.post(module, path, { action: "send", subject: "message" });
+            case "reply":
+                return apiEndpoint.post(module, path, { action: "send", subject: "reply" });
+            default:
+                return apiEndpoint.post(module, path, { action: "load", subject: action === "people" ? "people" : "messages" });
+        }
+    }
+    inboxRequest(request) {
+        return {
+            list: NEXUS_LISTS[request.list],
+            ...(request.search?.trim() && { searchKeyword: request.search.trim() }),
+            ...(request.domainType !== undefined && { domainType: request.domainType }),
+            ...(request.domainType !== undefined && request.parentId !== undefined && { parentId: request.parentId }),
+            ...(request.threadKind && { kind: NEXUS_THREAD_KINDS[request.threadKind] }),
+            skipCount: request.skip,
+            maxCount: request.take,
+        };
+    }
+    readInbox(result) {
+        const rows = rowsOf(result).map(row => this.readInboxRow(row));
+        if (!isRecord(result))
+            return { rows };
+        const total = result.totalCount === undefined ? rows.length : count(result.totalCount);
+        return { rows, total, matches: result.filterCount === undefined ? total : count(result.filterCount) };
+    }
+    readInboxRow(row) {
+        const one = isRecord(row) ? row : {};
+        const domainType = this.toDomainType(one.domainType);
+        const fromAvatar = text(one.fromAvatar ?? one.fromPicture);
+        return {
+            id: idOf(one.id) ?? "",
+            subject: text(one.subject ?? one.title) ?? "",
+            fromId: idOf(one.fromId) ?? "",
+            fromName: text(one.fromName) ?? "",
+            myRole: this.toRole(one.myRole),
+            // `kind` on the wire is the conversation's (Mail 1, Chat 2, Domain 3); what it opened with is `messageType`.
+            kind: this.toHeadKind(one.messageType ?? one.headMessageType),
+            domainType,
+            domainLabel: text(one.domainLabel),
+            lastMessageTime: text(one.lastMessageTime ?? one.lastMessageAt) ?? "",
+            lastAuthorName: text(one.lastAuthorName),
+            lastPreview: typeof one.lastPreview === "string" ? one.lastPreview : "",
+            messageCount: count(one.messageCount),
+            unreadCount: count(one.unreadCount),
+            archived: one.archived === true,
+            threadKind: this.toThreadKind(one.kind, domainType),
+            ...(typeof (one.starred ?? one.isStarred) === "boolean" && { starred: (one.starred ?? one.isStarred) === true }),
+            ...(fromAvatar && { fromAvatar }),
+        };
+    }
+    readThread(result) {
+        const row = isRecord(result) ? result : {};
+        const people = (value) => (Array.isArray(value) ? value.filter(isRecord).map(person => this.toPerson(person)) : []);
+        const domain = isRecord(row.domain) ? this.toDomain(row.domain) : null;
+        return {
+            id: idOf(row.id) ?? "",
+            subject: text(row.subject ?? row.title) ?? "",
+            from: isRecord(row.from) ? this.toPerson(row.from) : { id: "", name: "Unknown" },
+            to: people(row.to),
+            cc: people(row.cc),
+            bcc: people(row.bcc),
+            myRole: this.toRole(row.myRole),
+            archived: row.archived === true,
+            canSend: row.canSend !== false,
+            createdTime: text(row.createdTime ?? row.creationTime) ?? "",
+            messageCount: count(row.messageCount),
+            unreadCount: count(row.unreadCount),
+            ...(domain && { domain }),
+            threadKind: this.toThreadKind(row.kind, domain?.domainType ?? null),
+        };
+    }
+    historyRequest(threadId, request) {
+        return { id: threadId, beforeId: request.before ?? null, afterId: request.after ?? null, maxCount: request.take };
+    }
+    readHistory(result) {
+        // The chat's own History answer, each line with its `messageType`, which the chat's reader takes as its kind.
+        return this.chat.readHistory(result);
+    }
+    replyRequest(threadId, draft) {
+        // A Reply is a mail line (`messageType` 1) only when asked: the backend's default is a chat line, as its older callers send.
+        return {
+            id: threadId,
+            body: draft.body,
+            clientId: draft.clientId,
+            ...(draft.replyToId !== undefined && draft.replyToId !== null && { replyToId: draft.replyToId }),
+            ...(draft.kind === "mail" && { messageType: 1 }),
+        };
+    }
+    readReply(result, draft) {
+        // The answer is the chat's line; its author is in it, so the scope the chat's reader falls back on is never read.
+        return this.chat.readMessage(result, { domain: 0, parentId: "", userId: "" }, draft);
+    }
+    readMarkRequest(threadId, upTo) {
+        return { id: threadId, messageId: upTo };
+    }
+    composeRequest(draft) {
+        return {
+            to: draft.to,
+            ...(draft.cc?.length && { cc: draft.cc }),
+            ...(draft.bcc?.length && { bcc: draft.bcc }),
+            subject: draft.subject,
+            body: draft.body,
+            clientId: draft.clientId,
+        };
+    }
+    readComposed(result) {
+        const row = isRecord(result) ? result : {};
+        return { id: idOf(row.id) ?? "", messageId: idOf(row.messageId) ?? "" };
+    }
+    markRequest(ids) {
+        return { ids };
+    }
+    readChanged(result) {
+        return isRecord(result) ? count(result.count ?? result.changed) : count(result);
+    }
+    readUnread(result) {
+        const row = isRecord(result) ? result : {};
+        return { count: count(row.count), newest: Array.isArray(row.newest) ? row.newest.filter(isRecord).map(one => this.readInboxRow(one)) : [] };
+    }
+    peopleRequest(query) {
+        return { ...(query.search.trim() && { searchKeyword: query.search.trim() }), skipCount: query.skip, maxCount: query.pageSize };
+    }
+    readPeople(result) {
+        const items = rowsOf(result).map(row => this.toPerson(row));
+        if (Array.isArray(result) || !isRecord(result))
+            return { items, hasMore: false, total: items.length };
+        // The dropdown reads a full page as one with more after it; the total is shown as "25 of 1,240".
+        return { items, total: count(result.filterCount ?? result.totalCount) };
+    }
+    readDefaults(result) {
+        const row = isRecord(result) ? result : {};
+        const people = (value) => (Array.isArray(value) ? value.filter(isRecord).map(person => this.toPerson(person)) : []);
+        return { to: people(row.to), cc: people(row.cc), bcc: people(row.bcc) };
+    }
+    readFolders(result) {
+        const row = isRecord(result) ? result : {};
+        const lists = Object.entries(NEXUS_LISTS);
+        const folders = (Array.isArray(row.folders) ? row.folders : []).filter(isRecord).flatMap(one => {
+            const written = String(one.list ?? "").toLowerCase();
+            const list = lists.find(([word, number]) => word === written || number === Number(one.list))?.[0];
+            return list ? [{ list, unread: count(one.unread) }] : [];
+        });
+        const kinds = (Array.isArray(row.kinds) ? row.kinds : []).filter(isRecord).map(one => {
+            const domainType = this.toDomainType(one.domainType);
+            return { threadKind: this.toThreadKind(one.kind, domainType), domainType: this.toThreadKind(one.kind, domainType) === "domain" ? domainType : null, unread: count(one.unread), total: count(one.total) };
+        });
+        return { folders, kinds };
+    }
+    supports(action) {
+        // The Nexus Message API's doors (card MAIL-hub). An app on an older one turns them off in a subclass.
+        return action === "folders" || action === "markRead" || action === "markUnread" || action === "star";
+    }
+    /** A conversation's kind: the wire's number (Mail 1, Chat 2, Domain 3) or a word; without one, mail or its record's kind. */
+    toThreadKind(value, domainType) {
+        const written = String(value ?? "").toLowerCase();
+        if (written === "2" || written === "chat")
+            return "chat";
+        if (written === "3" || written === "domain")
+            return "domain";
+        if (written === "1" || written === "mail")
+            return "mail";
+        return domainType === null ? "mail" : "domain";
+    }
+    /** A person. */
+    toPerson(row) {
+        return {
+            id: idOf(row.id ?? row.userId) ?? "",
+            name: text(row.name ?? row.fullName ?? row.userName) ?? "Unknown",
+            ...(row.isActive === false && { isActive: false }),
+            ...(text(row.avatar ?? row.picture) && { avatar: text(row.avatar ?? row.picture) }),
+        };
+    }
+    /** A role, from the backend's `EChatParticipantRoles` (1 From, 2 To, 3 Cc, 4 Bcc) or a word. A plain member reads as To. */
+    toRole(value) {
+        const written = String(value ?? "").toLowerCase();
+        if (written === "from" || written === "to" || written === "cc" || written === "bcc")
+            return written;
+        return NEXUS_ROLES[Number(value)] ?? "to";
+    }
+    /** What a thread opened with: the backend's `EChatMessageTypes` (1 Mail, 2 Notification) or a word. */
+    toHeadKind(value) {
+        const written = String(value ?? "").toLowerCase();
+        return written === "2" || written === "notification" ? "notification" : "mail";
+    }
+    /** A domain type is the app's own value: kept as it came, a number or a word, and none when it is none. */
+    toDomainType(value) {
+        if (typeof value === "number")
+            return value === 0 ? null : value;
+        return text(value);
+    }
+    /** The record a thread is about. */
+    toDomain(row) {
+        const domainType = this.toDomainType(row.domainType);
+        if (domainType === null)
+            return null;
+        return { domainType, id: idOf(row.id), label: text(row.label) };
+    }
+}
+let registered;
+/** Makes an app's mail backend the one every mailbox uses, and returns it. Call it once, beside `defineApiModules`. */
+export function defineMessageBackend(backend) {
+    registered = backend;
+    return backend;
+}
+/** The app's mail backend: the one given to `defineMessageBackend`, else the Nexus one. */
+export function getMessageBackend() {
+    return (registered ??= new NexusMessageBackend());
+}

package/dist/Helpers/MessageHelpers.d.ts

@@ -0,0 +1,160 @@
+import type { ChatConversationType, ChatDomainValue, ChatId, ChatMessage, ChatMessageKind } from "../Interfaces/ChatInterfaces.ts";
+import type { MailInboxRow, MailList, MailPerson, MailRole, MailThreadHead, MessageSource } from "../Interfaces/MailInterfaces.ts";
+import type { TableLoader } from "../Interfaces/TableInterfaces.ts";
+import { type PagedPickerParams } from "./PagedPicker.ts";
+/** A role's name on screen. */
+export declare const MAIL_ROLE_LABELS: Readonly<Record<MailRole, string>>;
+/** A list's name on screen. */
+export declare const MAIL_LIST_LABELS: Readonly<Record<MailList, string>>;
+/** What a person copied unseen reads over the reply box: their reply makes them a Cc, seen by everyone. */
+export declare 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 declare const MAIL_PEOPLE_MAX = 50;
+/** The longest subject. */
+export declare const MAIL_SUBJECT_MAX = 100;
+/** The longest message. */
+export declare 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 declare const MAIL_UNREAD_MAX = 100;
+/** A list of people as one line: the first few names and how many more ("Kiran Shrestha, Ram Karki, Sita Rai +2"). */
+export interface MailPeopleLine {
+    /** The people named. */
+    shown: readonly MailPerson[];
+    /** How many are left out. */
+    more: number;
+    /** The line: the names, then "+2". */
+    text: string;
+    /** Every name, for a tooltip and a screen reader: "Kiran Shrestha, Ram Karki and Sita Rai". */
+    full: string;
+}
+/** 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 declare function mailPeopleLine(people: readonly MailPerson[], max?: number): MailPeopleLine;
+/** The note a reader of a thread sees over the reply box, or `null`: a person copied unseen who may reply. */
+export declare function mailBccNote(head: Pick<MailThreadHead, "myRole" | "canSend"> | null | undefined): string | null;
+/** An id for a new message, made once per form so a retried send writes it once. */
+export declare function newMailClientId(): string;
+/**
+ * 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 declare function mailPeoplePicker(source: Pick<MessageSource, "people">): PagedPickerParams<MailPerson>;
+/** What a New message form opens with: the default people by id, and the message's own id for a retried send. */
+export interface MailComposeValues extends Record<string, unknown> {
+    to: ChatId[];
+    cc: ChatId[];
+    bcc: ChatId[];
+    clientId: string;
+}
+/**
+ * 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 declare function mailComposeDefaults(source: Pick<MessageSource, "defaults">, picker?: PagedPickerParams<MailPerson>): (signal: AbortSignal) => Promise<MailComposeValues>;
+/**
+ * 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 declare function mailInboxLoader(source: Pick<MessageSource, "inbox">, list: MailList, about?: {
+    domainType: ChatDomainValue;
+    parentId: ChatId;
+}): TableLoader<MailInboxRow>;
+/** A line of an inbox row's preview: the Markdown as text, on one line. */
+export declare function mailPreviewText(preview: string | null | undefined): string;
+/** One line of a thread `localMessageSource` starts with. */
+export interface LocalMailLine {
+    /** Who wrote it; `null` for a line the system wrote. */
+    authorId: ChatId | null;
+    body: string;
+    /** Default: `mail` for a thread's first line, `chat` after it. */
+    kind?: ChatMessageKind;
+    /** When, as a UTC moment. */
+    createdAt: string;
+    /** The line it answers, by its place in the thread (0 the first). */
+    replyTo?: number;
+}
+/** A thread `localMessageSource` starts with. */
+export interface LocalMailThread {
+    id?: ChatId;
+    /** A chat's name, when it has one: a chat without one is called after its other people. */
+    subject: string;
+    /**
+     * A chat, not a mail: `one-to-one` or `group`. Its lines are chat lines, it lists under the mailbox's Chat, and a mail
+     * client opens it in a chat popup. `from` started it, `to` are the others.
+     */
+    chat?: ChatConversationType;
+    /** Who had starred it. */
+    starredBy?: readonly ChatId[];
+    from: ChatId;
+    to: readonly ChatId[];
+    cc?: readonly ChatId[];
+    bcc?: readonly ChatId[];
+    /** The record it is about. */
+    domain?: {
+        domainType: ChatDomainValue;
+        id?: ChatId | null;
+        label?: string | null;
+    } | null;
+    /** Oldest first. The first is the mail itself. */
+    lines: readonly LocalMailLine[];
+    /** How far each person had read, as the place of the last line they read (0 the first), by id. Default: nothing, but their own lines. */
+    read?: Readonly<Record<string, number>>;
+    /** Who had put it aside. */
+    archivedBy?: readonly ChatId[];
+    /** Nobody may reply any more. */
+    closed?: boolean;
+}
+/** The parts of a local mailbox that can be made to fail, to show what a page does then. */
+export type LocalMailFailure = "inbox" | "thread" | "history" | "reply" | "compose" | "people" | "defaults" | "unread" | "folders" | "marks";
+export interface LocalMessageSourceOptions {
+    /** Who is reading. */
+    userId: ChatId;
+    /** Everyone in the company: who can be written to, and whose names the lines carry. */
+    people: readonly MailPerson[];
+    threads?: readonly LocalMailThread[];
+    /** Who a new message goes to by default, per person. */
+    defaults?: Readonly<Record<string, Partial<Record<"to" | "cc" | "bcc", readonly ChatId[]>>>>;
+    /** Milliseconds each call waits, so a demo shows its loading states. Default 0. */
+    delay?: number;
+    /** The moment a new line is written at. Default now. */
+    now?: () => string;
+}
+/** What `localMessageSource` gives besides a `MessageSource`: other readers of the same mailbox, and a module's post. */
+export interface LocalMessageSource extends MessageSource {
+    /** The same mailbox, read by somebody else. */
+    as(userId: ChatId): MessageSource;
+    /**
+     * Writes a line as a module does after its own write (approved, sent back): a notification by default, the people
+     * it names added to the thread or raised (never lowered), the thread brought back to everyone else's inbox.
+     */
+    post(threadId: ChatId, line: {
+        authorId: ChatId | null;
+        body: string;
+        kind?: ChatMessageKind;
+        to?: readonly ChatId[];
+        cc?: readonly ChatId[];
+    }): ChatMessage;
+    /** The parts that answer with a failure until taken out again. */
+    readonly failing: Set<LocalMailFailure>;
+}
+/**
+ * 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 declare function localMessageSource(options: LocalMessageSourceOptions): LocalMessageSource;