@pocketping/sdk-node 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -33,6 +33,10 @@ interface Bridge {
     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>;
+    /** Called when a custom event is triggered from the widget */
+    onEvent?(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 +69,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 +95,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 +114,8 @@ interface Session {
     operatorOnline: boolean;
     aiActive: boolean;
     metadata?: SessionMetadata;
+    /** User identity if identified via PocketPing.identify() */
+    identity?: UserIdentity;
 }
 interface SessionMetadata {
     url?: string;
@@ -115,6 +150,8 @@ interface ConnectRequest {
     visitorId: string;
     sessionId?: string;
     metadata?: SessionMetadata;
+    /** User identity if already identified */
+    identity?: UserIdentity;
 }
 interface ConnectResponse {
     sessionId: string;
@@ -155,6 +192,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 +209,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 +252,7 @@ declare class PocketPing {
     private wss;
     private sessionSockets;
     private operatorOnline;
+    private eventHandlers;
     constructor(config?: PocketPingConfig);
     private initStorage;
     middleware(): (req: IncomingMessage & {
@@ -182,6 +262,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 +272,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 +396,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 WebhookPayload };

package/dist/index.d.ts

@@ -33,6 +33,10 @@ interface Bridge {
     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>;
+    /** Called when a custom event is triggered from the widget */
+    onEvent?(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 +69,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 +95,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 +114,8 @@ interface Session {
     operatorOnline: boolean;
     aiActive: boolean;
     metadata?: SessionMetadata;
+    /** User identity if identified via PocketPing.identify() */
+    identity?: UserIdentity;
 }
 interface SessionMetadata {
     url?: string;
@@ -115,6 +150,8 @@ interface ConnectRequest {
     visitorId: string;
     sessionId?: string;
     metadata?: SessionMetadata;
+    /** User identity if already identified */
+    identity?: UserIdentity;
 }
 interface ConnectResponse {
     sessionId: string;
@@ -155,6 +192,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 +209,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 +252,7 @@ declare class PocketPing {
     private wss;
     private sessionSockets;
     private operatorOnline;
+    private eventHandlers;
     constructor(config?: PocketPingConfig);
     private initStorage;
     middleware(): (req: IncomingMessage & {
@@ -182,6 +262,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 +272,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 +396,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 WebhookPayload };