@verba-ai/chat-sdk 1.0.0 → 1.0.1

package/README.md

@@ -1,102 +1,141 @@
-# Verba Chat Widget SDK
+# @verba-ai/chat-sdk
 
-A lightweight, professional-grade TypeScript SDK designed to embed the Verba AI chat widget into any web application via a secure `<iframe>`.
+A lightweight, TypeScript SDK for embedding the Verba AI chat widget into any web application.
 
-## 1. Project Scope
+The SDK acts as a secure, high-performance orchestration layer that manages the injection and lifecycle of the Verba chat `iframe`. It supports both floating and inline mounting strategies.
 
-The Verba Chat SDK acts as an orchestration layer between a host application and the Verba Chat service. It provides a zero-dependency, high-performance solution for developers to integrate chat capabilities with minimal effort.
+## Installation
 
-### Core Features
-*   **Isomorphic Design**: Works seamlessly in modern browsers.
-*   **Dual Mounting Strategies**:
-    *   **Floating Bubble**: A fixed-position toggle button at the bottom-right (or left) corner.
-    *   **Inline Mounting**: Target any DOM element or CSS selector to embed the chat directly.
-*   **Secure Communication**: Bi-directional `postMessage` bridge with strict origin validation and namespace protection.
-*   **Lifecycle Management**: Robust methods for `init()`, `show()`, `hide()`, and `destroy()`.
-*   **Zero Dependencies**: Optimized for minimum bundle size (< 5 KB gzipped).
+Install via your preferred package manager:
 
----
-
-## 2. Project Structure
-
-```text
-sdk/
-├── dist/                 # Compiled distribution files (ESM/UMD)
-├── public/               # Static assets
-├── src/
-│   ├── index.ts          # Main entry point (ChatSDK class)
-│   ├── messenger.ts      # Multi-origin communication bridge
-│   ├── ui.ts             # CSS-in-JS and DOM factory helpers
-│   └── types.ts          # Shared TypeScript interfaces & enums
-├── index.html            # Interactive developer demo page
-├── package.json          # Library metadata & build scripts
-├── tsconfig.json         # TypeScript compiler configuration
-└── vite.config.ts        # Vite library mode configuration
+```bash
+npm install @verba-ai/chat-sdk
+# or
+yarn add @verba-ai/chat-sdk
+# or
+pnpm add @verba-ai/chat-sdk
 ```
 
-### File Explanations
+---
 
-| File | Purpose |
-| :--- | :--- |
-| **`src/index.ts`** | The main entry point. Exports the `ChatSDK` class which manages the state machine and coordinates UI injection and messaging. |
-| **`src/messenger.ts`** | Encapsulates `window.postMessage` logic. It handles secure event dispatching, origin checks, and subscription management. |
-| **`src/ui.ts`** | Handles "CSS-in-JS". It injects required styles into the document head and contains factory functions for creating the iframe, bubble button, and containers. |
-| **`src/types.ts`** | Centralized location for all TypeScript definitions, ensuring type safety for the configuration and the messaging protocol. |
-| **`vite.config.ts`** | Configures Vite for **Library Mode**. It uses Rollup to generate optimized ESM and UMD bundles and handles `.d.ts` generation. |
-| **`index.html`** | A standalone demo page that allows developers to test the SDK's features in real-time, complete with a specialized event log. |
+## Usage
 
----
+### 1. Floating Bubble (Default)
+The easiest way to integrate the chat. It creates a fixed-position action button in the bottom corner of your screen that toggles the chat window.
 
-## 3. Getting Started
+```typescript
+import { ChatSDK } from '@verba-ai/chat-sdk';
 
-### Installation
+const chat = new ChatSDK({
+  // Required: Your unique Verba tenant ID
+  tenant: 'your-tenant-id',
+  
+  // Optional: Simple theme selection
+  theme: 'dark', 
+  
+  // Optional: Position of the bubble
+  position: 'bottom-right' 
+});
 
-```bash
-npm install @verba/chat-sdk
+// Inject the bubble into the DOM
+chat.init(); 
+
+// Optional programmatic controls
+// chat.show();
+// chat.hide();
+// chat.destroy();
 ```
 
-### Basic Usage (Floating)
+### 2. Inline Mounting
+If you want to render the chat inside a specific part of your page (like a dashboard panel or a dedicated contact page).
 
 ```typescript
-import { ChatSDK } from '@verba/chat-sdk';
+import { ChatSDK } from '@verba-ai/chat-sdk';
+
+// Ensure the container exists in your DOM
+// <div id="my-chat-container" style="height: 600px;"></div>
 
 const chat = new ChatSDK({
   tenant: 'your-tenant-id',
-  theme: 'dark'
+  
+  // Target a CSS selector or pass an HTMLElement directly
+  container: '#my-chat-container',
+  
+  // Optional: Advanced visual theming
+  theme: {
+    primaryColor: '#6366f1',
+    backgroundColor: '#080b14',
+    textColor: '#f1f5f9',
+    borderRadius: '12px'
+  }
 });
 
-chat.init(); // Injects the bubble
+chat.init();
 ```
 
-### Inline Usage
+### 3. Usage via CDN (UMD)
+If you aren't using a bundler (Webpack/Vite/Rollup), you can load the SDK directly via a script tag.
 
-```typescript
-new ChatSDK({
-  tenant: 'your-tenant-id',
-  container: '#chat-container'
-}).init();
+```html
+<script src="https://unpkg.com/@verba-ai/chat-sdk@latest/dist/chat-sdk.umd.cjs"></script>
+<script>
+  const { ChatSDK } = window.VerbaChatSDK;
+  
+  new ChatSDK({ tenant: 'your-tenant-id' }).init();
+</script>
 ```
 
 ---
 
-## 4. Development
+## 📚 API Reference
 
-### Build the Library
-To generate the production-ready bundles in the `dist/` directory:
-```bash
-npm run build:lib
-```
+### `ChatSDK` Class
 
-### Start Demo Server
-To view the interactive demo locally:
-```bash
-npm run dev
+The main entry point for the widget.
+
+#### Methods
+
+| Method | Description |
+| :--- | :--- |
+| `init()` | Injects the CSS and iframe into the DOM. Resolves the SDK state to `ready`. |
+| `show()` | Makes the widget visible (animates the iframe open in floating mode). |
+| `hide()` | Hides the widget (animates the iframe closed in floating mode). |
+| `destroy()`| Completely tears down the SDK, removing all injected DOM elements, styles, and events. |
+
+---
+
+### Configuration Types
+
+#### `ChatSDKConfig`
+
+```typescript
+interface ChatSDKConfig {
+  /** Your Verba tenant ID (Required) */
+  tenant: string;
+  
+  /** Where to mount the widget. Omit for floating bubble. */
+  container?: string | HTMLElement;
+  
+  /** Visual theme. String preset or detailed config. */
+  theme?: 'light' | 'dark' | ThemeConfig;
+  
+  /** Position of the floating bubble (Default: 'bottom-right') */
+  position?: 'bottom-right' | 'bottom-left';
+  
+  /** Arbitrary metadata to pass to the widget */
+  userMetadata?: Record<string, unknown>;
+}
 ```
 
+#### `ThemeConfig`
 
-## 5. Testing
+```typescript
+interface ThemeConfig {
+  primaryColor?: string;
+  textColor?: string;
+  backgroundColor?: string;
+  fontFamily?: string;
+  borderRadius?: string | number;
+}
+```
 
-| File | Purpose |
-| :--- | :--- |
-| **`index.html`** | A standalone demo page that allows testing SDK's features in real-time, complete with a specialized event log. |
-| **`test.html`** | Testing the actual builded library. |

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@verba-ai/chat-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Lightweight TypeScript SDK for embedding the Verba AI chat widget via iframe.",
-  "keywords": ["chat", "widget", "sdk", "iframe", "verba"],
+  "keywords": [
+    "chat",
+    "widget",
+    "sdk",
+    "iframe",
+    "verba"
+  ],
   "license": "MIT",
   "type": "module",
   "main": "./dist/chat-sdk.umd.cjs",
@@ -14,7 +20,9 @@
       "require": "./dist/chat-sdk.umd.cjs"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "dev": "vite",
     "build:lib": "tsc --noEmit && vite build --config vite.config.ts",