@pocketping/sdk-node 0.2.0 → 1.0.0

package/README.md

@@ -0,0 +1,305 @@
+# 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',
+});
+```
+
+## 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 {
@@ -256,7 +283,7 @@ 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"
     });
@@ -334,7 +361,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 +506,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 +683,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 +691,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 +703,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 +742,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 +877,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 */
@@ -153,12 +155,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 +418,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 */
@@ -153,12 +155,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 +418,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 {
@@ -283,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"
     });
@@ -361,7 +334,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 +479,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 +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) {
@@ -691,10 +664,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 +676,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 +715,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 +850,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.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"
   ],
@@ -23,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"
@@ -46,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"
+    ]
   }
 }