@pocketping/sdk-node 1.2.0 → 1.4.0

package/README.md

@@ -143,26 +143,103 @@ const clientIp = pp.getClientIp(request.headers);
 // Checks: CF-Connecting-IP, X-Real-IP, X-Forwarded-For
 ```
 
+## Built-in Bridges
+
+The SDK includes built-in bridges for Telegram, Discord, and Slack. No external libraries required - all communication uses HTTP APIs directly.
+
+### Telegram Bridge
+
+```typescript
+import { PocketPing, TelegramBridge } from '@pocketping/sdk-node';
+
+const pp = new PocketPing({
+  welcomeMessage: 'Hello!',
+});
+
+pp.addBridge(new TelegramBridge({
+  botToken: process.env.TELEGRAM_BOT_TOKEN!,
+  chatIds: process.env.TELEGRAM_CHAT_ID!,
+  showUrl: true,  // Show page URL in notifications
+}));
+```
+
+### Discord Bridge
+
+```typescript
+import { PocketPing, DiscordBridge } from '@pocketping/sdk-node';
+
+// Webhook mode (simple, send-only)
+pp.addBridge(DiscordBridge.withWebhook({
+  webhookUrl: process.env.DISCORD_WEBHOOK_URL!,
+}));
+
+// Or Bot mode (bidirectional)
+pp.addBridge(DiscordBridge.withBot({
+  botToken: process.env.DISCORD_BOT_TOKEN!,
+  channelId: process.env.DISCORD_CHANNEL_ID!,
+}));
+```
+
+### Slack Bridge
+
+```typescript
+import { PocketPing, SlackBridge } from '@pocketping/sdk-node';
+
+// Webhook mode (simple, send-only)
+pp.addBridge(SlackBridge.withWebhook({
+  webhookUrl: process.env.SLACK_WEBHOOK_URL!,
+}));
+
+// Or Bot mode (bidirectional)
+pp.addBridge(SlackBridge.withBot({
+  botToken: process.env.SLACK_BOT_TOKEN!,
+  channelId: process.env.SLACK_CHANNEL_ID!,
+}));
+```
+
+### Multiple Bridges
+
+You can add multiple bridges to receive notifications on all platforms simultaneously:
+
+```typescript
+const pp = new PocketPing({ welcomeMessage: 'Hello!' });
+
+pp.addBridge(new TelegramBridge({ ... }));
+pp.addBridge(DiscordBridge.withBot({ ... }));
+pp.addBridge(SlackBridge.withWebhook({ ... }));
+```
+
+### Reply Behavior
+
+- **Telegram:** uses native replies when `replyTo` is set and the Telegram message ID is available.
+- **Discord:** uses native replies via `message_reference` when the Discord message ID is available.
+- **Slack:** renders a quoted block (left bar) in the thread.
+
 ## Architecture Options
 
-### 1. Embedded Mode (Simple)
+### 1. Embedded Mode with Built-in Bridges (Simple)
 
-SDK handles everything directly - best for single server deployments:
+SDK handles everything directly including notifications - best for single server deployments:
 
 ```typescript
-import { PocketPing } from '@pocketping/sdk-node';
+import { PocketPing, TelegramBridge } from '@pocketping/sdk-node';
 
 const pp = new PocketPing({
   welcomeMessage: 'Hello!',
 });
 
+pp.addBridge(new TelegramBridge({
+  botToken: process.env.TELEGRAM_BOT_TOKEN!,
+  chatIds: process.env.TELEGRAM_CHAT_ID!,
+}));
+
 app.use('/pocketping', pp.middleware());
 pp.attachWebSocket(server);
 ```
 
-### 2. Bridge Server Mode (Recommended)
+### 2. Bridge Server Mode (Production)
 
-SDK connects to a dedicated bridge server for notifications:
+SDK connects to a dedicated bridge server (written in Go) for notifications:
 
 ```typescript
 const pp = new PocketPing({
@@ -171,7 +248,61 @@ const pp = new PocketPing({
 });
 ```
 
-The bridge server handles Telegram, Discord, and Slack integrations, keeping your main server lightweight.
+The bridge server handles Telegram, Discord, and Slack integrations via HTTP APIs, keeping your main server lightweight.
+
+## Receiving Operator Messages (WebhookHandler)
+
+To receive replies from operators via Telegram, Discord, or Slack, use the `WebhookHandler`:
+
+```typescript
+import { WebhookHandler } from '@pocketping/sdk-node';
+
+const webhookHandler = new WebhookHandler({
+  telegramBotToken: process.env.TELEGRAM_BOT_TOKEN,
+  slackBotToken: process.env.SLACK_BOT_TOKEN,
+  discordBotToken: process.env.DISCORD_BOT_TOKEN,
+  allowedBotIds: process.env.BRIDGE_TEST_BOT_IDS?.split(',').map((id) => id.trim()).filter(Boolean),
+  onOperatorMessage: async (sessionId, content, operatorName, source, attachments) => {
+    console.log(`Message from ${operatorName} via ${source}: ${content}`);
+
+    // Forward to widget
+    await pp.sendOperatorMessage(sessionId, content, source, operatorName);
+
+    // Handle attachments
+    for (const att of attachments) {
+      console.log(`Attachment: ${att.filename} (${att.size} bytes)`);
+      // att.data contains the file bytes
+    }
+  },
+  onOperatorMessageEdit: async (sessionId, bridgeMessageId, content, source) => {
+    console.log(`Edited message ${bridgeMessageId} via ${source}: ${content}`);
+  },
+  onOperatorMessageDelete: async (sessionId, bridgeMessageId, source) => {
+    console.log(`Deleted message ${bridgeMessageId} via ${source}`);
+  },
+});
+
+// Mount webhook routes
+app.post('/webhooks/telegram', async (req, res) => {
+  const result = await webhookHandler.handleTelegramWebhook(req.body);
+  res.json(result);
+});
+
+app.post('/webhooks/slack', async (req, res) => {
+  const result = await webhookHandler.handleSlackWebhook(req.body);
+  res.json(result);
+});
+
+app.post('/webhooks/discord', async (req, res) => {
+  const result = await webhookHandler.handleDiscordWebhook(req.body);
+  res.json(result);
+});
+```
+
+Configure webhooks on each platform to point to your server:
+- **Telegram**: Use `setWebhook` API
+- **Slack**: Configure Event Subscriptions
+- **Discord**: Set up Interactions Endpoint
 
 ## Custom Storage