@wabbit-dashboard/embed 1.0.0

package/README.md

@@ -0,0 +1,383 @@
+# @wabbit-dashboard/embed
+
+Wabbit Embed SDK - Unified widget library for embedding chat, forms, and email capture functionality into customer websites.
+
+## Installation
+
+### CDN (Recommended for Production)
+
+```html
+<script src="https://unpkg.com/@wabbit-dashboard/embed@1/dist/wabbit-embed.umd.min.js"></script>
+```
+
+For local development:
+```html
+<script src="http://localhost:3000/sdk/wabbit-embed.umd.js"></script>
+```
+
+> **Note**: For local development, run `make dev` from the project root. The SDK will be automatically built and served at `/sdk/wabbit-embed.umd.js`.
+
+### NPM
+
+```bash
+npm install @wabbit-dashboard/embed
+```
+
+```javascript
+import { Wabbit } from '@wabbit-dashboard/embed';
+```
+
+## Quick Start
+
+> 📖 **New to Wabbit?** Check out the [Getting Started Guide](./docs/getting-started.md) to integrate in 5 minutes.
+
+### Using CDN
+
+**Production:**
+```html
+<script src="https://unpkg.com/@wabbit-dashboard/embed@1/dist/wabbit-embed.umd.min.js"></script>
+<script>
+  Wabbit.init({
+    apiKey: 'pk_live_xxx',
+    chat: {
+      enabled: true,
+      collectionId: 'abc123',
+      position: 'bottom-right'
+    }
+  });
+</script>
+```
+
+**Local Development:**
+```html
+<script src="http://localhost:3000/sdk/wabbit-embed.umd.js"></script>
+<script>
+  Wabbit.init({
+    apiKey: 'pk_live_xxx',
+    apiUrl: 'http://localhost:3000',
+    chat: {
+      enabled: true,
+      collectionId: 'abc123',
+      position: 'bottom-right'
+    }
+  });
+</script>
+```
+
+## Configuration
+
+### Chat Widget
+
+```javascript
+Wabbit.init({
+  apiKey: 'pk_live_xxx',
+  chat: {
+    enabled: true,
+    collectionId: 'abc123',
+    position: 'bottom-right',      // 'bottom-right' | 'bottom-left'
+    triggerType: 'button',         // 'button' | 'auto' | 'scroll'
+    triggerDelay: 5000,            // ms before auto-open
+    theme: 'auto',                 // 'auto' | 'light' | 'dark'
+    primaryColor: '#6366f1',
+    welcomeMessage: 'Hi! How can I help?',
+    placeholder: 'Type your message...'
+  }
+});
+```
+
+### Form Widget
+
+```javascript
+Wabbit.init({
+  apiKey: 'pk_live_xxx',
+  forms: {
+    enabled: true,
+    containerId: 'feedback-form',  // DOM element ID
+    formId: 'form_xxx',
+    theme: 'auto',
+    onSubmit: (data) => {
+      console.log('Form submitted:', data);
+    },
+    onError: (error) => {
+      console.error('Form error:', error);
+    }
+  }
+});
+```
+
+### Email Capture
+
+```javascript
+Wabbit.init({
+  apiKey: 'pk_live_xxx',
+  emailCapture: {
+    enabled: true,
+    triggerAfterMessages: 3,
+    title: 'Stay in touch',
+    description: 'Get notified about updates',
+    fields: ['email'],             // 'email' | 'name' | 'company'
+    onCapture: (data) => {
+      console.log('Email captured:', data);
+    }
+  }
+});
+```
+
+## Testing
+
+### Option 1: Copy Embed Code from Dashboard (Recommended)
+
+1. **Start all services**:
+   ```bash
+   make dev
+   ```
+
+2. **Build the SDK** (required for local development):
+   ```bash
+   cd packages/embed
+   bun run build
+   ```
+
+3. **Get embed code from Dashboard**:
+   - Open Dashboard: `http://localhost:3000`
+   - Navigate to **Collections** → Select a collection → Click **"Embed Chat"** button
+   - Or navigate to **Forms** → Select a form → Click **"Embed"** button
+   - Copy the embed code from the modal
+
+4. **Paste into your HTML**:
+   - Create a test HTML file
+   - Paste the copied embed code
+   - Replace `YOUR_API_KEY` with your actual API key
+   - Open the HTML file in a browser
+
+### Option 2: Use Example Files
+
+1. **Configure settings**:
+   Edit `examples/config.js`:
+   ```javascript
+   window.WABBIT_CONFIG = {
+     "apiKey": "pk_live_your_actual_api_key",
+     "apiUrl": "http://localhost:3000",
+     "collectionId": "your-collection-id",
+     "formId": "your-form-id"
+   };
+   ```
+
+2. **Build the SDK**:
+   ```bash
+   cd packages/embed
+   bun run build
+   ```
+
+3. **Start a local server**:
+   ```bash
+   cd packages/embed
+   python3 -m http.server 8080
+   # or
+   npx http-server -p 8080
+   ```
+
+4. **Open example files**:
+   - **Complete example** (recommended): `http://localhost:8080/examples/test-complete.html`
+   - Chat only: `http://localhost:8080/examples/test-chat.html`
+   - Form only: `http://localhost:8080/examples/test-form.html`
+   - Email capture: `http://localhost:8080/examples/test-email-capture.html`
+
+See `examples/README.md` for more details.
+
+## Project Structure
+
+```
+packages/embed/
+├── src/                          # Source code
+│   ├── index.ts                  # Main entry point
+│   ├── core/                     # Core SDK functionality
+│   │   ├── wabbit.ts            # Main Wabbit class
+│   │   ├── config.ts            # Configuration management
+│   │   ├── api.ts               # API client
+│   │   ├── types.ts             # TypeScript type definitions
+│   │   └── events.ts            # Event emitter
+│   ├── chat/                     # Chat widget
+│   │   ├── ChatWidget.ts        # Main chat widget class
+│   │   ├── ChatBubble.ts        # Floating chat bubble
+│   │   ├── ChatPanel.ts         # Chat panel UI
+│   │   ├── WebSocketClient.ts   # WebSocket connection
+│   │   └── styles.ts            # Chat styles
+│   ├── forms/                    # Form widget
+│   │   ├── FormWidget.ts        # Main form widget class
+│   │   ├── FormRenderer.ts     # Form HTML renderer
+│   │   └── FormStyles.ts        # Form styles
+│   ├── email-capture/            # Email capture widget
+│   │   ├── EmailCaptureWidget.ts # Main email capture class
+│   │   ├── EmailCaptureModal.ts  # Email capture modal UI
+│   │   └── EmailCaptureStyles.ts # Email capture styles
+│   └── utils/                    # Utility functions
+│       ├── dom.ts               # DOM utilities
+│       ├── storage.ts           # localStorage wrapper
+│       └── theme.ts             # Theme detection
+├── dist/                         # Build output (generated)
+│   ├── wabbit-embed.umd.js       # UMD bundle (for CDN)
+│   ├── wabbit-embed.esm.js      # ES module bundle
+│   ├── wabbit-embed.cjs.js      # CommonJS bundle
+│   └── wabbit-embed.d.ts        # TypeScript definitions
+├── examples/                     # Example implementations
+│   ├── test-complete.html       # Complete integration example
+│   ├── test-chat.html           # Chat widget example
+│   ├── test-form.html           # Form widget example
+│   ├── test-email-capture.html # Email capture example
+│   ├── config.js                # Example configuration
+│   └── README.md                # Examples documentation
+├── tests/                        # Test files
+├── package.json                  # Package configuration
+├── tsconfig.json                 # TypeScript configuration
+├── rollup.config.js              # Rollup build configuration
+└── README.md                     # This file
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Build SDK (required before testing)
+bun run build
+
+# Development mode (watch)
+bun run dev
+
+# Production build
+bun run build:prod
+
+# Lint
+bun run lint
+```
+
+## API Reference
+
+### `Wabbit.init(config)`
+
+Initialize the Wabbit SDK.
+
+**Parameters:**
+- `config.apiKey` (string, required): Your Wabbit API key
+- `config.apiUrl` (string, optional): API base URL (default: auto-detected)
+- `config.chat` (ChatConfig, optional): Chat widget configuration
+- `config.forms` (FormConfig, optional): Form widget configuration
+- `config.emailCapture` (EmailCaptureConfig, optional): Email capture configuration
+
+**Example:**
+```javascript
+Wabbit.init({
+  apiKey: 'pk_live_xxx',
+  chat: { enabled: true, collectionId: 'abc123' }
+});
+```
+
+### `Wabbit.getInstance()`
+
+Get the current Wabbit instance.
+
+**Returns:** Wabbit instance or `null` if not initialized
+
+### `Wabbit.destroy()`
+
+Destroy the SDK instance and cleanup all widgets.
+
+### Configuration Types
+
+#### ChatConfig
+```typescript
+{
+  enabled: boolean;                  // Required
+  collectionId: string;              // Required
+  position?: 'bottom-right' | 'bottom-left';
+  triggerType?: 'button' | 'auto' | 'scroll';
+  triggerDelay?: number;
+  theme?: 'auto' | 'light' | 'dark';
+  primaryColor?: string;
+  welcomeMessage?: string;
+  placeholder?: string;
+}
+```
+
+#### FormConfig
+```typescript
+{
+  enabled: boolean;                  // Required
+  formId: string;                    // Required
+  containerId?: string;
+  theme?: 'auto' | 'light' | 'dark';
+  primaryColor?: string;
+  onSubmit?: (data, submissionId?) => void;
+  onError?: (error) => void;
+  onLoad?: () => void;
+}
+```
+
+#### EmailCaptureConfig
+```typescript
+{
+  enabled: boolean;                  // Required
+  triggerAfterMessages?: number;     // Default: 3
+  title?: string;
+  description?: string;
+  fields?: ('email' | 'name' | 'company')[];
+  onCapture?: (data) => void;
+}
+```
+
+## Programmatic Control
+
+```javascript
+const wabbit = Wabbit.getInstance();
+
+// Chat controls
+wabbit.chat.open();
+wabbit.chat.close();
+wabbit.chat.sendMessage('Hello');
+```
+
+## Troubleshooting
+
+### Chat widget not appearing
+- Check browser console for errors
+- Verify `chat.enabled` is `true`
+- Verify API key and collection ID are correct
+- Ensure WebSocket URL is accessible
+
+### Form not loading
+- Check API URL is correct (should be dashboard service URL, e.g., `http://localhost:3000`)
+- Verify form ID exists
+- Check browser console for errors
+- Verify CORS is configured correctly
+
+### Email capture not triggering
+- Ensure `emailCapture.enabled` is `true`
+- Check that chat widget is enabled (email capture requires chat)
+- Verify `triggerAfterMessages` value
+- Check localStorage for `wabbit_email_captured` or `wabbit_email_capture_dismissed` flags
+
+### Local development issues
+- **SDK not loading**: Make sure you've run `bun run build` in `packages/embed` directory
+- **File not found**: Ensure `dist/wabbit-embed.umd.js` exists after building
+- **CORS errors**: Check that all services are running (`make dev`)
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Documentation
+
+- 📖 [Getting Started Guide](./docs/getting-started.md) - Integrate in 5 minutes
+- 🌐 [Example Code](./examples/) - Integration examples (React, Vue, Vanilla JS)
+- 📚 API Reference - Coming soon
+- 🔧 Troubleshooting Guide - Coming soon
+
+## Related Resources
+
+- [Browser Compatibility](./BROWSER_COMPATIBILITY.md) - Browser compatibility test results
+- [Testing Guide](./TESTING.md) - Testing guide