cevro-messenger-sdk 0.1.0 → 0.1.1

package/README.md

@@ -1 +1,477 @@
-# messanger-sdk
+# Cevro Messenger SDK
+
+A lightweight, universal JavaScript SDK for integrating Cevro AI customer support chat into any website or web application. Works with vanilla JavaScript, React, Vue, Angular, and any other framework.
+
+## Installation
+
+### NPM / Yarn / PNPM
+
+```bash
+npm install cevro-messenger-sdk
+```
+
+```bash
+yarn add cevro-messenger-sdk
+```
+
+```bash
+pnpm add cevro-messenger-sdk
+```
+
+### CDN
+
+Add the script tag to your HTML:
+
+```html
+<!-- Using unpkg -->
+<script src="https://unpkg.com/cevro-messenger-sdk/dist/umd/cevro-messenger.min.js"></script>
+
+<!-- Or using jsdelivr -->
+<script src="https://cdn.jsdelivr.net/npm/cevro-messenger-sdk/dist/umd/cevro-messenger.min.js"></script>
+```
+
+## Quick Start
+
+### ES Modules (React, Vue, Angular, etc.)
+
+```javascript
+import { CevroMessenger } from 'cevro-messenger-sdk';
+
+const messenger = new CevroMessenger({
+  apiBase: 'https://api.cevro.ai',
+  workspaceId: 'your-workspace-id',
+  brandId: 'your-brand-id',
+});
+
+messenger.boot();
+```
+
+### Browser (Script Tag)
+
+```html
+<script src="https://unpkg.com/cevro-messenger-sdk/dist/umd/cevro-messenger.min.js"></script>
+<script>
+  const messenger = new CevroMessenger({
+    apiBase: 'https://api.cevro.ai',
+    workspaceId: 'your-workspace-id',
+    brandId: 'your-brand-id',
+  });
+
+  messenger.boot();
+</script>
+```
+
+## Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `apiBase` | `string` | Yes | - | API base URL for the Cevro backend |
+| `workspaceId` | `string` | Yes | - | Your Cevro workspace ID |
+| `brandId` | `string` | Yes | - | Brand ID for the workspace |
+| `player` | `PlayerData` | No | - | Authenticated user information |
+| `customLauncherSelector` | `string` | No | - | CSS selector for custom launcher button |
+| `hideDefaultLauncher` | `boolean` | No | `false` | Hide the default floating launcher button |
+| `alignment` | `'left' \| 'right'` | No | `'right'` | Horizontal position of the messenger |
+| `verticalPadding` | `number` | No | `20` | Padding from bottom (px) |
+| `horizontalPadding` | `number` | No | `20` | Padding from edge (px) |
+| `theme` | `'light' \| 'dark' \| 'system'` | No | `'light'` | Color theme |
+| `locale` | `string` | No | - | Locale (e.g., 'en', 'uk') |
+| `debug` | `boolean` | No | `false` | Enable debug logging |
+| `zIndex` | `number` | No | `2147483647` | Z-index for the widget |
+| `fileUpload` | `FileUploadConfig` | No | - | File upload settings |
+
+### PlayerData (Authenticated Users)
+
+Pass user information to identify authenticated users:
+
+```javascript
+const messenger = new CevroMessenger({
+  apiBase: 'https://api.cevro.ai',
+  workspaceId: 'your-workspace-id',
+  brandId: 'your-brand-id',
+  player: {
+    playerId: 'user-123',
+    email: 'user@example.com',
+    firstName: 'John',
+    lastName: 'Doe',
+    phone: '+1234567890',
+    customAttributes: {
+      plan: 'premium',
+      accountAge: 365,
+      verified: true,
+    },
+    playerHash: 'hmac-hash-for-verification', // Optional: HMAC for identity verification
+  },
+});
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `playerId` | `string` | Unique user ID on your platform (required) |
+| `email` | `string` | User's email address |
+| `firstName` | `string` | User's first name |
+| `lastName` | `string` | User's last name |
+| `phone` | `string` | User's phone number |
+| `customAttributes` | `object` | Custom key-value attributes (string, number, or boolean values) |
+| `playerHash` | `string` | HMAC hash for identity verification |
+
+### FileUploadConfig
+
+Configure file upload behavior:
+
+```javascript
+const messenger = new CevroMessenger({
+  // ... other options
+  fileUpload: {
+    allowedMimeTypes: ['image/*', 'application/pdf'],
+    additionalBlockedExtensions: ['.exe', '.bat'],
+  },
+});
+```
+
+## API Methods
+
+### `boot()`
+
+Initialize and render the messenger widget.
+
+```javascript
+messenger.boot();
+```
+
+### `shutdown(options?)`
+
+Remove the messenger from the page.
+
+```javascript
+// Normal shutdown
+messenger.shutdown();
+
+// Clear visitor data (visitor will get new identity on next init)
+messenger.shutdown({ clearVisitorData: true });
+```
+
+### `show()`
+
+Open the chat window.
+
+```javascript
+messenger.show();
+```
+
+### `hide()`
+
+Close the chat window.
+
+```javascript
+messenger.hide();
+```
+
+### `toggle()`
+
+Toggle the chat window visibility.
+
+```javascript
+messenger.toggle();
+```
+
+### `update(playerData)`
+
+Update user information. If `playerId` is added for the first time, the session will be re-initialized to merge the visitor with the authenticated player.
+
+```javascript
+// Identify a visitor as an authenticated user
+await messenger.update({
+  playerId: 'user-123',
+  email: 'user@example.com',
+  firstName: 'John',
+});
+```
+
+> **Note:** This is primarily used to identify anonymous visitors after they log in. The data will be used on the next session initialization.
+
+### `showNewMessage(prefilledText?)`
+
+Open the chat with optional pre-filled text.
+
+```javascript
+messenger.showNewMessage('I need help with my order');
+```
+
+### `getUnreadCount()`
+
+Get the current unread message count.
+
+```javascript
+const count = messenger.getUnreadCount();
+```
+
+### `getVisitorId()`
+
+Get the current visitor ID.
+
+```javascript
+const visitorId = messenger.getVisitorId();
+```
+
+## Events
+
+Subscribe to events using the `on()` method:
+
+```javascript
+// Subscribe to an event
+const unsubscribe = messenger.on('message:received', (data) => {
+  console.log('New message:', data.message);
+});
+
+// Unsubscribe later
+unsubscribe();
+```
+
+### Available Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `boot` | - | Messenger has been initialized |
+| `ready` | - | WebSocket connected and ready |
+| `show` | - | Chat window opened |
+| `hide` | - | Chat window closed |
+| `shutdown` | - | Messenger has been removed |
+| `session:initialized` | `{ sessionId, contactId, ticketId, isNewSession, isNewTicket }` | Session created/restored |
+| `message:received` | `{ ticketId, message }` | New message from agent/AI |
+| `message:sent` | `{ message }` | Message successfully sent |
+| `unread_count_change` | `{ count }` | Unread count changed |
+| `conversation:started` | `{ ticketId }` | New conversation started |
+| `chat:new_started` | - | New chat started after previous was closed |
+| `typing:start` | `{ ticketId, actor }` | Agent/AI started typing |
+| `typing:stop` | `{ ticketId, actor }` | Agent/AI stopped typing |
+| `error` | `{ type, error, message? }` | An error occurred |
+| `connection:open` | - | WebSocket connected |
+| `connection:close` | - | WebSocket disconnected |
+| `connection:error` | `{ error }` | WebSocket error |
+
+### Event Examples
+
+```javascript
+// Handle incoming messages
+messenger.on('message:received', (data) => {
+  console.log('New message:', data.message.body);
+
+  // Show browser notification
+  if (Notification.permission === 'granted') {
+    new Notification('New message', { body: data.message.body });
+  }
+});
+
+// Track when chat is opened
+messenger.on('show', () => {
+  analytics.track('chat_opened');
+});
+
+// Handle errors
+messenger.on('error', (data) => {
+  console.error(`Error [${data.type}]:`, data.error);
+
+  if (data.type === 'file_validation') {
+    alert(data.message);
+  }
+});
+
+// Update UI when unread count changes
+messenger.on('unread_count_change', (data) => {
+  document.querySelector('.notification-badge').textContent = data.count;
+});
+```
+
+## Framework Examples
+
+### React
+
+```jsx
+import { useEffect, useRef } from 'react';
+import { CevroMessenger } from 'cevro-messenger-sdk';
+
+function App() {
+  const messengerRef = useRef(null);
+
+  useEffect(() => {
+    messengerRef.current = new CevroMessenger({
+      apiBase: 'https://api.cevro.ai',
+      workspaceId: 'your-workspace-id',
+      brandId: 'your-brand-id',
+    });
+
+    messengerRef.current.boot();
+
+    return () => {
+      messengerRef.current?.shutdown();
+    };
+  }, []);
+
+  return <div>Your App</div>;
+}
+```
+
+### Vue 3
+
+```vue
+<script setup>
+import { onMounted, onUnmounted, ref } from 'vue';
+import { CevroMessenger } from 'cevro-messenger-sdk';
+
+const messenger = ref(null);
+
+onMounted(() => {
+  messenger.value = new CevroMessenger({
+    apiBase: 'https://api.cevro.ai',
+    workspaceId: 'your-workspace-id',
+    brandId: 'your-brand-id',
+  });
+
+  messenger.value.boot();
+});
+
+onUnmounted(() => {
+  messenger.value?.shutdown();
+});
+</script>
+
+<template>
+  <div>Your App</div>
+</template>
+```
+
+### Angular
+
+```typescript
+import { Component, OnDestroy, OnInit } from '@angular/core';
+import { CevroMessenger } from 'cevro-messenger-sdk';
+
+@Component({
+  selector: 'app-root',
+  template: '<div>Your App</div>',
+})
+export class AppComponent implements OnInit, OnDestroy {
+  private messenger: CevroMessenger | null = null;
+
+  ngOnInit() {
+    this.messenger = new CevroMessenger({
+      apiBase: 'https://api.cevro.ai',
+      workspaceId: 'your-workspace-id',
+      brandId: 'your-brand-id',
+    });
+
+    this.messenger.boot();
+  }
+
+  ngOnDestroy() {
+    this.messenger?.shutdown();
+  }
+}
+```
+
+### Next.js
+
+```jsx
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { CevroMessenger } from 'cevro-messenger-sdk';
+
+export default function ChatWidget() {
+  const messengerRef = useRef(null);
+
+  useEffect(() => {
+    // Only run on client side
+    if (typeof window !== 'undefined') {
+      messengerRef.current = new CevroMessenger({
+        apiBase: 'https://api.cevro.ai',
+        workspaceId: 'your-workspace-id',
+        brandId: 'your-brand-id',
+      });
+
+      messengerRef.current.boot();
+    }
+
+    return () => {
+      messengerRef.current?.shutdown();
+    };
+  }, []);
+
+  return null;
+}
+```
+
+## Custom Launcher
+
+Use your own button to open the chat:
+
+```html
+<button id="my-chat-button">Chat with us</button>
+
+<script>
+  const messenger = new CevroMessenger({
+    apiBase: 'https://api.cevro.ai',
+    workspaceId: 'your-workspace-id',
+    brandId: 'your-brand-id',
+    hideDefaultLauncher: true,
+    customLauncherSelector: '#my-chat-button',
+  });
+
+  messenger.boot();
+</script>
+```
+
+Or control it programmatically:
+
+```javascript
+const messenger = new CevroMessenger({
+  apiBase: 'https://api.cevro.ai',
+  workspaceId: 'your-workspace-id',
+  brandId: 'your-brand-id',
+  hideDefaultLauncher: true,
+});
+
+messenger.boot();
+
+document.getElementById('my-chat-button').addEventListener('click', () => {
+  messenger.toggle();
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import { CevroMessenger, CevroMessengerConfig } from 'cevro-messenger-sdk';
+
+const config: CevroMessengerConfig = {
+  apiBase: 'https://api.cevro.ai',
+  workspaceId: 'your-workspace-id',
+  brandId: 'your-brand-id',
+};
+
+const messenger = new CevroMessenger(config);
+
+messenger.on('message:received', (data) => {
+  console.log(data.message.body);
+});
+```
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+- iOS Safari (latest)
+- Android Chrome (latest)
+
+## License
+
+MIT
+
+## Support
+
+For support, contact us at [cevro.ai](https://cevro.ai)