@pocketping/sdk-node 0.1.0 → 1.0.0

package/dist/index.cjs

@@ -0,0 +1,884 @@
+"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_crypto = require("crypto");
+var import_ws = require("ws");
+
+// src/storage/memory.ts
+var MemoryStorage = class {
+  constructor() {
+    this.sessions = /* @__PURE__ */ new Map();
+    this.messages = /* @__PURE__ */ new Map();
+    this.messageById = /* @__PURE__ */ new Map();
+  }
+  async createSession(session) {
+    this.sessions.set(session.id, session);
+    this.messages.set(session.id, []);
+  }
+  async getSession(sessionId) {
+    return this.sessions.get(sessionId) ?? null;
+  }
+  async getSessionByVisitorId(visitorId) {
+    const visitorSessions = Array.from(this.sessions.values()).filter(
+      (s) => s.visitorId === visitorId
+    );
+    if (visitorSessions.length === 0) return null;
+    return visitorSessions.reduce(
+      (latest, s) => s.lastActivity > latest.lastActivity ? s : latest
+    );
+  }
+  async updateSession(session) {
+    this.sessions.set(session.id, session);
+  }
+  async deleteSession(sessionId) {
+    this.sessions.delete(sessionId);
+    this.messages.delete(sessionId);
+  }
+  async saveMessage(message) {
+    const sessionMessages = this.messages.get(message.sessionId) ?? [];
+    sessionMessages.push(message);
+    this.messages.set(message.sessionId, sessionMessages);
+    this.messageById.set(message.id, message);
+  }
+  async getMessages(sessionId, after, limit = 50) {
+    const sessionMessages = this.messages.get(sessionId) ?? [];
+    let startIndex = 0;
+    if (after) {
+      const afterIndex = sessionMessages.findIndex((m) => m.id === after);
+      if (afterIndex !== -1) {
+        startIndex = afterIndex + 1;
+      }
+    }
+    return sessionMessages.slice(startIndex, startIndex + limit);
+  }
+  async getMessage(messageId) {
+    return this.messageById.get(messageId) ?? null;
+  }
+  async cleanupOldSessions(olderThan) {
+    let count = 0;
+    for (const [id, session] of this.sessions) {
+      if (session.lastActivity < olderThan) {
+        this.sessions.delete(id);
+        this.messages.delete(id);
+        count++;
+      }
+    }
+    return count;
+  }
+};
+
+// src/pocketping.ts
+function getClientIp(req) {
+  const forwarded = req.headers["x-forwarded-for"];
+  if (forwarded) {
+    const ip = Array.isArray(forwarded) ? forwarded[0] : forwarded.split(",")[0];
+    return ip?.trim() ?? "unknown";
+  }
+  const realIp = req.headers["x-real-ip"];
+  if (realIp) {
+    return Array.isArray(realIp) ? realIp[0] ?? "unknown" : realIp;
+  }
+  return req.socket?.remoteAddress ?? "unknown";
+}
+function parseUserAgent(userAgent) {
+  if (!userAgent) {
+    return { deviceType: void 0, browser: void 0, os: void 0 };
+  }
+  const ua = userAgent.toLowerCase();
+  let deviceType;
+  if (["mobile", "android", "iphone", "ipod"].some((x) => ua.includes(x))) {
+    deviceType = "mobile";
+  } else if (["ipad", "tablet"].some((x) => ua.includes(x))) {
+    deviceType = "tablet";
+  } else {
+    deviceType = "desktop";
+  }
+  let browser;
+  if (ua.includes("firefox")) browser = "Firefox";
+  else if (ua.includes("edg")) browser = "Edge";
+  else if (ua.includes("chrome")) browser = "Chrome";
+  else if (ua.includes("safari")) browser = "Safari";
+  else if (ua.includes("opera") || ua.includes("opr")) browser = "Opera";
+  let os;
+  if (ua.includes("windows")) os = "Windows";
+  else if (ua.includes("mac os") || ua.includes("macos")) os = "macOS";
+  else if (ua.includes("linux")) os = "Linux";
+  else if (ua.includes("android")) os = "Android";
+  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 ?? [];
+  }
+  initStorage(storage) {
+    if (!storage || storage === "memory") {
+      return new MemoryStorage();
+    }
+    return storage;
+  }
+  // ─────────────────────────────────────────────────────────────────
+  // Express/Connect Middleware
+  // ─────────────────────────────────────────────────────────────────
+  middleware() {
+    return async (req, res, next) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+      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, 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;
+            const clientIp = getClientIp(req);
+            const userAgent = req.headers["user-agent"];
+            const uaInfo = parseUserAgent(connectReq.metadata?.userAgent ?? userAgent);
+            if (connectReq.metadata) {
+              connectReq.metadata.ip = clientIp;
+              connectReq.metadata.deviceType = connectReq.metadata.deviceType ?? uaInfo.deviceType;
+              connectReq.metadata.browser = connectReq.metadata.browser ?? uaInfo.browser;
+              connectReq.metadata.os = connectReq.metadata.os ?? uaInfo.os;
+            } else {
+              connectReq.metadata = {
+                ip: clientIp,
+                userAgent,
+                ...uaInfo
+              };
+            }
+            const connectResult = await this.handleConnect(connectReq);
+            sessionId = connectResult.sessionId;
+            result = connectResult;
+            break;
+          }
+          case "message":
+            result = await this.handleMessage(body);
+            break;
+          case "messages":
+            result = await this.handleGetMessages(query);
+            break;
+          case "typing":
+            result = await this.handleTyping(body);
+            break;
+          case "presence":
+            result = await this.handlePresence();
+            break;
+          case "read":
+            result = await this.handleRead(body);
+            break;
+          case "identify":
+            result = await this.handleIdentify(body);
+            break;
+          default:
+            if (next) {
+              next();
+              return;
+            }
+            res.statusCode = 404;
+            res.end(JSON.stringify({ error: "Not found" }));
+            return;
+        }
+        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;
+        res.end(JSON.stringify({ error: "Internal server error" }));
+      }
+    };
+  }
+  async parseBody(req) {
+    if (req.body) return req.body;
+    return new Promise((resolve, reject) => {
+      let data = "";
+      req.on("data", (chunk) => data += chunk);
+      req.on("end", () => {
+        try {
+          resolve(data ? JSON.parse(data) : {});
+        } catch {
+          reject(new Error("Invalid JSON"));
+        }
+      });
+      req.on("error", reject);
+    });
+  }
+  // ─────────────────────────────────────────────────────────────────
+  // WebSocket
+  // ─────────────────────────────────────────────────────────────────
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  attachWebSocket(server) {
+    this.wss = new import_ws.WebSocketServer({
+      server,
+      path: "/pocketping/stream"
+    });
+    this.wss.on("connection", (ws, req) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+      const sessionId = url.searchParams.get("sessionId");
+      if (!sessionId) {
+        ws.close(4e3, "sessionId required");
+        return;
+      }
+      if (!this.sessionSockets.has(sessionId)) {
+        this.sessionSockets.set(sessionId, /* @__PURE__ */ new Set());
+      }
+      this.sessionSockets.get(sessionId).add(ws);
+      ws.on("close", () => {
+        this.sessionSockets.get(sessionId)?.delete(ws);
+      });
+      ws.on("message", async (data) => {
+        try {
+          const event = JSON.parse(data.toString());
+          await this.handleWebSocketMessage(sessionId, event);
+        } catch (err) {
+          console.error("[PocketPing] WS message error:", err);
+        }
+      });
+    });
+  }
+  async handleWebSocketMessage(sessionId, event) {
+    switch (event.type) {
+      case "typing":
+        this.broadcastToSession(sessionId, {
+          type: "typing",
+          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) {
+        ws.send(message);
+      }
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────
+  // Protocol Handlers
+  // ─────────────────────────────────────────────────────────────────
+  async handleConnect(request) {
+    let session = null;
+    if (request.sessionId) {
+      session = await this.storage.getSession(request.sessionId);
+    }
+    if (!session && this.storage.getSessionByVisitorId) {
+      session = await this.storage.getSessionByVisitorId(request.visitorId);
+    }
+    if (!session) {
+      session = {
+        id: this.generateId(),
+        visitorId: request.visitorId,
+        createdAt: /* @__PURE__ */ new Date(),
+        lastActivity: /* @__PURE__ */ new Date(),
+        operatorOnline: this.operatorOnline,
+        aiActive: false,
+        metadata: request.metadata,
+        identity: request.identity
+      };
+      await this.storage.createSession(session);
+      await this.notifyBridges("new_session", session);
+      await this.config.onNewSession?.(session);
+    } 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);
+      }
+    }
+    const messages = await this.storage.getMessages(session.id);
+    return {
+      sessionId: session.id,
+      visitorId: session.visitorId,
+      operatorOnline: this.operatorOnline,
+      welcomeMessage: this.config.welcomeMessage,
+      messages
+    };
+  }
+  async handleMessage(request) {
+    const session = await this.storage.getSession(request.sessionId);
+    if (!session) {
+      throw new Error("Session not found");
+    }
+    const message = {
+      id: this.generateId(),
+      sessionId: request.sessionId,
+      content: request.content,
+      sender: request.sender,
+      timestamp: /* @__PURE__ */ new Date(),
+      replyTo: request.replyTo
+    };
+    await this.storage.saveMessage(message);
+    session.lastActivity = /* @__PURE__ */ new Date();
+    await this.storage.updateSession(session);
+    if (request.sender === "visitor") {
+      await this.notifyBridges("message", message, session);
+    }
+    this.broadcastToSession(request.sessionId, {
+      type: "message",
+      data: message
+    });
+    await this.config.onMessage?.(message, session);
+    return {
+      messageId: message.id,
+      timestamp: message.timestamp.toISOString()
+    };
+  }
+  async handleGetMessages(request) {
+    const limit = Math.min(request.limit ?? 50, 100);
+    const messages = await this.storage.getMessages(request.sessionId, request.after, limit + 1);
+    return {
+      messages: messages.slice(0, limit),
+      hasMore: messages.length > limit
+    };
+  }
+  async handleTyping(request) {
+    this.broadcastToSession(request.sessionId, {
+      type: "typing",
+      data: {
+        sessionId: request.sessionId,
+        sender: request.sender,
+        isTyping: request.isTyping ?? true
+      }
+    });
+    return { ok: true };
+  }
+  async handlePresence() {
+    return {
+      online: this.operatorOnline,
+      aiEnabled: !!this.config.ai,
+      aiActiveAfter: this.config.aiTakeoverDelay ?? 300
+    };
+  }
+  async handleRead(request) {
+    const session = await this.storage.getSession(request.sessionId);
+    if (!session) {
+      throw new Error("Session not found");
+    }
+    const status = request.status ?? "read";
+    const now = /* @__PURE__ */ new Date();
+    let updated = 0;
+    const messages = await this.storage.getMessages(request.sessionId);
+    for (const msg of messages) {
+      if (request.messageIds.includes(msg.id)) {
+        msg.status = status;
+        if (status === "delivered") {
+          msg.deliveredAt = now;
+        } else if (status === "read") {
+          msg.deliveredAt = msg.deliveredAt ?? now;
+          msg.readAt = now;
+        }
+        await this.storage.saveMessage(msg);
+        updated++;
+      }
+    }
+    this.broadcastToSession(request.sessionId, {
+      type: "read",
+      data: {
+        messageIds: request.messageIds,
+        status,
+        deliveredAt: status === "delivered" ? now.toISOString() : void 0,
+        readAt: status === "read" ? now.toISOString() : void 0
+      }
+    });
+    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) {
+    const response = await this.handleMessage({
+      sessionId,
+      content,
+      sender: "operator"
+    });
+    const message = {
+      id: response.messageId,
+      sessionId,
+      content,
+      sender: "operator",
+      timestamp: new Date(response.timestamp)
+    };
+    return message;
+  }
+  setOperatorOnline(online) {
+    this.operatorOnline = online;
+    for (const sessionId of this.sessionSockets.keys()) {
+      this.broadcastToSession(sessionId, {
+        type: "presence",
+        data: { online }
+      });
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────
+  // 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) {
+    for (const bridge of this.bridges) {
+      try {
+        switch (event) {
+          case "new_session":
+            await bridge.onNewSession?.(args[0]);
+            break;
+          case "message":
+            await bridge.onVisitorMessage?.(args[0], args[1]);
+            break;
+        }
+      } catch (err) {
+        console.error(`[PocketPing] Bridge ${bridge.name} error:`, err);
+      }
+    }
+  }
+  async notifyBridgesRead(sessionId, messageIds, status, session) {
+    for (const bridge of this.bridges) {
+      try {
+        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 = (0, import_crypto.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);
+  }
+  // ─────────────────────────────────────────────────────────────────
+  // Utilities
+  // ─────────────────────────────────────────────────────────────────
+  generateId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+  }
+  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 = {
+  MemoryStorage,
+  PocketPing
+});