@nabeh/chat-widget 0.1.0

package/README.md

@@ -0,0 +1,452 @@
+# Chat Widget Library
+
+Production-oriented TypeScript library for embedding an AI chat assistant into an Angular website or any browser-based application.
+
+## Publish to npm
+
+This package is configured for the npm organization scope `@nabeh` and for public publishing.
+
+### 1. Sign in with the CTO npm account
+
+If the CTO does not already have an npm account, create one first at `https://www.npmjs.com/signup`, then sign in.
+
+### 2. Create the npm organization
+
+While signed in to npm with the CTO account:
+
+- open `https://www.npmjs.com/`
+- click the profile menu in the top-right
+- click `Add an Organization`
+- enter the organization name `nabeh`
+
+The npm scope will be `@nabeh`.
+
+### 3. Log in on the publish machine
+
+Use the CTO account in the terminal:
+
+```bash
+npm logout
+npm login
+npm whoami
+```
+
+### 4. Build and verify the package
+
+```bash
+npm run clean
+npm run check
+npm run build
+npm pack --dry-run
+```
+
+### 5. Publish the package publicly
+
+```bash
+npm publish
+```
+
+For the next release:
+
+```bash
+npm version patch
+npm publish
+```
+
+Use `patch` for fixes, `minor` for new backward-compatible features, and `major` for breaking changes.
+
+Notes:
+
+- this package uses `"publishConfig": { "access": "public" }`
+- public org-scoped packages still use the scoped package name
+- npm docs for this flow:
+  - https://docs.npmjs.com/creating-an-organization
+  - https://docs.npmjs.com/creating-and-publishing-an-organization-scoped-package/
+
+## Project layout
+
+- `src/` - production TypeScript source
+- `docs/implementation-plan.md` - architecture and rollout notes
+- `local-test/mock-ai-server.js` - local mock backend
+- `local-test/chat-widget.js` - original quick prototype
+- `local-test/angular-usage-example.ts` - Angular init example
+
+## Library API
+
+Package usage:
+
+```ts
+import { createChatWidget } from "@nabeh/chat-widget";
+
+const widget = createChatWidget({
+  apiBaseUrl: "https://api.example.com",
+  endpoints: {
+    ask: "/knowledge_rag/ask",
+    history: "/knowledge_rag/get_chat_history",
+    deleteChat: "/knowledge_rag/delete_chat",
+    deleteLastQa: "/knowledge_rag/delete_last_qa_pair"
+  },
+  rag: {
+    chatId: "customer-portal-session-123",
+    knowledgeNames: ["employee-handbook", "policies"],
+    enableReferences: true
+  },
+  getAccessToken: async () => authService.getAccessToken(),
+  getUserContext: async () => ({
+    userId: currentUser.id,
+    displayName: currentUser.name
+  })
+});
+```
+
+Browser-global usage after loading the browser bundle:
+
+```html
+<script src="https://your-cdn.example.com/browser.iife.js"></script>
+<script>
+  window.ChatWidget.init({
+    apiBaseUrl: "https://api.example.com",
+    endpoints: {
+      ask: "/knowledge_rag/ask",
+      history: "/knowledge_rag/get_chat_history"
+    },
+    rag: {
+      chatId: "external-client-user-42",
+      knowledgeNames: ["client-kb-public", "client-kb-private"]
+    },
+    getAccessToken: async function () {
+      return window.appAccessToken;
+    },
+    getUserContext: async function () {
+      return {
+        userId: window.currentUser?.id,
+        displayName: window.currentUser?.name
+      };
+    }
+  });
+</script>
+```
+
+The browser bundle exposes:
+
+- `window.ChatWidget.init(config)`
+- `window.ChatWidget.createChatWidget(config)`
+
+`init()` returns a widget instance with methods like `open()`, `close()`, `toggle()`, `destroy()`, `loadChats()`, and `loadHistory()`.
+
+## Angular integration
+
+There are two supported ways to use this widget in Angular:
+
+1. load the browser bundle and call `window.ChatWidget.init(...)`
+2. install the npm package and import `createChatWidget(...)`
+
+### Option 1: Script-based Angular integration
+
+This is the closest match to your current setup.
+
+#### 1. Install or host the built bundle
+
+After `npm run build`, use:
+
+- `dist/browser.iife.js`
+
+Copy it into your Angular app assets folder, for example:
+
+- `src/assets/chat-widget/browser.iife.js`
+
+#### 2. Add the script in Angular
+
+In `angular.json`, add the built file under `architect > build > options > scripts`:
+
+```json
+[
+  "src/assets/chat-widget/browser.iife.js"
+]
+```
+
+Or add it directly in `src/index.html`:
+
+```html
+<script src="assets/chat-widget/browser.iife.js"></script>
+```
+
+#### 3. Initialize it after login
+
+Call it from a component or auth-ready service after the user session is available:
+
+```ts
+declare global {
+  interface Window {
+    ChatWidget?: {
+      init: (config: any) => any;
+    };
+  }
+}
+
+window.ChatWidget?.init({
+  apiBaseUrl: "http://192.168.0.126:8788",
+  endpoints: {
+    ask: "/my-chats/:chatId/messages",
+    history: "/my-chats/:chatId/messages",
+    listChats: "/my-chats",
+    createChat: "/my-chats",
+    updateChat: "/my-chats/:chatId",
+    deleteChat: "/my-chats/:chatId"
+  },
+  rag: {
+    knowledgeNames: ["sample-kb"],
+    loadHistoryOnOpen: true
+  },
+  getUserContext: async () => ({
+    userId: "demo-user-8",
+    email: "demo@example.com"
+  })
+});
+```
+
+Important:
+
+- `apiBaseUrl` must be your backend base URL, not the Angular frontend URL
+- if your backend runs on port `8788`, use `http://192.168.0.126:8788`
+- if authentication is required, also pass `getAccessToken`
+
+Example with token:
+
+```ts
+window.ChatWidget?.init({
+  apiBaseUrl: "http://192.168.0.126:8788",
+  endpoints: {
+    ask: "/my-chats/:chatId/messages",
+    history: "/my-chats/:chatId/messages",
+    listChats: "/my-chats",
+    createChat: "/my-chats",
+    updateChat: "/my-chats/:chatId",
+    deleteChat: "/my-chats/:chatId"
+  },
+  rag: {
+    knowledgeNames: ["sample-kb"],
+    loadHistoryOnOpen: true
+  },
+  getAccessToken: async () => localStorage.getItem("access_token"),
+  getUserContext: async () => ({
+    userId: "demo-user-8",
+    email: "demo@example.com"
+  })
+});
+```
+
+### Option 2: Install from npm in Angular
+
+Install the package:
+
+```bash
+npm install @nabeh/chat-widget
+```
+
+Then use it in Angular:
+
+```ts
+import { AfterViewInit, Component, OnDestroy } from "@angular/core";
+import { createChatWidget } from "@nabeh/chat-widget";
+
+@Component({
+  selector: "app-root",
+  template: ""
+})
+export class AppComponent implements AfterViewInit, OnDestroy {
+  private widget?: ReturnType<typeof createChatWidget>;
+
+  ngAfterViewInit(): void {
+    this.widget = createChatWidget({
+      apiBaseUrl: "http://192.168.0.126:8788",
+      endpoints: {
+        ask: "/my-chats/:chatId/messages",
+        history: "/my-chats/:chatId/messages",
+        listChats: "/my-chats",
+        createChat: "/my-chats",
+        updateChat: "/my-chats/:chatId",
+        deleteChat: "/my-chats/:chatId"
+      },
+      rag: {
+        knowledgeNames: ["sample-kb"],
+        loadHistoryOnOpen: true
+      },
+      getUserContext: async () => ({
+        userId: "demo-user-8",
+        email: "demo@example.com"
+      })
+    });
+  }
+
+  ngOnDestroy(): void {
+    this.widget?.destroy();
+  }
+}
+```
+
+## Configuration reference
+
+These are the main fields you should pass from Angular:
+
+- `apiBaseUrl`: backend base URL, for example `http://192.168.0.126:8788`
+- `endpoints.ask`: send-message endpoint
+- `endpoints.history`: fetch-history endpoint
+- `endpoints.listChats`: list sidebar chats
+- `endpoints.createChat`: create a new chat
+- `endpoints.updateChat`: update chat metadata like pin state
+- `endpoints.deleteChat`: delete a chat
+- `rag.knowledgeNames`: knowledge bases to query
+- `rag.loadHistoryOnOpen`: whether to load chat history automatically when opened
+- `getAccessToken`: function returning bearer token
+- `getUserContext`: function returning user identity information
+
+Example user context:
+
+```ts
+getUserContext: async () => ({
+  userId: "demo-user-8",
+  displayName: "Demo User",
+  email: "demo@example.com",
+  roles: ["researcher"]
+})
+```
+
+## Recommended Angular timing
+
+Initialize the widget:
+
+- after the user logs in
+- after token/user information is available
+- once per page/app shell, not on every route change
+
+Destroy the widget when the hosting Angular component is destroyed if you are using the npm import approach.
+
+## Knowledge RAG integration
+
+The widget is now aligned to the `knowledge_rag` endpoints:
+
+- `POST /knowledge_rag/ask`
+- `GET /knowledge_rag/get_chat_history`
+
+Production guidance:
+
+- pass the bearer token with `getAccessToken()`
+- do not hardcode tokens into the shipped widget
+- use a stable `rag.chatId` per user/session if you want conversation continuity
+- provide `rag.knowledgeNames` from the host application, not from the widget bundle
+- version your hosted script URL, for example:
+  - `/chat-widget/v1.0.0/browser.iife.js`
+  - `/chat-widget/latest/browser.iife.js`
+
+## Backend adapter integration
+
+When using the Postgres-backed adapter added in `backend/`, point the widget to the adapter endpoints instead of the raw RAG endpoints:
+
+```ts
+createChatWidget({
+  apiBaseUrl: "http://localhost:8788",
+  endpoints: {
+    ask: "/my-chats/:chatId/messages",
+    history: "/my-chats/:chatId/messages",
+    listChats: "/my-chats",
+    createChat: "/my-chats",
+    updateChat: "/my-chats/:chatId"
+  },
+  rag: {
+    knowledgeNames: ["sample-kb"],
+    loadHistoryOnOpen: false
+  },
+  getAccessToken: async () => authService.getAccessToken(),
+  getUserContext: async () => ({
+    userId: "demo-user-1",
+    displayName: "Demo User",
+    email: "demo@example.com",
+    roles: ["researcher"]
+  })
+});
+```
+
+The widget forwards `getUserContext()` to the adapter in the `X-Chat-User-Context` header. In your dummy site you can hardcode that object for testing; in the real client integration they should populate it from their logged-in user/session data.
+
+In the hybrid adapter flow, Postgres stores chat sidebar metadata only. Full message history and chat deletion are proxied to the AI backend.
+
+## Build outputs
+
+The library is configured to build:
+
+- `esm` for app imports
+- `cjs` for Node/CommonJS consumers
+- `iife` for script injection into an already deployed website
+
+Build tooling:
+
+```bash
+npm install
+npm run build
+```
+
+Output will be generated in `dist/`.
+
+## Local test flow
+
+### 1. Start the mock backend
+
+```bash
+node local-test/mock-ai-server.js
+```
+
+### 2. Build the browser bundle
+
+```bash
+npm install
+npm run build
+```
+
+### 3. Inject the built script into an Angular dummy app
+
+Copy the built browser file from `dist/` into Angular `src/assets/`, then add:
+
+```html
+<script src="/assets/browser.iife.js"></script>
+```
+
+### 4. Initialize after authentication
+
+```ts
+window.ChatWidget?.init({
+  apiBaseUrl: "http://localhost:8787",
+  endpoints: {
+    ask: "/knowledge_rag/ask",
+    history: "/knowledge_rag/get_chat_history"
+  },
+  rag: {
+    chatId: "angular-local-test-user-123",
+    knowledgeNames: ["sample-kb"]
+  },
+  getAccessToken: async () => "dummy-sso-token",
+  getUserContext: async () => ({
+    userId: "u-1001",
+    displayName: "Angular Test User"
+  })
+});
+```
+
+## Production integration guidance
+
+For the live Angular site:
+
+- host the built `iife` bundle on your CDN or app server
+- load it only after the user is authenticated
+- pass access token and user context from the host Angular app
+- keep RBAC validation in the AI backend
+
+Do not embed a separate login flow inside the widget.
+
+## Chat persistence adapter
+
+This repo now also includes a starter backend adapter in `backend/` for storing chat metadata in Postgres and wrapping the existing RAG APIs.
+
+Setup guide:
+
+- [docs/chat-backend-setup.md](/home/tarun/learnings/knowledge-platform-cb/docs/chat-backend-setup.md)