@pocketping/sdk-node 0.1.0 → 1.0.0

package/dist/index.d.ts

@@ -28,11 +28,17 @@ interface Bridge {
     /** Called when a new chat session is created */
     onNewSession?(session: Session): void | Promise<void>;
     /** Called when a visitor sends a message */
-    onMessage?(message: Message, session: Session): void | Promise<void>;
+    onVisitorMessage?(message: Message, session: Session): void | Promise<void>;
+    /** Called when an operator sends a message (for cross-bridge sync) */
+    onOperatorMessage?(message: Message, session: Session, sourceBridge?: string, operatorName?: string): void | Promise<void>;
     /** Called when visitor starts/stops typing */
     onTyping?(sessionId: string, isTyping: boolean): void | Promise<void>;
     /** Called when messages are marked as delivered/read */
-    onMessageRead?(sessionId: string, messageIds: string[], status: MessageStatus): void | Promise<void>;
+    onMessageRead?(sessionId: string, messageIds: string[], status: MessageStatus, session: Session): void | Promise<void>;
+    /** Called when a custom event is triggered from the widget */
+    onCustomEvent?(event: CustomEvent, session: Session): void | Promise<void>;
+    /** Called when a user identifies themselves via PocketPing.identify() */
+    onIdentityUpdate?(session: Session): void | Promise<void>;
     /** Cleanup when bridge is removed */
     destroy?(): void | Promise<void>;
 }
@@ -65,6 +71,24 @@ interface PocketPingConfig {
     onNewSession?: (session: Session) => void | Promise<void>;
     /** Callback when a message is received */
     onMessage?: (message: Message, session: Session) => void | Promise<void>;
+    /** Callback when a custom event is received from widget */
+    onEvent?: (event: CustomEvent, session: Session) => void | Promise<void>;
+    /** Callback when a user identifies themselves */
+    onIdentify?: (session: Session) => void | Promise<void>;
+    /** Webhook URL to forward custom events (Zapier, Make, n8n, etc.) */
+    webhookUrl?: string;
+    /** Secret key for HMAC-SHA256 signature (X-PocketPing-Signature header) */
+    webhookSecret?: string;
+    /** Webhook request timeout in milliseconds (default: 5000) */
+    webhookTimeout?: number;
+    /** Minimum supported widget version (e.g., "0.2.0") */
+    minWidgetVersion?: string;
+    /** Latest available widget version (e.g., "0.3.0") */
+    latestWidgetVersion?: string;
+    /** Custom message for version warnings */
+    versionWarningMessage?: string;
+    /** URL to upgrade instructions */
+    versionUpgradeUrl?: string;
 }
 interface AIConfig {
     provider: AIProvider | 'openai' | 'gemini' | 'anthropic';
@@ -73,6 +97,17 @@ interface AIConfig {
     systemPrompt?: string;
     fallbackAfter?: number;
 }
+/** User identity data from PocketPing.identify() */
+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;
+}
 interface Session {
     id: string;
     visitorId: string;
@@ -81,6 +116,8 @@ interface Session {
     operatorOnline: boolean;
     aiActive: boolean;
     metadata?: SessionMetadata;
+    /** User identity if identified via PocketPing.identify() */
+    identity?: UserIdentity;
 }
 interface SessionMetadata {
     url?: string;
@@ -115,6 +152,26 @@ interface ConnectRequest {
     visitorId: string;
     sessionId?: string;
     metadata?: SessionMetadata;
+    /** User identity if already identified */
+    identity?: UserIdentity;
+}
+/** Tracked element configuration (for SaaS auto-tracking) */
+interface TrackedElement {
+    /** CSS selector for the element(s) to track */
+    selector: string;
+    /** DOM event to listen for (default: 'click') */
+    event?: 'click' | 'submit' | 'focus' | 'change' | 'mouseenter';
+    /** Event name sent to backend */
+    name: string;
+    /** If provided, opens widget with this message when triggered */
+    widgetMessage?: string;
+    /** Additional data to send with the event */
+    data?: Record<string, unknown>;
+}
+/** Options for trigger() method */
+interface TriggerOptions {
+    /** If provided, opens the widget and shows this message */
+    widgetMessage?: string;
 }
 interface ConnectResponse {
     sessionId: string;
@@ -122,6 +179,8 @@ interface ConnectResponse {
     operatorOnline: boolean;
     welcomeMessage?: string;
     messages: Message[];
+    /** Tracked elements configuration (for SaaS auto-tracking) */
+    trackedElements?: TrackedElement[];
 }
 interface SendMessageRequest {
     sessionId: string;
@@ -155,6 +214,13 @@ interface ReadRequest {
 interface ReadResponse {
     updated: number;
 }
+interface IdentifyRequest {
+    sessionId: string;
+    identity: UserIdentity;
+}
+interface IdentifyResponse {
+    ok: boolean;
+}
 interface PresenceResponse {
     online: boolean;
     operators?: Array<{
@@ -165,6 +231,41 @@ interface PresenceResponse {
     aiEnabled: boolean;
     aiActiveAfter?: number;
 }
+/** 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;
+    /** Session ID (populated by SDK when event comes from widget) */
+    sessionId?: string;
+}
+/** Handler for custom events */
+type CustomEventHandler = (event: CustomEvent, session: Session) => void | Promise<void>;
+type VersionStatus = 'ok' | 'outdated' | 'deprecated' | 'unsupported';
+interface VersionCheckResult {
+    status: VersionStatus;
+    message?: string;
+    minVersion?: string;
+    latestVersion?: string;
+    canContinue: boolean;
+}
+/** Payload sent to webhook URL */
+interface WebhookPayload {
+    /** The custom event */
+    event: CustomEvent;
+    /** Session information */
+    session: {
+        id: string;
+        visitorId: string;
+        metadata?: SessionMetadata;
+        identity?: UserIdentity;
+    };
+    /** Timestamp when webhook was sent */
+    sentAt: string;
+}
 
 declare class PocketPing {
     private storage;
@@ -173,6 +274,7 @@ declare class PocketPing {
     private wss;
     private sessionSockets;
     private operatorOnline;
+    private eventHandlers;
     constructor(config?: PocketPingConfig);
     private initStorage;
     middleware(): (req: IncomingMessage & {
@@ -182,6 +284,7 @@ declare class PocketPing {
     private parseBody;
     attachWebSocket(server: any): void;
     private handleWebSocketMessage;
+    private handleCustomEvent;
     private broadcastToSession;
     handleConnect(request: ConnectRequest): Promise<ConnectResponse>;
     handleMessage(request: SendMessageRequest): Promise<SendMessageResponse>;
@@ -191,13 +294,109 @@ declare class PocketPing {
     }>;
     handlePresence(): Promise<PresenceResponse>;
     handleRead(request: ReadRequest): Promise<ReadResponse>;
+    /**
+     * Handle user identification from widget
+     * Called when visitor calls PocketPing.identify()
+     */
+    handleIdentify(request: IdentifyRequest): Promise<IdentifyResponse>;
+    /**
+     * Get a session by ID
+     */
+    getSession(sessionId: string): Promise<Session | null>;
     sendOperatorMessage(sessionId: string, content: string): Promise<Message>;
     setOperatorOnline(online: boolean): void;
+    /**
+     * Subscribe to custom events from widgets
+     * @param eventName - The name of the event to listen for, or '*' for all events
+     * @param handler - Callback function when event is received
+     * @returns Unsubscribe function
+     * @example
+     * // Listen for specific event
+     * pp.onEvent('clicked_pricing', async (event, session) => {
+     *   console.log(`User ${session.visitorId} clicked pricing: ${event.data?.plan}`)
+     * })
+     *
+     * // Listen for all events
+     * pp.onEvent('*', async (event, session) => {
+     *   console.log(`Event: ${event.name}`, event.data)
+     * })
+     */
+    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;
+    /**
+     * Send a custom event to a specific widget/session
+     * @param sessionId - The session ID to send the event to
+     * @param eventName - The name of the event
+     * @param data - Optional payload to send with the event
+     * @example
+     * // Send a promotion offer to a specific user
+     * pp.emitEvent('session-123', 'show_offer', {
+     *   discount: 20,
+     *   code: 'SAVE20',
+     *   message: 'Special offer just for you!'
+     * })
+     */
+    emitEvent(sessionId: string, eventName: string, data?: Record<string, unknown>): void;
+    /**
+     * Broadcast a custom event to all connected widgets
+     * @param eventName - The name of the event
+     * @param data - Optional payload to send with the event
+     * @example
+     * // Notify all users about maintenance
+     * pp.broadcastEvent('maintenance_warning', {
+     *   message: 'Site will be down for maintenance in 5 minutes'
+     * })
+     */
+    broadcastEvent(eventName: string, data?: Record<string, unknown>): void;
+    /**
+     * Process a custom event server-side (runs handlers, bridges, webhooks)
+     * Useful for server-side automation or triggering events programmatically
+     * @param sessionId - The session ID to associate with the event
+     * @param eventName - The name of the event
+     * @param data - Optional payload for the event
+     * @example
+     * // Trigger event from backend logic (e.g., after purchase)
+     * await pp.triggerEvent('session-123', 'purchase_completed', {
+     *   orderId: 'order-456',
+     *   amount: 99.99
+     * })
+     */
+    triggerEvent(sessionId: string, eventName: string, data?: Record<string, unknown>): Promise<void>;
     private notifyBridges;
     private notifyBridgesRead;
+    private notifyBridgesEvent;
+    private notifyBridgesIdentity;
+    /**
+     * Forward custom event to configured webhook URL (non-blocking)
+     * Used for integrations with Zapier, Make, n8n, or custom backends
+     */
+    private forwardToWebhook;
+    /**
+     * Forward identity update to webhook as a special event
+     */
+    private forwardIdentityToWebhook;
     addBridge(bridge: Bridge): void;
     private generateId;
     getStorage(): Storage;
+    /**
+     * Check widget version against configured min/latest versions
+     * @param widgetVersion - Version from X-PocketPing-Version header
+     * @returns Version check result with status and headers to set
+     */
+    checkWidgetVersion(widgetVersion: string | undefined): VersionCheckResult;
+    /**
+     * Set version warning headers on HTTP response
+     */
+    private setVersionHeaders;
+    /**
+     * Send version warning via WebSocket to a session
+     */
+    sendVersionWarning(sessionId: string, versionCheck: VersionCheckResult): void;
 }
 
 /**
@@ -219,4 +418,4 @@ declare class MemoryStorage implements Storage {
     cleanupOldSessions(olderThan: Date): Promise<number>;
 }
 
-export { type AIProvider, type Bridge, type ConnectRequest, type ConnectResponse, MemoryStorage, type Message, PocketPing, type PocketPingConfig, type PresenceResponse, type SendMessageRequest, type SendMessageResponse, type Session, type Storage };
+export { type AIProvider, type Bridge, type ConnectRequest, type ConnectResponse, type CustomEvent, type CustomEventHandler, MemoryStorage, type Message, PocketPing, type PocketPingConfig, type PresenceResponse, type SendMessageRequest, type SendMessageResponse, type Session, type Storage, type TrackedElement, type TriggerOptions, type WebhookPayload };