@pocketping/sdk-node 1.5.0 → 1.6.0

package/dist/index.cjs

@@ -1597,10 +1597,140 @@ var WebhookHandler = class {
   }
 };
 
+// src/errors.ts
+var PocketPingSetupError = class extends Error {
+  constructor(options) {
+    const message = `[PocketPing] ${options.bridge} configuration error: ${options.missing} is required`;
+    super(message);
+    this.name = "PocketPingSetupError";
+    this.bridge = options.bridge;
+    this.missing = options.missing;
+    this.guide = options.guide;
+    this.docsUrl = options.docsUrl || `https://pocketping.io/docs/${options.bridge.toLowerCase()}`;
+    console.error(this.getFormattedGuide());
+  }
+  getFormattedGuide() {
+    return `
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502  \u26A0\uFE0F  ${this.bridge} Setup Required
+\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+\u2502
+\u2502  Missing: ${this.missing}
+\u2502
+${this.guide.split("\n").map((line) => `\u2502  ${line}`).join("\n")}
+\u2502
+\u2502  \u{1F4D6} Full guide: ${this.docsUrl}
+\u2502
+\u2502  \u{1F4A1} Quick fix: npx @pocketping/cli init ${this.bridge.toLowerCase()}
+\u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+`;
+  }
+};
+var SETUP_GUIDES = {
+  discord: {
+    botToken: `
+To set up Discord Bot mode:
+
+1. Go to https://discord.com/developers/applications
+2. Create a new application
+3. Go to Bot \u2192 Add Bot \u2192 Reset Token
+4. Copy the token and set DISCORD_BOT_TOKEN
+
+Enable MESSAGE CONTENT INTENT in Bot settings!
+`,
+    channelId: `
+To get your Discord Channel ID:
+
+1. Enable Developer Mode in Discord:
+   User Settings \u2192 Advanced \u2192 Developer Mode
+2. Right-click on your channel \u2192 Copy ID
+3. Set DISCORD_CHANNEL_ID in your .env
+
+Tip: Use a Forum channel for organized threads!
+`,
+    webhookUrl: `
+To get a Discord Webhook URL:
+
+1. Go to your channel settings
+2. Integrations \u2192 Webhooks \u2192 New Webhook
+3. Copy the Webhook URL
+
+Note: Webhooks are send-only. Use Bot mode for full features.
+`
+  },
+  slack: {
+    botToken: `
+To set up Slack Bot mode:
+
+1. Go to https://api.slack.com/apps
+2. Create New App \u2192 From scratch
+3. OAuth & Permissions \u2192 Add Bot Token Scopes:
+   - chat:write, channels:read, channels:join
+   - channels:history, groups:history, users:read
+4. Install to Workspace \u2192 Copy Bot Token (xoxb-...)
+`,
+    channelId: `
+To get your Slack Channel ID:
+
+1. Right-click on your channel in Slack
+2. View channel details
+3. Scroll down to find Channel ID (starts with C or G)
+
+For private channels: /invite @YourBotName first
+`,
+    webhookUrl: `
+To get a Slack Webhook URL:
+
+1. Go to https://api.slack.com/apps
+2. Incoming Webhooks \u2192 Add New Webhook
+3. Select a channel \u2192 Copy Webhook URL
+
+Note: Webhooks are send-only. Use Bot mode for full features.
+`
+  },
+  telegram: {
+    botToken: `
+To create a Telegram Bot:
+
+1. Open @BotFather in Telegram
+2. Send /newbot
+3. Choose a name and username
+4. Copy the Bot Token you receive
+
+Set TELEGRAM_BOT_TOKEN in your .env
+`,
+    chatId: `
+To get your Telegram Chat ID:
+
+1. Create a group and enable Topics (for forums)
+2. Add your bot to the group as admin
+3. Add @getidsbot to the group
+4. Copy the Chat ID (starts with -100)
+
+The bot needs "Manage Topics" permission!
+`
+  }
+};
+
 // src/bridges/telegram.ts
 var TelegramBridge = class {
   constructor(botToken, chatId, options = {}) {
     this.name = "telegram";
+    if (!botToken) {
+      throw new PocketPingSetupError({
+        bridge: "Telegram",
+        missing: "botToken",
+        guide: SETUP_GUIDES.telegram.botToken
+      });
+    }
+    if (!chatId) {
+      throw new PocketPingSetupError({
+        bridge: "Telegram",
+        missing: "chatId",
+        guide: SETUP_GUIDES.telegram.chatId
+      });
+    }
     this.botToken = botToken;
     this.chatId = chatId;
     this.parseMode = options.parseMode ?? "HTML";
@@ -1769,12 +1899,14 @@ ${dataStr}
       text = `<b>User Identified</b>
 <b>ID:</b> ${this.escapeHtml(identity.id)}
 ` + (identity.name ? `<b>Name:</b> ${this.escapeHtml(identity.name)}
-` : "") + (identity.email ? `<b>Email:</b> ${this.escapeHtml(identity.email)}` : "");
+` : "") + (identity.email ? `<b>Email:</b> ${this.escapeHtml(identity.email)}
+` : "") + (session.userPhone ? `<b>Phone:</b> ${this.escapeHtml(session.userPhone)}` : "");
     } else {
       text = `*User Identified*
 *ID:* ${this.escapeMarkdown(identity.id)}
 ` + (identity.name ? `*Name:* ${this.escapeMarkdown(identity.name)}
-` : "") + (identity.email ? `*Email:* ${this.escapeMarkdown(identity.email)}` : "");
+` : "") + (identity.email ? `*Email:* ${this.escapeMarkdown(identity.email)}
+` : "") + (session.userPhone ? `*Phone:* ${this.escapeMarkdown(session.userPhone)}` : "");
     }
     try {
       await this.sendMessage(text.trim());
@@ -1872,6 +2004,20 @@ var DiscordBridge = class _DiscordBridge {
    * Create a Discord bridge using a webhook URL
    */
   static webhook(webhookUrl, options = {}) {
+    if (!webhookUrl) {
+      throw new PocketPingSetupError({
+        bridge: "Discord",
+        missing: "webhookUrl",
+        guide: SETUP_GUIDES.discord.webhookUrl
+      });
+    }
+    if (!webhookUrl.startsWith("https://discord.com/api/webhooks/")) {
+      throw new PocketPingSetupError({
+        bridge: "Discord",
+        missing: "valid webhookUrl",
+        guide: "Webhook URL must start with https://discord.com/api/webhooks/\n\n" + SETUP_GUIDES.discord.webhookUrl
+      });
+    }
     return new _DiscordBridge({
       mode: "webhook",
       webhookUrl,
@@ -1883,6 +2029,20 @@ var DiscordBridge = class _DiscordBridge {
    * Create a Discord bridge using a bot token
    */
   static bot(botToken, channelId, options = {}) {
+    if (!botToken) {
+      throw new PocketPingSetupError({
+        bridge: "Discord",
+        missing: "botToken",
+        guide: SETUP_GUIDES.discord.botToken
+      });
+    }
+    if (!channelId) {
+      throw new PocketPingSetupError({
+        bridge: "Discord",
+        missing: "channelId",
+        guide: SETUP_GUIDES.discord.channelId
+      });
+    }
     return new _DiscordBridge({
       mode: "bot",
       botToken,
@@ -2128,6 +2288,9 @@ ${JSON.stringify(event.data, null, 2)}
     if (identity.email) {
       fields.push({ name: "Email", value: identity.email, inline: true });
     }
+    if (session.userPhone) {
+      fields.push({ name: "Phone", value: session.userPhone, inline: true });
+    }
     const embed = {
       title: "User Identified",
       color: 5793266,
@@ -2213,6 +2376,20 @@ var SlackBridge = class _SlackBridge {
    * Create a Slack bridge using a webhook URL
    */
   static webhook(webhookUrl, options = {}) {
+    if (!webhookUrl) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "webhookUrl",
+        guide: SETUP_GUIDES.slack.webhookUrl
+      });
+    }
+    if (!webhookUrl.startsWith("https://hooks.slack.com/")) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "valid webhookUrl",
+        guide: "Webhook URL must start with https://hooks.slack.com/\n\n" + SETUP_GUIDES.slack.webhookUrl
+      });
+    }
     return new _SlackBridge({
       mode: "webhook",
       webhookUrl,
@@ -2225,6 +2402,27 @@ var SlackBridge = class _SlackBridge {
    * Create a Slack bridge using a bot token
    */
   static bot(botToken, channelId, options = {}) {
+    if (!botToken) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "botToken",
+        guide: SETUP_GUIDES.slack.botToken
+      });
+    }
+    if (!botToken.startsWith("xoxb-")) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "valid botToken",
+        guide: "Bot token must start with xoxb-\n\n" + SETUP_GUIDES.slack.botToken
+      });
+    }
+    if (!channelId) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "channelId",
+        guide: SETUP_GUIDES.slack.channelId
+      });
+    }
     return new _SlackBridge({
       mode: "bot",
       botToken,
@@ -2516,6 +2714,13 @@ ${identity.name}`
 ${identity.email}`
       });
     }
+    if (session.userPhone) {
+      fields.push({
+        type: "mrkdwn",
+        text: `*Phone:*
+${session.userPhone}`
+      });
+    }
     const blocks = [
       {
         type: "header",

package/dist/index.d.cts

@@ -207,6 +207,10 @@ interface Session {
     metadata?: SessionMetadata;
     /** User identity if identified via PocketPing.identify() */
     identity?: UserIdentity;
+    /** User phone from pre-chat form (E.164 format: +33612345678) */
+    userPhone?: string;
+    /** User phone country code (ISO: FR, US, etc.) */
+    userPhoneCountry?: string;
 }
 interface SessionMetadata {
     url?: string;

package/dist/index.d.ts

@@ -207,6 +207,10 @@ interface Session {
     metadata?: SessionMetadata;
     /** User identity if identified via PocketPing.identify() */
     identity?: UserIdentity;
+    /** User phone from pre-chat form (E.164 format: +33612345678) */
+    userPhone?: string;
+    /** User phone country code (ISO: FR, US, etc.) */
+    userPhoneCountry?: string;
 }
 interface SessionMetadata {
     url?: string;

package/dist/index.js

@@ -1566,10 +1566,140 @@ var WebhookHandler = class {
   }
 };
 
+// src/errors.ts
+var PocketPingSetupError = class extends Error {
+  constructor(options) {
+    const message = `[PocketPing] ${options.bridge} configuration error: ${options.missing} is required`;
+    super(message);
+    this.name = "PocketPingSetupError";
+    this.bridge = options.bridge;
+    this.missing = options.missing;
+    this.guide = options.guide;
+    this.docsUrl = options.docsUrl || `https://pocketping.io/docs/${options.bridge.toLowerCase()}`;
+    console.error(this.getFormattedGuide());
+  }
+  getFormattedGuide() {
+    return `
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502  \u26A0\uFE0F  ${this.bridge} Setup Required
+\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+\u2502
+\u2502  Missing: ${this.missing}
+\u2502
+${this.guide.split("\n").map((line) => `\u2502  ${line}`).join("\n")}
+\u2502
+\u2502  \u{1F4D6} Full guide: ${this.docsUrl}
+\u2502
+\u2502  \u{1F4A1} Quick fix: npx @pocketping/cli init ${this.bridge.toLowerCase()}
+\u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+`;
+  }
+};
+var SETUP_GUIDES = {
+  discord: {
+    botToken: `
+To set up Discord Bot mode:
+
+1. Go to https://discord.com/developers/applications
+2. Create a new application
+3. Go to Bot \u2192 Add Bot \u2192 Reset Token
+4. Copy the token and set DISCORD_BOT_TOKEN
+
+Enable MESSAGE CONTENT INTENT in Bot settings!
+`,
+    channelId: `
+To get your Discord Channel ID:
+
+1. Enable Developer Mode in Discord:
+   User Settings \u2192 Advanced \u2192 Developer Mode
+2. Right-click on your channel \u2192 Copy ID
+3. Set DISCORD_CHANNEL_ID in your .env
+
+Tip: Use a Forum channel for organized threads!
+`,
+    webhookUrl: `
+To get a Discord Webhook URL:
+
+1. Go to your channel settings
+2. Integrations \u2192 Webhooks \u2192 New Webhook
+3. Copy the Webhook URL
+
+Note: Webhooks are send-only. Use Bot mode for full features.
+`
+  },
+  slack: {
+    botToken: `
+To set up Slack Bot mode:
+
+1. Go to https://api.slack.com/apps
+2. Create New App \u2192 From scratch
+3. OAuth & Permissions \u2192 Add Bot Token Scopes:
+   - chat:write, channels:read, channels:join
+   - channels:history, groups:history, users:read
+4. Install to Workspace \u2192 Copy Bot Token (xoxb-...)
+`,
+    channelId: `
+To get your Slack Channel ID:
+
+1. Right-click on your channel in Slack
+2. View channel details
+3. Scroll down to find Channel ID (starts with C or G)
+
+For private channels: /invite @YourBotName first
+`,
+    webhookUrl: `
+To get a Slack Webhook URL:
+
+1. Go to https://api.slack.com/apps
+2. Incoming Webhooks \u2192 Add New Webhook
+3. Select a channel \u2192 Copy Webhook URL
+
+Note: Webhooks are send-only. Use Bot mode for full features.
+`
+  },
+  telegram: {
+    botToken: `
+To create a Telegram Bot:
+
+1. Open @BotFather in Telegram
+2. Send /newbot
+3. Choose a name and username
+4. Copy the Bot Token you receive
+
+Set TELEGRAM_BOT_TOKEN in your .env
+`,
+    chatId: `
+To get your Telegram Chat ID:
+
+1. Create a group and enable Topics (for forums)
+2. Add your bot to the group as admin
+3. Add @getidsbot to the group
+4. Copy the Chat ID (starts with -100)
+
+The bot needs "Manage Topics" permission!
+`
+  }
+};
+
 // src/bridges/telegram.ts
 var TelegramBridge = class {
   constructor(botToken, chatId, options = {}) {
     this.name = "telegram";
+    if (!botToken) {
+      throw new PocketPingSetupError({
+        bridge: "Telegram",
+        missing: "botToken",
+        guide: SETUP_GUIDES.telegram.botToken
+      });
+    }
+    if (!chatId) {
+      throw new PocketPingSetupError({
+        bridge: "Telegram",
+        missing: "chatId",
+        guide: SETUP_GUIDES.telegram.chatId
+      });
+    }
     this.botToken = botToken;
     this.chatId = chatId;
     this.parseMode = options.parseMode ?? "HTML";
@@ -1738,12 +1868,14 @@ ${dataStr}
       text = `<b>User Identified</b>
 <b>ID:</b> ${this.escapeHtml(identity.id)}
 ` + (identity.name ? `<b>Name:</b> ${this.escapeHtml(identity.name)}
-` : "") + (identity.email ? `<b>Email:</b> ${this.escapeHtml(identity.email)}` : "");
+` : "") + (identity.email ? `<b>Email:</b> ${this.escapeHtml(identity.email)}
+` : "") + (session.userPhone ? `<b>Phone:</b> ${this.escapeHtml(session.userPhone)}` : "");
     } else {
       text = `*User Identified*
 *ID:* ${this.escapeMarkdown(identity.id)}
 ` + (identity.name ? `*Name:* ${this.escapeMarkdown(identity.name)}
-` : "") + (identity.email ? `*Email:* ${this.escapeMarkdown(identity.email)}` : "");
+` : "") + (identity.email ? `*Email:* ${this.escapeMarkdown(identity.email)}
+` : "") + (session.userPhone ? `*Phone:* ${this.escapeMarkdown(session.userPhone)}` : "");
     }
     try {
       await this.sendMessage(text.trim());
@@ -1841,6 +1973,20 @@ var DiscordBridge = class _DiscordBridge {
    * Create a Discord bridge using a webhook URL
    */
   static webhook(webhookUrl, options = {}) {
+    if (!webhookUrl) {
+      throw new PocketPingSetupError({
+        bridge: "Discord",
+        missing: "webhookUrl",
+        guide: SETUP_GUIDES.discord.webhookUrl
+      });
+    }
+    if (!webhookUrl.startsWith("https://discord.com/api/webhooks/")) {
+      throw new PocketPingSetupError({
+        bridge: "Discord",
+        missing: "valid webhookUrl",
+        guide: "Webhook URL must start with https://discord.com/api/webhooks/\n\n" + SETUP_GUIDES.discord.webhookUrl
+      });
+    }
     return new _DiscordBridge({
       mode: "webhook",
       webhookUrl,
@@ -1852,6 +1998,20 @@ var DiscordBridge = class _DiscordBridge {
    * Create a Discord bridge using a bot token
    */
   static bot(botToken, channelId, options = {}) {
+    if (!botToken) {
+      throw new PocketPingSetupError({
+        bridge: "Discord",
+        missing: "botToken",
+        guide: SETUP_GUIDES.discord.botToken
+      });
+    }
+    if (!channelId) {
+      throw new PocketPingSetupError({
+        bridge: "Discord",
+        missing: "channelId",
+        guide: SETUP_GUIDES.discord.channelId
+      });
+    }
     return new _DiscordBridge({
       mode: "bot",
       botToken,
@@ -2097,6 +2257,9 @@ ${JSON.stringify(event.data, null, 2)}
     if (identity.email) {
       fields.push({ name: "Email", value: identity.email, inline: true });
     }
+    if (session.userPhone) {
+      fields.push({ name: "Phone", value: session.userPhone, inline: true });
+    }
     const embed = {
       title: "User Identified",
       color: 5793266,
@@ -2182,6 +2345,20 @@ var SlackBridge = class _SlackBridge {
    * Create a Slack bridge using a webhook URL
    */
   static webhook(webhookUrl, options = {}) {
+    if (!webhookUrl) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "webhookUrl",
+        guide: SETUP_GUIDES.slack.webhookUrl
+      });
+    }
+    if (!webhookUrl.startsWith("https://hooks.slack.com/")) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "valid webhookUrl",
+        guide: "Webhook URL must start with https://hooks.slack.com/\n\n" + SETUP_GUIDES.slack.webhookUrl
+      });
+    }
     return new _SlackBridge({
       mode: "webhook",
       webhookUrl,
@@ -2194,6 +2371,27 @@ var SlackBridge = class _SlackBridge {
    * Create a Slack bridge using a bot token
    */
   static bot(botToken, channelId, options = {}) {
+    if (!botToken) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "botToken",
+        guide: SETUP_GUIDES.slack.botToken
+      });
+    }
+    if (!botToken.startsWith("xoxb-")) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "valid botToken",
+        guide: "Bot token must start with xoxb-\n\n" + SETUP_GUIDES.slack.botToken
+      });
+    }
+    if (!channelId) {
+      throw new PocketPingSetupError({
+        bridge: "Slack",
+        missing: "channelId",
+        guide: SETUP_GUIDES.slack.channelId
+      });
+    }
     return new _SlackBridge({
       mode: "bot",
       botToken,
@@ -2485,6 +2683,13 @@ ${identity.name}`
 ${identity.email}`
       });
     }
+    if (session.userPhone) {
+      fields.push({
+        type: "mrkdwn",
+        text: `*Phone:*
+${session.userPhone}`
+      });
+    }
     const blocks = [
       {
         type: "header",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pocketping/sdk-node",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Node.js SDK for implementing PocketPing protocol",
   "main": "dist/index.cjs",