nexus-shared 2.0.0 → 3.0.0

package/dist/Helpers/ApiResponses.js

@@ -2,6 +2,10 @@ import { buildMessage, describeResult } from "./MessageBuilder.js";
 /*
  * Reading a server's answer as success or failure, the same way for every call: Nexus API responses, ASP.NET Core problem
  * details, or any JSON by its status. Pure, so it works in tests, in the browser, and on a server.
+ *
+ * What the server says always wins: a body that explains its refusal is shown in the server's own words, however it
+ * carried them (a list, one message object, or the message at the top level), and the messages built from the HTTP
+ * status are only the fallback for an answer that explains nothing.
  */
 /** Shown when nothing reached the server (the default wording; `messages.reason({ network: true })` follows `configureMessages`). */
 export const NETWORK_ERROR_MESSAGE = buildMessage("reason", { network: true });
@@ -15,6 +19,9 @@ function isRecord(value) {
 function text(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function count(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
 /** Messages by field from `{ errors: { Email: ["…"], "Addresses[0].City": "…" } }`. */
 function readErrorMap(errors) {
     if (!isRecord(errors))
@@ -27,14 +34,91 @@ function readErrorMap(errors) {
     }
     return Object.keys(result).length ? result : undefined;
 }
+/** The backend's defaults say nothing about what went wrong, so they are left out. */
+const EMPTY_CODES = ["SUCCESS", "GENERIC_ERROR"];
+/** A code worth keeping: not one of the backend's defaults. */
+function codeOf(value) {
+    const code = text(value);
+    return code && !EMPTY_CODES.includes(code) ? code : undefined;
+}
+/**
+ * One problem from any shape a backend sends it in: `{ message, messageCode, errorCode, inputName }`, a plain sentence,
+ * or a wording of the same fields (`errorMessage`, `code`, `field`, `propertyName`). Nothing without words to show.
+ */
+function readErrorMessage(value) {
+    if (typeof value === "string") {
+        const sentence = text(value);
+        return sentence ? { message: sentence } : undefined;
+    }
+    if (!isRecord(value))
+        return undefined;
+    const message = text(value.message) ?? text(value.errorMessage) ?? text(value.detail) ?? text(value.title);
+    if (!message)
+        return undefined;
+    const messageCode = codeOf(value.messageCode) ?? codeOf(value.code);
+    const errorCode = count(value.errorCode);
+    const inputName = text(value.inputName) ?? text(value.field) ?? text(value.propertyName);
+    return {
+        message,
+        ...(messageCode ? { messageCode } : {}),
+        ...(errorCode ? { errorCode } : {}),
+        ...(inputName ? { inputName } : {}),
+    };
+}
+/**
+ * Every problem a body lists, in its order, however it listed them: `errorMessages` as a list or as one message object,
+ * `errorMessage` either way, or an `errors` list (an `errors` map by field name is read by `readErrorMap` instead).
+ * Plain sentences count. Empty for a body that lists nothing; `fallback` is then read as the one problem, which is how
+ * the message and codes at the top level of a Nexus answer are read.
+ */
+export function readErrorMessages(body, fallback) {
+    const list = (values) => values.map(readErrorMessage).filter((problem) => Boolean(problem));
+    if (Array.isArray(body))
+        return list(body);
+    if (isRecord(body)) {
+        for (const key of ["errorMessages", "errorMessage", "errors"]) {
+            const value = body[key];
+            if (value === undefined || value === null)
+                continue;
+            // `errors` is a list of problems only when it is a list; as an object it names fields.
+            if (key === "errors" && !Array.isArray(value))
+                continue;
+            const problems = list(Array.isArray(value) ? value : [value]);
+            if (problems.length)
+                return problems;
+        }
+    }
+    if (fallback === undefined)
+        return [];
+    const own = readErrorMessage(fallback);
+    return own ? [own] : [];
+}
+/** The problems that name an input, as one message per name: several on one name joined, `"floor|rate"` naming both. */
+function fieldErrors(problems) {
+    const errors = {};
+    for (const { message, inputName } of problems) {
+        if (!inputName)
+            continue;
+        for (const part of inputName.split("|")) {
+            const name = part.trim();
+            if (!name)
+                continue;
+            errors[name] = errors[name] && errors[name] !== message ? `${errors[name]} ${message}` : message;
+        }
+    }
+    return Object.keys(errors).length ? errors : undefined;
+}
 /**
  * Reads a server's answer as success or failure:
- * - Nexus API responses, `{ isSuccess, message, messageCode, errorCode, inputName, result }`: `inputName` names the
- *   inputs the message is about, several joined with "|".
+ * - Nexus API responses, `{ isSuccess, code, errorMessages: [{ message, messageCode, errorCode, inputName }], result }`:
+ *   every problem is kept, in the server's order, and `inputName` names the inputs a message is about (several with "|").
+ *   `errorMessages` may be one message object instead of a list, and an older answer carries its one message and codes at
+ *   the top level (`{ isSuccess, message, messageCode, errorCode, inputName }`); all of them are read the same way.
  * - ASP.NET Core problem details and validation errors, `{ title, detail, errors: { Email: ["…"] } }`.
  * - Anything else by its HTTP status; the body is the result.
  *
- * A failure without a message of its own gets one by status, worded for what the call did (`context`, default: a save).
+ * The server's own words are the message whenever it sent any. Only a failure that explains nothing gets a message by
+ * status, worded for what the call did (`context`, default: a save).
  */
 export function readApiResponse(body, status, context) {
     const fallback = () => buildMessage("reason", { action: "save", ...context, status });
@@ -42,33 +126,40 @@ export function readApiResponse(body, status, context) {
     if (isRecord(body)) {
         if (typeof body.isSuccess === "boolean") {
             const ok = body.isSuccess && statusOk;
-            const message = text(body.message);
-            let errors;
-            const names = text(body.inputName);
-            if (!ok && names && message) {
-                errors = {};
-                for (const name of names.split("|"))
-                    if (name.trim())
-                        errors[name.trim()] = message;
-            }
-            // The backend's defaults ("SUCCESS", "GENERIC_ERROR", error 0) say nothing, so they are left out.
-            const code = text(body.messageCode);
-            const messageCode = code && code !== (ok ? "SUCCESS" : "GENERIC_ERROR") ? code : undefined;
-            const errorCode = typeof body.errorCode === "number" && body.errorCode !== 0 ? body.errorCode : undefined;
+            // A failure's problems: its list, else the message and codes at the top level as the one problem.
+            const problems = ok ? [] : readErrorMessages(body, body);
+            const said = problems.map(problem => problem.message).join(" ") || text(body.message);
+            const messageCode = problems[0]?.messageCode ?? codeOf(body.messageCode);
+            const errorCode = problems[0]?.errorCode ?? count(body.errorCode);
             return {
                 ok,
-                status,
+                // An answer read without its HTTP status (an app's own send function) still carries it as `code`.
+                status: status ?? count(body.code),
                 result: body.result,
-                message: message ?? (ok ? undefined : fallback()),
-                errors,
+                message: said ?? (ok ? undefined : fallback()),
+                errors: fieldErrors(problems),
+                ...(problems.length ? { errorMessages: problems } : {}),
                 ...(messageCode ? { messageCode } : {}),
-                ...(errorCode !== undefined ? { errorCode } : {}),
+                ...(errorCode ? { errorCode } : {}),
             };
         }
-        const errors = readErrorMap(body.errors);
-        if (errors || !statusOk) {
-            const message = text(body.message) ?? (errors ? undefined : (text(body.detail) ?? text(body.title)));
-            return { ok: false, status, result: body, message: message ?? (errors ? undefined : fallback()), errors };
+        // Another backend's envelope: its problems if it lists any, ASP.NET Core's field map, or its status.
+        const problems = readErrorMessages(body);
+        const errors = readErrorMap(body.errors) ?? fieldErrors(problems);
+        if (problems.length || errors || !statusOk) {
+            const said = problems.map(problem => problem.message).join(" ") || (text(body.message) ?? (errors ? undefined : (text(body.detail) ?? text(body.title))));
+            const messageCode = problems[0]?.messageCode;
+            const errorCode = problems[0]?.errorCode;
+            return {
+                ok: false,
+                status,
+                result: body,
+                message: said ?? (errors ? undefined : fallback()),
+                errors,
+                ...(problems.length ? { errorMessages: problems } : {}),
+                ...(messageCode ? { messageCode } : {}),
+                ...(errorCode ? { errorCode } : {}),
+            };
         }
         return { ok: true, status, result: body, message: text(body.message) };
     }
@@ -124,7 +215,7 @@ export function toFormData(values) {
     }
     return data;
 }
-const RESULT_KEYS = ["result", "message", "errors", "status", "network", "timeout", "aborted", "messageCode", "errorCode"];
+const RESULT_KEYS = ["result", "message", "errors", "errorMessages", "status", "network", "timeout", "aborted", "messageCode", "errorCode"];
 /** Whether a value is already a read answer (`{ ok, … }`), not a server's body. */
 export function isApiResult(value) {
     if (!isRecord(value) || typeof value.ok !== "boolean" || "isSuccess" in value)

package/dist/Helpers/ApiRoutes.d.ts

@@ -16,7 +16,6 @@ export declare const API_ACTIONS: {
     readonly listings: {
         readonly normal: "NormalListing";
         readonly flag: "FlagListing";
-        readonly archive: "ArchiveListing";
         readonly trash: "TrashListing";
         readonly deleted: "DeleteListing";
     };
@@ -24,7 +23,6 @@ export declare const API_ACTIONS: {
     readonly paginations: {
         readonly normal: "NormalPagination";
         readonly flag: "FlagPagination";
-        readonly archive: "ArchivePagination";
         readonly trash: "TrashPagination";
         readonly deleted: "DeletePagination";
     };
@@ -35,21 +33,17 @@ export declare const API_ACTIONS: {
     readonly delete: "Delete";
     readonly trash: "Trash";
     readonly trashFromDelete: "TrashFromDelete";
-    readonly archive: "Archive";
     readonly recover: "Recover";
-    readonly restore: "Restore";
     readonly flag: "Flag";
     readonly pin: "Pin";
     readonly audit: "AuditListing";
     readonly accessActions: "AccessActions";
     readonly massDescription: "MassDescription";
-    readonly massArchive: "MassArchive";
     readonly massTrash: "MassTrash";
     readonly massFlag: "MassFlag";
     readonly massPin: "MassPin";
     readonly massDelete: "MassDelete";
     readonly massRecover: "MassRecover";
-    readonly massRestore: "MassRestore";
     readonly massTrashFromDelete: "MassTrashFromDelete";
 };
 /** An endpoint's optional parts: `bodyType`, `query`, `action`, `subject`. */
@@ -100,8 +94,6 @@ export declare function apiController<TModule extends ApiModuleValue>(module: TM
     delete: ApiEndpoint<TModule>;
     trash: ApiEndpoint<TModule>;
     trashFromDelete: ApiEndpoint<TModule>;
-    archive: ApiEndpoint<TModule>;
-    restore: ApiEndpoint<TModule>;
     recover: ApiEndpoint<TModule>;
     flag: ApiEndpoint<TModule>;
     pin: ApiEndpoint<TModule>;
@@ -112,14 +104,12 @@ export declare function apiController<TModule extends ApiModuleValue>(module: TM
     /** Actions on many rows at once: POST `Room/MassDelete` and the rest, with the ids. */
     mass: {
         description: ApiEndpoint<TModule>;
-        archive: ApiEndpoint<TModule>;
         trash: ApiEndpoint<TModule>;
         trashFromDelete: ApiEndpoint<TModule>;
         flag: ApiEndpoint<TModule>;
         pin: ApiEndpoint<TModule>;
         delete: ApiEndpoint<TModule>;
         recover: ApiEndpoint<TModule>;
-        restore: ApiEndpoint<TModule>;
     };
     /** Any other action of the controller: `ROOMS.action("PUT", "Block/{id}", { action: "update" })`. */
     action: (method: HttpMethod, action: string, extras?: EndpointExtras) => ApiEndpoint<TModule>;

package/dist/Helpers/ApiRoutes.js

@@ -16,9 +16,9 @@ export const API_ACTIONS = {
     /** One page of the `normal` list. */
     pagination: "NormalPagination",
     /** Every record of each list a CRUD shows. */
-    listings: { normal: "NormalListing", flag: "FlagListing", archive: "ArchiveListing", trash: "TrashListing", deleted: "DeleteListing" },
+    listings: { normal: "NormalListing", flag: "FlagListing", trash: "TrashListing", deleted: "DeleteListing" },
     /** One page of each list a CRUD shows. */
-    paginations: { normal: "NormalPagination", flag: "FlagPagination", archive: "ArchivePagination", trash: "TrashPagination", deleted: "DeletePagination" },
+    paginations: { normal: "NormalPagination", flag: "FlagPagination", trash: "TrashPagination", deleted: "DeletePagination" },
     /** The records the user pinned, which a CRUD shows above its list. */
     pinListing: "PinListing",
     create: "Create",
@@ -26,21 +26,17 @@ export const API_ACTIONS = {
     delete: "Delete",
     trash: "Trash",
     trashFromDelete: "TrashFromDelete",
-    archive: "Archive",
     recover: "Recover",
-    restore: "Restore",
     flag: "Flag",
     pin: "Pin",
     audit: "AuditListing",
     accessActions: "AccessActions",
     massDescription: "MassDescription",
-    massArchive: "MassArchive",
     massTrash: "MassTrash",
     massFlag: "MassFlag",
     massPin: "MassPin",
     massDelete: "MassDelete",
     massRecover: "MassRecover",
-    massRestore: "MassRestore",
     massTrashFromDelete: "MassTrashFromDelete",
 };
 const define = (method) => (module, path, extras) => ({ ...extras, module, path, method });
@@ -95,8 +91,6 @@ export function apiController(module, controller, subject) {
         delete: endpoint("DELETE", at(`${A.delete}/{id}`), { action: "delete" }),
         trash: endpoint("DELETE", at(`${A.trash}/{id}`), { action: "trash" }),
         trashFromDelete: endpoint("PUT", at(`${A.trashFromDelete}/{id}`), { action: "trash" }),
-        archive: endpoint("PUT", at(`${A.archive}/{id}`), { action: "archive" }),
-        restore: endpoint("PUT", at(`${A.restore}/{id}`), { action: "restore" }),
         recover: endpoint("PUT", at(`${A.recover}/{id}`), { action: "recover" }),
         flag: endpoint("PUT", at(`${A.flag}/{id}`), { action: "flag" }),
         pin: endpoint("PUT", at(`${A.pin}/{id}`), { action: "pin" }),
@@ -107,14 +101,12 @@ export function apiController(module, controller, subject) {
         /** Actions on many rows at once: POST `Room/MassDelete` and the rest, with the ids. */
         mass: {
             description: endpoint("POST", at(A.massDescription), { action: "update" }),
-            archive: endpoint("POST", at(A.massArchive), { action: "archive" }),
             trash: endpoint("POST", at(A.massTrash), { action: "trash" }),
             trashFromDelete: endpoint("POST", at(A.massTrashFromDelete), { action: "trash" }),
             flag: endpoint("POST", at(A.massFlag), { action: "flag" }),
             pin: endpoint("POST", at(A.massPin), { action: "pin" }),
             delete: endpoint("POST", at(A.massDelete), { action: "delete" }),
             recover: endpoint("POST", at(A.massRecover), { action: "recover" }),
-            restore: endpoint("POST", at(A.massRestore), { action: "restore" }),
         },
         /** Any other action of the controller: `ROOMS.action("PUT", "Block/{id}", { action: "update" })`. */
         action: (method, action, extras) => endpoint(method, at(action), extras),

package/dist/Helpers/ChatBackend.d.ts

@@ -0,0 +1,134 @@
+import { type ApiEndpoint, type ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
+import type { AppChatDomain, ChatConversation, ChatDomainInfo, ChatDomainValue, ChatDraft, ChatHistory, ChatHistoryRequest, ChatId, ChatMessage, ChatParticipant, ChatParticipantPage, ChatParticipantQuery, ChatScope, ChatSummary, NewChatRequest } from "../Interfaces/ChatInterfaces.ts";
+/** The actions a chat needs from a backend. A backend that does not serve one takes that feature off the panel. */
+export declare const CHAT_ACTIONS: {
+    /** The conversations a record holds, for this reader. */
+    readonly conversations: "ConversationListing";
+    /** Starts one. */
+    readonly createConversation: "CreateConversation";
+    /** One page of messages. */
+    readonly history: "History";
+    /** Writes one message. */
+    readonly send: "Create";
+    /** The counts of many records at once, for the trigger icons in a list. */
+    readonly summaries: "Summaries";
+    /** The people in a conversation, and the ones who could join, searched. */
+    readonly participants: "ParticipantPagination";
+    /** How far this user has read. */
+    readonly read: "Read";
+    /** Removes one message. */
+    readonly remove: "Delete";
+    /** Adds people to a conversation. */
+    readonly addParticipants: "AddParticipants";
+};
+export type ChatAction = keyof typeof CHAT_ACTIONS;
+type Row = Record<string, unknown>;
+/**
+ * What a chat needs from a backend. Extend it for an app whose chat API differs from the Nexus one, and register it
+ * once beside the app's API modules:
+ *
+ * @example
+ * class HrChatBackend extends NexusChatBackend {
+ *   override endpoint(action: ChatAction) {
+ *     return action === "history" ? apiEndpoint.post(HrModule.Staff, "LeaveChat/Page") : super.endpoint(action);
+ *   }
+ * }
+ * defineChatBackend(new HrChatBackend());
+ */
+export declare abstract class ChatBackend<TDomain extends ChatDomainValue = AppChatDomain> {
+    /**
+     * Which endpoint serves an action. The module is one of the app's own (`AppModule`), as everywhere else in the API
+     * layer: an app on another backend registers a backend of its own and names its own modules here.
+     */
+    abstract endpoint(action: ChatAction): ApiEndpoint;
+    /** Whether the backend serves an action. Default true; `false` takes the feature off the panel. */
+    supports(action: ChatAction): boolean;
+    /** What asking for a record's conversations sends. */
+    abstract conversationsRequest(scope: ChatScope<TDomain>): unknown;
+    /** Reads them. */
+    abstract readConversations(result: unknown): readonly ChatConversation[];
+    /** What starting a conversation sends. */
+    abstract createConversationRequest(scope: ChatScope<TDomain>, request: NewChatRequest): unknown;
+    /** Reads the conversation that was started, or the one that already existed. */
+    abstract readConversation(result: unknown): ChatConversation;
+    /** What a history request sends: which conversation, and which page of it. */
+    abstract historyRequest(scope: ChatScope<TDomain>, request: ChatHistoryRequest, conversationId?: ChatId): unknown;
+    /** Reads a page of history. */
+    abstract readHistory(result: unknown): ChatHistory;
+    /** What sending a message sends. */
+    abstract sendRequest(scope: ChatScope<TDomain>, draft: ChatDraft, conversationId?: ChatId): unknown;
+    /** Reads the saved message. The draft is there for a backend that answers with an id alone. */
+    abstract readMessage(result: unknown, scope: ChatScope<TDomain>, draft: ChatDraft): ChatMessage;
+    /** What asking for many records' counts sends. One call carries one domain and many parent ids. */
+    abstract summariesRequest(domain: TDomain, parentIds: readonly ChatId[], userId: ChatId): unknown;
+    /** Reads those counts, by parent id as text (`String(parentId)`). Records the answer leaves out have no messages. */
+    abstract readSummaries(result: unknown): Map<string, ChatSummary>;
+    /** What a participant search sends. Without a conversation it asks who could be put in a new one. */
+    abstract participantsRequest(scope: ChatScope<TDomain>, query: ChatParticipantQuery, conversationId?: ChatId): unknown;
+    /** Reads a page of participants. */
+    abstract readParticipants(result: unknown): ChatParticipantPage;
+    /** What the read mark sends. */
+    abstract readMarkRequest(scope: ChatScope<TDomain>, upTo: ChatId, conversationId?: ChatId): unknown;
+    /** What adding people sends. */
+    abstract addParticipantsRequest(scope: ChatScope<TDomain>, userIds: readonly ChatId[], conversationId?: ChatId): unknown;
+    /** What removing a message sends, as the call's `params`: the id in the path. */
+    removeParams(scope: ChatScope<TDomain>, messageId: ChatId): Record<string, string | number>;
+}
+/**
+ * The Nexus Chat module: one controller, `Chat`, whose actions take the domain, the parent id and the reader, and
+ * answer as the other Nexus endpoints do (`{ results, totalCount, filterCount }` for pages). See the note at the top
+ * of this file: these are the shape the module is expected to take.
+ */
+export declare class NexusChatBackend<TDomain extends ChatDomainValue = AppChatDomain> extends ChatBackend<TDomain> {
+    /** The module the chat endpoints live in. `NexusModule.Chat` (bit 6). */
+    readonly module: ApiModuleValue;
+    /** The controller the actions hang off. */
+    readonly controller: string;
+    endpoint(action: ChatAction): ApiEndpoint;
+    conversationsRequest(scope: ChatScope<TDomain>): unknown;
+    readConversations(result: unknown): readonly ChatConversation[];
+    createConversationRequest(scope: ChatScope<TDomain>, request: NewChatRequest): unknown;
+    readConversation(result: unknown): ChatConversation;
+    historyRequest(scope: ChatScope<TDomain>, request: ChatHistoryRequest, conversationId?: ChatId): unknown;
+    readHistory(result: unknown): ChatHistory;
+    sendRequest(scope: ChatScope<TDomain>, draft: ChatDraft, conversationId?: ChatId): unknown;
+    readMessage(result: unknown, scope: ChatScope<TDomain>, draft: ChatDraft): ChatMessage;
+    summariesRequest(domain: TDomain, parentIds: readonly ChatId[], userId: ChatId): unknown;
+    readSummaries(result: unknown): Map<string, ChatSummary>;
+    participantsRequest(scope: ChatScope<TDomain>, query: ChatParticipantQuery, conversationId?: ChatId): unknown;
+    readParticipants(result: unknown): ChatParticipantPage;
+    readMarkRequest(scope: ChatScope<TDomain>, upTo: ChatId, conversationId?: ChatId): unknown;
+    addParticipantsRequest(scope: ChatScope<TDomain>, userIds: readonly ChatId[], conversationId?: ChatId): unknown;
+    /**
+     * One conversation row. The type comes back as the backend's `EChatTypes` number (0 one-to-one, 1 group) or as a
+     * name; both are read, because which it will be is not settled.
+     */
+    protected toConversation(row: Row): ChatConversation;
+    /** One message row. The names are the ones a Nexus contract uses; override this alone for a backend that differs. */
+    protected toMessage(row: Row): ChatMessage;
+    /** One set of counts. */
+    protected toSummary(row: Row): ChatSummary;
+    /** One participant row. */
+    protected toParticipant(row: Row): ChatParticipant;
+}
+/** Makes an app's chat backend the one every chat uses, and returns it. Call it once, beside `defineApiModules`. */
+export declare function defineChatBackend<T extends ChatBackend<any>>(backend: T): T;
+/** The app's chat backend: the one given to `defineChatBackend`, else the Nexus one. */
+export declare function getChatBackend(): ChatBackend<any>;
+/**
+ * Names the app's domains, for the panel's heading and its messages. The values are the app's own enum, so this
+ * package never holds a number of its own: the owner's list is Leave, Procurement, Applicants, Students, Companies,
+ * Tenders and the account kinds, and which number each one is belongs to the backend's `EDomainTypes`.
+ *
+ * @example
+ * defineChatDomains([
+ *   { domain: EDomainTypes.Leave, key: "leave", label: "Leave request" },
+ *   { domain: EDomainTypes.Procurement, key: "procurement", label: "Purchase order" },
+ * ]);
+ */
+export declare function defineChatDomains<TDomain extends ChatDomainValue>(list: readonly ChatDomainInfo<TDomain>[]): readonly ChatDomainInfo<TDomain>[];
+/** The registered domains. Empty until an app calls `defineChatDomains`. */
+export declare function getChatDomains(): readonly ChatDomainInfo<any>[];
+/** A domain's name on screen, or `undefined` when the app has not named it. */
+export declare function chatDomainLabel(domain: ChatDomainValue): string | undefined;
+export {};