@skywu/virtual-chat-sdk 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Virtual Chat Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,465 @@
+# @virtual-chat/sdk
+
+[![npm version](https://badge.fury.io/js/%40virtual-chat%2Fsdk.svg)](https://badge.fury.io/js/%40virtual-chat%2Fsdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A modern JavaScript/TypeScript SDK for embedding floating chat widgets into web applications. Features real-time messaging, virtual chat simulations, and seamless integration.
+
+## ✨ Features
+
+- 🎈 **Floating Button Mode** - Non-intrusive chat widget with smooth expand/collapse animations
+- 🎨 **Multiple UI Templates** - WhatsApp and Telegram-style themes with dark mode support
+- ⚡ **Real-time Communication** - WebSocket-based messaging with automatic reconnection
+- 📱 **Responsive Design** - Optimized for desktop, tablet, and mobile devices
+- 🔧 **Highly Customizable** - Configurable positioning, colors, and behavior
+- 📦 **TypeScript Support** - Full type definitions and IntelliSense support
+- 🚀 **Zero Config** - Works out of the box with minimal setup
+- 🔒 **Secure** - Built-in XSS protection and Shadow DOM isolation
+
+## 📦 Installation
+
+### npm/yarn (Recommended)
+
+```bash
+# npm
+npm install @virtual-chat/sdk
+
+# yarn
+yarn add @virtual-chat/sdk
+
+# pnpm
+pnpm add @virtual-chat/sdk
+```
+
+### CDN (Browser)
+
+### Option A: UMD (script tag) - Floating Button Mode
+
+```html
+<!-- 1) Include SDK from your server -->
+<script src="https://YOUR_SERVER_DOMAIN/sdk/chat-sdk.umd.js"></script>
+
+<!-- 2) Create a container (optional for floating mode) -->
+<div id="chat-container"></div>
+
+<!-- 3) Initialize with floating button mode -->
+<script>
+  const chat = ChatSDK.init({
+    container: '#chat-container',
+    projectId: 'YOUR_PROJECT_ID',
+    username: 'Visitor',
+    language: 'zh',
+    uiTemplate: 'whatsapp',
+    autoJoin: true,
+    // point SDK API to your server
+    apiBaseUrl: 'https://YOUR_SERVER_DOMAIN',
+    socketUrl: 'https://YOUR_SERVER_DOMAIN',
+
+    // Floating button mode (recommended for third-party sites)
+    mode: 'floating',
+    floatingButton: {
+      position: 'bottom-right',
+      offset: { bottom: 20, right: 20 },
+      icon: 'chat'
+    }
+  })
+  // No need to call chat.open() in floating mode - button handles it
+</script>
+```
+
+### Option B: ESM (module) - Floating Button Mode
+
+```html
+<script type="module">
+  import { ChatSDK } from 'https://YOUR_SERVER_DOMAIN/sdk/chat-sdk.esm.js'
+  const chat = ChatSDK.init({
+    container: '#chat-container',
+    projectId: 'YOUR_PROJECT_ID',
+    username: 'Visitor',
+    language: 'en',
+    autoJoin: true,
+    apiBaseUrl: 'https://YOUR_SERVER_DOMAIN',
+    socketUrl: 'https://YOUR_SERVER_DOMAIN',
+
+    // Floating button mode (recommended for third-party sites)
+    mode: 'floating',
+    floatingButton: {
+      position: 'bottom-right',
+      offset: { bottom: 20, right: 20 }
+    }
+  })
+  // No need to call chat.open() in floating mode - button handles it
+</script>
+```
+
+## Display Modes
+
+### Floating Button Mode (Recommended for Third-Party Sites)
+- **Default behavior**: Shows a floating button, expands to full-screen chat when clicked
+- **Configuration**: `mode: 'floating'` with `floatingButton` options
+- **Best for**: Third-party website integration, non-intrusive user experience
+
+### Full-Screen Mode (Traditional)
+- **Behavior**: Directly shows the chat interface
+- **Configuration**: `mode: 'fullscreen'` or omit the mode property
+- **Best for**: Dedicated chat pages, internal applications
+
+## Notes:
+- No API key is required on the client.
+- Replace `YOUR_SERVER_DOMAIN` with your actual server domain where this app is hosted.
+- `projectId` can be found in the Admin panel (Projects list).
+- CORS: ensure your server allows the third‑party origin if needed.
+- Optional UI customization: `primaryColor`, `backgroundColor`, `width`, `height`.
+- **Floating button positioning**: `position` ('bottom-right', 'bottom-left', 'top-right', 'top-left'), `offset` (pixels from edges), `zIndex`
+
+
+### 1. Include the SDK
+## Floating Button Configuration Examples
+
+### Basic Floating Button
+```javascript
+const chat = ChatSDK.init({
+  container: document.body,
+  projectId: 'YOUR_PROJECT_ID',
+  mode: 'floating',
+  apiBaseUrl: 'https://YOUR_SERVER_DOMAIN',
+  socketUrl: 'https://YOUR_SERVER_DOMAIN'
+})
+```
+
+### Custom Positioned Floating Button
+```javascript
+const chat = ChatSDK.init({
+  container: document.body,
+  projectId: 'YOUR_PROJECT_ID',
+  mode: 'floating',
+  floatingButton: {
+    position: 'bottom-left',        // 'bottom-right', 'bottom-left', 'top-right', 'top-left'
+    offset: { bottom: 24, left: 24 }, // Distance from edges in pixels
+    icon: 'chat',                   // Button icon type
+    zIndex: 2147483000             // CSS z-index for layering
+  },
+  apiBaseUrl: 'https://YOUR_SERVER_DOMAIN',
+  socketUrl: 'https://YOUR_SERVER_DOMAIN'
+})
+```
+
+### Full-Screen Mode (Traditional)
+```javascript
+const chat = ChatSDK.init({
+  container: '#chat-container',
+  projectId: 'YOUR_PROJECT_ID',
+  mode: 'fullscreen',  // or omit this line for default behavior
+  apiBaseUrl: 'https://YOUR_SERVER_DOMAIN',
+  socketUrl: 'https://YOUR_SERVER_DOMAIN'
+})
+chat.open() // Required for full-screen mode
+```
+
+```html
+<!-- Via CDN -->
+<script src="https://cdn.example.com/chat-sdk.umd.js"></script>
+
+<!-- Or download and host locally -->
+<script src="path/to/chat-sdk.umd.js"></script>
+```
+
+### 2. Create a Container
+
+```html
+<div id="chat-container"></div>
+```
+
+### 3. Initialize the Chat
+
+```javascript
+const chat = ChatSDK.init({
+  container: '#chat-container',
+  projectId: 'your-project-id',
+  username: 'John Doe',
+  language: 'en',
+  theme: 'light',
+  onReady: () => console.log('Chat ready!'),
+  onMessage: (message) => console.log('New message:', message)
+});
+```
+
+## Configuration Options
+
+### Required Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `container` | `string \| HTMLElement` | CSS selector or DOM element for the chat widget |
+| `projectId` | `string` | Unique identifier for your chat project |
+
+### Optional Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `templateId` | `string` | `undefined` | Specific template to load (uses project default if not specified) |
+| `userId` | `string` | Auto-generated | Unique user identifier |
+| `username` | `string` | Auto-generated | Display name for the user |
+| `language` | `string` | `'en'` | Language code (en, zh, es, fr, de, ja, ko, etc.) |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'light'` | UI theme |
+| `uiTemplate` | `'whatsapp' \| 'telegram' \| 'discord' \| 'slack'` | `'whatsapp'` | Chat UI style |
+| `width` | `string \| number` | `'400px'` | Widget width |
+| `height` | `string \| number` | `'600px'` | Widget height |
+| `autoJoin` | `boolean` | `false` | Automatically join chat on initialization |
+| `showAvatars` | `boolean` | `true` | Show user avatars |
+| `showUsernames` | `boolean` | `true` | Show usernames |
+| `allowInput` | `boolean` | `true` | Allow user to send messages |
+
+### API Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiBaseUrl` | `string` | Current origin | Base URL for API requests |
+| `socketUrl` | `string` | Current origin | WebSocket server URL |
+| `token` | `string` | `undefined` | Authentication token |
+
+### Event Callbacks
+
+| Callback | Parameters | Description |
+|----------|------------|-------------|
+| `onReady` | `()` | Called when SDK is initialized |
+| `onOpen` | `()` | Called when chat widget opens |
+| `onClose` | `()` | Called when chat widget closes |
+| `onJoin` | `({ userId, username })` | Called when user joins chat |
+| `onMessage` | `(message)` | Called when any message is received |
+| `onUserMessage` | `(message)` | Called when user sends a message |
+| `onError` | `(error)` | Called when an error occurs |
+| `onLanguageChange` | `(language)` | Called when language changes |
+| `onThemeChange` | `(theme)` | Called when theme changes |
+
+## API Methods
+
+### Core Methods
+
+```javascript
+// Open/close the chat widget
+chat.open();
+chat.close();
+
+// Join/leave the chat
+chat.joinChat();
+chat.leaveChat();
+
+// Send a message programmatically
+chat.sendMessage('Hello world!', 'text');
+
+// Destroy the widget
+chat.destroy();
+```
+
+### Configuration Methods
+
+```javascript
+// Change language
+chat.setLanguage('zh');
+
+// Change theme
+chat.setTheme('dark');
+
+// Switch template
+chat.setTemplate('template-id');
+```
+
+### State Methods
+
+```javascript
+// Check widget state
+const isOpen = chat.isOpen();
+const isJoined = chat.isJoined();
+
+// Get configuration
+const config = chat.getConfig();
+
+// Get message history
+const messages = chat.getMessages();
+```
+
+### Event Methods
+
+```javascript
+// Listen to events
+chat.on('message', (message) => {
+  console.log('New message:', message);
+});
+
+// Remove event listeners
+chat.off('message');
+
+// Emit custom events
+chat.emit('custom-event', data);
+```
+
+## Examples
+
+### Basic Chat Widget
+
+```javascript
+const chat = ChatSDK.init({
+  container: '#chat',
+  projectId: 'demo-project',
+  username: 'Visitor',
+  autoJoin: true
+});
+```
+
+### Customized Widget
+
+```javascript
+const chat = ChatSDK.init({
+  container: document.getElementById('chat-container'),
+  projectId: 'my-project',
+  templateId: 'customer-support',
+  username: 'Customer',
+  language: 'zh',
+  theme: 'dark',
+  width: '100%',
+  height: '500px',
+  uiTemplate: 'telegram',
+
+  onReady: () => {
+    console.log('Chat is ready!');
+    chat.open();
+  },
+
+  onMessage: (message) => {
+    // Track messages in analytics
+    analytics.track('chat_message_received', {
+      content: message.content,
+      type: message.messageType
+    });
+  },
+
+  onUserMessage: (message) => {
+    // Track user messages
+    analytics.track('chat_message_sent', {
+      content: message.content
+    });
+  }
+});
+```
+
+### Multi-language Support
+
+```javascript
+const chat = ChatSDK.init({
+  container: '#chat',
+  projectId: 'support-chat',
+  language: 'en' // Start with English
+});
+
+// Language switcher
+document.getElementById('lang-zh').addEventListener('click', () => {
+  chat.setLanguage('zh');
+});
+
+document.getElementById('lang-es').addEventListener('click', () => {
+  chat.setLanguage('es');
+});
+```
+
+### Event-driven Integration
+
+```javascript
+const chat = ChatSDK.init({
+  container: '#chat',
+  projectId: 'sales-demo',
+
+  onJoin: ({ userId, username }) => {
+    // Notify your backend
+    fetch('/api/chat-joined', {
+      method: 'POST',
+      body: JSON.stringify({ userId, username })
+    });
+  },
+
+  onUserMessage: (message) => {
+    // Process user messages
+    if (message.content.includes('pricing')) {
+      // Show pricing modal
+      showPricingModal();
+    }
+  },
+
+  onError: (error) => {
+    // Handle errors gracefully
+    console.error('Chat error:', error);
+    showErrorNotification('Chat temporarily unavailable');
+  }
+});
+```
+
+## Browser Support
+
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## TypeScript Support
+
+The SDK includes full TypeScript definitions:
+
+```typescript
+import { ChatSDK, ChatSDKConfig, ChatMessage } from '@virtual-chat/sdk';
+
+const config: ChatSDKConfig = {
+  container: '#chat',
+  projectId: 'my-project',
+  onMessage: (message: ChatMessage) => {
+    console.log(message.content);
+  }
+};
+
+const chat = ChatSDK.init(config);
+```
+
+## Error Handling
+
+```javascript
+const chat = ChatSDK.init({
+  container: '#chat',
+  projectId: 'my-project',
+
+  onError: (error) => {
+    switch (error.code) {
+      case 'CONTAINER_NOT_FOUND':
+        console.error('Chat container not found');
+        break;
+      case 'PROJECT_LOAD_ERROR':
+        console.error('Failed to load project');
+        break;
+      case 'SOCKET_CONNECTION_ERROR':
+        console.error('Connection failed');
+        break;
+      default:
+        console.error('Unknown error:', error.message);
+    }
+  }
+});
+```
+
+## Building from Source
+
+```bash
+# Install dependencies
+npm install
+
+# Build for production
+npm run build
+
+# Build and watch for development
+npm run dev
+
+# Type checking
+npm run type-check
+```
+
+## License
+
+MIT License - see LICENSE file for details.