@pixygon/chatbot-react 0.1.1 → 0.1.3

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

@@ -1,13 +1,12 @@
 import * as react from 'react';
-import { Api } from '@reduxjs/toolkit/query';
 
-/** RTK Query Api generics are invariant — a host's concrete baseApi
- *  (with literal `reducerPath` and specific tag types) cannot fit into a
- *  narrower-looking `Api<BFn, {}, string, string>`. We therefore accept
- *  any concrete Api shape and rely on injectChatbotEndpoints to do the
- *  runtime work. The host's hooks (returned by createChatbotComponents)
- *  remain fully typed inside the package; the host doesn't need a cast. */
-type AnyApi$1 = Api<any, any, any, any>;
+/** RTK Query's `Api<...>` type carries `unique symbol` brand fields that
+ *  make even `Api<any, any, any, any>` reject concrete host APIs. We accept
+ *  `any` for `apiSlice` on the public surface and rely on the runtime
+ *  injection inside `injectChatbotEndpoints` to do the wiring. The host's
+ *  hooks (returned by `createChatbotComponents`) stay fully typed inside
+ *  pages — only the input is loose. */
+type AnyApi$1 = any;
 interface ChatbotBrand {
     /** Display name shown in the embed header, system prompt, etc. */
     name: string;
@@ -39,10 +38,10 @@ interface TenantWithCap {
     chatCostCapUsdMonthly?: number | null;
 }
 
-/** See `context.ts` — RTK Query's Api generics are invariant, so we accept
- *  the host's concrete Api shape via `any` parameters. The runtime cast
- *  inside the function preserves all internal logic. */
-type AnyApi = Api<any, any, any, any>;
+/** See `context.ts` — `apiSlice` is `any` on the public surface to dodge
+ *  RTK Query's `unique symbol` brands. Internal logic still uses the host's
+ *  baseApi at runtime; only the input type is loose. */
+type AnyApi = any;
 interface KnowledgeDocument {
     _id: string;
     tenantId?: string;

package/package.json

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