@pixygon/chatbot-react 0.1.2 → 0.1.4

package/README.md

@@ -1,95 +1,181 @@
 # @pixygon/chatbot-react
 
-React + MUI + RTK Query components for the Pixygon chatbot.
+Ready-to-mount **React 18/19 + MUI 6/7 + RTK Query** pages for the Pixygon
+chatbot stack. Pair with [`@pixygon/chatbot-server`](https://www.npmjs.com/package/@pixygon/chatbot-server)
+on the API side.
+
+```
++----------------------+      +----------------------+
+|   Host React app     |----->| createChatbotComponents()
+|  (your baseApi here) |      +----------------------+
++----------------------+               |
+                                       v
+       KnowledgePage · ChatPage · ChatAnalyticsPage · EmbedChatPage · ChatbotSettings
+                                       |
+                                       v
+                               HTTP -> chatbot-server
+```
+
+You configure once at boot, then mount the components in your router or
+settings tree. Hooks close over the active tenant id, branding, and your
+existing RTK Query base.
+
+---
 
 ## Install
 
 ```bash
 npm install @pixygon/chatbot-react
-# Peer deps the host already has:
-# - react ≥18
-# - @mui/material, @mui/icons-material, @emotion/react, @emotion/styled ≥11
-# - @reduxjs/toolkit ≥2, react-redux ≥9
 ```
 
-## Usage
+Peer dependencies the host already has:
+
+| Peer | Range |
+|---|---|
+| `react` / `react-dom` | ^18 or ^19 |
+| `@mui/material` / `@mui/icons-material` | ^6 or ^7 |
+| `@emotion/react` / `@emotion/styled` | ^11 |
+| `@reduxjs/toolkit` | ^2 |
+| `react-redux` | ^9 |
+
+The host's `baseApi` should include these RTK Query tag types so cache
+invalidation works:
 
 ```ts
+tagTypes: [..., "Knowledge", "ChatConversation"]
+```
+
+---
+
+## Configure once
+
+```tsx
+// src/chatbot.tsx
 import { createChatbotComponents } from "@pixygon/chatbot-react";
+import { useParams } from "react-router";
 import { baseApi } from "@/apis/baseApi";
 import { useAppSelector } from "@/store/store";
+import { useGetTenantQuery, useUpdateTenantMutation } from "@/apis/tenantApi";
 
-export const chatbot = createChatbotComponents({
+const chatbot = createChatbotComponents({
   apiSlice: baseApi,
-  pathPrefix: "/tenants",                              // or "/companies"
+  pathPrefix: "/tenants",                                   // or "/companies"
   useTenantId: () => useAppSelector((s) => s.global.activeTenantId),
-  apiBase: import.meta.env.VITE_API_URL,
+  apiBase: import.meta.env.VITE_API_URL,                    // public surface origin
   brand: {
     name: "TotalHMS",
     tagline: "Powered by TotalHMS",
     primaryColor: "#8FB7C9",
   },
 });
-```
 
-Then drop into your router:
+export const KnowledgePage = chatbot.KnowledgePage;
+export const ChatPage = chatbot.ChatPage;
+export const ChatAnalyticsPage = chatbot.ChatAnalyticsPage;
 
-```tsx
-<Route path="/knowledge" element={<chatbot.KnowledgePage />} />
-<Route path="/chat" element={<chatbot.ChatPage />} />
-<Route path="/chat-analytics" element={<chatbot.ChatAnalyticsPage />} />
-<Route path="/embed/chat/:tenantSlug" element={<EmbedRoute />} />
+// Small wrapper so the route can hand the slug from useParams down to the page.
+export function EmbedChatPageRoute() {
+  const { tenantSlug } = useParams();
+  return <chatbot.EmbedChatPage tenantSlug={tenantSlug} />;
+}
+
+// Settings card — host supplies tenant + save handler (Tenant model lives here).
+export function ChatbotSettings({ tenantId }: { tenantId: string }) {
+  const { data: tenant } = useGetTenantQuery(tenantId);
+  const [updateTenant] = useUpdateTenantMutation();
+  return (
+    <chatbot.ChatbotSettings
+      tenant={tenant ?? null}
+      onSave={(patch) =>
+        updateTenant({ tenantId, patch }).unwrap().then(() => undefined)
+      }
+    />
+  );
+}
 ```
 
-`EmbedChatPage` reads `tenantSlug` from props, so the host wires it through:
+## Drop into routes
 
 ```tsx
-function EmbedRoute() {
-  const { tenantSlug } = useParams();
-  return <chatbot.EmbedChatPage tenantSlug={tenantSlug} />;
-}
+import { KnowledgePage, ChatPage, ChatAnalyticsPage, EmbedChatPageRoute } from "@/chatbot";
+
+<Route path="/embed/chat/:tenantSlug" element={<EmbedChatPageRoute />} />
+
+<Route element={<DashboardLayout />}>
+  <Route path="/knowledge"       element={<KnowledgePage />} />
+  <Route path="/chat"            element={<ChatPage />} />
+  <Route path="/chat-analytics"  element={<ChatAnalyticsPage />} />
+</Route>
 ```
 
-Settings card (drops into the host's settings page, host supplies the
-tenant + save handler since the Tenant model lives in the host):
+## Drop into a settings page
 
 ```tsx
-<chatbot.ChatbotSettings
-  tenant={activeTenant}
-  onSave={(patch) => updateTenant({ tenantId, patch }).unwrap()}
-/>
+<ChatbotSettings tenantId={activeTenantId} />
 ```
 
+---
+
 ## What you get
 
-- `KnowledgePage` — list + paste-text upload + delete
-- `ChatPage` — operator chat UI with sessionId-keyed threads
-- `ChatAnalyticsPage` — KPI tiles, knowledge gaps, top questions, keywords,
-  semantic clusters, cost timeseries, source usage, drill-down dialog
-- `EmbedChatPage` — iframe-friendly chat UI for the public anonymous surface
-- `ChatbotSettings` — cost cap input + copy-pasteable embed snippet
+| Component | Purpose |
+|---|---|
+| `KnowledgePage` | List, paste/upload, delete knowledge documents per tenant |
+| `ChatPage` | Operator chat UI with session-keyed threads and citations |
+| `ChatAnalyticsPage` | KPI tiles · knowledge gaps · top questions · keywords · semantic clusters · cost timeseries · source usage · question drill-down |
+| `EmbedChatPage` | Iframe-friendly anonymous chat for the public surface |
+| `ChatbotSettings` | Per-tenant monthly cost cap + copy-pasteable embed snippet |
+
+---
+
+## Embed widget
 
-The bootstrap snippet is served as a separate static file at
-`@pixygon/chatbot-react/chatbot.js`. Symlink or copy to your app's `public/`:
+`chatbot.js` is shipped as a static file inside the package. Drop it in your
+app's `public/` so it's served at `/chatbot.js`:
 
 ```bash
 cp node_modules/@pixygon/chatbot-react/public/chatbot.js public/chatbot.js
 ```
 
-## RTK Query tag types
+Then anyone can embed your chatbot on any HTML page:
 
-The host's `baseApi` should include these tags so invalidation works:
-
-```ts
-tagTypes: [..., "Knowledge", "ChatConversation"]
+```html
+<script src="https://app.example.com/chatbot.js"
+        data-tenant-slug="acme"
+        defer></script>
 ```
 
+The widget renders a floating launcher, opens an iframe pointed at
+`/embed/chat/<slug>` on your dashboard, and `postMessage`s a
+`pixygon-chatbot:close` event when the user closes it. The `ChatbotSettings`
+card auto-generates the snippet with the right URL.
+
+---
+
 ## Hooks-only API
 
-If you only want the RTK Query hooks without the pages, use `injectChatbotEndpoints`:
+Skip the pages if you want to build your own UI:
 
 ```ts
 import { injectChatbotEndpoints } from "@pixygon/chatbot-react";
-const { useListDocumentsQuery, useSendMessageMutation, ... } =
-  injectChatbotEndpoints(baseApi, { pathPrefix: "/tenants" });
+
+const {
+  useListDocumentsQuery,
+  useCreateDocumentMutation,
+  useDeleteDocumentMutation,
+  useSendMessageMutation,
+  useGetConversationQuery,
+  useRateMessageMutation,
+  useChatOverviewQuery,
+  useKnowledgeGapsQuery,
+  useSemanticClustersQuery,
+  // ...
+} = injectChatbotEndpoints(baseApi, { pathPrefix: "/tenants" });
 ```
+
+---
+
+## Companion package
+
+`@pixygon/chatbot-server` is the Express + Mongoose backend these components
+expect. See its README for the API wire-up.

package/dist/index.d.ts

@@ -213,6 +213,7 @@ declare function createChatbotComponents(cfg: ChatbotComponentConfig): {
         }) => Promise<void>;
         embedScriptUrl?: string;
     }) => react.JSX.Element | null;
+    ChatLauncher: () => react.JSX.Element;
     KnowledgePageBase: (props: {
         tenantId?: string | null;
     }) => react.JSX.Element;

package/dist/index.js

@@ -1044,8 +1044,248 @@ function createChatbotSettings(cfg) {
   };
 }
 
+// src/pages/ChatLauncher.tsx
+import { useEffect as useEffect4, useRef as useRef3, useState as useState6 } from "react";
+import {
+  Box as Box6,
+  Typography as Typography6,
+  IconButton as IconButton5,
+  Fab,
+  TextField as TextField5,
+  Stack as Stack6,
+  Tooltip as Tooltip5,
+  Chip as Chip6,
+  Slide,
+  Paper,
+  Divider as Divider3,
+  Alert as Alert5
+} from "@mui/material";
+import {
+  ChatBubble,
+  Close as Close3,
+  Send as Send3,
+  RestartAlt as RestartAlt2,
+  ThumbUp as ThumbUp4,
+  ThumbDown as ThumbDown4
+} from "@mui/icons-material";
+import { Fragment as Fragment2, jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
+function createChatLauncher(cfg, hooks) {
+  return function ChatLauncher() {
+    const tenantId = cfg.useTenantId();
+    const [open, setOpen] = useState6(false);
+    const [sessionId, setSessionId] = useState6(null);
+    const [draft, setDraft] = useState6("");
+    const [optimistic, setOptimistic] = useState6([]);
+    const [error, setError] = useState6(null);
+    const scrollRef = useRef3(null);
+    const [sendMessage, { isLoading: sending }] = hooks.useSendMessageMutation();
+    const [rateMessage] = hooks.useRateMessageMutation();
+    const { data: conversation } = hooks.useGetConversationQuery(
+      { tenantId, sessionId },
+      { skip: !tenantId || !sessionId || !open }
+    );
+    const display = [
+      ...conversation?.messages || [],
+      ...optimistic.filter((o) => !(conversation?.messages || []).some(
+        (m) => m.content === o.content && m.role === o.role
+      ))
+    ];
+    useEffect4(() => {
+      if (!open) return;
+      scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight, behavior: "smooth" });
+    }, [display.length, open]);
+    const handleSend = async () => {
+      if (!draft.trim() || sending || !tenantId) return;
+      setError(null);
+      const localUser = { _localId: `local-${Date.now()}`, role: "user", content: draft.trim() };
+      const localPending = { _localId: `pending-${Date.now()}`, role: "assistant", content: "Thinking\u2026", pending: true };
+      setOptimistic((prev) => [...prev, localUser, localPending]);
+      setDraft("");
+      try {
+        const res = await sendMessage({
+          tenantId,
+          sessionId: sessionId || void 0,
+          message: localUser.content
+        }).unwrap();
+        if (!sessionId) setSessionId(res.sessionId);
+        setOptimistic((prev) => prev.filter((p) => p._localId !== localPending._localId));
+      } catch (e) {
+        setError(e?.data?.error || "Send failed");
+        setOptimistic((prev) => prev.filter((p) => !p.pending));
+      }
+    };
+    const handleRate = async (messageId, rating) => {
+      if (!conversation || !tenantId) return;
+      await rateMessage({ tenantId, conversationId: conversation._id, messageId, rating });
+    };
+    const handleNewChat = () => {
+      setSessionId(null);
+      setOptimistic([]);
+      setError(null);
+    };
+    const primary = cfg.brand.primaryColor;
+    return /* @__PURE__ */ jsxs6(Fragment2, { children: [
+      /* @__PURE__ */ jsx6(
+        Fab,
+        {
+          color: "primary",
+          "aria-label": open ? "Close assistant" : "Open assistant",
+          onClick: () => setOpen((o) => !o),
+          sx: {
+            position: "fixed",
+            right: 24,
+            bottom: 24,
+            zIndex: 1300,
+            bgcolor: primary,
+            "&:hover": { bgcolor: primary, filter: "brightness(0.92)" }
+          },
+          children: open ? /* @__PURE__ */ jsx6(Close3, {}) : /* @__PURE__ */ jsx6(ChatBubble, {})
+        }
+      ),
+      /* @__PURE__ */ jsx6(Slide, { direction: "up", in: open, mountOnEnter: true, unmountOnExit: true, children: /* @__PURE__ */ jsxs6(
+        Paper,
+        {
+          elevation: 8,
+          sx: {
+            position: "fixed",
+            right: 24,
+            bottom: 96,
+            zIndex: 1299,
+            width: { xs: "calc(100vw - 48px)", sm: 380 },
+            height: { xs: "calc(100vh - 144px)", sm: 580 },
+            maxHeight: "80vh",
+            display: "flex",
+            flexDirection: "column",
+            borderRadius: 2,
+            overflow: "hidden"
+          },
+          children: [
+            /* @__PURE__ */ jsxs6(Box6, { sx: {
+              p: 1.5,
+              bgcolor: primary,
+              color: "white",
+              display: "flex",
+              alignItems: "center",
+              gap: 1
+            }, children: [
+              /* @__PURE__ */ jsxs6(Box6, { sx: { flex: 1 }, children: [
+                /* @__PURE__ */ jsxs6(Typography6, { variant: "subtitle2", fontWeight: 700, children: [
+                  cfg.brand.name,
+                  " Assistant"
+                ] }),
+                cfg.brand.tagline && /* @__PURE__ */ jsx6(Typography6, { variant: "caption", sx: { opacity: 0.85, display: "block" }, children: cfg.brand.tagline })
+              ] }),
+              /* @__PURE__ */ jsx6(Tooltip5, { title: "New chat", children: /* @__PURE__ */ jsx6(IconButton5, { size: "small", onClick: handleNewChat, sx: { color: "white" }, children: /* @__PURE__ */ jsx6(RestartAlt2, { fontSize: "small" }) }) }),
+              /* @__PURE__ */ jsx6(Tooltip5, { title: "Close", children: /* @__PURE__ */ jsx6(IconButton5, { size: "small", onClick: () => setOpen(false), sx: { color: "white" }, children: /* @__PURE__ */ jsx6(Close3, { fontSize: "small" }) }) })
+            ] }),
+            /* @__PURE__ */ jsx6(
+              Box6,
+              {
+                ref: scrollRef,
+                sx: { flex: 1, overflowY: "auto", p: 1.5, bgcolor: "background.default" },
+                children: !tenantId ? /* @__PURE__ */ jsx6(Alert5, { severity: "info", children: "Select a tenant to start chatting." }) : display.length === 0 ? /* @__PURE__ */ jsxs6(Stack6, { alignItems: "center", sx: { py: 6 }, spacing: 1.5, children: [
+                  /* @__PURE__ */ jsx6(ChatBubble, { sx: { fontSize: 40, color: "text.secondary" } }),
+                  /* @__PURE__ */ jsx6(Typography6, { variant: "body2", color: "text.secondary", align: "center", children: "Ask anything \u2014 answers come from your knowledge base only." })
+                ] }) : /* @__PURE__ */ jsx6(Stack6, { spacing: 1.5, children: display.map((turn, i) => /* @__PURE__ */ jsx6(
+                  CompactTurn,
+                  {
+                    turn,
+                    onRate: turn._id ? (r) => handleRate(turn._id, r) : void 0
+                  },
+                  turn._id || turn._localId || String(i)
+                )) })
+              }
+            ),
+            /* @__PURE__ */ jsx6(Divider3, {}),
+            /* @__PURE__ */ jsxs6(Box6, { sx: { p: 1, bgcolor: "background.paper" }, children: [
+              error && /* @__PURE__ */ jsx6(Alert5, { severity: "error", sx: { mb: 1 }, children: error }),
+              /* @__PURE__ */ jsxs6(Stack6, { direction: "row", spacing: 0.5, alignItems: "flex-end", children: [
+                /* @__PURE__ */ jsx6(
+                  TextField5,
+                  {
+                    fullWidth: true,
+                    size: "small",
+                    multiline: true,
+                    maxRows: 4,
+                    placeholder: "Ask the assistant\u2026",
+                    value: draft,
+                    onChange: (e) => setDraft(e.target.value),
+                    onKeyDown: (e) => {
+                      if (e.key === "Enter" && !e.shiftKey) {
+                        e.preventDefault();
+                        handleSend();
+                      }
+                    },
+                    disabled: sending || !tenantId
+                  }
+                ),
+                /* @__PURE__ */ jsx6(
+                  IconButton5,
+                  {
+                    color: "primary",
+                    onClick: handleSend,
+                    disabled: !draft.trim() || sending || !tenantId,
+                    children: /* @__PURE__ */ jsx6(Send3, {})
+                  }
+                )
+              ] })
+            ] })
+          ]
+        }
+      ) })
+    ] });
+  };
+}
+function CompactTurn({ turn, onRate }) {
+  const isUser = turn.role === "user";
+  return /* @__PURE__ */ jsx6(Box6, { sx: { display: "flex", justifyContent: isUser ? "flex-end" : "flex-start" }, children: /* @__PURE__ */ jsxs6(Box6, { sx: { maxWidth: "85%" }, children: [
+    /* @__PURE__ */ jsx6(
+      Box6,
+      {
+        sx: {
+          bgcolor: isUser ? "primary.main" : "background.paper",
+          color: isUser ? "primary.contrastText" : "text.primary",
+          px: 1.5,
+          py: 1,
+          borderRadius: 1.5,
+          border: "1px solid",
+          borderColor: isUser ? "primary.main" : "divider",
+          whiteSpace: "pre-wrap",
+          wordBreak: "break-word",
+          opacity: turn.pending ? 0.6 : 1,
+          fontSize: 14
+        },
+        children: /* @__PURE__ */ jsx6(Typography6, { variant: "body2", children: turn.content })
+      }
+    ),
+    !isUser && turn.citations?.length > 0 && /* @__PURE__ */ jsx6(Stack6, { direction: "row", spacing: 0.5, sx: { mt: 0.5, flexWrap: "wrap", gap: 0.5 }, children: turn.citations.map((c, i) => /* @__PURE__ */ jsx6(Tooltip5, { title: c.snippet, children: /* @__PURE__ */ jsx6(Chip6, { label: `[${i + 1}]`, size: "small", variant: "outlined" }) }, c.chunkId || i)) }),
+    !isUser && onRate && /* @__PURE__ */ jsxs6(Stack6, { direction: "row", spacing: 0.5, sx: { mt: 0.25 }, children: [
+      /* @__PURE__ */ jsx6(
+        IconButton5,
+        {
+          size: "small",
+          onClick: () => onRate(1),
+          color: turn.rating === 1 ? "primary" : "default",
+          sx: { p: 0.25 },
+          children: /* @__PURE__ */ jsx6(ThumbUp4, { sx: { fontSize: 14 } })
+        }
+      ),
+      /* @__PURE__ */ jsx6(
+        IconButton5,
+        {
+          size: "small",
+          onClick: () => onRate(-1),
+          color: turn.rating === -1 ? "error" : "default",
+          sx: { p: 0.25 },
+          children: /* @__PURE__ */ jsx6(ThumbDown4, { sx: { fontSize: 14 } })
+        }
+      )
+    ] })
+  ] }) });
+}
+
 // src/index.tsx
-import { jsx as jsx6 } from "react/jsx-runtime";
+import { jsx as jsx7 } from "react/jsx-runtime";
 function createChatbotComponents(cfg) {
   const resolved = resolveConfig(cfg);
   const hooks = injectChatbotEndpoints(cfg.apiSlice, { pathPrefix: cfg.pathPrefix });
@@ -1054,17 +1294,18 @@ function createChatbotComponents(cfg) {
   const ChatAnalyticsPageBase = createChatAnalyticsPage(resolved, hooks);
   const EmbedChatPageBase = createEmbedChatPage(resolved);
   const ChatbotSettings = createChatbotSettings(resolved);
+  const ChatLauncher = createChatLauncher(resolved, hooks);
   const KnowledgePage = () => {
     const tenantId = cfg.useTenantId();
-    return /* @__PURE__ */ jsx6(KnowledgePageBase, { tenantId });
+    return /* @__PURE__ */ jsx7(KnowledgePageBase, { tenantId });
   };
   const ChatPage = () => {
     const tenantId = cfg.useTenantId();
-    return /* @__PURE__ */ jsx6(ChatPageBase, { tenantId });
+    return /* @__PURE__ */ jsx7(ChatPageBase, { tenantId });
   };
   const ChatAnalyticsPage = () => {
     const tenantId = cfg.useTenantId();
-    return /* @__PURE__ */ jsx6(ChatAnalyticsPageBase, { tenantId });
+    return /* @__PURE__ */ jsx7(ChatAnalyticsPageBase, { tenantId });
   };
   return {
     hooks,
@@ -1073,6 +1314,7 @@ function createChatbotComponents(cfg) {
     ChatAnalyticsPage,
     EmbedChatPage: EmbedChatPageBase,
     ChatbotSettings,
+    ChatLauncher,
     // Base variants if the host wants to pass tenantId explicitly.
     KnowledgePageBase,
     ChatPageBase,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixygon/chatbot-react",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "React + MUI pages for the Pixygon chatbot: knowledge base admin, chat, analytics, embeddable widget.",
   "type": "module",
   "main": "./dist/index.js",