@pocketping/widget 0.1.0

package/README.md

@@ -0,0 +1,321 @@
+# @pocketping/widget
+
+Embeddable chat widget for PocketPing. Drop-in customer support chat that connects to your backend and notifies you via Telegram, Discord, or Slack.
+
+## Installation
+
+### Via CDN (Recommended)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@pocketping/widget/dist/index.global.js"></script>
+<script>
+  PocketPing.init({
+    endpoint: 'https://yoursite.com/pocketping'
+  });
+</script>
+```
+
+### Via npm
+
+```bash
+npm install @pocketping/widget
+```
+
+```javascript
+import { init } from '@pocketping/widget';
+
+init({
+  endpoint: 'https://yoursite.com/pocketping'
+});
+```
+
+---
+
+## Configuration Options
+
+### Required
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `endpoint` | `string` | Your backend endpoint (e.g., `"https://yoursite.com/pocketping"`) |
+
+---
+
+### Branding
+
+Customize the widget's branding to match your company identity.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `operatorName` | `string` | - | Company/operator name displayed in header |
+| `operatorAvatar` | `string` | - | Operator/company avatar URL (displayed in header) |
+| `logoUrl` | `string` | - | Company logo URL (alternative to avatar) |
+| `headerTitle` | `string` | `operatorName` | Header title text |
+| `headerSubtitle` | `string` | - | Header subtitle (e.g., "We usually reply within minutes") |
+| `welcomeMessage` | `string` | - | Welcome message shown when chat opens |
+| `placeholder` | `string` | `"Type a message..."` | Placeholder text for message input |
+
+**Example:**
+
+```javascript
+PocketPing.init({
+  endpoint: 'https://yoursite.com/pocketping',
+  operatorName: 'Acme Support',
+  operatorAvatar: 'https://yoursite.com/avatar.png',
+  headerTitle: 'Chat with us',
+  headerSubtitle: 'We usually reply within 5 minutes',
+  welcomeMessage: 'Hi there! How can we help you today?',
+  placeholder: 'Ask us anything...'
+});
+```
+
+---
+
+### Appearance
+
+Control the visual appearance of the widget.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Color theme (`'auto'` follows system preference) |
+| `primaryColor` | `string` | `'#6366f1'` | Primary brand color (hex format) |
+| `primaryTextColor` | `string` | `'#ffffff'` | Text color on primary background |
+| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Widget position on screen |
+| `offset` | `number` | `20` | Distance from edge in pixels |
+| `borderRadius` | `number` | `16` | Border radius in pixels |
+| `fontFamily` | `string` | System font stack | Custom font family |
+| `zIndex` | `number` | `9999` | Z-index for widget layering |
+| `toggleIcon` | `'chat' \| 'message' \| 'help' \| string` | `'chat'` | Toggle button icon (or custom SVG) |
+| `customCSS` | `string` | - | Custom CSS to inject |
+
+**Example:**
+
+```javascript
+PocketPing.init({
+  endpoint: 'https://yoursite.com/pocketping',
+  theme: 'dark',
+  primaryColor: '#10b981',
+  primaryTextColor: '#ffffff',
+  position: 'bottom-left',
+  offset: 24,
+  borderRadius: 12,
+  fontFamily: '"Inter", sans-serif',
+  zIndex: 10000,
+  toggleIcon: 'help'
+});
+```
+
+**Custom Icon Example:**
+
+```javascript
+PocketPing.init({
+  endpoint: 'https://yoursite.com/pocketping',
+  toggleIcon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 17h-2v-2h2v2zm2.07-7.75l-.9.92C13.45 12.9 13 13.5 13 15h-2v-.5c0-1.1.45-2.1 1.17-2.83l1.24-1.26c.37-.36.59-.86.59-1.41 0-1.1-.9-2-2-2s-2 .9-2 2H8c0-2.21 1.79-4 4-4s4 1.79 4 4c0 .88-.36 1.68-.93 2.25z"/></svg>'
+});
+```
+
+**Custom CSS Example:**
+
+```javascript
+PocketPing.init({
+  endpoint: 'https://yoursite.com/pocketping',
+  customCSS: `
+    .pocketping-header {
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    }
+    .pocketping-message--visitor {
+      background: #e0e7ff;
+    }
+  `
+});
+```
+
+---
+
+### Behavior
+
+Control when and how the widget behaves.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `showOnPages` | `string[]` | - | Only show on pages matching these regex patterns |
+| `hideOnPages` | `string[]` | - | Hide on pages matching these regex patterns |
+| `showDelay` | `number` | `0` | Delay before showing widget (ms) |
+| `autoOpenDelay` | `number` | `0` | Auto-open chat after delay (ms, `0` = disabled) |
+| `soundEnabled` | `boolean` | `true` | Play sound on new message |
+| `showUnreadBadge` | `boolean` | `true` | Show unread badge on toggle button |
+| `persistOpenState` | `boolean` | `false` | Persist chat open/closed state in localStorage |
+
+**Example:**
+
+```javascript
+PocketPing.init({
+  endpoint: 'https://yoursite.com/pocketping',
+  showOnPages: ['^/pricing', '^/contact', '^/help'],
+  hideOnPages: ['^/admin', '^/checkout'],
+  showDelay: 3000,
+  autoOpenDelay: 10000,
+  soundEnabled: true,
+  showUnreadBadge: true,
+  persistOpenState: true
+});
+```
+
+---
+
+### Callbacks
+
+React to widget events in your application.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `onOpen` | `() => void` | Called when chat window opens |
+| `onClose` | `() => void` | Called when chat window closes |
+| `onMessage` | `(message: Message) => void` | Called when a message is received |
+| `onConnect` | `(sessionId: string) => void` | Called when connected to backend |
+| `onError` | `(error: Error) => void` | Called when connection fails |
+
+**Example:**
+
+```javascript
+PocketPing.init({
+  endpoint: 'https://yoursite.com/pocketping',
+  onOpen: () => {
+    console.log('Chat opened');
+    analytics.track('chat_opened');
+  },
+  onClose: () => {
+    console.log('Chat closed');
+  },
+  onMessage: (message) => {
+    console.log('New message:', message.content);
+  },
+  onConnect: (sessionId) => {
+    console.log('Connected with session:', sessionId);
+  },
+  onError: (error) => {
+    console.error('Chat error:', error.message);
+  }
+});
+```
+
+---
+
+## Complete Example
+
+```javascript
+PocketPing.init({
+  // Required
+  endpoint: 'https://api.yoursite.com/pocketping',
+
+  // Branding
+  operatorName: 'Acme Inc.',
+  operatorAvatar: 'https://yoursite.com/logo-small.png',
+  headerTitle: 'Chat with Acme Support',
+  headerSubtitle: 'We typically reply within 5 minutes',
+  welcomeMessage: 'Welcome! How can we help you today?',
+  placeholder: 'Type your question...',
+
+  // Appearance
+  theme: 'auto',
+  primaryColor: '#2563eb',
+  primaryTextColor: '#ffffff',
+  position: 'bottom-right',
+  offset: 20,
+  borderRadius: 16,
+  fontFamily: '"Inter", system-ui, sans-serif',
+  zIndex: 9999,
+  toggleIcon: 'chat',
+
+  // Behavior
+  showOnPages: ['^/pricing', '^/features', '^/contact'],
+  hideOnPages: ['^/admin'],
+  showDelay: 2000,
+  autoOpenDelay: 0,
+  soundEnabled: true,
+  showUnreadBadge: true,
+  persistOpenState: true,
+
+  // Callbacks
+  onOpen: () => analytics.track('chat_opened'),
+  onClose: () => analytics.track('chat_closed'),
+  onConnect: (sessionId) => console.log('Session:', sessionId),
+  onError: (error) => console.error('Error:', error)
+});
+```
+
+---
+
+## Programmatic Control
+
+After initialization, you can control the widget programmatically:
+
+```javascript
+// Open the chat
+PocketPing.open();
+
+// Close the chat
+PocketPing.close();
+
+// Toggle the chat
+PocketPing.toggle();
+
+// Destroy the widget
+PocketPing.destroy();
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript definitions are included:
+
+```typescript
+import { init, PocketPingConfig, Message } from '@pocketping/widget';
+
+const config: PocketPingConfig = {
+  endpoint: 'https://yoursite.com/pocketping',
+  onMessage: (message: Message) => {
+    console.log(message.content);
+  }
+};
+
+init(config);
+```
+
+---
+
+## CSS Classes
+
+For advanced customization, you can target these CSS classes:
+
+| Class | Element |
+|-------|---------|
+| `.pocketping-container` | Main container |
+| `.pocketping-toggle` | Toggle button |
+| `.pocketping-toggle--unread` | Toggle with unread badge |
+| `.pocketping-window` | Chat window |
+| `.pocketping-header` | Chat header |
+| `.pocketping-messages` | Messages container |
+| `.pocketping-message` | Individual message |
+| `.pocketping-message--visitor` | Visitor message |
+| `.pocketping-message--operator` | Operator message |
+| `.pocketping-message--ai` | AI message |
+| `.pocketping-input` | Input container |
+| `.pocketping-input__field` | Text input |
+| `.pocketping-input__send` | Send button |
+
+---
+
+## Browser Support
+
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,145 @@
+interface PocketPingConfig {
+    /** Your backend endpoint (e.g., "https://yoursite.com/pocketping") */
+    endpoint: string;
+    /** Company/operator name displayed in header */
+    operatorName?: string;
+    /** Operator/company avatar URL (displayed in header) */
+    operatorAvatar?: string;
+    /** Company logo URL (displayed in header, alternative to avatar) */
+    logoUrl?: string;
+    /** Header title (defaults to operatorName) */
+    headerTitle?: string;
+    /** Header subtitle (e.g., "We usually reply within minutes") */
+    headerSubtitle?: string;
+    /** Welcome message shown when chat opens */
+    welcomeMessage?: string;
+    /** Placeholder text for message input */
+    placeholder?: string;
+    /** Color theme */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Primary brand color (hex, e.g., "#6366f1") */
+    primaryColor?: string;
+    /** Text color on primary background (defaults to white) */
+    primaryTextColor?: string;
+    /** Widget position */
+    position?: 'bottom-right' | 'bottom-left';
+    /** Distance from edge in pixels (default: 20) */
+    offset?: number;
+    /** Border radius in pixels (default: 16) */
+    borderRadius?: number;
+    /** Font family (defaults to system font stack) */
+    fontFamily?: string;
+    /** Z-index for widget (default: 9999) */
+    zIndex?: number;
+    /** Toggle button icon: 'chat' | 'message' | 'help' | custom SVG string */
+    toggleIcon?: 'chat' | 'message' | 'help' | string;
+    /** Custom CSS to inject (for advanced customization) */
+    customCSS?: string;
+    /** Only show on certain pages (regex patterns) */
+    showOnPages?: string[];
+    /** Hide on certain pages (regex patterns) */
+    hideOnPages?: string[];
+    /** Delay before showing widget in ms (default: 0) */
+    showDelay?: number;
+    /** Auto-open chat after delay in ms (0 = disabled) */
+    autoOpenDelay?: number;
+    /** Play sound on new message */
+    soundEnabled?: boolean;
+    /** Show unread badge on toggle button */
+    showUnreadBadge?: boolean;
+    /** Persist chat open/closed state in localStorage */
+    persistOpenState?: boolean;
+    /** Called when chat window opens */
+    onOpen?: () => void;
+    /** Called when chat window closes */
+    onClose?: () => void;
+    /** Called when a message is received */
+    onMessage?: (message: Message) => void;
+    /** Called when connected to backend */
+    onConnect?: (sessionId: string) => void;
+    /** Called when connection fails */
+    onError?: (error: Error) => void;
+}
+type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read';
+interface Message {
+    id: string;
+    sessionId: string;
+    content: string;
+    sender: 'visitor' | 'operator' | 'ai';
+    timestamp: string;
+    replyTo?: string;
+    metadata?: Record<string, unknown>;
+    status?: MessageStatus;
+    deliveredAt?: string;
+    readAt?: string;
+}
+interface Session {
+    sessionId: string;
+    visitorId: string;
+    operatorOnline: boolean;
+    messages: Message[];
+}
+interface PresenceResponse {
+    online: boolean;
+    operators?: Array<{
+        id: string;
+        name: string;
+        avatar?: string;
+    }>;
+    aiEnabled?: boolean;
+    aiActiveAfter?: number;
+}
+
+type Listener<T> = (data: T) => void;
+declare class PocketPingClient {
+    private config;
+    private session;
+    private ws;
+    private isOpen;
+    private listeners;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectTimeout;
+    constructor(config: PocketPingConfig);
+    connect(): Promise<Session>;
+    disconnect(): void;
+    sendMessage(content: string): Promise<Message>;
+    fetchMessages(after?: string): Promise<Message[]>;
+    sendTyping(isTyping?: boolean): Promise<void>;
+    sendReadStatus(messageIds: string[], status: MessageStatus): Promise<void>;
+    getPresence(): Promise<PresenceResponse>;
+    getSession(): Session | null;
+    getMessages(): Message[];
+    isConnected(): boolean;
+    isWidgetOpen(): boolean;
+    setOpen(open: boolean): void;
+    toggleOpen(): void;
+    on<T>(event: string, listener: Listener<T>): () => void;
+    private emit;
+    private connectWebSocket;
+    private handleWebSocketEvent;
+    private scheduleReconnect;
+    private startPolling;
+    private fetch;
+    private getOrCreateVisitorId;
+    private getStoredSessionId;
+    private storeSessionId;
+    private generateId;
+}
+
+declare function init(config: PocketPingConfig): PocketPingClient;
+declare function destroy(): void;
+declare function open(): void;
+declare function close(): void;
+declare function toggle(): void;
+declare function sendMessage(content: string): Promise<Message>;
+declare const _default: {
+    init: typeof init;
+    destroy: typeof destroy;
+    open: typeof open;
+    close: typeof close;
+    toggle: typeof toggle;
+    sendMessage: typeof sendMessage;
+};
+
+export { type Message, type PocketPingConfig, close, _default as default, destroy, init, open, sendMessage, toggle };

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+interface PocketPingConfig {
+    /** Your backend endpoint (e.g., "https://yoursite.com/pocketping") */
+    endpoint: string;
+    /** Company/operator name displayed in header */
+    operatorName?: string;
+    /** Operator/company avatar URL (displayed in header) */
+    operatorAvatar?: string;
+    /** Company logo URL (displayed in header, alternative to avatar) */
+    logoUrl?: string;
+    /** Header title (defaults to operatorName) */
+    headerTitle?: string;
+    /** Header subtitle (e.g., "We usually reply within minutes") */
+    headerSubtitle?: string;
+    /** Welcome message shown when chat opens */
+    welcomeMessage?: string;
+    /** Placeholder text for message input */
+    placeholder?: string;
+    /** Color theme */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Primary brand color (hex, e.g., "#6366f1") */
+    primaryColor?: string;
+    /** Text color on primary background (defaults to white) */
+    primaryTextColor?: string;
+    /** Widget position */
+    position?: 'bottom-right' | 'bottom-left';
+    /** Distance from edge in pixels (default: 20) */
+    offset?: number;
+    /** Border radius in pixels (default: 16) */
+    borderRadius?: number;
+    /** Font family (defaults to system font stack) */
+    fontFamily?: string;
+    /** Z-index for widget (default: 9999) */
+    zIndex?: number;
+    /** Toggle button icon: 'chat' | 'message' | 'help' | custom SVG string */
+    toggleIcon?: 'chat' | 'message' | 'help' | string;
+    /** Custom CSS to inject (for advanced customization) */
+    customCSS?: string;
+    /** Only show on certain pages (regex patterns) */
+    showOnPages?: string[];
+    /** Hide on certain pages (regex patterns) */
+    hideOnPages?: string[];
+    /** Delay before showing widget in ms (default: 0) */
+    showDelay?: number;
+    /** Auto-open chat after delay in ms (0 = disabled) */
+    autoOpenDelay?: number;
+    /** Play sound on new message */
+    soundEnabled?: boolean;
+    /** Show unread badge on toggle button */
+    showUnreadBadge?: boolean;
+    /** Persist chat open/closed state in localStorage */
+    persistOpenState?: boolean;
+    /** Called when chat window opens */
+    onOpen?: () => void;
+    /** Called when chat window closes */
+    onClose?: () => void;
+    /** Called when a message is received */
+    onMessage?: (message: Message) => void;
+    /** Called when connected to backend */
+    onConnect?: (sessionId: string) => void;
+    /** Called when connection fails */
+    onError?: (error: Error) => void;
+}
+type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read';
+interface Message {
+    id: string;
+    sessionId: string;
+    content: string;
+    sender: 'visitor' | 'operator' | 'ai';
+    timestamp: string;
+    replyTo?: string;
+    metadata?: Record<string, unknown>;
+    status?: MessageStatus;
+    deliveredAt?: string;
+    readAt?: string;
+}
+interface Session {
+    sessionId: string;
+    visitorId: string;
+    operatorOnline: boolean;
+    messages: Message[];
+}
+interface PresenceResponse {
+    online: boolean;
+    operators?: Array<{
+        id: string;
+        name: string;
+        avatar?: string;
+    }>;
+    aiEnabled?: boolean;
+    aiActiveAfter?: number;
+}
+
+type Listener<T> = (data: T) => void;
+declare class PocketPingClient {
+    private config;
+    private session;
+    private ws;
+    private isOpen;
+    private listeners;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectTimeout;
+    constructor(config: PocketPingConfig);
+    connect(): Promise<Session>;
+    disconnect(): void;
+    sendMessage(content: string): Promise<Message>;
+    fetchMessages(after?: string): Promise<Message[]>;
+    sendTyping(isTyping?: boolean): Promise<void>;
+    sendReadStatus(messageIds: string[], status: MessageStatus): Promise<void>;
+    getPresence(): Promise<PresenceResponse>;
+    getSession(): Session | null;
+    getMessages(): Message[];
+    isConnected(): boolean;
+    isWidgetOpen(): boolean;
+    setOpen(open: boolean): void;
+    toggleOpen(): void;
+    on<T>(event: string, listener: Listener<T>): () => void;
+    private emit;
+    private connectWebSocket;
+    private handleWebSocketEvent;
+    private scheduleReconnect;
+    private startPolling;
+    private fetch;
+    private getOrCreateVisitorId;
+    private getStoredSessionId;
+    private storeSessionId;
+    private generateId;
+}
+
+declare function init(config: PocketPingConfig): PocketPingClient;
+declare function destroy(): void;
+declare function open(): void;
+declare function close(): void;
+declare function toggle(): void;
+declare function sendMessage(content: string): Promise<Message>;
+declare const _default: {
+    init: typeof init;
+    destroy: typeof destroy;
+    open: typeof open;
+    close: typeof close;
+    toggle: typeof toggle;
+    sendMessage: typeof sendMessage;
+};
+
+export { type Message, type PocketPingConfig, close, _default as default, destroy, init, open, sendMessage, toggle };