@pocketping/sdk-node 0.1.0 → 1.0.0

package/dist/index.js

@@ -1,32 +1,6 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  MemoryStorage: () => MemoryStorage,
-  PocketPing: () => PocketPing
-});
-module.exports = __toCommonJS(index_exports);
-
 // src/pocketping.ts
-var import_ws = require("ws");
+import { createHmac } from "crypto";
+import { WebSocketServer, WebSocket } from "ws";
 
 // src/storage/memory.ts
 var MemoryStorage = class {
@@ -131,11 +105,27 @@ function parseUserAgent(userAgent) {
   else if (ua.includes("iphone") || ua.includes("ipad")) os = "iOS";
   return { deviceType, browser, os };
 }
+function parseVersion(version) {
+  return version.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+}
+function compareVersions(a, b) {
+  const vA = parseVersion(a);
+  const vB = parseVersion(b);
+  const len = Math.max(vA.length, vB.length);
+  for (let i = 0; i < len; i++) {
+    const numA = vA[i] ?? 0;
+    const numB = vB[i] ?? 0;
+    if (numA < numB) return -1;
+    if (numA > numB) return 1;
+  }
+  return 0;
+}
 var PocketPing = class {
   constructor(config = {}) {
     this.wss = null;
     this.sessionSockets = /* @__PURE__ */ new Map();
     this.operatorOnline = false;
+    this.eventHandlers = /* @__PURE__ */ new Map();
     this.config = config;
     this.storage = this.initStorage(config.storage);
     this.bridges = config.bridges ?? [];
@@ -155,16 +145,32 @@ var PocketPing = class {
       const path = url.pathname.replace(/^\/+/, "").replace(/\/+$/, "");
       res.setHeader("Access-Control-Allow-Origin", "*");
       res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, X-PocketPing-Version");
+      res.setHeader("Access-Control-Expose-Headers", "X-PocketPing-Version-Status, X-PocketPing-Min-Version, X-PocketPing-Latest-Version, X-PocketPing-Version-Message");
       if (req.method === "OPTIONS") {
         res.statusCode = 204;
         res.end();
         return;
       }
+      const widgetVersion = req.headers["x-pocketping-version"];
+      const versionCheck = this.checkWidgetVersion(widgetVersion);
+      this.setVersionHeaders(res, versionCheck);
+      if (!versionCheck.canContinue) {
+        res.statusCode = 426;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({
+          error: "Widget version unsupported",
+          message: versionCheck.message,
+          minVersion: versionCheck.minVersion,
+          upgradeUrl: this.config.versionUpgradeUrl || "https://docs.pocketping.io/widget/installation"
+        }));
+        return;
+      }
       try {
         const body = await this.parseBody(req);
         const query = Object.fromEntries(url.searchParams);
         let result;
+        let sessionId;
         switch (path) {
           case "connect": {
             const connectReq = body;
@@ -183,7 +189,9 @@ var PocketPing = class {
                 ...uaInfo
               };
             }
-            result = await this.handleConnect(connectReq);
+            const connectResult = await this.handleConnect(connectReq);
+            sessionId = connectResult.sessionId;
+            result = connectResult;
             break;
           }
           case "message":
@@ -201,6 +209,9 @@ var PocketPing = class {
           case "read":
             result = await this.handleRead(body);
             break;
+          case "identify":
+            result = await this.handleIdentify(body);
+            break;
           default:
             if (next) {
               next();
@@ -213,6 +224,11 @@ var PocketPing = class {
         res.setHeader("Content-Type", "application/json");
         res.statusCode = 200;
         res.end(JSON.stringify(result));
+        if (sessionId && versionCheck.status !== "ok") {
+          setTimeout(() => {
+            this.sendVersionWarning(sessionId, versionCheck);
+          }, 500);
+        }
       } catch (error) {
         console.error("[PocketPing] Error:", error);
         res.statusCode = 500;
@@ -240,7 +256,7 @@ var PocketPing = class {
   // ─────────────────────────────────────────────────────────────────
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   attachWebSocket(server) {
-    this.wss = new import_ws.WebSocketServer({
+    this.wss = new WebSocketServer({
       server,
       path: "/pocketping/stream"
     });
@@ -276,14 +292,49 @@ var PocketPing = class {
           data: event.data
         });
         break;
+      case "event":
+        const customEvent = event.data;
+        customEvent.sessionId = sessionId;
+        await this.handleCustomEvent(sessionId, customEvent);
+        break;
+    }
+  }
+  async handleCustomEvent(sessionId, event) {
+    const session = await this.storage.getSession(sessionId);
+    if (!session) {
+      console.warn(`[PocketPing] Event received for unknown session: ${sessionId}`);
+      return;
+    }
+    const handlers = this.eventHandlers.get(event.name);
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          await handler(event, session);
+        } catch (err) {
+          console.error(`[PocketPing] Event handler error for '${event.name}':`, err);
+        }
+      }
+    }
+    const wildcardHandlers = this.eventHandlers.get("*");
+    if (wildcardHandlers) {
+      for (const handler of wildcardHandlers) {
+        try {
+          await handler(event, session);
+        } catch (err) {
+          console.error(`[PocketPing] Wildcard event handler error:`, err);
+        }
+      }
     }
+    await this.config.onEvent?.(event, session);
+    await this.notifyBridgesEvent(event, session);
+    this.forwardToWebhook(event, session);
   }
   broadcastToSession(sessionId, event) {
     const sockets = this.sessionSockets.get(sessionId);
     if (!sockets) return;
     const message = JSON.stringify(event);
     for (const ws of sockets) {
-      if (ws.readyState === import_ws.WebSocket.OPEN) {
+      if (ws.readyState === WebSocket.OPEN) {
         ws.send(message);
       }
     }
@@ -307,20 +358,31 @@ var PocketPing = class {
         lastActivity: /* @__PURE__ */ new Date(),
         operatorOnline: this.operatorOnline,
         aiActive: false,
-        metadata: request.metadata
+        metadata: request.metadata,
+        identity: request.identity
       };
       await this.storage.createSession(session);
       await this.notifyBridges("new_session", session);
       await this.config.onNewSession?.(session);
-    } else if (request.metadata) {
-      if (session.metadata) {
-        request.metadata.ip = session.metadata.ip ?? request.metadata.ip;
-        request.metadata.country = session.metadata.country ?? request.metadata.country;
-        request.metadata.city = session.metadata.city ?? request.metadata.city;
+    } else {
+      let needsUpdate = false;
+      if (request.metadata) {
+        if (session.metadata) {
+          request.metadata.ip = session.metadata.ip ?? request.metadata.ip;
+          request.metadata.country = session.metadata.country ?? request.metadata.country;
+          request.metadata.city = session.metadata.city ?? request.metadata.city;
+        }
+        session.metadata = request.metadata;
+        needsUpdate = true;
+      }
+      if (request.identity) {
+        session.identity = request.identity;
+        needsUpdate = true;
+      }
+      if (needsUpdate) {
+        session.lastActivity = /* @__PURE__ */ new Date();
+        await this.storage.updateSession(session);
       }
-      session.metadata = request.metadata;
-      session.lastActivity = /* @__PURE__ */ new Date();
-      await this.storage.updateSession(session);
     }
     const messages = await this.storage.getMessages(session.id);
     return {
@@ -417,10 +479,39 @@ var PocketPing = class {
         readAt: status === "read" ? now.toISOString() : void 0
       }
     });
-    await this.notifyBridgesRead(request.sessionId, request.messageIds, status);
+    await this.notifyBridgesRead(request.sessionId, request.messageIds, status, session);
     return { updated };
   }
   // ─────────────────────────────────────────────────────────────────
+  // User Identity
+  // ─────────────────────────────────────────────────────────────────
+  /**
+   * Handle user identification from widget
+   * Called when visitor calls PocketPing.identify()
+   */
+  async handleIdentify(request) {
+    if (!request.identity?.id) {
+      throw new Error("identity.id is required");
+    }
+    const session = await this.storage.getSession(request.sessionId);
+    if (!session) {
+      throw new Error("Session not found");
+    }
+    session.identity = request.identity;
+    session.lastActivity = /* @__PURE__ */ new Date();
+    await this.storage.updateSession(session);
+    await this.notifyBridgesIdentity(session);
+    await this.config.onIdentify?.(session);
+    this.forwardIdentityToWebhook(session);
+    return { ok: true };
+  }
+  /**
+   * Get a session by ID
+   */
+  async getSession(sessionId) {
+    return this.storage.getSession(sessionId);
+  }
+  // ─────────────────────────────────────────────────────────────────
   // Operator Actions (for bridges)
   // ─────────────────────────────────────────────────────────────────
   async sendOperatorMessage(sessionId, content) {
@@ -448,6 +539,113 @@ var PocketPing = class {
     }
   }
   // ─────────────────────────────────────────────────────────────────
+  // Custom Events (bidirectional)
+  // ─────────────────────────────────────────────────────────────────
+  /**
+   * 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, handler) {
+    if (!this.eventHandlers.has(eventName)) {
+      this.eventHandlers.set(eventName, /* @__PURE__ */ new Set());
+    }
+    this.eventHandlers.get(eventName).add(handler);
+    return () => {
+      this.eventHandlers.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.eventHandlers.get(eventName)?.delete(handler);
+  }
+  /**
+   * 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, eventName, data) {
+    const event = {
+      name: eventName,
+      data,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      sessionId
+    };
+    this.broadcastToSession(sessionId, {
+      type: "event",
+      data: event
+    });
+  }
+  /**
+   * 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, data) {
+    const event = {
+      name: eventName,
+      data,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    for (const sessionId of this.sessionSockets.keys()) {
+      event.sessionId = sessionId;
+      this.broadcastToSession(sessionId, {
+        type: "event",
+        data: event
+      });
+    }
+  }
+  /**
+   * 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
+   * })
+   */
+  async triggerEvent(sessionId, eventName, data) {
+    const event = {
+      name: eventName,
+      data,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      sessionId
+    };
+    await this.handleCustomEvent(sessionId, event);
+  }
+  // ─────────────────────────────────────────────────────────────────
   // Bridges
   // ─────────────────────────────────────────────────────────────────
   async notifyBridges(event, ...args) {
@@ -458,7 +656,7 @@ var PocketPing = class {
             await bridge.onNewSession?.(args[0]);
             break;
           case "message":
-            await bridge.onMessage?.(args[0], args[1]);
+            await bridge.onVisitorMessage?.(args[0], args[1]);
             break;
         }
       } catch (err) {
@@ -466,15 +664,95 @@ var PocketPing = class {
       }
     }
   }
-  async notifyBridgesRead(sessionId, messageIds, status) {
+  async notifyBridgesRead(sessionId, messageIds, status, session) {
     for (const bridge of this.bridges) {
       try {
-        await bridge.onMessageRead?.(sessionId, messageIds, status);
+        await bridge.onMessageRead?.(sessionId, messageIds, status, session);
       } catch (err) {
         console.error(`[PocketPing] Bridge ${bridge.name} read notification error:`, err);
       }
     }
   }
+  async notifyBridgesEvent(event, session) {
+    for (const bridge of this.bridges) {
+      try {
+        await bridge.onCustomEvent?.(event, session);
+      } catch (err) {
+        console.error(`[PocketPing] Bridge ${bridge.name} event notification error:`, err);
+      }
+    }
+  }
+  async notifyBridgesIdentity(session) {
+    for (const bridge of this.bridges) {
+      try {
+        await bridge.onIdentityUpdate?.(session);
+      } catch (err) {
+        console.error(`[PocketPing] Bridge ${bridge.name} identity notification error:`, err);
+      }
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────
+  // Webhook Forwarding
+  // ─────────────────────────────────────────────────────────────────
+  /**
+   * Forward custom event to configured webhook URL (non-blocking)
+   * Used for integrations with Zapier, Make, n8n, or custom backends
+   */
+  forwardToWebhook(event, session) {
+    if (!this.config.webhookUrl) return;
+    const payload = {
+      event,
+      session: {
+        id: session.id,
+        visitorId: session.visitorId,
+        metadata: session.metadata,
+        identity: session.identity
+      },
+      sentAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const body = JSON.stringify(payload);
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.config.webhookSecret) {
+      const signature = createHmac("sha256", this.config.webhookSecret).update(body).digest("hex");
+      headers["X-PocketPing-Signature"] = `sha256=${signature}`;
+    }
+    const timeout = this.config.webhookTimeout ?? 5e3;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    fetch(this.config.webhookUrl, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal
+    }).then((response) => {
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        console.error(`[PocketPing] Webhook returned ${response.status}: ${response.statusText}`);
+      }
+    }).catch((err) => {
+      clearTimeout(timeoutId);
+      if (err.name === "AbortError") {
+        console.error(`[PocketPing] Webhook timed out after ${timeout}ms`);
+      } else {
+        console.error(`[PocketPing] Webhook error:`, err.message);
+      }
+    });
+  }
+  /**
+   * Forward identity update to webhook as a special event
+   */
+  forwardIdentityToWebhook(session) {
+    if (!this.config.webhookUrl || !session.identity) return;
+    const event = {
+      name: "identify",
+      data: session.identity,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      sessionId: session.id
+    };
+    this.forwardToWebhook(event, session);
+  }
   addBridge(bridge) {
     this.bridges.push(bridge);
     bridge.init?.(this);
@@ -488,9 +766,91 @@ var PocketPing = class {
   getStorage() {
     return this.storage;
   }
+  // ─────────────────────────────────────────────────────────────────
+  // Version Management
+  // ─────────────────────────────────────────────────────────────────
+  /**
+   * 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) {
+    if (!widgetVersion) {
+      return {
+        status: "ok",
+        canContinue: true
+      };
+    }
+    const { minWidgetVersion, latestWidgetVersion } = this.config;
+    if (!minWidgetVersion && !latestWidgetVersion) {
+      return {
+        status: "ok",
+        canContinue: true
+      };
+    }
+    let status = "ok";
+    let message;
+    let canContinue = true;
+    if (minWidgetVersion && compareVersions(widgetVersion, minWidgetVersion) < 0) {
+      status = "unsupported";
+      message = this.config.versionWarningMessage || `Widget version ${widgetVersion} is no longer supported. Minimum version: ${minWidgetVersion}`;
+      canContinue = false;
+    } else if (latestWidgetVersion && compareVersions(widgetVersion, latestWidgetVersion) < 0) {
+      const majorDiff = parseVersion(latestWidgetVersion)[0] - parseVersion(widgetVersion)[0];
+      if (majorDiff >= 1) {
+        status = "deprecated";
+        message = this.config.versionWarningMessage || `Widget version ${widgetVersion} is deprecated. Please update to ${latestWidgetVersion}`;
+      } else {
+        status = "outdated";
+        message = `A newer widget version ${latestWidgetVersion} is available`;
+      }
+    }
+    return {
+      status,
+      message,
+      minVersion: minWidgetVersion,
+      latestVersion: latestWidgetVersion,
+      canContinue
+    };
+  }
+  /**
+   * Set version warning headers on HTTP response
+   */
+  setVersionHeaders(res, versionCheck) {
+    if (versionCheck.status !== "ok") {
+      res.setHeader("X-PocketPing-Version-Status", versionCheck.status);
+      if (versionCheck.minVersion) {
+        res.setHeader("X-PocketPing-Min-Version", versionCheck.minVersion);
+      }
+      if (versionCheck.latestVersion) {
+        res.setHeader("X-PocketPing-Latest-Version", versionCheck.latestVersion);
+      }
+      if (versionCheck.message) {
+        res.setHeader("X-PocketPing-Version-Message", versionCheck.message);
+      }
+    }
+  }
+  /**
+   * Send version warning via WebSocket to a session
+   */
+  sendVersionWarning(sessionId, versionCheck) {
+    if (versionCheck.status === "ok") return;
+    this.broadcastToSession(sessionId, {
+      type: "version_warning",
+      data: {
+        severity: versionCheck.status === "unsupported" ? "error" : versionCheck.status === "deprecated" ? "warning" : "info",
+        message: versionCheck.message,
+        currentVersion: "unknown",
+        // Will be filled by widget
+        minVersion: versionCheck.minVersion,
+        latestVersion: versionCheck.latestVersion,
+        canContinue: versionCheck.canContinue,
+        upgradeUrl: this.config.versionUpgradeUrl || "https://docs.pocketping.io/widget/installation"
+      }
+    });
+  }
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
+export {
   MemoryStorage,
   PocketPing
-});
+};

package/package.json

@@ -1,17 +1,28 @@
 {
   "name": "@pocketping/sdk-node",
-  "version": "0.1.0",
+  "version": "1.0.0",
+  "type": "module",
   "description": "Node.js SDK for implementing PocketPing protocol",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
   "files": [
     "dist"
   ],
   "scripts": {
+    "clean": "rm -rf dist && find src -name '*.js' -o -name '*.js.map' -o -name '*.d.ts' -o -name '*.d.ts.map' | xargs rm -f 2>/dev/null || true",
+    "prebuild": "pnpm clean",
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "test": "vitest"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "ws": "^8.16.0"
@@ -20,7 +31,7 @@
     "@types/ws": "^8.5.10",
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
-    "vitest": "^1.2.0"
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "express": "^4.18.0 || ^5.0.0"
@@ -43,5 +54,22 @@
     "type": "git",
     "url": "https://github.com/Ruwad-io/pocketping.git",
     "directory": "packages/sdk-node"
+  },
+  "release": {
+    "extends": "semantic-release-monorepo",
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/exec",
+        {
+          "prepareCmd": "npm pkg set version=${nextRelease.version}"
+        }
+      ],
+      "@semantic-release/github"
+    ]
   }
 }