@pocketping/sdk-node 0.1.0 → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,421 @@
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Storage adapter interface.
+ * Implement this interface to use any database with PocketPing.
+ */
+interface Storage {
+    createSession(session: Session): Promise<void>;
+    getSession(sessionId: string): Promise<Session | null>;
+    getSessionByVisitorId?(visitorId: string): Promise<Session | null>;
+    updateSession(session: Session): Promise<void>;
+    deleteSession(sessionId: string): Promise<void>;
+    saveMessage(message: Message): Promise<void>;
+    getMessages(sessionId: string, after?: string, limit?: number): Promise<Message[]>;
+    getMessage(messageId: string): Promise<Message | null>;
+    cleanupOldSessions?(olderThan: Date): Promise<number>;
+}
+
+/**
+ * Bridge interface for notification channels.
+ * Implement this interface to add support for Telegram, Discord, Slack, etc.
+ */
+interface Bridge {
+    /** Unique name for this bridge */
+    name: string;
+    /** Called when the bridge is added to PocketPing */
+    init?(pocketping: PocketPing): void | Promise<void>;
+    /** Called when a new chat session is created */
+    onNewSession?(session: Session): void | Promise<void>;
+    /** Called when a visitor sends a message */
+    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, 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>;
+}
+
+/**
+ * AI provider interface.
+ * Implement this to add support for OpenAI, Gemini, Claude, or local models.
+ */
+interface AIProvider {
+    /** Provider name */
+    name: string;
+    /** Generate a response to the conversation */
+    generateResponse(messages: Message[], systemPrompt?: string): Promise<string>;
+    /** Check if the provider is available */
+    isAvailable(): Promise<boolean>;
+}
+
+interface PocketPingConfig {
+    /** Storage adapter for sessions and messages */
+    storage?: Storage | 'memory';
+    /** Notification bridges (Telegram, Discord, etc.) */
+    bridges?: Bridge[];
+    /** AI fallback configuration */
+    ai?: AIConfig;
+    /** Welcome message shown to new visitors */
+    welcomeMessage?: string;
+    /** Seconds of inactivity before AI takes over (default: 300) */
+    aiTakeoverDelay?: number;
+    /** Callback when a new session is created */
+    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';
+    apiKey?: string;
+    model?: string;
+    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;
+    createdAt: Date;
+    lastActivity: Date;
+    operatorOnline: boolean;
+    aiActive: boolean;
+    metadata?: SessionMetadata;
+    /** User identity if identified via PocketPing.identify() */
+    identity?: UserIdentity;
+}
+interface SessionMetadata {
+    url?: string;
+    referrer?: string;
+    pageTitle?: string;
+    userAgent?: string;
+    timezone?: string;
+    language?: string;
+    screenResolution?: string;
+    ip?: string;
+    country?: string;
+    city?: string;
+    deviceType?: 'desktop' | 'mobile' | 'tablet';
+    browser?: string;
+    os?: string;
+    [key: string]: unknown;
+}
+type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read';
+interface Message {
+    id: string;
+    sessionId: string;
+    content: string;
+    sender: 'visitor' | 'operator' | 'ai';
+    timestamp: Date;
+    replyTo?: string;
+    metadata?: Record<string, unknown>;
+    status?: MessageStatus;
+    deliveredAt?: Date;
+    readAt?: Date;
+}
+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;
+    visitorId: string;
+    operatorOnline: boolean;
+    welcomeMessage?: string;
+    messages: Message[];
+    /** Tracked elements configuration (for SaaS auto-tracking) */
+    trackedElements?: TrackedElement[];
+}
+interface SendMessageRequest {
+    sessionId: string;
+    content: string;
+    sender: 'visitor' | 'operator';
+    replyTo?: string;
+}
+interface SendMessageResponse {
+    messageId: string;
+    timestamp: string;
+}
+interface GetMessagesRequest {
+    sessionId: string;
+    after?: string;
+    limit?: number;
+}
+interface GetMessagesResponse {
+    messages: Message[];
+    hasMore: boolean;
+}
+interface TypingRequest {
+    sessionId: string;
+    sender: 'visitor' | 'operator';
+    isTyping?: boolean;
+}
+interface ReadRequest {
+    sessionId: string;
+    messageIds: string[];
+    status?: MessageStatus;
+}
+interface ReadResponse {
+    updated: number;
+}
+interface IdentifyRequest {
+    sessionId: string;
+    identity: UserIdentity;
+}
+interface IdentifyResponse {
+    ok: boolean;
+}
+interface PresenceResponse {
+    online: boolean;
+    operators?: Array<{
+        id: string;
+        name: string;
+        avatar?: string;
+    }>;
+    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;
+    private bridges;
+    private config;
+    private wss;
+    private sessionSockets;
+    private operatorOnline;
+    private eventHandlers;
+    constructor(config?: PocketPingConfig);
+    private initStorage;
+    middleware(): (req: IncomingMessage & {
+        body?: unknown;
+        query?: Record<string, string>;
+    }, res: ServerResponse, next?: () => void) => void;
+    private parseBody;
+    attachWebSocket(server: any): void;
+    private handleWebSocketMessage;
+    private handleCustomEvent;
+    private broadcastToSession;
+    handleConnect(request: ConnectRequest): Promise<ConnectResponse>;
+    handleMessage(request: SendMessageRequest): Promise<SendMessageResponse>;
+    handleGetMessages(request: GetMessagesRequest): Promise<GetMessagesResponse>;
+    handleTyping(request: TypingRequest): Promise<{
+        ok: boolean;
+    }>;
+    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;
+}
+
+/**
+ * In-memory storage adapter.
+ * Useful for development and testing. Data is lost on restart.
+ */
+declare class MemoryStorage implements Storage {
+    private sessions;
+    private messages;
+    private messageById;
+    createSession(session: Session): Promise<void>;
+    getSession(sessionId: string): Promise<Session | null>;
+    getSessionByVisitorId(visitorId: string): Promise<Session | null>;
+    updateSession(session: Session): Promise<void>;
+    deleteSession(sessionId: string): Promise<void>;
+    saveMessage(message: Message): Promise<void>;
+    getMessages(sessionId: string, after?: string, limit?: number): Promise<Message[]>;
+    getMessage(messageId: string): Promise<Message | null>;
+    cleanupOldSessions(olderThan: Date): Promise<number>;
+}
+
+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 };