@pocketping/widget 0.1.0 → 0.2.0

package/README.md

@@ -7,7 +7,7 @@ Embeddable chat widget for PocketPing. Drop-in customer support chat that connec
 ### Via CDN (Recommended)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@pocketping/widget/dist/index.global.js"></script>
+<script src="https://cdn.pocketping.io/widget.js"></script>
 <script>
   PocketPing.init({
     endpoint: 'https://yoursite.com/pocketping'
@@ -260,18 +260,96 @@ PocketPing.close();
 // Toggle the chat
 PocketPing.toggle();
 
+// Send a message programmatically
+PocketPing.sendMessage('Hello!');
+
 // Destroy the widget
 PocketPing.destroy();
 ```
 
 ---
 
+## Custom Events
+
+PocketPing supports bidirectional custom events between your website and the backend. This enables powerful interactions like triggering alerts when users take specific actions.
+
+### Triggering Events (Widget → Backend)
+
+Send events to your backend when users perform actions:
+
+```javascript
+// Notify when user clicks pricing
+PocketPing.trigger('clicked_pricing', { plan: 'pro', source: 'header' });
+
+// Track user interactions
+PocketPing.trigger('viewed_demo');
+PocketPing.trigger('downloaded_pdf', { name: 'whitepaper.pdf' });
+
+// Report errors
+PocketPing.trigger('error_occurred', { code: 500, page: window.location.pathname });
+```
+
+Events are forwarded to your backend and displayed in Telegram/Discord/Slack with full context.
+
+### Listening for Events (Backend → Widget)
+
+Your backend can send events to the widget. Subscribe to handle them:
+
+```javascript
+// Subscribe to an event
+const unsubscribe = PocketPing.onEvent('show_offer', (data) => {
+  showPopup(`Special offer: ${data.discount}% off!`);
+});
+
+// Unsubscribe when done
+unsubscribe();
+
+// Or use offEvent
+PocketPing.onEvent('announcement', handleAnnouncement);
+PocketPing.offEvent('announcement', handleAnnouncement);
+```
+
+### Event Callback
+
+You can also use an `onEvent` callback in the init config:
+
+```javascript
+PocketPing.init({
+  endpoint: 'https://yoursite.com/pocketping',
+  onEvent: (event) => {
+    console.log('Received event:', event.name, event.data);
+  }
+});
+```
+
+### Use Cases
+
+| Event | Use Case |
+|-------|----------|
+| `clicked_pricing` | Alert sales team when visitor shows interest |
+| `error_spike` | Get notified of frontend errors |
+| `cart_abandoned` | Trigger follow-up message |
+| `show_offer` | Display personalized offer |
+| `request_demo` | Open demo scheduling modal |
+| `announcement` | Show system-wide notification |
+
+---
+
 ## TypeScript Support
 
 Full TypeScript definitions are included:
 
 ```typescript
-import { init, PocketPingConfig, Message } from '@pocketping/widget';
+import {
+  init,
+  trigger,
+  onEvent,
+  offEvent,
+  PocketPingConfig,
+  Message,
+  CustomEvent,
+  CustomEventHandler
+} from '@pocketping/widget';
 
 const config: PocketPingConfig = {
   endpoint: 'https://yoursite.com/pocketping',
@@ -281,6 +359,15 @@ const config: PocketPingConfig = {
 };
 
 init(config);
+
+// Type-safe events
+trigger('clicked_pricing', { plan: 'pro' });
+
+const handler: CustomEventHandler = (data, event: CustomEvent) => {
+  console.log(event.name, data);
+};
+
+onEvent('show_offer', handler);
 ```
 
 ---

package/dist/index.d.mts

@@ -59,6 +59,8 @@ interface PocketPingConfig {
     onConnect?: (sessionId: string) => void;
     /** Called when connection fails */
     onError?: (error: Error) => void;
+    /** Called when a version mismatch is detected */
+    onVersionWarning?: (warning: VersionWarning) => void;
 }
 type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read';
 interface Message {
@@ -78,6 +80,8 @@ interface Session {
     visitorId: string;
     operatorOnline: boolean;
     messages: Message[];
+    /** User identity if identified via PocketPing.identify() */
+    identity?: UserIdentity;
 }
 interface PresenceResponse {
     online: boolean;
@@ -89,6 +93,55 @@ interface PresenceResponse {
     aiEnabled?: boolean;
     aiActiveAfter?: number;
 }
+type VersionWarningSeverity = 'info' | 'warning' | 'error';
+interface VersionWarning {
+    /** Severity level of the warning */
+    severity: VersionWarningSeverity;
+    /** Human-readable warning message */
+    message: string;
+    /** Current widget version */
+    currentVersion: string;
+    /** Minimum supported version (if applicable) */
+    minVersion?: string;
+    /** Latest available version (if applicable) */
+    latestVersion?: string;
+    /** Whether the widget should still function */
+    canContinue: boolean;
+    /** URL to upgrade instructions */
+    upgradeUrl?: string;
+}
+/** Custom event sent from widget to backend or vice versa */
+interface CustomEvent {
+    /** Event name (e.g., 'clicked_pricing', 'show_offer') */
+    name: string;
+    /** Event payload */
+    data?: Record<string, unknown>;
+    /** Timestamp of the event */
+    timestamp: string;
+}
+/** Handler for custom events */
+type CustomEventHandler = (data: Record<string, unknown> | undefined, event: CustomEvent) => void;
+/**
+ * User identity data for identifying visitors
+ * @example
+ * PocketPing.identify({
+ *   id: 'user_123',
+ *   email: 'john@example.com',
+ *   name: 'John Doe',
+ *   plan: 'pro',
+ *   company: 'Acme Inc'
+ * })
+ */
+interface UserIdentity {
+    /** Required unique user identifier */
+    id: string;
+    /** User's email address */
+    email?: string;
+    /** User's display name */
+    name?: string;
+    /** Any custom fields (plan, company, etc.) */
+    [key: string]: unknown;
+}
 
 type Listener<T> = (data: T) => void;
 declare class PocketPingClient {
@@ -97,6 +150,7 @@ declare class PocketPingClient {
     private ws;
     private isOpen;
     private listeners;
+    private customEventHandlers;
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimeout;
@@ -108,6 +162,33 @@ declare class PocketPingClient {
     sendTyping(isTyping?: boolean): Promise<void>;
     sendReadStatus(messageIds: string[], status: MessageStatus): Promise<void>;
     getPresence(): Promise<PresenceResponse>;
+    /**
+     * Identify the current user with metadata
+     * Call after user logs in or when user data becomes available
+     * @param identity - User identity data with required id field
+     * @example
+     * PocketPing.identify({
+     *   id: 'user_123',
+     *   email: 'john@example.com',
+     *   name: 'John Doe',
+     *   plan: 'pro',
+     *   company: 'Acme Inc'
+     * })
+     */
+    identify(identity: UserIdentity): Promise<void>;
+    /**
+     * Reset the user identity and optionally start a new session
+     * Call on user logout to clear user data
+     * @param options - Optional settings: { newSession: boolean }
+     */
+    reset(options?: {
+        newSession?: boolean;
+    }): Promise<void>;
+    /**
+     * Get the current user identity
+     * @returns UserIdentity or null if not identified
+     */
+    getIdentity(): UserIdentity | null;
     getSession(): Session | null;
     getMessages(): Message[];
     isConnected(): boolean;
@@ -116,14 +197,45 @@ declare class PocketPingClient {
     toggleOpen(): void;
     on<T>(event: string, listener: Listener<T>): () => void;
     private emit;
+    /**
+     * Trigger a custom event to the backend
+     * @param eventName - The name of the event (e.g., 'clicked_pricing', 'viewed_demo')
+     * @param data - Optional payload to send with the event
+     * @example
+     * PocketPing.trigger('clicked_cta', { button: 'signup', page: '/pricing' })
+     */
+    trigger(eventName: string, data?: Record<string, unknown>): void;
+    /**
+     * Subscribe to custom events from the backend
+     * @param eventName - The name of the event to listen for (e.g., 'show_offer', 'open_chat')
+     * @param handler - Callback function when event is received
+     * @returns Unsubscribe function
+     * @example
+     * const unsubscribe = PocketPing.onEvent('show_offer', (data) => {
+     *   showPopup(data.message)
+     * })
+     */
+    onEvent(eventName: string, handler: CustomEventHandler): () => void;
+    /**
+     * Unsubscribe from a custom event
+     * @param eventName - The name of the event
+     * @param handler - The handler to remove
+     */
+    offEvent(eventName: string, handler: CustomEventHandler): void;
+    private emitCustomEvent;
     private connectWebSocket;
     private handleWebSocketEvent;
+    private handleVersionWarning;
     private scheduleReconnect;
     private startPolling;
     private fetch;
+    private checkVersionHeaders;
     private getOrCreateVisitorId;
     private getStoredSessionId;
     private storeSessionId;
+    private getStoredIdentity;
+    private storeIdentity;
+    private clearIdentity;
     private generateId;
 }
 
@@ -133,6 +245,77 @@ declare function open(): void;
 declare function close(): void;
 declare function toggle(): void;
 declare function sendMessage(content: string): Promise<Message>;
+/**
+ * Trigger a custom event to the backend
+ * @param eventName - The name of the event (e.g., 'clicked_pricing', 'viewed_demo')
+ * @param data - Optional payload to send with the event
+ * @example
+ * PocketPing.trigger('clicked_cta', { button: 'signup', page: '/pricing' })
+ */
+declare function trigger(eventName: string, data?: Record<string, unknown>): void;
+/**
+ * Subscribe to custom events from the backend
+ * @param eventName - The name of the event to listen for
+ * @param handler - Callback function when event is received
+ * @returns Unsubscribe function
+ * @example
+ * const unsubscribe = PocketPing.onEvent('show_offer', (data) => {
+ *   showPopup(data.message)
+ * })
+ */
+declare function onEvent(eventName: string, handler: CustomEventHandler): () => void;
+/**
+ * Unsubscribe from a custom event
+ * @param eventName - The name of the event
+ * @param handler - The handler to remove
+ */
+declare function offEvent(eventName: string, handler: CustomEventHandler): void;
+/**
+ * Identify the current user with metadata
+ * Call after user logs in or when user data becomes available
+ * @param identity - User identity data with required id field
+ * @example
+ * PocketPing.identify({
+ *   id: 'user_123',
+ *   email: 'john@example.com',
+ *   name: 'John Doe',
+ *   plan: 'pro',
+ *   company: 'Acme Inc'
+ * })
+ */
+declare function identify(identity: UserIdentity): Promise<void>;
+/**
+ * Reset the user identity and optionally start a new session
+ * Call on user logout to clear user data
+ * @param options - Optional settings: { newSession: boolean }
+ * @example
+ * // Clear identity but keep session
+ * PocketPing.reset()
+ *
+ * // Clear everything and start fresh
+ * PocketPing.reset({ newSession: true })
+ */
+declare function reset(options?: {
+    newSession?: boolean;
+}): Promise<void>;
+/**
+ * Get the current user identity
+ * @returns UserIdentity or null if not identified
+ */
+declare function getIdentity(): UserIdentity | null;
+/**
+ * Subscribe to internal widget events
+ * @param eventName - Event name: 'versionWarning', 'message', 'connect', 'typing', etc.
+ * @param handler - Callback function
+ * @returns Unsubscribe function
+ * @example
+ * PocketPing.on('versionWarning', (warning) => {
+ *   if (warning.severity === 'error') {
+ *     showUpgradeNotice(warning.message);
+ *   }
+ * })
+ */
+declare function on<T>(eventName: string, handler: (data: T) => void): () => void;
 declare const _default: {
     init: typeof init;
     destroy: typeof destroy;
@@ -140,6 +323,13 @@ declare const _default: {
     close: typeof close;
     toggle: typeof toggle;
     sendMessage: typeof sendMessage;
+    trigger: typeof trigger;
+    onEvent: typeof onEvent;
+    offEvent: typeof offEvent;
+    on: typeof on;
+    identify: typeof identify;
+    reset: typeof reset;
+    getIdentity: typeof getIdentity;
 };
 
-export { type Message, type PocketPingConfig, close, _default as default, destroy, init, open, sendMessage, toggle };
+export { type CustomEvent, type CustomEventHandler, type Message, type PocketPingConfig, type UserIdentity, type VersionWarning, close, _default as default, destroy, getIdentity, identify, init, offEvent, on, onEvent, open, reset, sendMessage, toggle, trigger };

package/dist/index.d.ts

@@ -59,6 +59,8 @@ interface PocketPingConfig {
     onConnect?: (sessionId: string) => void;
     /** Called when connection fails */
     onError?: (error: Error) => void;
+    /** Called when a version mismatch is detected */
+    onVersionWarning?: (warning: VersionWarning) => void;
 }
 type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read';
 interface Message {
@@ -78,6 +80,8 @@ interface Session {
     visitorId: string;
     operatorOnline: boolean;
     messages: Message[];
+    /** User identity if identified via PocketPing.identify() */
+    identity?: UserIdentity;
 }
 interface PresenceResponse {
     online: boolean;
@@ -89,6 +93,55 @@ interface PresenceResponse {
     aiEnabled?: boolean;
     aiActiveAfter?: number;
 }
+type VersionWarningSeverity = 'info' | 'warning' | 'error';
+interface VersionWarning {
+    /** Severity level of the warning */
+    severity: VersionWarningSeverity;
+    /** Human-readable warning message */
+    message: string;
+    /** Current widget version */
+    currentVersion: string;
+    /** Minimum supported version (if applicable) */
+    minVersion?: string;
+    /** Latest available version (if applicable) */
+    latestVersion?: string;
+    /** Whether the widget should still function */
+    canContinue: boolean;
+    /** URL to upgrade instructions */
+    upgradeUrl?: string;
+}
+/** Custom event sent from widget to backend or vice versa */
+interface CustomEvent {
+    /** Event name (e.g., 'clicked_pricing', 'show_offer') */
+    name: string;
+    /** Event payload */
+    data?: Record<string, unknown>;
+    /** Timestamp of the event */
+    timestamp: string;
+}
+/** Handler for custom events */
+type CustomEventHandler = (data: Record<string, unknown> | undefined, event: CustomEvent) => void;
+/**
+ * User identity data for identifying visitors
+ * @example
+ * PocketPing.identify({
+ *   id: 'user_123',
+ *   email: 'john@example.com',
+ *   name: 'John Doe',
+ *   plan: 'pro',
+ *   company: 'Acme Inc'
+ * })
+ */
+interface UserIdentity {
+    /** Required unique user identifier */
+    id: string;
+    /** User's email address */
+    email?: string;
+    /** User's display name */
+    name?: string;
+    /** Any custom fields (plan, company, etc.) */
+    [key: string]: unknown;
+}
 
 type Listener<T> = (data: T) => void;
 declare class PocketPingClient {
@@ -97,6 +150,7 @@ declare class PocketPingClient {
     private ws;
     private isOpen;
     private listeners;
+    private customEventHandlers;
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimeout;
@@ -108,6 +162,33 @@ declare class PocketPingClient {
     sendTyping(isTyping?: boolean): Promise<void>;
     sendReadStatus(messageIds: string[], status: MessageStatus): Promise<void>;
     getPresence(): Promise<PresenceResponse>;
+    /**
+     * Identify the current user with metadata
+     * Call after user logs in or when user data becomes available
+     * @param identity - User identity data with required id field
+     * @example
+     * PocketPing.identify({
+     *   id: 'user_123',
+     *   email: 'john@example.com',
+     *   name: 'John Doe',
+     *   plan: 'pro',
+     *   company: 'Acme Inc'
+     * })
+     */
+    identify(identity: UserIdentity): Promise<void>;
+    /**
+     * Reset the user identity and optionally start a new session
+     * Call on user logout to clear user data
+     * @param options - Optional settings: { newSession: boolean }
+     */
+    reset(options?: {
+        newSession?: boolean;
+    }): Promise<void>;
+    /**
+     * Get the current user identity
+     * @returns UserIdentity or null if not identified
+     */
+    getIdentity(): UserIdentity | null;
     getSession(): Session | null;
     getMessages(): Message[];
     isConnected(): boolean;
@@ -116,14 +197,45 @@ declare class PocketPingClient {
     toggleOpen(): void;
     on<T>(event: string, listener: Listener<T>): () => void;
     private emit;
+    /**
+     * Trigger a custom event to the backend
+     * @param eventName - The name of the event (e.g., 'clicked_pricing', 'viewed_demo')
+     * @param data - Optional payload to send with the event
+     * @example
+     * PocketPing.trigger('clicked_cta', { button: 'signup', page: '/pricing' })
+     */
+    trigger(eventName: string, data?: Record<string, unknown>): void;
+    /**
+     * Subscribe to custom events from the backend
+     * @param eventName - The name of the event to listen for (e.g., 'show_offer', 'open_chat')
+     * @param handler - Callback function when event is received
+     * @returns Unsubscribe function
+     * @example
+     * const unsubscribe = PocketPing.onEvent('show_offer', (data) => {
+     *   showPopup(data.message)
+     * })
+     */
+    onEvent(eventName: string, handler: CustomEventHandler): () => void;
+    /**
+     * Unsubscribe from a custom event
+     * @param eventName - The name of the event
+     * @param handler - The handler to remove
+     */
+    offEvent(eventName: string, handler: CustomEventHandler): void;
+    private emitCustomEvent;
     private connectWebSocket;
     private handleWebSocketEvent;
+    private handleVersionWarning;
     private scheduleReconnect;
     private startPolling;
     private fetch;
+    private checkVersionHeaders;
     private getOrCreateVisitorId;
     private getStoredSessionId;
     private storeSessionId;
+    private getStoredIdentity;
+    private storeIdentity;
+    private clearIdentity;
     private generateId;
 }
 
@@ -133,6 +245,77 @@ declare function open(): void;
 declare function close(): void;
 declare function toggle(): void;
 declare function sendMessage(content: string): Promise<Message>;
+/**
+ * Trigger a custom event to the backend
+ * @param eventName - The name of the event (e.g., 'clicked_pricing', 'viewed_demo')
+ * @param data - Optional payload to send with the event
+ * @example
+ * PocketPing.trigger('clicked_cta', { button: 'signup', page: '/pricing' })
+ */
+declare function trigger(eventName: string, data?: Record<string, unknown>): void;
+/**
+ * Subscribe to custom events from the backend
+ * @param eventName - The name of the event to listen for
+ * @param handler - Callback function when event is received
+ * @returns Unsubscribe function
+ * @example
+ * const unsubscribe = PocketPing.onEvent('show_offer', (data) => {
+ *   showPopup(data.message)
+ * })
+ */
+declare function onEvent(eventName: string, handler: CustomEventHandler): () => void;
+/**
+ * Unsubscribe from a custom event
+ * @param eventName - The name of the event
+ * @param handler - The handler to remove
+ */
+declare function offEvent(eventName: string, handler: CustomEventHandler): void;
+/**
+ * Identify the current user with metadata
+ * Call after user logs in or when user data becomes available
+ * @param identity - User identity data with required id field
+ * @example
+ * PocketPing.identify({
+ *   id: 'user_123',
+ *   email: 'john@example.com',
+ *   name: 'John Doe',
+ *   plan: 'pro',
+ *   company: 'Acme Inc'
+ * })
+ */
+declare function identify(identity: UserIdentity): Promise<void>;
+/**
+ * Reset the user identity and optionally start a new session
+ * Call on user logout to clear user data
+ * @param options - Optional settings: { newSession: boolean }
+ * @example
+ * // Clear identity but keep session
+ * PocketPing.reset()
+ *
+ * // Clear everything and start fresh
+ * PocketPing.reset({ newSession: true })
+ */
+declare function reset(options?: {
+    newSession?: boolean;
+}): Promise<void>;
+/**
+ * Get the current user identity
+ * @returns UserIdentity or null if not identified
+ */
+declare function getIdentity(): UserIdentity | null;
+/**
+ * Subscribe to internal widget events
+ * @param eventName - Event name: 'versionWarning', 'message', 'connect', 'typing', etc.
+ * @param handler - Callback function
+ * @returns Unsubscribe function
+ * @example
+ * PocketPing.on('versionWarning', (warning) => {
+ *   if (warning.severity === 'error') {
+ *     showUpgradeNotice(warning.message);
+ *   }
+ * })
+ */
+declare function on<T>(eventName: string, handler: (data: T) => void): () => void;
 declare const _default: {
     init: typeof init;
     destroy: typeof destroy;
@@ -140,6 +323,13 @@ declare const _default: {
     close: typeof close;
     toggle: typeof toggle;
     sendMessage: typeof sendMessage;
+    trigger: typeof trigger;
+    onEvent: typeof onEvent;
+    offEvent: typeof offEvent;
+    on: typeof on;
+    identify: typeof identify;
+    reset: typeof reset;
+    getIdentity: typeof getIdentity;
 };
 
-export { type Message, type PocketPingConfig, close, _default as default, destroy, init, open, sendMessage, toggle };
+export { type CustomEvent, type CustomEventHandler, type Message, type PocketPingConfig, type UserIdentity, type VersionWarning, close, _default as default, destroy, getIdentity, identify, init, offEvent, on, onEvent, open, reset, sendMessage, toggle, trigger };