@pixygon/chatbot-react 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# @pixygon/chatbot-react
+
+React + MUI + RTK Query components for the Pixygon chatbot.
+
+## 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
+
+```ts
+import { createChatbotComponents } from "@pixygon/chatbot-react";
+import { baseApi } from "@/apis/baseApi";
+import { useAppSelector } from "@/store/store";
+
+export const chatbot = createChatbotComponents({
+  apiSlice: baseApi,
+  pathPrefix: "/tenants",                              // or "/companies"
+  useTenantId: () => useAppSelector((s) => s.global.activeTenantId),
+  apiBase: import.meta.env.VITE_API_URL,
+  brand: {
+    name: "TotalHMS",
+    tagline: "Powered by TotalHMS",
+    primaryColor: "#8FB7C9",
+  },
+});
+```
+
+Then drop into your router:
+
+```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 />} />
+```
+
+`EmbedChatPage` reads `tenantSlug` from props, so the host wires it through:
+
+```tsx
+function EmbedRoute() {
+  const { tenantSlug } = useParams();
+  return <chatbot.EmbedChatPage tenantSlug={tenantSlug} />;
+}
+```
+
+Settings card (drops into the host's settings page, host supplies the
+tenant + save handler since the Tenant model lives in the host):
+
+```tsx
+<chatbot.ChatbotSettings
+  tenant={activeTenant}
+  onSave={(patch) => updateTenant({ tenantId, patch }).unwrap()}
+/>
+```
+
+## 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
+
+The bootstrap snippet is served as a separate static file at
+`@pixygon/chatbot-react/chatbot.js`. Symlink or copy to your app's `public/`:
+
+```bash
+cp node_modules/@pixygon/chatbot-react/public/chatbot.js public/chatbot.js
+```
+
+## RTK Query tag types
+
+The host's `baseApi` should include these tags so invalidation works:
+
+```ts
+tagTypes: [..., "Knowledge", "ChatConversation"]
+```
+
+## Hooks-only API
+
+If you only want the RTK Query hooks without the pages, use `injectChatbotEndpoints`:
+
+```ts
+import { injectChatbotEndpoints } from "@pixygon/chatbot-react";
+const { useListDocumentsQuery, useSendMessageMutation, ... } =
+  injectChatbotEndpoints(baseApi, { pathPrefix: "/tenants" });
+```

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+import * as react from 'react';
+import { Api, BaseQueryFn, EndpointDefinitions } from '@reduxjs/toolkit/query';
+
+interface ChatbotBrand {
+    /** Display name shown in the embed header, system prompt, etc. */
+    name: string;
+    /** Optional tagline under the header. */
+    tagline?: string;
+    /** Primary color for the launcher button + header. CSS-compatible. */
+    primaryColor?: string;
+}
+interface ChatbotComponentConfig {
+    /** The host's RTK Query baseApi. Endpoints get injected onto it. */
+    apiSlice: Api<BaseQueryFn, EndpointDefinitions, string, string>;
+    /** Path prefix the server router was mounted under. */
+    pathPrefix: string;
+    /** Hook the host implements to surface the active tenant id. */
+    useTenantId: () => string | null | undefined;
+    /** Origin of the host API, e.g. "http://localhost:4000/v1". Used by the
+     *  anonymous EmbedChatPage which talks to the public route directly. */
+    apiBase: string;
+    /** Branding for the embed widget + ChatbotSettings copy. */
+    brand?: ChatbotBrand;
+}
+interface ResolvedChatbotConfig extends ChatbotComponentConfig {
+    brand: Required<ChatbotBrand>;
+}
+
+interface TenantWithCap {
+    _id: string;
+    slug: string;
+    chatCostCapUsdMonthly?: number | null;
+}
+
+interface KnowledgeDocument {
+    _id: string;
+    tenantId?: string;
+    companyId?: string;
+    title: string;
+    source?: string;
+    sourceType: "text" | "url" | "file";
+    status: "pending" | "processing" | "ready" | "failed";
+    chunkCount: number;
+    processedAt?: string;
+    lastError?: string;
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface ChatCitation {
+    documentTitle: string;
+    snippet: string;
+    chunkId?: string;
+    documentId?: string;
+    similarity?: number;
+}
+interface ChatTurn {
+    _id?: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    citedChunkIds?: string[];
+    tokensInput?: number;
+    tokensOutput?: number;
+    costUsd?: number;
+    model?: string;
+    rating?: number;
+    retrievalSimilarity?: number;
+    retrievedCount?: number;
+    createdAt: string;
+}
+interface ChatConversation {
+    _id: string;
+    sessionId: string;
+    userId?: string;
+    title: string;
+    messages: ChatTurn[];
+    totalTokensInput: number;
+    totalTokensOutput: number;
+    totalCostUsd: number;
+    lastMessageAt: string;
+    createdAt: string;
+}
+interface ConversationSummary {
+    _id: string;
+    sessionId: string;
+    userId?: string;
+    title: string;
+    messageCount: number;
+    totalCostUsd: number;
+    totalTokensInput: number;
+    totalTokensOutput: number;
+    lastMessageAt: string;
+    createdAt: string;
+}
+interface ChatOverview {
+    conversations: number;
+    messages: number;
+    totalCostUsd: number;
+    totalTokensInput: number;
+    totalTokensOutput: number;
+    ratingsHelpful: number;
+    ratingsUnhelpful: number;
+    ratingsUnrated: number;
+}
+interface TopQuestion {
+    question: string;
+    normalized: string;
+    count: number;
+    lastAskedAt: string;
+}
+interface Keyword {
+    term: string;
+    count: number;
+}
+interface CostDay {
+    date: string;
+    costUsd: number;
+    tokensInput: number;
+    tokensOutput: number;
+    messages: number;
+}
+interface KnowledgeGap {
+    question: string;
+    normalized: string;
+    count: number;
+    avgSimilarity: number;
+    negativeRatings: number;
+    noRetrievalCount: number;
+    gapScore: number;
+    lastAskedAt: string;
+}
+interface DocumentUsage {
+    documentId: string;
+    title: string;
+    citationCount: number;
+    uniqueConversations: number;
+    chunkCount: number;
+    citedChunkCount: number;
+    status: "unused" | "underused" | "active";
+}
+interface ConversationMatch {
+    _id: string;
+    sessionId: string;
+    title: string;
+    messageCount: number;
+    question: string;
+    assistantReply: string;
+    rating?: number;
+    retrievalSimilarity?: number;
+    createdAt: string;
+}
+interface SemanticCluster {
+    representative: string;
+    count: number;
+    members: string[];
+    avgSimilarity: number;
+}
+/**
+ * Inject all chatbot endpoints into the host's RTK Query baseApi. The host
+ * decides the path prefix — `/tenants` for hosts that use TotalHMS-style
+ * URLs, `/companies` for Recurrify-style.
+ *
+ *   const chatbotHooks = injectChatbotEndpoints(baseApi, { pathPrefix: "/companies" });
+ *   const { useListDocumentsQuery, useSendMessageMutation } = chatbotHooks;
+ *
+ * The host should add "Knowledge" + "ChatConversation" to baseApi's
+ * tagTypes when constructing it.
+ */
+declare function injectChatbotEndpoints(baseApi: Api<BaseQueryFn, EndpointDefinitions, string, string>, opts?: {
+    pathPrefix: string;
+}): any;
+type ChatbotHooks = ReturnType<typeof injectChatbotEndpoints>;
+
+/**
+ * Build the chatbot React surface for a host. Returns ready-to-mount page
+ * components closed over the host's API slice + branding.
+ *
+ *   const chatbot = createChatbotComponents({
+ *     apiSlice: baseApi,
+ *     pathPrefix: "/tenants",
+ *     useTenantId: () => useAppSelector((s) => s.global.activeTenantId),
+ *     apiBase: import.meta.env.VITE_API_URL,
+ *     brand: { name: "TotalHMS", primaryColor: "#8FB7C9" },
+ *   });
+ *
+ *   <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={<chatbot.EmbedChatPage />} />
+ */
+declare function createChatbotComponents(cfg: ChatbotComponentConfig): {
+    hooks: any;
+    KnowledgePage: () => react.JSX.Element;
+    ChatPage: () => react.JSX.Element;
+    ChatAnalyticsPage: () => react.JSX.Element;
+    EmbedChatPage: (props: {
+        tenantSlug?: string;
+    }) => react.JSX.Element;
+    ChatbotSettings: (props: {
+        tenant: TenantWithCap | null | undefined;
+        onSave: (patch: {
+            chatCostCapUsdMonthly: number | null;
+        }) => Promise<void>;
+        embedScriptUrl?: string;
+    }) => react.JSX.Element | null;
+    KnowledgePageBase: (props: {
+        tenantId?: string | null;
+    }) => react.JSX.Element;
+    ChatPageBase: (props: {
+        tenantId?: string | null;
+    }) => react.JSX.Element;
+    ChatAnalyticsPageBase: (props: {
+        tenantId?: string | null;
+    }) => react.JSX.Element;
+    EmbedChatPageBase: (props: {
+        tenantSlug?: string;
+    }) => react.JSX.Element;
+};
+
+export { type ChatCitation, type ChatConversation, type ChatOverview, type ChatTurn, type ChatbotBrand, type ChatbotComponentConfig, type ChatbotHooks, type ConversationMatch, type ConversationSummary, type CostDay, type DocumentUsage, type Keyword, type KnowledgeDocument, type KnowledgeGap, type ResolvedChatbotConfig, type SemanticCluster, type TopQuestion, createChatbotComponents, injectChatbotEndpoints };