@pocketping/widget 0.3.3 → 0.3.5

package/dist/{index.d.mts → index.d.cts}

@@ -123,6 +123,24 @@ interface CustomEvent {
 }
 /** Handler for custom events */
 type CustomEventHandler = (data: Record<string, unknown> | undefined, event: CustomEvent) => void;
+/** Options for trigger() method */
+interface TriggerOptions {
+    /** If provided, opens the widget and shows this message */
+    widgetMessage?: string;
+}
+/** 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>;
+}
 /**
  * User identity data for identifying visitors
  * @example
@@ -159,6 +177,13 @@ declare class PocketPingClient {
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimeout;
+    private pollingTimeout;
+    private pollingFailures;
+    private maxPollingFailures;
+    private trackedElementCleanups;
+    private currentTrackedElements;
+    private inspectorMode;
+    private inspectorCleanup;
     constructor(config: ResolvedPocketPingConfig);
     connect(): Promise<Session>;
     disconnect(): void;
@@ -206,10 +231,15 @@ declare class PocketPingClient {
      * 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
+     * @param options - Optional trigger options (widgetMessage to open chat)
      * @example
-     * PocketPing.trigger('clicked_cta', { button: 'signup', page: '/pricing' })
+     * // Silent event (just notify bridges)
+     * PocketPing.trigger('clicked_cta', { button: 'signup' })
+     *
+     * // Open widget with message
+     * PocketPing.trigger('clicked_pricing', { plan: 'pro' }, { widgetMessage: 'Need help choosing a plan?' })
      */
-    trigger(eventName: string, data?: Record<string, unknown>): void;
+    trigger(eventName: string, data?: Record<string, unknown>, options?: TriggerOptions): void;
     /**
      * Subscribe to custom events from the backend
      * @param eventName - The name of the event to listen for (e.g., 'show_offer', 'open_chat')
@@ -228,11 +258,38 @@ declare class PocketPingClient {
      */
     offEvent(eventName: string, handler: CustomEventHandler): void;
     private emitCustomEvent;
+    /**
+     * Setup tracked elements from config (used by SaaS dashboard)
+     * @param elements - Array of tracked element configurations
+     */
+    setupTrackedElements(elements: TrackedElement[]): void;
+    /**
+     * Cleanup all tracked element listeners
+     */
+    private cleanupTrackedElements;
+    /**
+     * Get current tracked elements configuration
+     */
+    getTrackedElements(): TrackedElement[];
+    /**
+     * Enable inspector mode for visual element selection
+     * This shows an overlay that allows clicking on elements to get their CSS selector
+     */
+    private enableInspectorMode;
+    /**
+     * Disable inspector mode
+     */
+    private disableInspectorMode;
+    /**
+     * Check if inspector mode is active
+     */
+    isInspectorModeActive(): boolean;
     private connectWebSocket;
     private handleWebSocketEvent;
     private handleVersionWarning;
     private scheduleReconnect;
     private startPolling;
+    private stopPolling;
     private fetch;
     private checkVersionHeaders;
     private getOrCreateVisitorId;
@@ -254,10 +311,29 @@ 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
+ * @param options - Optional trigger options (widgetMessage to open chat)
  * @example
- * PocketPing.trigger('clicked_cta', { button: 'signup', page: '/pricing' })
+ * // Silent event (just notify bridges)
+ * PocketPing.trigger('clicked_cta', { button: 'signup' })
+ *
+ * // Open widget with message
+ * PocketPing.trigger('clicked_pricing', { plan: 'pro' }, { widgetMessage: 'Need help choosing?' })
+ */
+declare function trigger(eventName: string, data?: Record<string, unknown>, options?: TriggerOptions): void;
+/**
+ * Setup tracked elements for auto-tracking (typically called by SaaS backend)
+ * @param elements - Array of tracked element configurations
+ * @example
+ * PocketPing.setupTrackedElements([
+ *   { selector: '#search-btn', event: 'click', name: 'clicked_search' },
+ *   { selector: '.pricing-card', event: 'click', name: 'viewed_pricing', widgetMessage: 'Need help?' }
+ * ])
+ */
+declare function setupTrackedElements(elements: TrackedElement[]): void;
+/**
+ * Get current tracked elements configuration
  */
-declare function trigger(eventName: string, data?: Record<string, unknown>): void;
+declare function getTrackedElements(): TrackedElement[];
 /**
  * Subscribe to custom events from the backend
  * @param eventName - The name of the event to listen for
@@ -335,6 +411,8 @@ declare const _default: {
     identify: typeof identify;
     reset: typeof reset;
     getIdentity: typeof getIdentity;
+    setupTrackedElements: typeof setupTrackedElements;
+    getTrackedElements: typeof getTrackedElements;
 };
 
-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 };
+export { type CustomEvent, type CustomEventHandler, type Message, type PocketPingConfig, type TrackedElement, type TriggerOptions, type UserIdentity, type VersionWarning, close, _default as default, destroy, getIdentity, getTrackedElements, identify, init, offEvent, on, onEvent, open, reset, sendMessage, setupTrackedElements, toggle, trigger };

package/dist/index.d.ts

@@ -123,6 +123,24 @@ interface CustomEvent {
 }
 /** Handler for custom events */
 type CustomEventHandler = (data: Record<string, unknown> | undefined, event: CustomEvent) => void;
+/** Options for trigger() method */
+interface TriggerOptions {
+    /** If provided, opens the widget and shows this message */
+    widgetMessage?: string;
+}
+/** 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>;
+}
 /**
  * User identity data for identifying visitors
  * @example
@@ -159,6 +177,13 @@ declare class PocketPingClient {
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimeout;
+    private pollingTimeout;
+    private pollingFailures;
+    private maxPollingFailures;
+    private trackedElementCleanups;
+    private currentTrackedElements;
+    private inspectorMode;
+    private inspectorCleanup;
     constructor(config: ResolvedPocketPingConfig);
     connect(): Promise<Session>;
     disconnect(): void;
@@ -206,10 +231,15 @@ declare class PocketPingClient {
      * 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
+     * @param options - Optional trigger options (widgetMessage to open chat)
      * @example
-     * PocketPing.trigger('clicked_cta', { button: 'signup', page: '/pricing' })
+     * // Silent event (just notify bridges)
+     * PocketPing.trigger('clicked_cta', { button: 'signup' })
+     *
+     * // Open widget with message
+     * PocketPing.trigger('clicked_pricing', { plan: 'pro' }, { widgetMessage: 'Need help choosing a plan?' })
      */
-    trigger(eventName: string, data?: Record<string, unknown>): void;
+    trigger(eventName: string, data?: Record<string, unknown>, options?: TriggerOptions): void;
     /**
      * Subscribe to custom events from the backend
      * @param eventName - The name of the event to listen for (e.g., 'show_offer', 'open_chat')
@@ -228,11 +258,38 @@ declare class PocketPingClient {
      */
     offEvent(eventName: string, handler: CustomEventHandler): void;
     private emitCustomEvent;
+    /**
+     * Setup tracked elements from config (used by SaaS dashboard)
+     * @param elements - Array of tracked element configurations
+     */
+    setupTrackedElements(elements: TrackedElement[]): void;
+    /**
+     * Cleanup all tracked element listeners
+     */
+    private cleanupTrackedElements;
+    /**
+     * Get current tracked elements configuration
+     */
+    getTrackedElements(): TrackedElement[];
+    /**
+     * Enable inspector mode for visual element selection
+     * This shows an overlay that allows clicking on elements to get their CSS selector
+     */
+    private enableInspectorMode;
+    /**
+     * Disable inspector mode
+     */
+    private disableInspectorMode;
+    /**
+     * Check if inspector mode is active
+     */
+    isInspectorModeActive(): boolean;
     private connectWebSocket;
     private handleWebSocketEvent;
     private handleVersionWarning;
     private scheduleReconnect;
     private startPolling;
+    private stopPolling;
     private fetch;
     private checkVersionHeaders;
     private getOrCreateVisitorId;
@@ -254,10 +311,29 @@ 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
+ * @param options - Optional trigger options (widgetMessage to open chat)
  * @example
- * PocketPing.trigger('clicked_cta', { button: 'signup', page: '/pricing' })
+ * // Silent event (just notify bridges)
+ * PocketPing.trigger('clicked_cta', { button: 'signup' })
+ *
+ * // Open widget with message
+ * PocketPing.trigger('clicked_pricing', { plan: 'pro' }, { widgetMessage: 'Need help choosing?' })
+ */
+declare function trigger(eventName: string, data?: Record<string, unknown>, options?: TriggerOptions): void;
+/**
+ * Setup tracked elements for auto-tracking (typically called by SaaS backend)
+ * @param elements - Array of tracked element configurations
+ * @example
+ * PocketPing.setupTrackedElements([
+ *   { selector: '#search-btn', event: 'click', name: 'clicked_search' },
+ *   { selector: '.pricing-card', event: 'click', name: 'viewed_pricing', widgetMessage: 'Need help?' }
+ * ])
+ */
+declare function setupTrackedElements(elements: TrackedElement[]): void;
+/**
+ * Get current tracked elements configuration
  */
-declare function trigger(eventName: string, data?: Record<string, unknown>): void;
+declare function getTrackedElements(): TrackedElement[];
 /**
  * Subscribe to custom events from the backend
  * @param eventName - The name of the event to listen for
@@ -335,6 +411,8 @@ declare const _default: {
     identify: typeof identify;
     reset: typeof reset;
     getIdentity: typeof getIdentity;
+    setupTrackedElements: typeof setupTrackedElements;
+    getTrackedElements: typeof getTrackedElements;
 };
 
-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 };
+export { type CustomEvent, type CustomEventHandler, type Message, type PocketPingConfig, type TrackedElement, type TriggerOptions, type UserIdentity, type VersionWarning, close, _default as default, destroy, getIdentity, getTrackedElements, identify, init, offEvent, on, onEvent, open, reset, sendMessage, setupTrackedElements, toggle, trigger };