@bangdb/web-sdk 1.0.5 → 1.0.7

package/README.md

@@ -0,0 +1,199 @@
+# @bangdb/web-sdk
+
+A self-contained AI chat widget that mounts itself into any web page. Works as a plain `<script>` tag, an npm package, or inside a React, Angular app.
+
+---
+
+## Installation
+
+```bash
+npm install @bangdb/web-sdk
+# or
+pnpm add @bangdb/web-sdk
+```
+
+---
+
+## Quick Start
+
+### Script tag
+
+```html
+<script src="https://cdn.jsdelivr.net/@bangdb/web-sdk/dist/index.global.js"></script>
+<script>
+  window.BangdbChatWidget.init({
+    config: {
+      apikey: "your-api-key",
+      baseURL: "your-bangdb-instance.com:18080",
+      userid: "user-123",
+      indexName: "my-index",
+    },
+  });
+</script>
+```
+
+### ES Module
+
+```ts
+import { init } from "@bangdb/web-sdk";
+
+init({
+  config: {
+    apikey: "your-api-key",
+    baseURL: "your-bangdb-instance.com:18080",
+    userid: "user-123",
+    indexName: "my-index",
+  },
+});
+```
+
+### React
+
+```tsx
+// components/Chat.tsx
+"use client"; // Next.js App Router only
+
+import { useEffect, useRef } from "react";
+import { type ChatWidgetOptions, ChatWidget } from "@bangdb/web-sdk";
+
+export default function Chat(props: ChatWidgetOptions) {
+  const mountedRef = useRef(false);
+
+  useEffect(() => {
+    if (mountedRef.current) return;
+    mountedRef.current = true;
+
+    new ChatWidget(props);
+
+    return () => {
+      document.getElementById("ai-chat-widget-root")?.remove();
+      mountedRef.current = false;
+    };
+  }, []);
+
+  return null; // widget mounts itself into document.body
+}
+```
+
+```tsx
+// app/layout.tsx
+import Chat from "@/components/Chat";
+
+export default function Layout({ children }) {
+  return (
+    <>
+      {children}
+      <Chat
+        config={{
+          apikey: process.env.NEXT_PUBLIC_BANGDB_API_KEY!,
+          baseURL: process.env.NEXT_PUBLIC_BANGDB_BASE_URL!,
+          userid: "user-123",
+          indexName: "my-index",
+        }}
+      />
+    </>
+  );
+}
+```
+
+---
+
+## Configuration
+
+### `ChatWidgetOptions`
+
+| Option        | Type | Required | Description                   |
+|---------------|---|---|-------------------------------|
+| `config`      | `ApiConfig` | ✅ | API connection settings       |
+| `colorTokens` | `ColorTokens` | ❌ | Override default theme colors |
+| `title`       | `string` | ❌ | Custom chat header title      |
+
+### `ApiConfig`
+
+| Option                  | Type | Required | Description                                      |
+|-------------------------|---|---|--------------------------------------------------|
+| `apikey`                | `string` | ✅ | BangDB API key                                   |
+| `backendURL`            | `string` | ✅ | BangDB instance URL with PORT                    |
+| `userid`                | `string` | ✅ | BangDB userid                                    |
+| `indexName`             | `string` | ✅ | Vector index to query against                    |
+| `resourceURL`           | `string` | ❌ | Resource service URL with PORT for images/tables |
+
+---
+
+If you use KaTeX for math rendering, import its CSS in your app:
+
+```ts
+import "katex/dist/katex.min.css";
+```
+
+---
+
+## Theming
+
+Override any part of the default dark theme by passing `colorTokens`:
+
+```ts
+init({
+  config: { ... },
+  colorTokens: {
+      background: "oklch(0.2223 0.0060 271.1393)",
+      foreground: "oklch(0.9551 0 0)",
+      card: "oklch(0.2568 0.0076 274.6528)",
+      cardForeground: "oklch(0.9551 0 0)",
+      primary: "oklch(0.611 0.1217 157.75)",
+      primaryForeground: "oklch(0.9491 0 0)",
+      secondary: "oklch(0.2940 0.0130 272.9312)",
+      secondaryForeground: "oklch(0.9551 0 0)",
+      muted: "oklch(0.2940 0.0130 272.9312)",
+      mutedForeground: "oklch(0.7058 0 0)",
+      accent: "oklch(0.2795 0.0368 260.0310)",
+      accentForeground: "oklch(0.7857 0.1153 246.6596)",
+      border: "oklch(0.3289 0.0092 268.3843)",
+      input: "oklch(0.3289 0.0092 268.3843)",
+      ring: "oklch(0.611 0.1217 157.75)",
+      radius: "0.5rem",
+      shadowPanel:
+          "0 32px 80px rgba(0,0,0,0.6), 0 0 0 1px rgba(255,255,255,0.06)",
+      shadowBubble:
+          "0 8px 32px color-mix(in oklab, oklch(0.611 0.1217 157.75) 40%, transparent)",
+      shadowInput:
+          "0 0 0 2px color-mix(in oklab, oklch(0.611 0.1217 157.75) 50%, transparent)",
+  },
+});
+```
+
+## TypeScript Support
+
+All types are exported from the package root:
+
+```ts
+import type {
+  ChatWidgetOptions,
+  ApiConfig,
+  ColorTokens,
+} from "@bangdb/web-sdk";
+```
+
+---
+
+## Browser Support
+
+The widget uses Shadow DOM (`mode: "open"`) for style isolation. It requires a modern browser that supports:
+
+- Shadow DOM v1
+- Custom Elements
+- `requestAnimationFrame`
+- ES2020+
+
+---
+
+## Peer Dependencies
+
+The following are **not** bundled and must be provided by the consumer if used:
+
+| Package | When needed |
+|---|---|
+| `katex` | Math rendering in markdown |
+| `katex/dist/katex.min.css` | KaTeX styles (import in your app) |
+
+---

package/dist/index.d.mts

@@ -31,9 +31,15 @@ interface ChatWidgetOptions {
     title?: string;
     config: ApiConfig;
     logo?: string;
+    tools?: {
+        id: string;
+        name: string;
+    }[];
 }
 declare class ChatWidget {
     private font;
+    private static DEFAULT_TOOLS;
+    private tools;
     private injectThemeVars;
     private injectGlobalFonts;
     private TOKENS;
@@ -52,6 +58,8 @@ declare class ChatWidget {
     init(): Promise<void>;
     private handleChatDataChange;
     private handleModeChange;
+    /** Repositions the chat panel above/below/left/right based on where the bubble is on screen */
+    private updatePanelPosition;
     createChatBubble(): HTMLElement;
     createChatUI(): HTMLElement;
     chatArea(): HTMLElement;

package/dist/index.d.ts

@@ -31,9 +31,15 @@ interface ChatWidgetOptions {
     title?: string;
     config: ApiConfig;
     logo?: string;
+    tools?: {
+        id: string;
+        name: string;
+    }[];
 }
 declare class ChatWidget {
     private font;
+    private static DEFAULT_TOOLS;
+    private tools;
     private injectThemeVars;
     private injectGlobalFonts;
     private TOKENS;
@@ -52,6 +58,8 @@ declare class ChatWidget {
     init(): Promise<void>;
     private handleChatDataChange;
     private handleModeChange;
+    /** Repositions the chat panel above/below/left/right based on where the bubble is on screen */
+    private updatePanelPosition;
     createChatBubble(): HTMLElement;
     createChatUI(): HTMLElement;
     chatArea(): HTMLElement;