@nabeh/chat-widget 0.1.0 → 0.1.2

package/README.md

@@ -1,280 +1,46 @@
-# Chat Widget Library
+# @nabeh/chat-widget
 
-Production-oriented TypeScript library for embedding an AI chat assistant into an Angular website or any browser-based application.
+Embeddable AI chat widget for Angular and other web applications.
 
-## 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:
+## Installation
 
 ```bash
 npm install @nabeh/chat-widget
 ```
 
-Then use it in Angular:
+## Angular Usage
+
+Use the widget after the user session is available so you can pass user context and, if needed, an access token.
 
 ```ts
-import { AfterViewInit, Component, OnDestroy } from "@angular/core";
-import { createChatWidget } from "@nabeh/chat-widget";
+import { AfterViewInit, Component, OnDestroy } from '@angular/core';
+import { createChatWidget } from '@nabeh/chat-widget';
 
 @Component({
-  selector: "app-root",
-  template: ""
+  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",
+      apiBaseUrl: 'http://your-api-url',
       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"
+        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"],
+        knowledgeNames: ['sample-kb'],
         loadHistoryOnOpen: true
       },
       getUserContext: async () => ({
-        userId: "demo-user-8",
-        email: "demo@example.com"
+        userId: 'your-user-id',
+        // email: 'user@example.com'
       })
     });
   }
@@ -285,168 +51,70 @@ export class AppComponent implements AfterViewInit, OnDestroy {
 }
 ```
 
-## Configuration reference
-
-These are the main fields you should pass from Angular:
+## Configuration
 
-- `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
+- `apiBaseUrl`: Backend base URL. Example: `https://api.example.com`
+- `endpoints.ask`: Send-message endpoint
+- `endpoints.history`: Fetch chat history endpoint
+- `endpoints.listChats`: List chats endpoint
+- `endpoints.createChat`: Create chat endpoint
+- `endpoints.updateChat`: Update chat metadata endpoint
+- `endpoints.deleteChat`: Delete chat endpoint
+- `rag.knowledgeNames`: Knowledge bases to query
+- `rag.loadHistoryOnOpen`: Load history automatically when the widget opens
+- `getUserContext`: Function that returns the current user context
+- `getAccessToken`: Optional function that returns a bearer token
 
-Example user context:
+## Example With Token
 
 ```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
+import { createChatWidget } from '@nabeh/chat-widget';
 
-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",
+const widget = createChatWidget({
+  apiBaseUrl: 'http://your-api-url',
   endpoints: {
-    ask: "/knowledge_rag/ask",
-    history: "/knowledge_rag/get_chat_history"
+    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: {
-    chatId: "angular-local-test-user-123",
-    knowledgeNames: ["sample-kb"]
+    knowledgeNames: ['sample-kb'],
+    loadHistoryOnOpen: true
   },
-  getAccessToken: async () => "dummy-sso-token",
+  getAccessToken: async () => localStorage.getItem('access_token'),
   getUserContext: async () => ({
-    userId: "u-1001",
-    displayName: "Angular Test User"
+    userId: 'your-user-id',
+    email: 'user@example.com'
   })
 });
 ```
 
-## Production integration guidance
+## Browser Global
 
-For the live Angular site:
+If you are loading the browser bundle manually, the package also exposes:
 
-- 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
+- `window.ChatWidget.init(config)`
+- `window.ChatWidget.createChatWidget(config)`
 
-Do not embed a separate login flow inside the widget.
+## Widget Instance API
 
-## Chat persistence adapter
+`createChatWidget(...)` returns an instance with:
 
-This repo now also includes a starter backend adapter in `backend/` for storing chat metadata in Postgres and wrapping the existing RAG APIs.
+- `open()`
+- `close()`
+- `toggle()`
+- `destroy()`
+- `sendMessage(message)`
+- `setAccessTokenProvider(provider)`
+- `getChatId()`
+- `loadChats()`
+- `loadHistory()`
 
-Setup guide:
+## Notes
 
-- [docs/chat-backend-setup.md](/home/tarun/learnings/knowledge-platform-cb/docs/chat-backend-setup.md)
+- `apiBaseUrl` should point to your backend, not your Angular frontend
+- initialize the widget after authentication if your backend requires user identity or tokens
+- call `destroy()` when the hosting Angular component is destroyed