@pocketping/widget 0.1.0 → 0.2.0

package/dist/index.global.js

@@ -24,10 +24,17 @@ var PocketPing = (() => {
     close: () => close,
     default: () => index_default,
     destroy: () => destroy,
+    getIdentity: () => getIdentity,
+    identify: () => identify,
     init: () => init,
+    offEvent: () => offEvent,
+    on: () => on,
+    onEvent: () => onEvent,
     open: () => open,
+    reset: () => reset,
     sendMessage: () => sendMessage,
-    toggle: () => toggle
+    toggle: () => toggle,
+    trigger: () => trigger
   });
 
   // ../../node_modules/.pnpm/preact@10.28.2/node_modules/preact/dist/preact.mjs
@@ -1036,6 +1043,9 @@ var PocketPing = (() => {
     return null;
   }
 
+  // src/version.ts
+  var VERSION = "0.2.0";
+
   // src/client.ts
   var PocketPingClient = class {
     constructor(config) {
@@ -1043,6 +1053,7 @@ var PocketPing = (() => {
       this.ws = null;
       this.isOpen = false;
       this.listeners = /* @__PURE__ */ new Map();
+      this.customEventHandlers = /* @__PURE__ */ new Map();
       this.reconnectAttempts = 0;
       this.maxReconnectAttempts = 5;
       this.reconnectTimeout = null;
@@ -1054,6 +1065,7 @@ var PocketPing = (() => {
     async connect() {
       const visitorId = this.getOrCreateVisitorId();
       const storedSessionId = this.getStoredSessionId();
+      const storedIdentity = this.getStoredIdentity();
       const response = await this.fetch("/connect", {
         method: "POST",
         body: JSON.stringify({
@@ -1067,14 +1079,17 @@ var PocketPing = (() => {
             timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
             language: navigator.language,
             screenResolution: `${window.screen.width}x${window.screen.height}`
-          }
+          },
+          // Include stored identity if available
+          identity: storedIdentity || void 0
         })
       });
       this.session = {
         sessionId: response.sessionId,
         visitorId: response.visitorId,
         operatorOnline: response.operatorOnline ?? false,
-        messages: response.messages ?? []
+        messages: response.messages ?? [],
+        identity: response.identity || storedIdentity || void 0
       };
       this.storeSessionId(response.sessionId);
       this.connectWebSocket();
@@ -1197,6 +1212,69 @@ var PocketPing = (() => {
       return this.fetch("/presence", { method: "GET" });
     }
     // ─────────────────────────────────────────────────────────────────
+    // User Identity
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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'
+     * })
+     */
+    async identify(identity) {
+      if (!identity?.id) {
+        throw new Error("[PocketPing] identity.id is required");
+      }
+      this.storeIdentity(identity);
+      if (this.session) {
+        try {
+          await this.fetch("/identify", {
+            method: "POST",
+            body: JSON.stringify({
+              sessionId: this.session.sessionId,
+              identity
+            })
+          });
+          this.session.identity = identity;
+          this.emit("identify", identity);
+        } catch (err) {
+          console.error("[PocketPing] Failed to identify:", err);
+          throw err;
+        }
+      }
+    }
+    /**
+     * Reset the user identity and optionally start a new session
+     * Call on user logout to clear user data
+     * @param options - Optional settings: { newSession: boolean }
+     */
+    async reset(options) {
+      this.clearIdentity();
+      if (this.session) {
+        this.session.identity = void 0;
+      }
+      if (options?.newSession) {
+        localStorage.removeItem("pocketping_session_id");
+        localStorage.removeItem("pocketping_visitor_id");
+        this.disconnect();
+        await this.connect();
+      }
+      this.emit("reset", null);
+    }
+    /**
+     * Get the current user identity
+     * @returns UserIdentity or null if not identified
+     */
+    getIdentity() {
+      return this.session?.identity || this.getStoredIdentity();
+    }
+    // ─────────────────────────────────────────────────────────────────
     // State
     // ─────────────────────────────────────────────────────────────────
     getSession() {
@@ -1239,6 +1317,67 @@ var PocketPing = (() => {
       this.listeners.get(event)?.forEach((listener) => listener(data));
     }
     // ─────────────────────────────────────────────────────────────────
+    // Custom Events (bidirectional)
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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, data) {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        console.warn("[PocketPing] Cannot trigger event: WebSocket not connected");
+        return;
+      }
+      const event = {
+        name: eventName,
+        data,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      this.ws.send(JSON.stringify({
+        type: "event",
+        data: event
+      }));
+      this.emit(`event:${eventName}`, event);
+    }
+    /**
+     * 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, handler) {
+      if (!this.customEventHandlers.has(eventName)) {
+        this.customEventHandlers.set(eventName, /* @__PURE__ */ new Set());
+      }
+      this.customEventHandlers.get(eventName).add(handler);
+      return () => {
+        this.customEventHandlers.get(eventName)?.delete(handler);
+      };
+    }
+    /**
+     * Unsubscribe from a custom event
+     * @param eventName - The name of the event
+     * @param handler - The handler to remove
+     */
+    offEvent(eventName, handler) {
+      this.customEventHandlers.get(eventName)?.delete(handler);
+    }
+    emitCustomEvent(event) {
+      const handlers = this.customEventHandlers.get(event.name);
+      if (handlers) {
+        handlers.forEach((handler) => handler(event.data, event));
+      }
+      this.emit("event", event);
+      this.emit(`event:${event.name}`, event);
+    }
+    // ─────────────────────────────────────────────────────────────────
     // WebSocket
     // ─────────────────────────────────────────────────────────────────
     connectWebSocket() {
@@ -1336,6 +1475,40 @@ var PocketPing = (() => {
           }
           this.emit("read", readData);
           break;
+        case "event":
+          const customEvent = event.data;
+          this.emitCustomEvent(customEvent);
+          break;
+        case "version_warning":
+          const versionWarning = event.data;
+          this.handleVersionWarning(versionWarning);
+          break;
+      }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Version Management
+    // ─────────────────────────────────────────────────────────────────
+    handleVersionWarning(warning) {
+      const prefix = "[PocketPing]";
+      const upgradeHint = warning.upgradeUrl ? ` Upgrade: ${warning.upgradeUrl}` : " Update your widget to the latest version.";
+      switch (warning.severity) {
+        case "error":
+          console.error(`${prefix} \u{1F6A8} VERSION ERROR: ${warning.message}${upgradeHint}`);
+          console.error(`${prefix} Current: ${warning.currentVersion}, Required: ${warning.minVersion || "unknown"}`);
+          break;
+        case "warning":
+          console.warn(`${prefix} \u26A0\uFE0F VERSION WARNING: ${warning.message}${upgradeHint}`);
+          console.warn(`${prefix} Current: ${warning.currentVersion}, Latest: ${warning.latestVersion || "unknown"}`);
+          break;
+        case "info":
+          console.info(`${prefix} \u2139\uFE0F ${warning.message}`);
+          break;
+      }
+      this.emit("versionWarning", warning);
+      this.config.onVersionWarning?.(warning);
+      if (!warning.canContinue) {
+        console.error(`${prefix} Widget is incompatible with backend. Please update immediately.`);
+        this.disconnect();
       }
     }
     scheduleReconnect() {
@@ -1381,15 +1554,46 @@ var PocketPing = (() => {
         ...options,
         headers: {
           "Content-Type": "application/json",
+          "X-PocketPing-Version": VERSION,
           ...options.headers
         }
       });
+      this.checkVersionHeaders(response);
       if (!response.ok) {
         const error = await response.text();
         throw new Error(`PocketPing API error: ${response.status} ${error}`);
       }
       return response.json();
     }
+    checkVersionHeaders(response) {
+      const versionStatus = response.headers.get("X-PocketPing-Version-Status");
+      const minVersion = response.headers.get("X-PocketPing-Min-Version");
+      const latestVersion = response.headers.get("X-PocketPing-Latest-Version");
+      const versionMessage = response.headers.get("X-PocketPing-Version-Message");
+      if (!versionStatus || versionStatus === "ok") {
+        return;
+      }
+      let severity = "info";
+      let canContinue = true;
+      if (versionStatus === "deprecated") {
+        severity = "warning";
+      } else if (versionStatus === "unsupported") {
+        severity = "error";
+        canContinue = false;
+      } else if (versionStatus === "outdated") {
+        severity = "info";
+      }
+      const warning = {
+        severity,
+        message: versionMessage || `Widget version ${VERSION} is ${versionStatus}`,
+        currentVersion: VERSION,
+        minVersion: minVersion || void 0,
+        latestVersion: latestVersion || void 0,
+        canContinue,
+        upgradeUrl: "https://docs.pocketping.io/widget/installation"
+      };
+      this.handleVersionWarning(warning);
+    }
     // ─────────────────────────────────────────────────────────────────
     // Storage
     // ─────────────────────────────────────────────────────────────────
@@ -1408,6 +1612,20 @@ var PocketPing = (() => {
     storeSessionId(sessionId) {
       localStorage.setItem("pocketping_session_id", sessionId);
     }
+    getStoredIdentity() {
+      try {
+        const stored = localStorage.getItem("pocketping_user_identity");
+        return stored ? JSON.parse(stored) : null;
+      } catch {
+        return null;
+      }
+    }
+    storeIdentity(identity) {
+      localStorage.setItem("pocketping_user_identity", JSON.stringify(identity));
+    }
+    clearIdentity() {
+      localStorage.removeItem("pocketping_user_identity");
+    }
     generateId() {
       return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
     }
@@ -1460,6 +1678,48 @@ var PocketPing = (() => {
     }
     return client.sendMessage(content);
   }
+  function trigger(eventName, data) {
+    if (!client) {
+      console.warn("[PocketPing] Not initialized, cannot trigger event");
+      return;
+    }
+    client.trigger(eventName, data);
+  }
+  function onEvent(eventName, handler) {
+    if (!client) {
+      console.warn("[PocketPing] Not initialized, cannot subscribe to event");
+      return () => {
+      };
+    }
+    return client.onEvent(eventName, handler);
+  }
+  function offEvent(eventName, handler) {
+    client?.offEvent(eventName, handler);
+  }
+  async function identify(identity) {
+    if (!client) {
+      throw new Error("[PocketPing] Not initialized");
+    }
+    return client.identify(identity);
+  }
+  async function reset(options) {
+    if (!client) {
+      console.warn("[PocketPing] Not initialized");
+      return;
+    }
+    return client.reset(options);
+  }
+  function getIdentity() {
+    return client?.getIdentity() || null;
+  }
+  function on(eventName, handler) {
+    if (!client) {
+      console.warn("[PocketPing] Not initialized, cannot subscribe to event");
+      return () => {
+      };
+    }
+    return client.on(eventName, handler);
+  }
   if (typeof document !== "undefined") {
     const script = document.currentScript;
     if (script?.dataset.endpoint) {
@@ -1470,6 +1730,6 @@ var PocketPing = (() => {
       });
     }
   }
-  var index_default = { init, destroy, open, close, toggle, sendMessage };
+  var index_default = { init, destroy, open, close, toggle, sendMessage, trigger, onEvent, offEvent, on, identify, reset, getIdentity };
   return __toCommonJS(index_exports);
 })();