@pocketping/sdk-node 0.2.0 → 1.1.0

package/README.md

@@ -0,0 +1,376 @@
+# PocketPing Node.js SDK
+
+Node.js SDK for PocketPing - real-time customer chat with mobile notifications.
+
+## Installation
+
+```bash
+npm install @pocketping/sdk-node
+
+# Or with pnpm
+pnpm add @pocketping/sdk-node
+
+# Or with yarn
+yarn add @pocketping/sdk-node
+```
+
+## Quick Start with Express
+
+```typescript
+import express from 'express';
+import { createServer } from 'http';
+import { PocketPing } from '@pocketping/sdk-node';
+
+const app = express();
+const server = createServer(app);
+
+app.use(express.json());
+
+// Initialize PocketPing
+const pp = new PocketPing({
+  welcomeMessage: 'Hi! How can we help you today?',
+  onNewSession: (session) => {
+    console.log(`New session: ${session.id}`);
+  },
+  onMessage: (message, session) => {
+    console.log(`Message from ${message.sender}: ${message.content}`);
+  },
+});
+
+// Mount PocketPing routes
+app.use('/pocketping', pp.middleware());
+
+// Attach WebSocket for real-time communication
+pp.attachWebSocket(server);
+
+server.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+## Configuration Options
+
+```typescript
+const pp = new PocketPing({
+  // Welcome message shown to new visitors
+  welcomeMessage: 'Hi! How can we help you?',
+
+  // Callbacks
+  onNewSession: (session) => { /* ... */ },
+  onMessage: (message, session) => { /* ... */ },
+  onEvent: (event, session) => { /* ... */ },
+
+  // Custom storage (default: in-memory)
+  storage: new MemoryStorage(),
+
+  // Bridge server for notifications (Telegram, Discord, Slack)
+  bridgeServerUrl: 'http://localhost:3001',
+
+  // Protocol version settings
+  protocolVersion: '1.0',
+  minSupportedVersion: '0.1',
+
+  // IP filtering (see IP Filtering section below)
+  ipFilter: {
+    enabled: true,
+    mode: 'blocklist',
+    blocklist: ['203.0.113.0/24'],
+  },
+});
+```
+
+## IP Filtering
+
+Block or allow specific IP addresses or CIDR ranges:
+
+```typescript
+const pp = new PocketPing({
+  ipFilter: {
+    enabled: true,
+    mode: 'blocklist',  // 'allowlist' | 'blocklist' | 'both'
+    blocklist: [
+      '203.0.113.0/24',   // CIDR range
+      '198.51.100.50',    // Single IP
+    ],
+    allowlist: [
+      '10.0.0.0/8',       // Internal network
+    ],
+    logBlocked: true,     // Log blocked requests (default: true)
+    blockedStatusCode: 403,
+    blockedMessage: 'Forbidden',
+  },
+});
+
+// Or with a custom filter function
+const pp = new PocketPing({
+  ipFilter: {
+    enabled: true,
+    mode: 'blocklist',
+    customFilter: (ip, request) => {
+      // Return true to allow, false to block, null to defer to list-based filtering
+      if (ip.startsWith('192.168.')) return true;  // Always allow local
+      return null;  // Use blocklist/allowlist
+    },
+  },
+});
+```
+
+### Modes
+
+| Mode | Behavior |
+|------|----------|
+| `blocklist` | Block IPs in blocklist, allow all others (default) |
+| `allowlist` | Only allow IPs in allowlist, block all others |
+| `both` | Allowlist takes precedence, then blocklist is applied |
+
+### CIDR Support
+
+The SDK supports CIDR notation for IP ranges:
+- Single IP: `192.168.1.1` (treated as `/32`)
+- Class C: `192.168.1.0/24` (256 addresses)
+- Class B: `172.16.0.0/16` (65,536 addresses)
+- Class A: `10.0.0.0/8` (16M addresses)
+
+### Manual IP Check
+
+```typescript
+// Check IP manually
+const result = pp.checkIpFilter('192.168.1.50');
+// result: { allowed: boolean, reason: string, matchedRule?: string }
+
+// Get client IP from request headers
+const clientIp = pp.getClientIp(request.headers);
+// Checks: CF-Connecting-IP, X-Real-IP, X-Forwarded-For
+```
+
+## Architecture Options
+
+### 1. Embedded Mode (Simple)
+
+SDK handles everything directly - best for single server deployments:
+
+```typescript
+import { PocketPing } from '@pocketping/sdk-node';
+
+const pp = new PocketPing({
+  welcomeMessage: 'Hello!',
+});
+
+app.use('/pocketping', pp.middleware());
+pp.attachWebSocket(server);
+```
+
+### 2. Bridge Server Mode (Recommended)
+
+SDK connects to a dedicated bridge server for notifications:
+
+```typescript
+const pp = new PocketPing({
+  welcomeMessage: 'Hello!',
+  bridgeServerUrl: process.env.BRIDGE_SERVER_URL,
+});
+```
+
+The bridge server handles Telegram, Discord, and Slack integrations, keeping your main server lightweight.
+
+## Custom Storage
+
+Implement the `Storage` interface for persistence:
+
+```typescript
+import { Storage, Session, Message } from '@pocketping/sdk-node';
+
+class PostgresStorage implements Storage {
+  async createSession(session: Session): Promise<void> {
+    // Your implementation
+  }
+
+  async getSession(sessionId: string): Promise<Session | null> {
+    // Your implementation
+  }
+
+  async saveMessage(message: Message): Promise<void> {
+    // Your implementation
+  }
+
+  async getMessages(sessionId: string, options?: { after?: string; limit?: number }): Promise<Message[]> {
+    // Your implementation
+  }
+
+  // ... implement other methods
+}
+
+const pp = new PocketPing({
+  storage: new PostgresStorage(),
+});
+```
+
+## Events / Callbacks
+
+```typescript
+const pp = new PocketPing({
+  onNewSession: (session) => {
+    console.log(`New session: ${session.id}`);
+    // Notify your team, log to analytics, etc.
+  },
+  onMessage: (message, session) => {
+    console.log(`Message from ${message.sender}: ${message.content}`);
+  },
+  onEvent: (event, session) => {
+    console.log(`Custom event: ${event.name}`, event.data);
+  },
+});
+```
+
+## Custom Events
+
+PocketPing supports bidirectional custom events between your website and backend.
+
+### Listening for Events (Widget -> Backend)
+
+```typescript
+// Using callback in config
+const pp = new PocketPing({
+  onEvent: (event, session) => {
+    console.log(`Event ${event.name} from session ${session.id}`);
+    console.log(`Data:`, event.data);
+  },
+});
+
+// Or using subscription
+pp.onEvent('clicked_pricing', (event, session) => {
+  console.log(`User interested in: ${event.data?.plan}`);
+});
+
+// Subscribe to all events
+pp.onEvent('*', (event, session) => {
+  console.log(`Event: ${event.name}`, event.data);
+});
+```
+
+### Sending Events (Backend -> Widget)
+
+```typescript
+// Send to a specific session
+await pp.emitEvent('session-123', 'show_offer', {
+  discount: 20,
+  code: 'SAVE20',
+});
+
+// Broadcast to all connected sessions
+await pp.broadcastEvent('announcement', {
+  message: 'New feature launched!',
+});
+```
+
+## User Identification
+
+Track and identify users across sessions:
+
+```typescript
+// On the frontend (widget)
+PocketPing.identify({
+  userId: 'user_123',
+  email: 'john@example.com',
+  name: 'John Doe',
+  plan: 'pro',
+});
+
+// Get current identity
+const identity = PocketPing.getIdentity();
+
+// Reset identity (e.g., on logout)
+PocketPing.reset();
+```
+
+User identity is automatically included in session metadata and forwarded to bridges.
+
+## Operator Presence
+
+Control operator online status:
+
+```typescript
+// Set operator as online
+pp.setOperatorOnline(true);
+
+// Set operator as offline
+pp.setOperatorOnline(false);
+```
+
+When using the bridge server, presence is managed automatically via Telegram/Discord/Slack commands.
+
+## API Reference
+
+### PocketPing Class
+
+| Method | Description |
+|--------|-------------|
+| `middleware()` | Returns Express middleware for HTTP routes |
+| `attachWebSocket(server)` | Attaches WebSocket handler for real-time communication |
+| `setOperatorOnline(online)` | Sets operator online/offline status |
+| `onEvent(name, callback)` | Subscribe to custom events |
+| `offEvent(name, callback)` | Unsubscribe from custom events |
+| `emitEvent(sessionId, name, data)` | Send event to specific session |
+| `broadcastEvent(name, data)` | Broadcast event to all sessions |
+| `getSession(sessionId)` | Get session by ID |
+| `getMessages(sessionId, options)` | Get messages for a session |
+
+### Types
+
+```typescript
+interface Session {
+  id: string;
+  visitorId: string;
+  metadata: SessionMetadata;
+  createdAt: Date;
+  lastActivity: Date;
+  status: 'active' | 'closed';
+}
+
+interface Message {
+  id: string;
+  sessionId: string;
+  sender: 'visitor' | 'operator' | 'system' | 'ai';
+  content: string;
+  timestamp: Date;
+  metadata?: Record<string, unknown>;
+}
+
+interface CustomEvent {
+  name: string;
+  data?: Record<string, unknown>;
+  timestamp: Date;
+  sessionId?: string;
+}
+```
+
+## Widget Integration
+
+Add the widget to your website:
+
+```html
+<script src="https://unpkg.com/@pocketping/widget"></script>
+<script>
+  PocketPing.init({
+    endpoint: '/pocketping',
+    theme: 'light', // or 'dark'
+    primaryColor: '#667eea',
+  });
+</script>
+```
+
+Or via npm:
+
+```typescript
+import { init } from '@pocketping/widget';
+
+init({
+  endpoint: '/pocketping',
+  theme: 'dark',
+  primaryColor: '#667eea',
+});
+```
+
+## License
+
+MIT

package/dist/{index.mjs → index.cjs}

@@ -1,6 +1,33 @@
+"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
-import { createHmac } from "crypto";
-import { WebSocketServer, WebSocket } from "ws";
+var import_crypto = require("crypto");
+var import_ws = require("ws");
 
 // src/storage/memory.ts
 var MemoryStorage = class {
@@ -65,6 +92,71 @@ var MemoryStorage = class {
   }
 };
 
+// src/utils/ip-filter.ts
+function ipToNumber(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let num = 0;
+  for (const part of parts) {
+    const n = parseInt(part, 10);
+    if (isNaN(n) || n < 0 || n > 255) return null;
+    num = num << 8 | n;
+  }
+  return num >>> 0;
+}
+function parseCidr(cidr) {
+  const [ip, bits] = cidr.split("/");
+  const base = ipToNumber(ip);
+  if (base === null) return null;
+  const prefix = bits ? parseInt(bits, 10) : 32;
+  if (isNaN(prefix) || prefix < 0 || prefix > 32) return null;
+  const mask = prefix === 0 ? 0 : ~0 << 32 - prefix >>> 0;
+  return { base: (base & mask) >>> 0, mask };
+}
+function ipMatchesCidr(ip, cidr) {
+  const ipNum = ipToNumber(ip);
+  if (ipNum === null) return false;
+  const parsed = parseCidr(cidr);
+  if (!parsed) return false;
+  return (ipNum & parsed.mask) >>> 0 === parsed.base;
+}
+function ipMatchesAny(ip, list) {
+  return list.some((entry) => ipMatchesCidr(ip, entry));
+}
+function shouldAllowIp(ip, config) {
+  const { mode = "blocklist", allowlist = [], blocklist = [] } = config;
+  switch (mode) {
+    case "allowlist":
+      if (ipMatchesAny(ip, allowlist)) {
+        return { allowed: true, reason: "allowlist" };
+      }
+      return { allowed: false, reason: "not_in_allowlist" };
+    case "blocklist":
+      if (ipMatchesAny(ip, blocklist)) {
+        return { allowed: false, reason: "blocklist" };
+      }
+      return { allowed: true, reason: "default" };
+    case "both":
+      if (ipMatchesAny(ip, allowlist)) {
+        return { allowed: true, reason: "allowlist" };
+      }
+      if (ipMatchesAny(ip, blocklist)) {
+        return { allowed: false, reason: "blocklist" };
+      }
+      return { allowed: true, reason: "default" };
+    default:
+      return { allowed: true, reason: "default" };
+  }
+}
+async function checkIpFilter(ip, config, requestInfo) {
+  if (config.customFilter) {
+    const customResult = await config.customFilter(ip, requestInfo);
+    if (customResult === true) return { allowed: true, reason: "custom" };
+    if (customResult === false) return { allowed: false, reason: "custom" };
+  }
+  return shouldAllowIp(ip, config);
+}
+
 // src/pocketping.ts
 function getClientIp(req) {
   const forwarded = req.headers["x-forwarded-for"];
@@ -152,6 +244,34 @@ var PocketPing = class {
         res.end();
         return;
       }
+      if (this.config.ipFilter?.enabled) {
+        const clientIp = getClientIp(req);
+        const filterResult = await checkIpFilter(clientIp, this.config.ipFilter, {
+          path
+        });
+        if (!filterResult.allowed) {
+          if (this.config.ipFilter.logBlocked !== false) {
+            const logEvent = {
+              type: "blocked",
+              ip: clientIp,
+              reason: filterResult.reason,
+              path,
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            if (this.config.ipFilter.logger) {
+              this.config.ipFilter.logger(logEvent);
+            } else {
+              console.log(`[PocketPing] IP blocked: ${clientIp} - reason: ${filterResult.reason}`);
+            }
+          }
+          res.statusCode = this.config.ipFilter.blockedStatusCode ?? 403;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({
+            error: this.config.ipFilter.blockedMessage ?? "Forbidden"
+          }));
+          return;
+        }
+      }
       const widgetVersion = req.headers["x-pocketping-version"];
       const versionCheck = this.checkWidgetVersion(widgetVersion);
       this.setVersionHeaders(res, versionCheck);
@@ -256,11 +376,35 @@ var PocketPing = class {
   // ─────────────────────────────────────────────────────────────────
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   attachWebSocket(server) {
-    this.wss = new WebSocketServer({
+    this.wss = new import_ws.WebSocketServer({
       server,
       path: "/pocketping/stream"
     });
-    this.wss.on("connection", (ws, req) => {
+    this.wss.on("connection", async (ws, req) => {
+      if (this.config.ipFilter?.enabled) {
+        const clientIp = getClientIp(req);
+        const filterResult = await checkIpFilter(clientIp, this.config.ipFilter, {
+          path: "/pocketping/stream"
+        });
+        if (!filterResult.allowed) {
+          if (this.config.ipFilter.logBlocked !== false) {
+            const logEvent = {
+              type: "blocked",
+              ip: clientIp,
+              reason: filterResult.reason,
+              path: "/pocketping/stream",
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            if (this.config.ipFilter.logger) {
+              this.config.ipFilter.logger(logEvent);
+            } else {
+              console.log(`[PocketPing] WS IP blocked: ${clientIp} - reason: ${filterResult.reason}`);
+            }
+          }
+          ws.close(4003, this.config.ipFilter.blockedMessage ?? "Forbidden");
+          return;
+        }
+      }
       const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
       const sessionId = url.searchParams.get("sessionId");
       if (!sessionId) {
@@ -334,7 +478,7 @@ var PocketPing = class {
     if (!sockets) return;
     const message = JSON.stringify(event);
     for (const ws of sockets) {
-      if (ws.readyState === WebSocket.OPEN) {
+      if (ws.readyState === import_ws.WebSocket.OPEN) {
         ws.send(message);
       }
     }
@@ -479,7 +623,7 @@ 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 };
   }
   // ─────────────────────────────────────────────────────────────────
@@ -656,7 +800,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) {
@@ -664,10 +808,10 @@ 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);
       }
@@ -676,7 +820,7 @@ var PocketPing = class {
   async notifyBridgesEvent(event, session) {
     for (const bridge of this.bridges) {
       try {
-        await bridge.onEvent?.(event, session);
+        await bridge.onCustomEvent?.(event, session);
       } catch (err) {
         console.error(`[PocketPing] Bridge ${bridge.name} event notification error:`, err);
       }
@@ -715,7 +859,7 @@ var PocketPing = class {
       "Content-Type": "application/json"
     };
     if (this.config.webhookSecret) {
-      const signature = createHmac("sha256", this.config.webhookSecret).update(body).digest("hex");
+      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;
@@ -850,7 +994,8 @@ var PocketPing = class {
     });
   }
 };
-export {
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
   MemoryStorage,
   PocketPing
-};
+});

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

@@ -28,13 +28,15 @@ interface Bridge {
     /** Called when a new chat session is created */
     onNewSession?(session: Session): void | Promise<void>;
     /** Called when a visitor sends a message */
-    onMessage?(message: Message, session: Session): void | Promise<void>;
+    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): void | Promise<void>;
+    onMessageRead?(sessionId: string, messageIds: string[], status: MessageStatus, session: Session): void | Promise<void>;
     /** Called when a custom event is triggered from the widget */
-    onEvent?(event: CustomEvent, session: Session): void | Promise<void>;
+    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 */
@@ -54,6 +56,52 @@ interface AIProvider {
     isAvailable(): Promise<boolean>;
 }
 
+/**
+ * IP Filtering utilities for PocketPing SDK
+ * Supports CIDR notation and individual IP addresses
+ */
+type IpFilterMode = 'allowlist' | 'blocklist' | 'both';
+interface IpFilterConfig {
+    /** Enable/disable IP filtering (default: false) */
+    enabled?: boolean;
+    /** Filter mode (default: 'blocklist') */
+    mode?: IpFilterMode;
+    /** IPs/CIDRs to allow (e.g., ['192.168.1.0/24', '10.0.0.1']) */
+    allowlist?: string[];
+    /** IPs/CIDRs to block (e.g., ['203.0.113.0/24', '198.51.100.50']) */
+    blocklist?: string[];
+    /** Custom filter callback for advanced logic */
+    customFilter?: IpFilterCallback;
+    /** Log blocked requests for security auditing (default: true) */
+    logBlocked?: boolean;
+    /** Custom logger function */
+    logger?: (event: IpFilterLogEvent) => void;
+    /** HTTP status code for blocked requests (default: 403) */
+    blockedStatusCode?: number;
+    /** Response message for blocked requests (default: 'Forbidden') */
+    blockedMessage?: string;
+    /** Trust proxy headers (X-Forwarded-For, etc.) (default: true) */
+    trustProxy?: boolean;
+    /** Ordered list of headers to check for client IP */
+    proxyHeaders?: string[];
+}
+interface IpFilterLogEvent {
+    type: 'blocked' | 'allowed';
+    ip: string;
+    reason: 'allowlist' | 'blocklist' | 'custom' | 'not_in_allowlist' | 'default';
+    path: string;
+    timestamp: Date;
+    sessionId?: string;
+}
+/**
+ * Custom IP filter callback
+ * Return true to allow, false to block, undefined to defer to list-based filtering
+ */
+type IpFilterCallback = (ip: string, request: {
+    path: string;
+    sessionId?: string;
+}) => boolean | undefined | Promise<boolean | undefined>;
+
 interface PocketPingConfig {
     /** Storage adapter for sessions and messages */
     storage?: Storage | 'memory';
@@ -87,6 +135,8 @@ interface PocketPingConfig {
     versionWarningMessage?: string;
     /** URL to upgrade instructions */
     versionUpgradeUrl?: string;
+    /** IP filtering configuration (allowlist/blocklist) */
+    ipFilter?: IpFilterConfig;
 }
 interface AIConfig {
     provider: AIProvider | 'openai' | 'gemini' | 'anthropic';
@@ -153,12 +203,32 @@ interface ConnectRequest {
     /** 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;
@@ -396,4 +466,4 @@ declare class MemoryStorage implements Storage {
     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 WebhookPayload };
+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 };

package/dist/index.d.ts

@@ -28,13 +28,15 @@ interface Bridge {
     /** Called when a new chat session is created */
     onNewSession?(session: Session): void | Promise<void>;
     /** Called when a visitor sends a message */
-    onMessage?(message: Message, session: Session): void | Promise<void>;
+    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): void | Promise<void>;
+    onMessageRead?(sessionId: string, messageIds: string[], status: MessageStatus, session: Session): void | Promise<void>;
     /** Called when a custom event is triggered from the widget */
-    onEvent?(event: CustomEvent, session: Session): void | Promise<void>;
+    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 */
@@ -54,6 +56,52 @@ interface AIProvider {
     isAvailable(): Promise<boolean>;
 }
 
+/**
+ * IP Filtering utilities for PocketPing SDK
+ * Supports CIDR notation and individual IP addresses
+ */
+type IpFilterMode = 'allowlist' | 'blocklist' | 'both';
+interface IpFilterConfig {
+    /** Enable/disable IP filtering (default: false) */
+    enabled?: boolean;
+    /** Filter mode (default: 'blocklist') */
+    mode?: IpFilterMode;
+    /** IPs/CIDRs to allow (e.g., ['192.168.1.0/24', '10.0.0.1']) */
+    allowlist?: string[];
+    /** IPs/CIDRs to block (e.g., ['203.0.113.0/24', '198.51.100.50']) */
+    blocklist?: string[];
+    /** Custom filter callback for advanced logic */
+    customFilter?: IpFilterCallback;
+    /** Log blocked requests for security auditing (default: true) */
+    logBlocked?: boolean;
+    /** Custom logger function */
+    logger?: (event: IpFilterLogEvent) => void;
+    /** HTTP status code for blocked requests (default: 403) */
+    blockedStatusCode?: number;
+    /** Response message for blocked requests (default: 'Forbidden') */
+    blockedMessage?: string;
+    /** Trust proxy headers (X-Forwarded-For, etc.) (default: true) */
+    trustProxy?: boolean;
+    /** Ordered list of headers to check for client IP */
+    proxyHeaders?: string[];
+}
+interface IpFilterLogEvent {
+    type: 'blocked' | 'allowed';
+    ip: string;
+    reason: 'allowlist' | 'blocklist' | 'custom' | 'not_in_allowlist' | 'default';
+    path: string;
+    timestamp: Date;
+    sessionId?: string;
+}
+/**
+ * Custom IP filter callback
+ * Return true to allow, false to block, undefined to defer to list-based filtering
+ */
+type IpFilterCallback = (ip: string, request: {
+    path: string;
+    sessionId?: string;
+}) => boolean | undefined | Promise<boolean | undefined>;
+
 interface PocketPingConfig {
     /** Storage adapter for sessions and messages */
     storage?: Storage | 'memory';
@@ -87,6 +135,8 @@ interface PocketPingConfig {
     versionWarningMessage?: string;
     /** URL to upgrade instructions */
     versionUpgradeUrl?: string;
+    /** IP filtering configuration (allowlist/blocklist) */
+    ipFilter?: IpFilterConfig;
 }
 interface AIConfig {
     provider: AIProvider | 'openai' | 'gemini' | 'anthropic';
@@ -153,12 +203,32 @@ interface ConnectRequest {
     /** 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;
@@ -396,4 +466,4 @@ declare class MemoryStorage implements Storage {
     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 WebhookPayload };
+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 };

package/dist/index.js

@@ -1,33 +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_crypto = require("crypto");
-var import_ws = require("ws");
+import { createHmac } from "crypto";
+import { WebSocketServer, WebSocket } from "ws";
 
 // src/storage/memory.ts
 var MemoryStorage = class {
@@ -92,6 +65,71 @@ var MemoryStorage = class {
   }
 };
 
+// src/utils/ip-filter.ts
+function ipToNumber(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let num = 0;
+  for (const part of parts) {
+    const n = parseInt(part, 10);
+    if (isNaN(n) || n < 0 || n > 255) return null;
+    num = num << 8 | n;
+  }
+  return num >>> 0;
+}
+function parseCidr(cidr) {
+  const [ip, bits] = cidr.split("/");
+  const base = ipToNumber(ip);
+  if (base === null) return null;
+  const prefix = bits ? parseInt(bits, 10) : 32;
+  if (isNaN(prefix) || prefix < 0 || prefix > 32) return null;
+  const mask = prefix === 0 ? 0 : ~0 << 32 - prefix >>> 0;
+  return { base: (base & mask) >>> 0, mask };
+}
+function ipMatchesCidr(ip, cidr) {
+  const ipNum = ipToNumber(ip);
+  if (ipNum === null) return false;
+  const parsed = parseCidr(cidr);
+  if (!parsed) return false;
+  return (ipNum & parsed.mask) >>> 0 === parsed.base;
+}
+function ipMatchesAny(ip, list) {
+  return list.some((entry) => ipMatchesCidr(ip, entry));
+}
+function shouldAllowIp(ip, config) {
+  const { mode = "blocklist", allowlist = [], blocklist = [] } = config;
+  switch (mode) {
+    case "allowlist":
+      if (ipMatchesAny(ip, allowlist)) {
+        return { allowed: true, reason: "allowlist" };
+      }
+      return { allowed: false, reason: "not_in_allowlist" };
+    case "blocklist":
+      if (ipMatchesAny(ip, blocklist)) {
+        return { allowed: false, reason: "blocklist" };
+      }
+      return { allowed: true, reason: "default" };
+    case "both":
+      if (ipMatchesAny(ip, allowlist)) {
+        return { allowed: true, reason: "allowlist" };
+      }
+      if (ipMatchesAny(ip, blocklist)) {
+        return { allowed: false, reason: "blocklist" };
+      }
+      return { allowed: true, reason: "default" };
+    default:
+      return { allowed: true, reason: "default" };
+  }
+}
+async function checkIpFilter(ip, config, requestInfo) {
+  if (config.customFilter) {
+    const customResult = await config.customFilter(ip, requestInfo);
+    if (customResult === true) return { allowed: true, reason: "custom" };
+    if (customResult === false) return { allowed: false, reason: "custom" };
+  }
+  return shouldAllowIp(ip, config);
+}
+
 // src/pocketping.ts
 function getClientIp(req) {
   const forwarded = req.headers["x-forwarded-for"];
@@ -179,6 +217,34 @@ var PocketPing = class {
         res.end();
         return;
       }
+      if (this.config.ipFilter?.enabled) {
+        const clientIp = getClientIp(req);
+        const filterResult = await checkIpFilter(clientIp, this.config.ipFilter, {
+          path
+        });
+        if (!filterResult.allowed) {
+          if (this.config.ipFilter.logBlocked !== false) {
+            const logEvent = {
+              type: "blocked",
+              ip: clientIp,
+              reason: filterResult.reason,
+              path,
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            if (this.config.ipFilter.logger) {
+              this.config.ipFilter.logger(logEvent);
+            } else {
+              console.log(`[PocketPing] IP blocked: ${clientIp} - reason: ${filterResult.reason}`);
+            }
+          }
+          res.statusCode = this.config.ipFilter.blockedStatusCode ?? 403;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({
+            error: this.config.ipFilter.blockedMessage ?? "Forbidden"
+          }));
+          return;
+        }
+      }
       const widgetVersion = req.headers["x-pocketping-version"];
       const versionCheck = this.checkWidgetVersion(widgetVersion);
       this.setVersionHeaders(res, versionCheck);
@@ -283,11 +349,35 @@ 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"
     });
-    this.wss.on("connection", (ws, req) => {
+    this.wss.on("connection", async (ws, req) => {
+      if (this.config.ipFilter?.enabled) {
+        const clientIp = getClientIp(req);
+        const filterResult = await checkIpFilter(clientIp, this.config.ipFilter, {
+          path: "/pocketping/stream"
+        });
+        if (!filterResult.allowed) {
+          if (this.config.ipFilter.logBlocked !== false) {
+            const logEvent = {
+              type: "blocked",
+              ip: clientIp,
+              reason: filterResult.reason,
+              path: "/pocketping/stream",
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            if (this.config.ipFilter.logger) {
+              this.config.ipFilter.logger(logEvent);
+            } else {
+              console.log(`[PocketPing] WS IP blocked: ${clientIp} - reason: ${filterResult.reason}`);
+            }
+          }
+          ws.close(4003, this.config.ipFilter.blockedMessage ?? "Forbidden");
+          return;
+        }
+      }
       const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
       const sessionId = url.searchParams.get("sessionId");
       if (!sessionId) {
@@ -361,7 +451,7 @@ var PocketPing = class {
     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);
       }
     }
@@ -506,7 +596,7 @@ 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 };
   }
   // ─────────────────────────────────────────────────────────────────
@@ -683,7 +773,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) {
@@ -691,10 +781,10 @@ 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);
       }
@@ -703,7 +793,7 @@ var PocketPing = class {
   async notifyBridgesEvent(event, session) {
     for (const bridge of this.bridges) {
       try {
-        await bridge.onEvent?.(event, session);
+        await bridge.onCustomEvent?.(event, session);
       } catch (err) {
         console.error(`[PocketPing] Bridge ${bridge.name} event notification error:`, err);
       }
@@ -742,7 +832,7 @@ var PocketPing = class {
       "Content-Type": "application/json"
     };
     if (this.config.webhookSecret) {
-      const signature = (0, import_crypto.createHmac)("sha256", this.config.webhookSecret).update(body).digest("hex");
+      const signature = createHmac("sha256", this.config.webhookSecret).update(body).digest("hex");
       headers["X-PocketPing-Signature"] = `sha256=${signature}`;
     }
     const timeout = this.config.webhookTimeout ?? 5e3;
@@ -877,8 +967,7 @@ var PocketPing = class {
     });
   }
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
+export {
   MemoryStorage,
   PocketPing
-});
+};

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@pocketping/sdk-node",
-  "version": "0.2.0",
+  "version": "1.1.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"
   ],
@@ -14,16 +22,20 @@
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "lint": "biome check src tests",
+    "lint:fix": "biome check --write src tests",
+    "format": "biome format --write src tests"
   },
   "dependencies": {
     "ws": "^8.16.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
     "@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"
@@ -46,5 +58,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"
+    ]
   }
 }