nexus-shared 1.1.21 → 3.0.0

package/dist/Interfaces/TypeInterfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/Server.Index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Services/ApiProxy.ts";
+export * from "./Services/ServerApi.ts";

package/dist/Server.Index.js

@@ -0,0 +1,5 @@
+// Server-only code: layouts that read configuration, API helpers that use secrets.
+// Import from "nexus-shared/server".
+// Services
+export * from "./Services/ApiProxy.js";
+export * from "./Services/ServerApi.js";

package/dist/Services/ApiProxy.d.ts

@@ -0,0 +1,32 @@
+import type { ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
+export interface ApiProxyOptions {
+    /** The user's token for the backend, such as from the session cookie. Without one, the request's own Authorization header goes on. */
+    token?: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
+    /** Headers to add, such as a tenant from the session. */
+    headers?: (request: Request) => Record<string, string> | undefined | Promise<Record<string, string> | undefined>;
+    /** Serves only these modules, of those the app's `ApiModules` sends through the proxy. Default: all of those. */
+    allow?: readonly ApiModuleValue[];
+    /** Milliseconds to wait for the backend to start answering. Default 60,000. */
+    timeout?: number;
+    /** The `fetch` to use. Default: the global one. */
+    fetch?: typeof fetch;
+}
+/** What a Next.js route handler for `[module]/[...path]` receives. */
+export interface ApiProxyContext {
+    params: Promise<{
+        module: string;
+        path?: string[];
+    }>;
+}
+/**
+ * Makes the route handlers of the proxy. Only the modules' configured roots can be reached: a path cannot climb out of
+ * its module (`..` is refused), and the query goes on unchanged.
+ */
+export declare function createApiProxy(options?: ApiProxyOptions): {
+    GET: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    HEAD: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    POST: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    PUT: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    PATCH: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    DELETE: (request: Request, context: ApiProxyContext) => Promise<Response>;
+};

package/dist/Services/ApiProxy.js

@@ -0,0 +1,111 @@
+import { DEFAULT_API_TIMEOUT, isFrameworkError } from "../Helpers/ApiClient.js";
+import { getApiModules } from "../Helpers/ApiModules.js";
+import { joinUrl } from "../Helpers/ApiRoutes.js";
+import { buildMessage } from "../Helpers/MessageBuilder.js";
+import { serverModuleRoot } from "./ServerApi.js";
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+/** Request headers that belong to this hop, or to the app (its cookies), not to the backend. */
+const REQUEST_HEADERS_TO_SKIP = new Set(["host", "connection", "content-length", "transfer-encoding", "keep-alive", "upgrade", "cookie", "te", "trailer", "proxy-authorization", "proxy-connection", "accept-encoding"]);
+/**
+ * Response headers that belong to the backend's hop. `content-encoding` and `content-length` go too: `fetch` has already
+ * decompressed the body, so passing them on would make the browser decode it twice.
+ */
+const RESPONSE_HEADERS_TO_SKIP = new Set(["connection", "transfer-encoding", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "upgrade", "content-encoding", "content-length"]);
+/** An answer the client reads like the backend's own. */
+function failure(status, message, messageCode) {
+    return Response.json({ isSuccess: false, code: status, message, messageCode }, { status });
+}
+/** A backend redirect to its own host, pointed back through the proxy. */
+function rewriteLocation(location, root, module, proxyPath) {
+    const target = new URL(location, root);
+    if (target.host !== root.host)
+        return location;
+    const base = root.pathname.replace(/\/+$/, "");
+    const relative = target.pathname.startsWith(`${base}/`) ? target.pathname.slice(base.length + 1) : target.pathname.replace(/^\/+/, "");
+    return `${joinUrl(joinUrl(proxyPath, module), relative)}${target.search}`;
+}
+/**
+ * Makes the route handlers of the proxy. Only the modules' configured roots can be reached: a path cannot climb out of
+ * its module (`..` is refused), and the query goes on unchanged.
+ */
+export function createApiProxy(options = {}) {
+    async function handle(request, context) {
+        const method = request.method.toUpperCase();
+        if (!METHODS.has(method))
+            return failure(405, buildMessage("reason", { status: 405 }), "METHOD_NOT_ALLOWED");
+        const { module: key, path = [] } = await context.params;
+        // Asked on every request, so the app's modules count even when they were registered after this route was made.
+        const modules = getApiModules();
+        const info = modules.info(key);
+        if (!info || (options.allow && !options.allow.includes(info.module)))
+            return failure(404, `No API module is named "${key}".`, "MODULE_NOT_FOUND");
+        if (!modules.proxies(info.module))
+            return failure(404, `The ${info.label} API is not called through this app's proxy.`, "MODULE_NOT_PROXIED");
+        if (path.some(segment => segment === "." || segment === ".." || /[\\/]/.test(segment)))
+            return failure(400, "The API path is not valid.", "INVALID_PATH");
+        const incoming = new URL(request.url);
+        let root;
+        try {
+            root = new URL(await serverModuleRoot(info.module, incoming.origin));
+        }
+        catch (error) {
+            if (isFrameworkError(error))
+                throw error;
+            return failure(500, error instanceof Error ? error.message : String(error), "MODULE_NOT_CONFIGURED");
+        }
+        const target = new URL(joinUrl(root.toString(), path.map(encodeURIComponent).join("/")));
+        target.search = incoming.search;
+        const headers = new Headers();
+        request.headers.forEach((value, name) => {
+            if (!REQUEST_HEADERS_TO_SKIP.has(name.toLowerCase()))
+                headers.set(name, value);
+        });
+        for (const [name, value] of Object.entries((await options.headers?.(request)) ?? {}))
+            headers.set(name, value);
+        const token = await options.token?.(request);
+        if (token)
+            headers.set("Authorization", /^bearer /i.test(token) ? token : `Bearer ${token}`);
+        const controller = new AbortController();
+        const timeout = options.timeout ?? DEFAULT_API_TIMEOUT;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeout);
+        // The browser left: stop waiting for the backend.
+        const leave = () => controller.abort();
+        request.signal?.addEventListener("abort", leave, { once: true });
+        let answer;
+        try {
+            answer = await (options.fetch ?? globalThis.fetch)(target, {
+                method,
+                headers,
+                body: method === "GET" || method === "HEAD" ? undefined : await request.arrayBuffer(),
+                redirect: "manual",
+                cache: "no-store",
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (isFrameworkError(error))
+                throw error;
+            if (timedOut)
+                return failure(504, buildMessage("reason", { timeout: true }), "BACKEND_TIMEOUT");
+            return failure(502, `The ${info.label} API cannot be reached. Try again in a moment.`, "BACKEND_UNREACHABLE");
+        }
+        finally {
+            // The timeout covers the wait for the answer to start; a long download then streams through.
+            clearTimeout(timer);
+            request.signal?.removeEventListener("abort", leave);
+        }
+        const responseHeaders = new Headers();
+        answer.headers.forEach((value, name) => {
+            const lower = name.toLowerCase();
+            if (RESPONSE_HEADERS_TO_SKIP.has(lower))
+                return;
+            responseHeaders.append(name, lower === "location" ? rewriteLocation(value, root, info.key, modules.proxyPath) : value);
+        });
+        return new Response(method === "HEAD" ? null : answer.body, { status: answer.status, statusText: answer.statusText, headers: responseHeaders });
+    }
+    return { GET: handle, HEAD: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle };
+}

package/dist/Services/BrowserApi.d.ts

@@ -0,0 +1,95 @@
+import { type ConfirmOptions } from "../Components/Layouts/MessageBox.tsx";
+import { type ApiCall, type ApiResponseReader } from "../Helpers/ApiClient.ts";
+import { type ApiToastDefaults, type ApiToastOption } from "../Helpers/ApiToasts.ts";
+import type { ApiCallOptions, ApiResult, ApiTarget } from "../Interfaces/ApiInterfaces.ts";
+import type { DropdownItem, DropdownPage, DropdownPageRequest } from "../Interfaces/InputInterfaces.ts";
+/** Options of a browser call, on top of every call's options. */
+export interface BrowserApiOptions {
+    /** Toasts for this call. Default: errors always, successes for POST, PUT, PATCH, and DELETE. See `ApiToastOption`. */
+    toast?: ApiToastOption;
+}
+/** How browser calls behave. Where they go (the proxy or each module's root) is the app's `ApiModules`. */
+export interface BrowserApiConfig {
+    /** Headers on every call, such as the tenant or branch. */
+    headers?: (call: ApiCall<BrowserApiOptions>) => Record<string, string> | undefined;
+    /** A bearer token for every call. Leave it out with the proxy, which adds the token from the user's cookie. */
+    token?: (call: ApiCall<BrowserApiOptions>) => string | null | undefined;
+    /** Cookies on calls straight to a module on another origin: `include`. Default: the browser's (same origin only). */
+    credentials?: RequestCredentials;
+    /** Milliseconds to wait for an answer. Default 60,000. */
+    timeout?: number;
+    /**
+     * Reads every answer, for a backend that does not answer as Nexus or ASP.NET Core do. Default `readApiResponse`.
+     * A call still reads its own with `read`. Registered once, it holds for calls the components make inside
+     * themselves too (`Crud`'s lists and actions, `ApiForm`'s save), which cannot be given one.
+     */
+    read?: ApiResponseReader<BrowserApiOptions>;
+    /** Which toasts show when a call does not say. Default: errors always, successes for changes. */
+    toast?: ApiToastDefaults;
+    /** After a 401, or an expired token (Nexus error 2003), such as to send the user to sign in. The error toast shows too. */
+    onSignedOut?: (result: ApiResult) => void;
+    /** After every answer, such as to log failures. */
+    onResult?: (result: ApiResult, call: ApiCall<BrowserApiOptions>) => void;
+}
+/**
+ * Sets up `api` for the app. Call it once in a client module that the root layout loads; later calls change only the
+ * settings they name. Nothing is needed when the proxy is at `/api/app` and the defaults suit.
+ */
+export declare function configureApi(config: BrowserApiConfig): void;
+/**
+ * The app's default response reader, when it registered one (`configureApi({ read })`). For answers that did not come
+ * from a call and so have no client to read them: what an `ApiForm`'s own send function returned.
+ */
+export declare function getApiReader(): ApiResponseReader<BrowserApiOptions> | undefined;
+/**
+ * The app's call settings, for a request `api` cannot make: a download, which has to read the file's own bytes and the
+ * headers that name it, rather than an answer read as JSON. The headers, the token, and the cookie rule an app
+ * registered once belong on such a request too (`Services/ExcelApi.ts` is the one caller).
+ */
+export declare function getApiCallSettings(): BrowserApiConfig;
+/** Options of `api.confirm`: the call's, and changes to the question. */
+export type ConfirmApiOptions = ApiCallOptions & BrowserApiOptions & {
+    question?: Partial<ConfirmOptions>;
+};
+/**
+ * Asks first, then sends. The question comes from the message builder ("Delete Room 204?", "This cannot be undone.",
+ * a Delete button, in red for actions that lose something). Resolves with the answer, or `null` when the user said no.
+ */
+declare function confirmThenSend<T = unknown>(target: ApiTarget, { question, ...options }?: ConfirmApiOptions): Promise<ApiResult<T> | null>;
+/**
+ * Calls APIs from the browser, with toasts.
+ *
+ * @example
+ * const ROOMS = MODULES.controller(NexusModule.Reservation, "Room", "room");   // MODULES: the app's defineApiModules(…)
+ *
+ * const rooms = await api.get<Room[]>(ROOMS.listing);                  // error toast if it fails
+ * if (rooms.ok) setRows(rooms.result);
+ *
+ * await api.put(ROOMS.update, values, { subject: `Room ${values.number}` });   // "Room 204 saved." or why not
+ * await api.delete(ROOMS.delete, { params: { id }, toast: { loading: true } });
+ * await api.confirm(ROOMS.delete, { params: { id }, subject: "Room 204" });   // "Delete Room 204?" first; null if not
+ * await api.post("/api/demo-rooms", values, { toast: false });        // a URL, no toasts
+ */
+export declare const api: import("../Shared.Index.ts").ApiClient<BrowserApiOptions> & {
+    confirm: typeof confirmThenSend;
+};
+export interface ApiOptionsLoaderOptions<TRow, TItem> {
+    /** Turns a row the API sends into a dropdown item. Default: the row is the item. */
+    toItem?: (row: TRow) => TItem;
+    /**
+     * What is sent for a page. Default, as Nexus pagination APIs take it: `{ searchKeyword, skipCount, maxCount }`, in the
+     * body for POST and in the query for GET.
+     */
+    request?: (page: DropdownPageRequest) => Record<string, unknown>;
+    /** Other options of the call, such as `params` or `headers`. */
+    call?: Omit<ApiCallOptions, "body" | "signal">;
+}
+/**
+ * A dropdown's `loadOptions` for an API that sends pages (`{ results, totalCount, filterCount }`) or a whole list.
+ * Failures show in the dropdown, with Retry, not as a toast.
+ *
+ * @example
+ * <Dropdown name="roomId" label="Room" valueKey="id" labelKey="number" loadOptions={apiOptionsLoader(ROOMS.pagination)} />
+ */
+export declare function apiOptionsLoader<TRow extends DropdownItem = DropdownItem, TItem extends DropdownItem = TRow>(target: ApiTarget, { toItem, request, call }?: ApiOptionsLoaderOptions<TRow, TItem>): (page: DropdownPageRequest) => Promise<DropdownPage<TItem>>;
+export {};

package/dist/Services/BrowserApi.js

@@ -0,0 +1,129 @@
+"use client";
+import { messageBox } from "../Components/Layouts/MessageBox.js";
+import { toast } from "../Components/Layouts/Toaster.js";
+import { apiCallContext, createApiClient } from "../Helpers/ApiClient.js";
+import { unwrapApiResult } from "../Helpers/ApiResponses.js";
+import { getApiModules } from "../Helpers/ApiModules.js";
+import { isApiEndpoint, joinUrl } from "../Helpers/ApiRoutes.js";
+import { planApiToast, planLoadingToast } from "../Helpers/ApiToasts.js";
+import { buildMessage } from "../Helpers/MessageBuilder.js";
+let settings = {};
+/**
+ * Sets up `api` for the app. Call it once in a client module that the root layout loads; later calls change only the
+ * settings they name. Nothing is needed when the proxy is at `/api/app` and the defaults suit.
+ */
+export function configureApi(config) {
+    settings = { ...settings, ...config };
+}
+/**
+ * The app's default response reader, when it registered one (`configureApi({ read })`). For answers that did not come
+ * from a call and so have no client to read them: what an `ApiForm`'s own send function returned.
+ */
+export function getApiReader() {
+    return settings.read;
+}
+/**
+ * The app's call settings, for a request `api` cannot make: a download, which has to read the file's own bytes and the
+ * headers that name it, rather than an answer read as JSON. The headers, the token, and the cookie rule an app
+ * registered once belong on such a request too (`Services/ExcelApi.ts` is the one caller).
+ */
+export function getApiCallSettings() {
+    return settings;
+}
+/** Nexus error code for an expired token. */
+const TOKEN_EXPIRED = 2003;
+const TOAST_DURATION = 5000;
+function showToast(plan, id) {
+    // `icon`, `duration`, and `closable` are set, so a loading toast turned into this one loses its spinner and timer.
+    toast(plan.title, { id, tone: plan.tone, message: plan.message, icon: undefined, duration: TOAST_DURATION, closable: true });
+}
+const config = {
+    resolveUrl: (endpoint, path) => joinUrl(getApiModules().browserUrl(endpoint.module), path),
+    headers: call => settings.headers?.(call),
+    token: call => settings.token?.(call),
+    get timeout() {
+        return settings.timeout;
+    },
+    get credentials() {
+        return settings.credentials;
+    },
+    get read() {
+        return settings.read;
+    },
+    dedupe: true,
+    onStart(call) {
+        const loading = planLoadingToast(call.context, call.options.toast);
+        const loadingId = loading ? toast.loading(loading) : undefined;
+        return result => {
+            if (result.status === 401 || result.errorCode === TOKEN_EXPIRED)
+                settings.onSignedOut?.(result);
+            settings.onResult?.(result, call);
+            const plan = planApiToast(result, call.method, call.context, call.options.toast, settings.toast);
+            if (!plan) {
+                if (loadingId)
+                    toast.dismiss(loadingId);
+                return;
+            }
+            // The same failure twice (two lists on a page loading the same URL) shows one toast, not two.
+            showToast(plan, loadingId ?? (plan.tone === "danger" && call.url ? `nx-api:${call.method}:${call.url}` : undefined));
+        };
+    },
+};
+const client = createApiClient(config);
+/** Actions that lose something, asked about in red. */
+const DESTRUCTIVE = new Set(["delete", "trash", "reject", "cancel"]);
+/**
+ * Asks first, then sends. The question comes from the message builder ("Delete Room 204?", "This cannot be undone.",
+ * a Delete button, in red for actions that lose something). Resolves with the answer, or `null` when the user said no.
+ */
+async function confirmThenSend(target, { question, ...options } = {}) {
+    const { context } = apiCallContext(target, options);
+    const yes = await messageBox.confirm({
+        title: buildMessage("confirm", context),
+        message: buildMessage("confirmDetail", context) || undefined,
+        tone: typeof context.action === "string" && DESTRUCTIVE.has(context.action) ? "danger" : "question",
+        confirmLabel: buildMessage("label", context),
+        ...question,
+    });
+    return yes ? client.send(target, options) : null;
+}
+/**
+ * Calls APIs from the browser, with toasts.
+ *
+ * @example
+ * const ROOMS = MODULES.controller(NexusModule.Reservation, "Room", "room");   // MODULES: the app's defineApiModules(…)
+ *
+ * const rooms = await api.get<Room[]>(ROOMS.listing);                  // error toast if it fails
+ * if (rooms.ok) setRows(rooms.result);
+ *
+ * await api.put(ROOMS.update, values, { subject: `Room ${values.number}` });   // "Room 204 saved." or why not
+ * await api.delete(ROOMS.delete, { params: { id }, toast: { loading: true } });
+ * await api.confirm(ROOMS.delete, { params: { id }, subject: "Room 204" });   // "Delete Room 204?" first; null if not
+ * await api.post("/api/demo-rooms", values, { toast: false });        // a URL, no toasts
+ */
+export const api = Object.assign(client, { confirm: confirmThenSend });
+/**
+ * A dropdown's `loadOptions` for an API that sends pages (`{ results, totalCount, filterCount }`) or a whole list.
+ * Failures show in the dropdown, with Retry, not as a toast.
+ *
+ * @example
+ * <Dropdown name="roomId" label="Room" valueKey="id" labelKey="number" loadOptions={apiOptionsLoader(ROOMS.pagination)} />
+ */
+export function apiOptionsLoader(target, { toItem, request, call } = {}) {
+    const method = call?.method ?? (isApiEndpoint(target) ? target.method : "GET");
+    return async (page) => {
+        const sent = request ? request(page) : { searchKeyword: page.search || undefined, skipCount: page.skip, maxCount: page.pageSize };
+        const answer = unwrapApiResult(await api.send(target, {
+            ...call,
+            method,
+            ...(method === "GET" ? { query: { ...call?.query, ...sent } } : { body: sent }),
+            signal: page.signal,
+            toast: false,
+        }));
+        const rows = Array.isArray(answer) ? answer : (answer?.results ?? []);
+        const items = toItem ? rows.map(toItem) : rows;
+        if (Array.isArray(answer))
+            return { items, hasMore: false, total: items.length };
+        return { items, total: answer?.filterCount, hasMore: page.skip + rows.length < (answer?.filterCount ?? 0) };
+    };
+}

package/dist/Services/ChatApi.d.ts

@@ -0,0 +1,37 @@
+import { type ChatBackend } from "../Helpers/ChatBackend.ts";
+import { ChatSummaryCache } from "../Helpers/ChatSummaries.ts";
+import type { ApiCallOptions } from "../Interfaces/ApiInterfaces.ts";
+import type { ChatDomainValue, ChatId, ChatPlaceSource, ChatScope, ChatSource, ChatSummary } from "../Interfaces/ChatInterfaces.ts";
+/** Options of one chat's source. */
+export interface ApiChatSourceOptions {
+    /** Which conversation at the place, when the record holds more than one. */
+    conversationId?: ChatId;
+    /** The backend to use, when it is not the app's registered one. */
+    backend?: ChatBackend<ChatDomainValue>;
+    /** Extras on every call this source makes, such as a header. */
+    call?: Omit<ApiCallOptions, "body" | "signal" | "params">;
+}
+/**
+ * A conversation's data through the app's API.
+ *
+ * @example
+ * const scope = { domain: EDomainTypes.Leave, parentId: leave.id, userId: me.id };
+ * const source = useMemo(() => apiChatSource(scope), [scope.domain, scope.parentId, scope.userId]);
+ */
+export declare function apiChatSource<TDomain extends ChatDomainValue>(scope: ChatScope<TDomain>, options?: ApiChatSourceOptions): ChatSource;
+/**
+ * The conversations a record holds, and how to start another.
+ *
+ * @example
+ * const place = useMemo(() => apiChatPlace(scope), [scope.domain, scope.parentId, scope.userId]);
+ */
+export declare function apiChatPlace<TDomain extends ChatDomainValue>(scope: ChatScope<TDomain>, options?: ApiChatSourceOptions): ChatPlaceSource;
+/** Asks the app's backend for many records' counts in one call. */
+export declare function loadChatSummaries(domain: ChatDomainValue, parentIds: readonly ChatId[], userId: ChatId): Promise<Map<string, ChatSummary>>;
+/**
+ * The counts every trigger icon on the page reads, filled in one call per domain however many icons there are. A page
+ * that already has the counts in its rows passes them to the icon instead, and never touches this.
+ */
+export declare function chatSummaries(): ChatSummaryCache;
+/** Replaces the page's count cache: a test's, or one with a different batching window. */
+export declare function defineChatSummaries(replacement: ChatSummaryCache): ChatSummaryCache;

package/dist/Services/ChatApi.js

@@ -0,0 +1,98 @@
+"use client";
+import { getChatBackend } from "../Helpers/ChatBackend.js";
+import { ChatSummaryCache } from "../Helpers/ChatSummaries.js";
+import { unwrapApiResult } from "../Helpers/ApiResponses.js";
+import { api } from "./BrowserApi.js";
+const callOptions = (options, signal) => ({ ...options?.call, ...(signal && { signal }), toast: false });
+/**
+ * A conversation's data through the app's API.
+ *
+ * @example
+ * const scope = { domain: EDomainTypes.Leave, parentId: leave.id, userId: me.id };
+ * const source = useMemo(() => apiChatSource(scope), [scope.domain, scope.parentId, scope.userId]);
+ */
+export function apiChatSource(scope, options) {
+    const backend = (options?.backend ?? getChatBackend());
+    const chat = options?.conversationId;
+    const source = {
+        async history(request) {
+            const answer = await api.send(backend.endpoint("history"), { ...callOptions(options, request.signal), body: backend.historyRequest(scope, request, chat) });
+            return backend.readHistory(unwrapApiResult(answer));
+        },
+        async send(draft, signal) {
+            const answer = await api.send(backend.endpoint("send"), { ...callOptions(options, signal), body: backend.sendRequest(scope, draft, chat) });
+            return backend.readMessage(unwrapApiResult(answer), scope, draft);
+        },
+    };
+    if (backend.supports("participants")) {
+        source.participants = async (query) => {
+            const answer = await api.send(backend.endpoint("participants"), { ...callOptions(options, query.signal), body: backend.participantsRequest(scope, query, chat) });
+            return backend.readParticipants(unwrapApiResult(answer));
+        };
+    }
+    if (backend.supports("addParticipants")) {
+        source.addParticipants = async (ids, signal) => {
+            const answer = await api.send(backend.endpoint("addParticipants"), { ...callOptions(options, signal), body: backend.addParticipantsRequest(scope, ids, chat) });
+            return backend.readParticipants(unwrapApiResult(answer)).items;
+        };
+    }
+    if (backend.supports("read")) {
+        source.markRead = async (upTo, signal) => {
+            unwrapApiResult(await api.send(backend.endpoint("read"), { ...callOptions(options, signal), body: backend.readMarkRequest(scope, upTo, chat) }));
+        };
+    }
+    if (backend.supports("remove")) {
+        source.remove = async (messageId, signal) => {
+            unwrapApiResult(await api.send(backend.endpoint("remove"), { ...callOptions(options, signal), params: backend.removeParams(scope, messageId) }));
+        };
+    }
+    return source;
+}
+/**
+ * The conversations a record holds, and how to start another.
+ *
+ * @example
+ * const place = useMemo(() => apiChatPlace(scope), [scope.domain, scope.parentId, scope.userId]);
+ */
+export function apiChatPlace(scope, options) {
+    const backend = (options?.backend ?? getChatBackend());
+    const place = {
+        async conversations(signal) {
+            const answer = await api.send(backend.endpoint("conversations"), { ...callOptions(options, signal), body: backend.conversationsRequest(scope) });
+            return backend.readConversations(unwrapApiResult(answer));
+        },
+    };
+    if (backend.supports("createConversation")) {
+        place.create = async (request, signal) => {
+            const answer = await api.send(backend.endpoint("createConversation"), { ...callOptions(options, signal), body: backend.createConversationRequest(scope, request) });
+            return backend.readConversation(unwrapApiResult(answer));
+        };
+    }
+    if (backend.supports("participants")) {
+        // Without a conversation, this asks who could be put in a new one here.
+        place.participants = async (query) => {
+            const answer = await api.send(backend.endpoint("participants"), { ...callOptions(options, query.signal), body: backend.participantsRequest(scope, query) });
+            return backend.readParticipants(unwrapApiResult(answer));
+        };
+    }
+    return place;
+}
+/** Asks the app's backend for many records' counts in one call. */
+export async function loadChatSummaries(domain, parentIds, userId) {
+    const backend = getChatBackend();
+    const answer = await api.send(backend.endpoint("summaries"), { body: backend.summariesRequest(domain, parentIds, userId), toast: false });
+    return backend.readSummaries(unwrapApiResult(answer));
+}
+let cache;
+/**
+ * The counts every trigger icon on the page reads, filled in one call per domain however many icons there are. A page
+ * that already has the counts in its rows passes them to the icon instead, and never touches this.
+ */
+export function chatSummaries() {
+    return (cache ??= new ChatSummaryCache({ load: loadChatSummaries }));
+}
+/** Replaces the page's count cache: a test's, or one with a different batching window. */
+export function defineChatSummaries(replacement) {
+    cache = replacement;
+    return replacement;
+}

package/dist/Services/ExcelApi.d.ts

@@ -0,0 +1,46 @@
+import type { ApiCallOptions, ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { ExcelDownload, ExcelEndpoints, ExcelExportQuery, ExcelImportAnswer, ExcelSettings, ExcelSheetRow, ExcelVerifyAnswer } from "../Interfaces/ExcelInterfaces.ts";
+/** Options every spreadsheet call takes. */
+export interface ExcelCallOptions extends Pick<ApiCallOptions, "params" | "query" | "headers" | "signal" | "timeout" | "subject" | "read"> {
+    /** Shows no toast for this call. Default: a failure is told, a success is not (the panel says what happened). */
+    toast?: false;
+}
+/** Options of an export. Its `query` is what the person has on screen, not query-string values. */
+export interface ExcelExportOptions extends Omit<ExcelCallOptions, "query"> {
+    /** The search, the sort and the filters the person has on screen. */
+    query?: ExcelExportQuery;
+    /**
+     * Rows the search on screen leaves, when the page knows. Over the backend's limit, the person is asked first and
+     * told what will happen; without it, nothing is asked and the answer's own headers say what was left out.
+     */
+    rows?: number;
+    /** What one row is, for the question and the toast: "city". Default: the settings' subject. */
+    subject?: string;
+    /** Asks nothing, whatever the count. For a page that asked already. */
+    confirm?: false;
+}
+/**
+ * The limits and the shape of the sheet. It is the same for everybody and changes once a release, so the first answer
+ * is kept for as long as the page lives - the backend says the same with a `Cache-Control` of an hour.
+ */
+export declare function excelSettings(endpoints: ExcelEndpoints, options?: ExcelCallOptions): Promise<ApiResult<ExcelSettings>>;
+/** Forgets the kept settings, for a test or an app that changed what a sheet holds while it ran. */
+export declare function clearExcelSettings(): void;
+/** The template to fill in, as the backend built it, under the name the answer gives it. */
+export declare function downloadExcelTemplate(endpoints: ExcelEndpoints, options?: ExcelCallOptions): Promise<ApiResult<ExcelDownload>>;
+/**
+ * An export of what the person has on screen: the search, the sort and the filters, sent to the model's own action.
+ * Not a file written from the rows the browser happens to hold - the backend writes every row the search leaves, up to
+ * its own limit, and says in the answer's headers what it left out.
+ *
+ * Over that limit the person is asked first, because a file that is quietly short is worse than one they chose.
+ */
+export declare function exportExcel(endpoints: ExcelEndpoints, options?: ExcelExportOptions): Promise<ApiResult<ExcelDownload> | null>;
+/** The filled file read and judged, with nothing written. The rows it answers with are what an import sends back. */
+export declare function verifyExcelFile(endpoints: ExcelEndpoints, file: File, options?: ExcelCallOptions): Promise<ApiResult<ExcelVerifyAnswer>>;
+/**
+ * Writes the rows a verify answered with, as the person left them - the **rows**, never the file again, or every fix
+ * they made on screen would be lost. Every check runs again on the way in: what the browser sends is a row, not a
+ * decision.
+ */
+export declare function importExcelRows(endpoints: ExcelEndpoints, rows: readonly ExcelSheetRow[], options?: ExcelCallOptions): Promise<ApiResult<ExcelImportAnswer>>;