@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/_internal/client/features/maintenance/views/RepositoryCacheStatusPanel.js

@@ -0,0 +1,161 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Button, Div, FieldInput, Heading, Skeleton, Span, Text } from "@mohasinac/appkit/client";
+import { normalizeError } from "../../../../../errors/normalize.js";
+import { toUserMessage } from "../../../../../errors/error-display-map.js";
+import { ADMIN_ENDPOINTS } from "../../../../../constants/api-endpoints.js";
+import { ACTIONS } from "../../../../shared/actions/action-registry.js";
+import { useSession } from "../../../../../react/contexts/SessionContext.js";
+import { isAdminUser } from "../../../../../features/auth/role-predicates.js";
+function formatMs(ms) {
+    if (ms === null)
+        return "—";
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    return `${Math.round(s / 60)}m`;
+}
+/**
+ * Item 8 §18 (overhaul brief) — the `CacheManager` in-memory read cache
+ * (today: site settings' 2 fixed keys, products' dynamic per-id/per-slug
+ * prefix), a different layer entirely from `CacheInvalidationPanel` above it
+ * on this page, which clears Next.js's page/ISR cache instead.
+ *
+ * 🛑 "Clear" is write-gated SERVER-SIDE on `admin:maintenance:clear-cache`,
+ * which `maintenance_employee` does not hold (viewing is `view-cache`, which
+ * it does). `ActionDef.permissions` is UI metadata only — `<Button action>`
+ * does not read it — so the buttons are hidden here via `isAdminUser`
+ * directly, the same predicate CLAUDE.md's RBAC rules require everywhere
+ * else, rather than relying on the 403 alone to communicate the boundary.
+ */
+export function RepositoryCacheStatusPanel() {
+    const { user } = useSession();
+    const canClear = isAdminUser(user);
+    const [status, setStatus] = React.useState(null);
+    const [loading, setLoading] = React.useState(true);
+    const [error, setError] = React.useState(null);
+    const [clearingId, setClearingId] = React.useState(null);
+    // Item 8 (overhaul brief) — draft TTL-minutes input per named row, keyed
+    // by source id. Seeded from the live ttlMs once status loads; typing
+    // doesn't save until "Save".
+    const [ttlDrafts, setTtlDrafts] = React.useState({});
+    const [savingTtlId, setSavingTtlId] = React.useState(null);
+    const load = React.useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const res = await fetch(ADMIN_ENDPOINTS.MAINTENANCE_CACHE);
+            const body = (await res.json());
+            if (!res.ok || !body.success) {
+                setError(toUserMessage("code" in body ? String(body.code) : undefined, undefined, {
+                    fallback: `Could not load cache status (HTTP ${res.status}).`,
+                }));
+                return;
+            }
+            setStatus(body.data);
+            setTtlDrafts((prev) => {
+                const next = { ...prev };
+                for (const n of body.data.named) {
+                    if (next[n.id] === undefined) {
+                        next[n.id] = n.ttlMs !== null ? String(Math.round(n.ttlMs / 60000)) : "";
+                    }
+                }
+                return next;
+            });
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            setError(toUserMessage(e.code, undefined, {
+                fallback: "Could not reach the cache status endpoint.",
+            }));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, []);
+    React.useEffect(() => {
+        void load();
+    }, [load]);
+    async function clear(kind, id) {
+        setClearingId(id ?? "all");
+        setError(null);
+        try {
+            const res = await fetch(ADMIN_ENDPOINTS.MAINTENANCE_CACHE, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(kind === "all" ? { kind } : { kind, id }),
+            });
+            const body = (await res.json());
+            if (!res.ok || !body.success) {
+                setError(toUserMessage("code" in body ? String(body.code) : undefined, undefined, {
+                    fallback: `Could not clear that cache (HTTP ${res.status}).`,
+                }));
+                return;
+            }
+            setStatus(body.data.status);
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            setError(toUserMessage(e.code, undefined, {
+                fallback: "Could not reach the cache endpoint.",
+            }));
+        }
+        finally {
+            setClearingId(null);
+        }
+    }
+    async function saveTtl(id) {
+        const raw = ttlDrafts[id] ?? "";
+        const minutes = Number(raw);
+        if (raw.trim() === "" || !Number.isFinite(minutes) || minutes < 0) {
+            setError("Enter a whole number of minutes, 0 or greater.");
+            return;
+        }
+        setSavingTtlId(id);
+        setError(null);
+        try {
+            const res = await fetch(ADMIN_ENDPOINTS.MAINTENANCE_CACHE, {
+                method: "PATCH",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ id, minutes }),
+            });
+            const body = (await res.json());
+            if (!res.ok || !body.success) {
+                setError(toUserMessage("code" in body ? String(body.code) : undefined, undefined, {
+                    fallback: `Could not save that TTL (HTTP ${res.status}).`,
+                }));
+                return;
+            }
+            setStatus(body.data.status);
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            setError(toUserMessage(e.code, undefined, {
+                fallback: "Could not reach the cache endpoint.",
+            }));
+        }
+        finally {
+            setSavingTtlId(null);
+        }
+    }
+    const row = {
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "space-between",
+        padding: "0.5rem 0",
+        borderBottom: "1px solid var(--appkit-color-border-subtle)",
+        gap: "0.75rem",
+    };
+    return (_jsxs(Div, { style: {
+            padding: "1rem 1.25rem",
+            border: "1px solid var(--appkit-color-border)",
+            borderRadius: 8,
+            background: "var(--appkit-color-surface)",
+            marginBottom: "1.5rem",
+        }, children: [_jsxs(Div, { style: { display: "flex", alignItems: "center", justifyContent: "space-between" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600 }, children: "Repository read cache" }), canClear ? (_jsx(Button, { action: ACTIONS.ADMIN["clear-repository-cache"], variant: "ghost", size: "sm", isLoading: clearingId === "all", disabled: clearingId !== null, onClick: () => clear("all"), children: "Clear all" })) : null] }), _jsx(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)", margin: "0.35rem 0 0.9rem" }, children: "In-memory reads of Firestore documents \u2014 a different layer from the page cache above. Clearing one forces its next read to go to Firestore instead of this process\u2019s memory." }), error ? (_jsx(Text, { as: "p", role: "alert", style: { color: "var(--appkit-color-error)", marginBottom: "0.75rem" }, children: error })) : null, loading ? (_jsxs(Div, { style: { display: "flex", flexDirection: "column", gap: "0.5rem" }, children: [_jsx(Skeleton, { height: "1.5rem" }), _jsx(Skeleton, { height: "1.5rem" }), _jsx(Skeleton, { height: "1.5rem" })] })) : status ? (_jsxs(_Fragment, { children: [_jsx(Div, { style: row, children: _jsx(Span, { weight: "semibold", style: { fontSize: "0.8rem", color: "var(--appkit-color-text-muted)" }, children: "Named caches" }) }), status.named.map((n) => (_jsxs(Div, { style: row, children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", children: n.label }), _jsx(Text, { size: "xs", style: { color: "var(--appkit-color-text-muted)" }, children: n.cached
+                                            ? `cached, age ${formatMs(n.ageMs)}, expires in ${formatMs(n.expiresInMs)}`
+                                            : "not cached" })] }), canClear ? (_jsxs(Div, { style: { display: "flex", alignItems: "center", gap: "0.5rem" }, children: [_jsx(Div, { style: { width: "5.5rem" }, children: _jsx(FieldInput, { name: `ttl-${n.id}`, type: "number", label: "TTL (min)", value: ttlDrafts[n.id] ?? "", onChange: (next) => setTtlDrafts((prev) => ({ ...prev, [n.id]: next })) }) }), _jsx(Button, { variant: "outline", size: "sm", isLoading: savingTtlId === n.id, disabled: savingTtlId !== null, onClick: () => saveTtl(n.id), children: "Save" }), _jsx(Button, { action: ACTIONS.ADMIN["clear-repository-cache"], variant: "ghost", size: "sm", isLoading: clearingId === n.id, disabled: clearingId !== null || !n.cached, onClick: () => clear("named", n.id) })] })) : null] }, n.id))), _jsx(Div, { style: { ...row, marginTop: "0.5rem" }, children: _jsx(Span, { weight: "semibold", style: { fontSize: "0.8rem", color: "var(--appkit-color-text-muted)" }, children: "Keyed caches (per-id/per-slug)" }) }), status.keyed.map((k) => (_jsxs(Div, { style: row, children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", children: k.label }), _jsxs(Text, { size: "xs", style: { color: "var(--appkit-color-text-muted)" }, children: [k.entryCount, " entr", k.entryCount === 1 ? "y" : "ies", " cached"] })] }), canClear ? (_jsxs(Button, { action: ACTIONS.ADMIN["clear-repository-cache"], variant: "ghost", size: "sm", isLoading: clearingId === k.id, disabled: clearingId !== null || k.entryCount === 0, onClick: () => clear("keyed", k.id), children: ["Clear all ", k.label] })) : null] }, k.id)))] })) : null] }));
+}

package/dist/_internal/client/features/maintenance/views/ServerErrorDetailView.d.ts

@@ -1,8 +1,11 @@
 import * as React from "react";
 import type { ServerErrorDocument } from "../../../../../features/server-errors/schemas/firestore";
+import type { DashboardCard } from "../../../../shared/features/dashboard/recent-entry";
 export interface ServerErrorDetailViewProps {
     doc: ServerErrorDocument;
     related: ServerErrorDocument[];
     backHref: string;
+    /** Admin-curated page-region cards (Phase 12). Omit for no extra content. */
+    pageRegionCards?: DashboardCard[];
 }
-export declare function ServerErrorDetailView({ doc, related, backHref, }: ServerErrorDetailViewProps): React.JSX.Element;
+export declare function ServerErrorDetailView({ doc, related, backHref, pageRegionCards, }: ServerErrorDetailViewProps): React.JSX.Element;

package/dist/_internal/client/features/maintenance/views/ServerErrorDetailView.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Anchor, Div, Heading, Li, Pre, Section, Text, Ul } from "@mohasinac/appkit/client";
+import { AdminComposableRegion } from "../../../../../features/dashboard/components/AdminComposableRegion.js";
 function fmt(t) {
     return new Date(t).toISOString().replace("T", " ").slice(0, 19);
 }
-export function ServerErrorDetailView({ doc, related, backHref, }) {
-    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1200px", margin: "0 auto" }, children: [_jsx(Text, { as: "p", children: _jsx(Anchor, { href: backHref, external: false, children: "\u2190 Back to list" }) }), _jsxs(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: [doc.code, " ", _jsx(Text, { size: "xs", style: { fontSize: "1rem", color: "var(--appkit-color-text-muted)" }, children: doc.source })] }), _jsxs(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)" }, children: [fmt(doc.occurredAt), " \u2014 ", doc.method ?? "—", " ", doc.route] }), _jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Message" }), _jsx(Text, { as: "p", style: { fontFamily: "monospace", whiteSpace: "pre-wrap" }, children: doc.message })] }), _jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Metadata" }), _jsxs("dl", { style: { display: "grid", gridTemplateColumns: "auto 1fr", gap: "0.25rem 1rem", fontSize: "0.85rem" }, children: [_jsx("dt", { children: "request ID" }), _jsx("dd", { style: { fontFamily: "monospace" }, children: doc.requestId }), doc.userId ? (_jsxs(_Fragment, { children: [_jsx("dt", { children: "user ID" }), _jsx("dd", { style: { fontFamily: "monospace" }, children: doc.userId })] })) : null, doc.userAgent ? (_jsxs(_Fragment, { children: [_jsx("dt", { children: "user agent" }), _jsx("dd", { children: doc.userAgent })] })) : null, doc.bodyDigest ? (_jsxs(_Fragment, { children: [_jsx("dt", { children: "body digest" }), _jsx("dd", { style: { fontFamily: "monospace" }, children: doc.bodyDigest })] })) : null] })] }), doc.stack ? (_jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Stack" }), _jsx(Pre, { style: { fontFamily: "monospace", fontSize: "0.78rem", background: "var(--appkit-color-text)", color: "var(--appkit-color-border)", padding: "0.75rem", borderRadius: 4, overflowX: "auto" }, children: doc.stack })] })) : null, doc.componentStack ? (_jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Component stack" }), _jsx(Pre, { style: { fontFamily: "monospace", fontSize: "0.78rem", background: "var(--appkit-color-text)", color: "var(--appkit-color-border)", padding: "0.75rem", borderRadius: 4, overflowX: "auto" }, children: doc.componentStack })] })) : null, related.length > 0 ? (_jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Related client errors (same requestId)" }), _jsx(Ul, { children: related.map((r) => (_jsxs(Li, { style: { fontFamily: "monospace", fontSize: "0.82rem" }, children: [fmt(r.occurredAt), " \u2014 ", r.code, " \u2014 ", r.message.slice(0, 100)] }, r.id))) })] })) : null] }));
+export function ServerErrorDetailView({ doc, related, backHref, pageRegionCards = [], }) {
+    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1200px", margin: "0 auto" }, children: [_jsx(Text, { as: "p", children: _jsx(Anchor, { href: backHref, external: false, children: "\u2190 Back to list" }) }), _jsxs(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: [doc.code, " ", _jsx(Text, { size: "xs", style: { fontSize: "1rem", color: "var(--appkit-color-text-muted)" }, children: doc.source })] }), _jsxs(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)" }, children: [fmt(doc.occurredAt), " \u2014 ", doc.method ?? "—", " ", doc.route] }), _jsx(AdminComposableRegion, { pageId: "admin-maintenance-server-errors-id", initialCards: pageRegionCards }), _jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Message" }), _jsx(Text, { as: "p", style: { fontFamily: "monospace", whiteSpace: "pre-wrap" }, children: doc.message })] }), _jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Metadata" }), _jsxs("dl", { style: { display: "grid", gridTemplateColumns: "auto 1fr", gap: "0.25rem 1rem", fontSize: "0.85rem" }, children: [_jsx("dt", { children: "request ID" }), _jsx("dd", { style: { fontFamily: "monospace" }, children: doc.requestId }), doc.userId ? (_jsxs(_Fragment, { children: [_jsx("dt", { children: "user ID" }), _jsx("dd", { style: { fontFamily: "monospace" }, children: doc.userId })] })) : null, doc.userAgent ? (_jsxs(_Fragment, { children: [_jsx("dt", { children: "user agent" }), _jsx("dd", { children: doc.userAgent })] })) : null, doc.bodyDigest ? (_jsxs(_Fragment, { children: [_jsx("dt", { children: "body digest" }), _jsx("dd", { style: { fontFamily: "monospace" }, children: doc.bodyDigest })] })) : null] })] }), doc.stack ? (_jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Stack" }), _jsx(Pre, { style: { fontFamily: "monospace", fontSize: "0.78rem", background: "var(--appkit-color-text)", color: "var(--appkit-color-border)", padding: "0.75rem", borderRadius: 4, overflowX: "auto" }, children: doc.stack })] })) : null, doc.componentStack ? (_jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Component stack" }), _jsx(Pre, { style: { fontFamily: "monospace", fontSize: "0.78rem", background: "var(--appkit-color-text)", color: "var(--appkit-color-border)", padding: "0.75rem", borderRadius: 4, overflowX: "auto" }, children: doc.componentStack })] })) : null, related.length > 0 ? (_jsxs(Section, { style: { marginTop: "1.25rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600, marginBottom: "0.5rem" }, children: "Related client errors (same requestId)" }), _jsx(Ul, { children: related.map((r) => (_jsxs(Li, { style: { fontFamily: "monospace", fontSize: "0.82rem" }, children: [fmt(r.occurredAt), " \u2014 ", r.code, " \u2014 ", r.message.slice(0, 100)] }, r.id))) })] })) : null] }));
 }

package/dist/_internal/client/features/maintenance/views/ServerErrorsListView.d.ts

@@ -1,10 +1,20 @@
 import * as React from "react";
 import type { ServerErrorDocument, ServerErrorSource } from "../../../../../features/server-errors/schemas/firestore";
+import type { DashboardCard } from "../../../../shared/features/dashboard/recent-entry";
 export interface ServerErrorsListViewProps {
     title: string;
     subtitle?: string;
     source: ServerErrorSource | "all";
     rows: ServerErrorDocument[];
     detailHrefBase: string;
+    /**
+     * Stable, hand-chosen page-region id (Phase 12) — this one view is shared
+     * by four distinct `/admin/maintenance/*-errors` (+ payment-rollbacks)
+     * routes, so every caller computes its own route-template-derived id
+     * rather than this component guessing one.
+     */
+    pageId: string;
+    /** Admin-curated page-region cards (Phase 12). Omit for no extra content. */
+    pageRegionCards?: DashboardCard[];
 }
-export declare function ServerErrorsListView({ title, subtitle, source, rows, detailHrefBase, }: ServerErrorsListViewProps): React.JSX.Element;
+export declare function ServerErrorsListView({ title, subtitle, source, rows, detailHrefBase, pageId, pageRegionCards, }: ServerErrorsListViewProps): React.JSX.Element;

package/dist/_internal/client/features/maintenance/views/ServerErrorsListView.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Anchor, Div, Heading, Input, Label, Span, Table, Tbody, Td, Text, Th, Thead, Tr } from "@mohasinac/appkit/client";
+import { AdminComposableRegion } from "../../../../../features/dashboard/components/AdminComposableRegion.js";
 const BORDER_STYLE = "1px solid var(--appkit-color-border)";
 const COLUMNS = [
     { key: "occurredAtFmt", label: "When", width: "180px" },
@@ -18,14 +19,14 @@ function fmt(occurredAt) {
 function preview(message, max = 100) {
     return message.length > max ? message.slice(0, max) + "…" : message;
 }
-export function ServerErrorsListView({ title, subtitle, source, rows, detailHrefBase, }) {
+export function ServerErrorsListView({ title, subtitle, source, rows, detailHrefBase, pageId, pageRegionCards = [], }) {
     const [codeFilter, setCodeFilter] = React.useState("");
     const [routeFilter, setRouteFilter] = React.useState("");
     const filtered = React.useMemo(() => {
         return rows.filter((r) => (!codeFilter || r.code.toLowerCase().includes(codeFilter.toLowerCase())) &&
             (!routeFilter || r.route.toLowerCase().includes(routeFilter.toLowerCase())));
     }, [rows, codeFilter, routeFilter]);
-    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1400px", margin: "0 auto" }, children: [_jsx(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: title }), subtitle ? (_jsx(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)", marginBottom: "1rem" }, children: subtitle })) : null, _jsxs(Div, { style: { display: "flex", gap: "0.75rem", marginBottom: "1rem", alignItems: "center" }, children: [_jsxs(Label, { style: { fontSize: "0.85rem" }, children: ["Code", _jsx(Input, { bare: true, type: "search", value: codeFilter, onChange: (e) => setCodeFilter(e.target.value), placeholder: "e.g. NOT_FOUND", style: { marginLeft: "0.5rem", padding: "0.35rem 0.5rem", border: BORDER_STYLE, borderRadius: 4 } })] }), _jsxs(Label, { style: { fontSize: "0.85rem" }, children: ["Route", _jsx(Input, { bare: true, type: "search", value: routeFilter, onChange: (e) => setRouteFilter(e.target.value), placeholder: "e.g. /api/orders", style: { marginLeft: "0.5rem", padding: "0.35rem 0.5rem", border: BORDER_STYLE, borderRadius: 4 } })] }), _jsxs(Span, { style: { marginLeft: "auto", fontSize: "0.85rem", color: "var(--appkit-color-text-muted)" }, children: [filtered.length, " of ", rows.length, " (source=", source, ")"] })] }), _jsx(Div, { style: { overflowX: "auto", border: BORDER_STYLE, borderRadius: 6 }, children: _jsxs(Table, { style: { width: "100%", borderCollapse: "collapse", fontSize: "0.85rem" }, children: [_jsx(Thead, { style: { background: "var(--appkit-color-bg)" }, children: _jsx(Tr, { children: COLUMNS.map((c) => (_jsx(Th, { style: {
+    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1400px", margin: "0 auto" }, children: [_jsx(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: title }), subtitle ? (_jsx(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)", marginBottom: "1rem" }, children: subtitle })) : null, _jsx(AdminComposableRegion, { pageId: pageId, initialCards: pageRegionCards }), _jsxs(Div, { style: { display: "flex", gap: "0.75rem", marginBottom: "1rem", alignItems: "center" }, children: [_jsxs(Label, { style: { fontSize: "0.85rem" }, children: ["Code", _jsx(Input, { bare: true, type: "search", value: codeFilter, onChange: (e) => setCodeFilter(e.target.value), placeholder: "e.g. NOT_FOUND", style: { marginLeft: "0.5rem", padding: "0.35rem 0.5rem", border: BORDER_STYLE, borderRadius: 4 } })] }), _jsxs(Label, { style: { fontSize: "0.85rem" }, children: ["Route", _jsx(Input, { bare: true, type: "search", value: routeFilter, onChange: (e) => setRouteFilter(e.target.value), placeholder: "e.g. /api/orders", style: { marginLeft: "0.5rem", padding: "0.35rem 0.5rem", border: BORDER_STYLE, borderRadius: 4 } })] }), _jsxs(Span, { style: { marginLeft: "auto", fontSize: "0.85rem", color: "var(--appkit-color-text-muted)" }, children: [filtered.length, " of ", rows.length, " (source=", source, ")"] })] }), _jsx(Div, { style: { overflowX: "auto", border: BORDER_STYLE, borderRadius: 6 }, children: _jsxs(Table, { style: { width: "100%", borderCollapse: "collapse", fontSize: "0.85rem" }, children: [_jsx(Thead, { style: { background: "var(--appkit-color-bg)" }, children: _jsx(Tr, { children: COLUMNS.map((c) => (_jsx(Th, { style: {
                                         textAlign: "left",
                                         padding: "0.5rem 0.75rem",
                                         borderBottom: BORDER_STYLE,

package/dist/_internal/server/features/ads/booking.d.ts

@@ -39,7 +39,7 @@ export interface BookAdSlotInput {
  * Take a slot. Returns the booking id.
  *
  * Throws **409** when the slot is taken (a well-formed request against a
- * world that moved — the same distinction the lottery config write makes for
+ * world that moved — the same distinction the giveaway config write makes for
  * a pulled slot) and **400** for a past period or an unknown placement.
  */
 export declare function bookAdSlot(input: BookAdSlotInput): Promise<string>;

package/dist/_internal/server/features/ads/booking.js

@@ -45,7 +45,7 @@ import { AD_BOOKING_COLLECTION, adBookingId, adPeriodOf, adPeriodStart, isAdBook
  * Take a slot. Returns the booking id.
  *
  * Throws **409** when the slot is taken (a well-formed request against a
- * world that moved — the same distinction the lottery config write makes for
+ * world that moved — the same distinction the giveaway config write makes for
  * a pulled slot) and **400** for a past period or an unknown placement.
  */
 export async function bookAdSlot(input) {

package/dist/_internal/server/features/assistant/actions.d.ts

@@ -0,0 +1,29 @@
+import type { AnyAssistantToolDef } from "./tools/define";
+export interface AssistantUser {
+    id: string;
+    email: string;
+    displayName: string;
+}
+export interface AssistantAnswer {
+    text: string;
+}
+/** The buyer-facing entry point — unchanged behaviour (`roles: ["buyer"]`, builtin tools only). */
+export declare function answerAssistantQuestion(user: AssistantUser, question: string): Promise<AssistantAnswer>;
+/**
+ * The admin/seller-facing entry point — 2E-ii (overhaul brief). A SEPARATE
+ * exported function rather than a `roles` parameter bolted onto
+ * `answerAssistantQuestion`, because the two have different RBAC postures:
+ * the buyer one is reachable by anyone signed in; this one is for a
+ * session that has already passed an admin/seller gate at the ROUTE level
+ * (mirroring every other admin-only surface in this codebase) — the
+ * caller's own `roles` is trusted input here, not re-derived.
+ *
+ * `extraTools` is where `createSearchNavTool(...)` (or any other
+ * consumer-supplied tool) joins the builtin set — appkit cannot import the
+ * consumer's own nav tree, so the caller flattens it and passes the
+ * resulting tool in.
+ */
+export declare function answerAdminAssistantQuestion(user: AssistantUser, question: string, opts: {
+    roles: readonly string[];
+    extraTools?: readonly AnyAssistantToolDef[];
+}): Promise<AssistantAnswer>;

package/dist/_internal/server/features/assistant/actions.js

@@ -0,0 +1,170 @@
+import { logServerWarning } from "../../../../monitoring/index.js";
+import { AuthorizationError } from "../../../../errors/index.js";
+import { GroqModelProvider } from "../../../../providers/ai-groq/index.js";
+import { getProviders } from "../../../../contracts/registry.js";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { runAssistantTurn } from "./turn.js";
+import { escalateToHuman } from "./escalate.js";
+import { classifyEscalation } from "./severity.js";
+import { BUILTIN_ASSISTANT_TOOLS } from "./tools/builtin/index.js";
+import { mergeAssistantToolRegistries } from "./tools/registry.js";
+import { appendAssistantTurn, getAssistantHistory } from "./history-store.js";
+/**
+ * `answerAssistantQuestion()` — the ONE public entry point this feature
+ * exports from `server.ts`. Everything above it (routing, redaction,
+ * handles, budget, quorum, escalation, the tool registry) is wiring this
+ * function assembles; nothing else needs to be imported by a consumer.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:writes-firestore
+ */
+function getAssistantProviders() {
+    // A registered `aiProviders` list wins outright — this is the seam a
+    // second vendor wires through, same as `payment`/`shipping` already do.
+    const registered = getProviders().aiProviders;
+    if (registered && registered.length > 0)
+        return registered;
+    // Env read happens inside the provider's own `turn()` call, never cached
+    // at module load — see providers/ai-groq's docstring.
+    return [new GroqModelProvider()];
+}
+/**
+ * 🛑 `!== false` — the opposite polarity to `assertChatEnabled` in
+ * `_internal/server/features/messages/actions.ts`. This is a kill switch on
+ * an already-shipped path, not an opt-in for a new one: an unseeded
+ * document, a never-written field, or a failed read must all mean ON, or a
+ * settings outage silently takes the assistant down with no admin action.
+ * Checked server-side so a stale client (the widget already rendered before
+ * an admin flips the switch) cannot route around it.
+ */
+async function assertAssistantEnabled() {
+    const settings = await siteSettingsRepository.getSingleton();
+    if (settings?.assistant?.enabled === false) {
+        throw new AuthorizationError("The assistant is not currently available.");
+    }
+}
+/**
+ * Shared by both public entry points below — the refusal/escalation
+ * handling is IDENTICAL regardless of who is asking or which tools they
+ * have; only `roles` and `tools` differ. Extracted 2026-11-02 (Phase 2E-ii)
+ * when `answerAdminAssistantQuestion` was added, rather than hand-copying
+ * ~45 lines of escalation logic a second time (Duplication Decision
+ * Framework's bug-fix-multiplier criterion — a fix to the refusal path
+ * would otherwise need two commits).
+ */
+async function runAnswerTurn(user, question, opts) {
+    await assertAssistantEnabled();
+    const history = await getAssistantHistory(user.id);
+    const outcome = await runAssistantTurn({
+        /*
+         * There is no real "conversation" any more — the shared inbox was
+         * dropped. `userId` doubles as the handle registry's scoping key,
+         * which only needs to be stable for the lifetime of this one call.
+         */
+        conversationId: user.id,
+        userId: user.id,
+        roles: opts.roles,
+        /*
+         * 🛑 "redacted", not "none" — free text can carry a phone number, an
+         * email or an address at any time, and nothing stops the caller. See
+         * redaction.ts's `assertAlreadyPublic` docstring for why "none" is
+         * reserved for text whose SOURCE is already a public projection.
+         */
+        piiClass: "redacted",
+        messages: [
+            ...history.map((m) => ({ role: m.role, content: m.content })),
+            { role: "user", content: question },
+        ],
+    }, {
+        providers: getAssistantProviders(),
+        tools: opts.tools,
+        /*
+         * Owner's instruction 2026-10-31 ("its fine with groq"). Groq is the
+         * only registered vendor, so without this a money/policy answer could
+         * never clear review and every such question would escalate. The
+         * reviewer still runs a different model lineage (Qwen vs gpt-oss);
+         * see quorum.ts for why that is weaker than cross-vendor.
+         */
+        allowSameVendorQuorum: true,
+    });
+    /*
+     * A refusal is never silence: the buyer gets "someone will get back to
+     * you" and a real `supportTickets` row is filed, so a question the
+     * assistant could not answer reaches a human instead of evaporating.
+     */
+    let replyText = outcome.ok ? outcome.text : "";
+    if (!outcome.ok) {
+        /*
+         * 🛑 The reason goes in the MESSAGE, not only the data bag — appkit's
+         * logger has previously been found to drop a metadata object entirely,
+         * so the one field needed to diagnose a refusal belongs in the string.
+         */
+        logServerWarning(`[assistant] turn refused: ${outcome.reason}`, {
+            userId: user.id,
+        });
+        /*
+         * Severity is decided from OUR refusal reason plus the buyer's topic —
+         * never by asking the model (see severity.ts: a model already failing to
+         * answer is not a reliable judge of how badly it failed, and a
+         * severity prompt is an injection target).
+         */
+        const decision = classifyEscalation(outcome.reason, question);
+        /*
+         * 🛑 `escalates: false` means file NOTHING — today that is only a
+         * flagged prompt injection. Ticketing hostile input would spam the
+         * human queue and hand an attacker a one-message-per-ticket flood.
+         */
+        if (!decision.escalates) {
+            replyText = decision.buyerMessage;
+        }
+        else {
+            const escalated = await escalateToHuman({
+                userId: user.id,
+                userEmail: user.email,
+                userDisplayName: user.displayName,
+                conversationId: user.id,
+                question,
+                reason: outcome.reason,
+                severity: decision.severity,
+                priority: decision.priority,
+            });
+            /*
+             * The promise is only made when the ticket actually exists. Saying
+             * "someone will get back to you" after the write failed is a lie the
+             * buyer cannot detect — the exact silent-degrade shape
+             * `audit-silent-degrade` R1 exists for.
+             */
+            replyText = escalated
+                ? decision.buyerMessage
+                : "I'm having trouble answering right now — please try again in a moment.";
+        }
+    }
+    await appendAssistantTurn(user.id, question, replyText);
+    return { text: replyText };
+}
+/** The buyer-facing entry point — unchanged behaviour (`roles: ["buyer"]`, builtin tools only). */
+export async function answerAssistantQuestion(user, question) {
+    return runAnswerTurn(user, question, { roles: ["buyer"], tools: BUILTIN_ASSISTANT_TOOLS });
+}
+/**
+ * The admin/seller-facing entry point — 2E-ii (overhaul brief). A SEPARATE
+ * exported function rather than a `roles` parameter bolted onto
+ * `answerAssistantQuestion`, because the two have different RBAC postures:
+ * the buyer one is reachable by anyone signed in; this one is for a
+ * session that has already passed an admin/seller gate at the ROUTE level
+ * (mirroring every other admin-only surface in this codebase) — the
+ * caller's own `roles` is trusted input here, not re-derived.
+ *
+ * `extraTools` is where `createSearchNavTool(...)` (or any other
+ * consumer-supplied tool) joins the builtin set — appkit cannot import the
+ * consumer's own nav tree, so the caller flattens it and passes the
+ * resulting tool in.
+ */
+export async function answerAdminAssistantQuestion(user, question, opts) {
+    return runAnswerTurn(user, question, {
+        roles: opts.roles,
+        tools: mergeAssistantToolRegistries(BUILTIN_ASSISTANT_TOOLS, opts.extraTools ?? []),
+    });
+}

package/dist/_internal/server/features/assistant/budget.d.ts

@@ -0,0 +1,28 @@
+export interface BudgetDecision {
+    allowed: boolean;
+    /** Operator-facing. Never rendered to a buyer. */
+    reason?: string;
+}
+/**
+ * Reserve `tokens` against today's allowance.
+ *
+ * 🛑 Reserved BEFORE the model call, like `message-budget`, and for the same
+ * reason: a call that is made and then fails has still been paid for. There
+ * is deliberately no `release()` — a compensating decrement is what lets a
+ * partially-failed turn double-refund itself back over the ceiling.
+ *
+ * 🛑 Estimate-then-reserve, not measure-then-charge. The real token count is
+ * only known AFTER the response, which is too late to refuse it. The caller
+ * passes a conservative estimate; over-reserving costs a little headroom,
+ * under-reserving costs money.
+ */
+export declare function reserveTokens(tokens: number): Promise<BudgetDecision>;
+/**
+ * Conservative pre-call estimate, in tokens.
+ *
+ * ~4 chars/token is the usual English approximation; this rounds UP and adds
+ * the tool manifest and a full `maxOutputTokens` of headroom, because the
+ * cost of over-estimating is a little unused allowance and the cost of
+ * under-estimating is an unbounded bill.
+ */
+export declare function estimateTurnTokens(promptChars: number, maxOutputTokens: number, toolCount: number): number;

package/dist/_internal/server/features/assistant/budget.js

@@ -0,0 +1,132 @@
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { logServerWarning } from "../../../../monitoring/index.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+/**
+ * A4's token budget — clones `messageBudget`'s shape and REVERSES all three
+ * of its trades, each for a stated reason.
+ *
+ * | `messageBudget`        | here                      | why |
+ * |------------------------|---------------------------|-----|
+ * | single doc, ~1 write/s | **sharded**               | a turn is N tool rounds and users are concurrent |
+ * | fails **open**         | **fails CLOSED**          | failing open on a metered API is a spend vulnerability |
+ * | counts calls           | counts **tokens**         | a 100k-token context is not one unit |
+ *
+ * 🛑 The fail-open half is not hypothetical: `reserveSend` returns
+ * `{allowed: true}` when its transaction THROWS, and an unreadable
+ * `siteSettings` falls back to defaults and continues. That is right for
+ * email — refusing to send an order confirmation because a counter was
+ * unreadable is worse than sending one over quota — and exactly wrong for a
+ * metered LLM, where the failure mode is an unbounded bill.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:writes-firestore
+ */
+const COLLECTION = "assistantBudget";
+/**
+ * 🛑 Same `Asia/Kolkata` reasoning as `BUDGET_TIMEZONE`, and it is
+ * load-bearing for the same reason: the `{shard}_{YYYY-MM-DD}` doc id must
+ * mean the same calendar day on a Vercel lambda (UTC) and a regional
+ * Function. A floating local date gives two partial budgets at midnight and
+ * doubles the day's ceiling.
+ */
+const BUDGET_TIMEZONE = "Asia/Kolkata";
+/**
+ * Shard count. A turn spends several rounds, and users are concurrent, so a
+ * single document would serialise every turn on one ~1 write/s hot key —
+ * `message-budget`'s own docstring says to shard before any concurrent
+ * fan-out. 10 keeps per-shard contention low while leaving the ceiling
+ * exactly divisible, so no shard silently gets a larger slice.
+ */
+const SHARDS = 10;
+/** Daily token ceiling across all shards. Override with ASSISTANT_TOKEN_BUDGET. */
+const DEFAULT_DAILY_TOKENS = 200000;
+/** `en-CA` formats as YYYY-MM-DD natively. */
+function budgetDate(now) {
+    return new Intl.DateTimeFormat("en-CA", {
+        timeZone: BUDGET_TIMEZONE,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).format(now);
+}
+function dailyCeiling() {
+    const raw = Number(process.env.ASSISTANT_TOKEN_BUDGET);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_DAILY_TOKENS;
+}
+/**
+ * Reserve `tokens` against today's allowance.
+ *
+ * 🛑 Reserved BEFORE the model call, like `message-budget`, and for the same
+ * reason: a call that is made and then fails has still been paid for. There
+ * is deliberately no `release()` — a compensating decrement is what lets a
+ * partially-failed turn double-refund itself back over the ceiling.
+ *
+ * 🛑 Estimate-then-reserve, not measure-then-charge. The real token count is
+ * only known AFTER the response, which is too late to refuse it. The caller
+ * passes a conservative estimate; over-reserving costs a little headroom,
+ * under-reserving costs money.
+ */
+export async function reserveTokens(tokens) {
+    /*
+     * 🛑 The env kill switch is checked FIRST, before any I/O — "fails closed,
+     * env kill switch first". An operator who needs to stop the spend must not
+     * have that depend on Firestore being reachable.
+     */
+    if (process.env.ASSISTANT_DISABLED === "1") {
+        return { allowed: false, reason: "ASSISTANT_DISABLED=1" };
+    }
+    const ceiling = dailyCeiling();
+    const perShard = Math.floor(ceiling / SHARDS);
+    const now = new Date();
+    const date = budgetDate(now);
+    // Random shard: spreads contention without needing per-user affinity.
+    const shard = Math.floor(Math.random() * SHARDS);
+    try {
+        const db = getAdminDb();
+        const ref = db.collection(COLLECTION).doc(`${shard}_${date}`);
+        return await db.runTransaction(async (tx) => {
+            const snap = await tx.get(ref);
+            const used = snap.exists ? (snap.data()?.tokens ?? 0) : 0;
+            if (used + tokens > perShard) {
+                return {
+                    allowed: false,
+                    reason: `shard ${shard} would exceed its slice (${used}+${tokens} > ${perShard})`,
+                };
+            }
+            tx.set(ref, { shard, date, tokens: used + tokens, updatedAt: now }, { merge: true });
+            return { allowed: true };
+        });
+    }
+    catch (err) {
+        /*
+         * 🛑 FAIL CLOSED — the single most important line in this file, and the
+         * exact inversion of `reserveSend`, which returns `{allowed: true}` from
+         * its own catch.
+         *
+         * If the counter cannot be read or written we do not know what has been
+         * spent, and "unknown spend" on a metered API must resolve to "stop", not
+         * "continue". The caller degrades visibly: the buyer gets a refusal and
+         * an escalation, which is a worse answer and a bounded bill.
+         */
+        logServerWarning("[assistant] budget unavailable — refusing (fail-closed)", {
+            error: normalizeError(err).message,
+        });
+        return { allowed: false, reason: "budget counter unavailable" };
+    }
+}
+/**
+ * Conservative pre-call estimate, in tokens.
+ *
+ * ~4 chars/token is the usual English approximation; this rounds UP and adds
+ * the tool manifest and a full `maxOutputTokens` of headroom, because the
+ * cost of over-estimating is a little unused allowance and the cost of
+ * under-estimating is an unbounded bill.
+ */
+export function estimateTurnTokens(promptChars, maxOutputTokens, toolCount) {
+    const promptTokens = Math.ceil(promptChars / 4);
+    // Each tool's JSON Schema plus description costs roughly this much context.
+    const manifestTokens = toolCount * 120;
+    return promptTokens + manifestTokens + maxOutputTokens;
+}