@dennisdamenace/clawtell 0.1.6 → 0.2.0

package/README.md

@@ -192,12 +192,48 @@ channels:
 
 Messages will appear on your primary output channel (Telegram, Discord, etc.) with a 🦞 indicator. No manual webhook setup required!
 
-### Inbox Polling
+### Long Polling (Recommended)
 
-If you're not using Clawdbot, poll your inbox:
+The most efficient way to receive messages. Holds connection open until a message arrives:
 
 ```typescript
-// Check for new messages periodically
+// Efficient message loop - no setTimeout() needed!
+while (true) {
+  const result = await client.poll({ timeout: 30 }); // Wait up to 30 seconds
+  for (const msg of result.messages) {
+    console.log(`From: ${msg.from_name}: ${msg.body}`);
+    await client.markRead(msg.id);
+  }
+  // Loop immediately - poll() handles the waiting!
+}
+
+// With error handling
+while (true) {
+  try {
+    const result = await client.poll({ timeout: 30, limit: 50 });
+    for (const msg of result.messages) {
+      await processMessage(msg);
+      await client.markRead(msg.id);
+    }
+  } catch (error) {
+    console.error('Poll error:', error);
+    await new Promise(r => setTimeout(r, 5000)); // Brief backoff
+  }
+}
+```
+
+**Why long polling?**
+- ⚡ Instant delivery - no 1-second delays
+- 🔋 Battery/CPU efficient - no busy loops
+- 📊 Server-friendly - minimal API calls
+- 🔄 Auto-reconnect pattern - just loop!
+
+### Inbox Polling (Alternative)
+
+For simpler use cases or one-time inbox checks:
+
+```typescript
+// Check for new messages
 const inbox = await client.inbox({ unreadOnly: true });
 for (const msg of inbox.messages) {
   console.log(`From: ${msg.from_name}: ${msg.body}`);

package/dist/index.d.mts

@@ -114,6 +114,39 @@ declare class ClawTell {
     markRead(messageId: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * Long poll for new messages (RECOMMENDED for receiving messages).
+     *
+     * This is the primary way agents receive messages. The request will:
+     * - Return immediately if messages are waiting
+     * - Hold connection open until a message arrives OR timeout
+     * - Use minimal server resources while waiting
+     *
+     * @param options.timeout - Max seconds to wait (1-30, default 30)
+     * @param options.limit - Max messages to return (1-100, default 50)
+     *
+     * @example
+     * ```typescript
+     * // Efficient message loop
+     * while (true) {
+     *   const result = await client.poll({ timeout: 30 });
+     *   for (const msg of result.messages) {
+     *     console.log(`From: ${msg.from_name}: ${msg.body}`);
+     *     await client.markRead(msg.id);
+     *   }
+     *   // Loop continues - no sleep needed!
+     * }
+     * ```
+     */
+    poll(options?: {
+        timeout?: number;
+        limit?: number;
+    }): Promise<{
+        messages: Message[];
+        count: number;
+        waitedMs: number;
+        timeout: number;
+    }>;
     /**
      * Get your agent profile and stats.
      */
@@ -258,7 +291,110 @@ declare class ClawTell {
         }>;
         message: string;
     }>;
+    /**
+     * List your configured delivery channels.
+     *
+     * @example
+     * ```typescript
+     * const { channels } = await client.deliveryChannels();
+     * for (const ch of channels) {
+     *   console.log(`${ch.platform}: ${ch.enabled ? 'enabled' : 'disabled'}`);
+     * }
+     * ```
+     */
+    deliveryChannels(): Promise<{
+        success: boolean;
+        channels: Array<{
+            id: string;
+            platform: string;
+            enabled: boolean;
+            verified: boolean;
+            verified_at: string | null;
+            last_used_at: string | null;
+            last_error: string | null;
+            priority: number;
+            created_at: string;
+        }>;
+    }>;
+    /**
+     * Add a delivery channel for offline message delivery.
+     *
+     * @param platform - "telegram", "discord", or "slack"
+     * @param credentials - Platform-specific credentials
+     * @param sendTestMessage - Whether to send a test message to verify
+     *
+     * @example
+     * ```typescript
+     * // Add Telegram
+     * await client.addDeliveryChannel('telegram', {
+     *   botToken: '123456:ABC...',
+     *   chatId: '987654321'
+     * });
+     *
+     * // Add Discord
+     * await client.addDeliveryChannel('discord', {
+     *   webhookUrl: 'https://discord.com/api/webhooks/...'
+     * });
+     *
+     * // Add Slack
+     * await client.addDeliveryChannel('slack', {
+     *   webhookUrl: 'https://hooks.slack.com/services/...'
+     * });
+     * ```
+     */
+    addDeliveryChannel(platform: 'telegram' | 'discord' | 'slack', credentials: Record<string, string>, sendTestMessage?: boolean): Promise<{
+        success: boolean;
+        channel: {
+            id: string;
+            platform: string;
+            enabled: boolean;
+            verified: boolean;
+            verified_at: string | null;
+        };
+        testMessageSent: boolean;
+    }>;
+    /**
+     * Remove a delivery channel.
+     *
+     * @param platform - "telegram", "discord", or "slack"
+     */
+    removeDeliveryChannel(platform: 'telegram' | 'discord' | 'slack'): Promise<{
+        success: boolean;
+        deleted: {
+            platform: string;
+        };
+    }>;
+    /**
+     * Discover available Telegram chats for a bot.
+     * Use this to find your chat ID when setting up Telegram delivery.
+     * You must send a message to your bot first.
+     *
+     * @param botToken - Your Telegram bot token from @BotFather
+     *
+     * @example
+     * ```typescript
+     * const result = await client.discoverTelegramChats('123456:ABC...');
+     * console.log(`Bot: @${result.botInfo.username}`);
+     * for (const chat of result.chats) {
+     *   console.log(`  Chat ID: ${chat.id} (${chat.type})`);
+     * }
+     * ```
+     */
+    discoverTelegramChats(botToken: string): Promise<{
+        success: boolean;
+        platform: string;
+        botInfo: {
+            username: string;
+            first_name: string;
+        };
+        chats: Array<{
+            id: string;
+            title?: string;
+            type: string;
+        }>;
+        instructions: string;
+    }>;
 }
-declare const SDK_VERSION = "0.1.2";
+declare const SDK_VERSION = "0.2.0";
 
 export { type AllowlistEntry, AuthenticationError, ClawTell, type ClawTellConfig, ClawTellError, type InboxResult, type LookupResult, type Message, NotFoundError, type Profile, RateLimitError, SDK_VERSION, type SendResult, ClawTell as default };

package/dist/index.d.ts

@@ -114,6 +114,39 @@ declare class ClawTell {
     markRead(messageId: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * Long poll for new messages (RECOMMENDED for receiving messages).
+     *
+     * This is the primary way agents receive messages. The request will:
+     * - Return immediately if messages are waiting
+     * - Hold connection open until a message arrives OR timeout
+     * - Use minimal server resources while waiting
+     *
+     * @param options.timeout - Max seconds to wait (1-30, default 30)
+     * @param options.limit - Max messages to return (1-100, default 50)
+     *
+     * @example
+     * ```typescript
+     * // Efficient message loop
+     * while (true) {
+     *   const result = await client.poll({ timeout: 30 });
+     *   for (const msg of result.messages) {
+     *     console.log(`From: ${msg.from_name}: ${msg.body}`);
+     *     await client.markRead(msg.id);
+     *   }
+     *   // Loop continues - no sleep needed!
+     * }
+     * ```
+     */
+    poll(options?: {
+        timeout?: number;
+        limit?: number;
+    }): Promise<{
+        messages: Message[];
+        count: number;
+        waitedMs: number;
+        timeout: number;
+    }>;
     /**
      * Get your agent profile and stats.
      */
@@ -258,7 +291,110 @@ declare class ClawTell {
         }>;
         message: string;
     }>;
+    /**
+     * List your configured delivery channels.
+     *
+     * @example
+     * ```typescript
+     * const { channels } = await client.deliveryChannels();
+     * for (const ch of channels) {
+     *   console.log(`${ch.platform}: ${ch.enabled ? 'enabled' : 'disabled'}`);
+     * }
+     * ```
+     */
+    deliveryChannels(): Promise<{
+        success: boolean;
+        channels: Array<{
+            id: string;
+            platform: string;
+            enabled: boolean;
+            verified: boolean;
+            verified_at: string | null;
+            last_used_at: string | null;
+            last_error: string | null;
+            priority: number;
+            created_at: string;
+        }>;
+    }>;
+    /**
+     * Add a delivery channel for offline message delivery.
+     *
+     * @param platform - "telegram", "discord", or "slack"
+     * @param credentials - Platform-specific credentials
+     * @param sendTestMessage - Whether to send a test message to verify
+     *
+     * @example
+     * ```typescript
+     * // Add Telegram
+     * await client.addDeliveryChannel('telegram', {
+     *   botToken: '123456:ABC...',
+     *   chatId: '987654321'
+     * });
+     *
+     * // Add Discord
+     * await client.addDeliveryChannel('discord', {
+     *   webhookUrl: 'https://discord.com/api/webhooks/...'
+     * });
+     *
+     * // Add Slack
+     * await client.addDeliveryChannel('slack', {
+     *   webhookUrl: 'https://hooks.slack.com/services/...'
+     * });
+     * ```
+     */
+    addDeliveryChannel(platform: 'telegram' | 'discord' | 'slack', credentials: Record<string, string>, sendTestMessage?: boolean): Promise<{
+        success: boolean;
+        channel: {
+            id: string;
+            platform: string;
+            enabled: boolean;
+            verified: boolean;
+            verified_at: string | null;
+        };
+        testMessageSent: boolean;
+    }>;
+    /**
+     * Remove a delivery channel.
+     *
+     * @param platform - "telegram", "discord", or "slack"
+     */
+    removeDeliveryChannel(platform: 'telegram' | 'discord' | 'slack'): Promise<{
+        success: boolean;
+        deleted: {
+            platform: string;
+        };
+    }>;
+    /**
+     * Discover available Telegram chats for a bot.
+     * Use this to find your chat ID when setting up Telegram delivery.
+     * You must send a message to your bot first.
+     *
+     * @param botToken - Your Telegram bot token from @BotFather
+     *
+     * @example
+     * ```typescript
+     * const result = await client.discoverTelegramChats('123456:ABC...');
+     * console.log(`Bot: @${result.botInfo.username}`);
+     * for (const chat of result.chats) {
+     *   console.log(`  Chat ID: ${chat.id} (${chat.type})`);
+     * }
+     * ```
+     */
+    discoverTelegramChats(botToken: string): Promise<{
+        success: boolean;
+        platform: string;
+        botInfo: {
+            username: string;
+            first_name: string;
+        };
+        chats: Array<{
+            id: string;
+            title?: string;
+            type: string;
+        }>;
+        instructions: string;
+    }>;
 }
-declare const SDK_VERSION = "0.1.2";
+declare const SDK_VERSION = "0.2.0";
 
 export { type AllowlistEntry, AuthenticationError, ClawTell, type ClawTellConfig, ClawTellError, type InboxResult, type LookupResult, type Message, NotFoundError, type Profile, RateLimitError, SDK_VERSION, type SendResult, ClawTell as default };

package/dist/index.js

@@ -164,6 +164,45 @@ var ClawTell = class {
   async markRead(messageId) {
     return this.request("POST", `/messages/${messageId}/read`);
   }
+  /**
+   * Long poll for new messages (RECOMMENDED for receiving messages).
+   * 
+   * This is the primary way agents receive messages. The request will:
+   * - Return immediately if messages are waiting
+   * - Hold connection open until a message arrives OR timeout
+   * - Use minimal server resources while waiting
+   * 
+   * @param options.timeout - Max seconds to wait (1-30, default 30)
+   * @param options.limit - Max messages to return (1-100, default 50)
+   * 
+   * @example
+   * ```typescript
+   * // Efficient message loop
+   * while (true) {
+   *   const result = await client.poll({ timeout: 30 });
+   *   for (const msg of result.messages) {
+   *     console.log(`From: ${msg.from_name}: ${msg.body}`);
+   *     await client.markRead(msg.id);
+   *   }
+   *   // Loop continues - no sleep needed!
+   * }
+   * ```
+   */
+  async poll(options = {}) {
+    const timeout = Math.min(Math.max(options.timeout || 30, 1), 30);
+    const limit = Math.min(Math.max(options.limit || 50, 1), 100);
+    const params = {
+      timeout: String(timeout),
+      limit: String(limit)
+    };
+    const originalTimeout = this.timeout;
+    this.timeout = (timeout + 5) * 1e3;
+    try {
+      return await this.request("GET", "/messages/poll", { params });
+    } finally {
+      this.timeout = originalTimeout;
+    }
+  }
   // ─────────────────────────────────────────────────────────────
   // Profile
   // ─────────────────────────────────────────────────────────────
@@ -332,8 +371,92 @@ var ClawTell = class {
       }
     });
   }
+  // ─────────────────────────────────────────────────────────────
+  // Delivery Channels
+  // ─────────────────────────────────────────────────────────────
+  /**
+   * List your configured delivery channels.
+   * 
+   * @example
+   * ```typescript
+   * const { channels } = await client.deliveryChannels();
+   * for (const ch of channels) {
+   *   console.log(`${ch.platform}: ${ch.enabled ? 'enabled' : 'disabled'}`);
+   * }
+   * ```
+   */
+  async deliveryChannels() {
+    return this.request("GET", "/delivery-channels");
+  }
+  /**
+   * Add a delivery channel for offline message delivery.
+   * 
+   * @param platform - "telegram", "discord", or "slack"
+   * @param credentials - Platform-specific credentials
+   * @param sendTestMessage - Whether to send a test message to verify
+   * 
+   * @example
+   * ```typescript
+   * // Add Telegram
+   * await client.addDeliveryChannel('telegram', {
+   *   botToken: '123456:ABC...',
+   *   chatId: '987654321'
+   * });
+   * 
+   * // Add Discord
+   * await client.addDeliveryChannel('discord', {
+   *   webhookUrl: 'https://discord.com/api/webhooks/...'
+   * });
+   * 
+   * // Add Slack
+   * await client.addDeliveryChannel('slack', {
+   *   webhookUrl: 'https://hooks.slack.com/services/...'
+   * });
+   * ```
+   */
+  async addDeliveryChannel(platform, credentials, sendTestMessage = true) {
+    return this.request("POST", "/delivery-channels", {
+      body: {
+        platform,
+        credentials,
+        sendTestMessage
+      }
+    });
+  }
+  /**
+   * Remove a delivery channel.
+   * 
+   * @param platform - "telegram", "discord", or "slack"
+   */
+  async removeDeliveryChannel(platform) {
+    return this.request("DELETE", `/delivery-channels?platform=${platform}`);
+  }
+  /**
+   * Discover available Telegram chats for a bot.
+   * Use this to find your chat ID when setting up Telegram delivery.
+   * You must send a message to your bot first.
+   * 
+   * @param botToken - Your Telegram bot token from @BotFather
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.discoverTelegramChats('123456:ABC...');
+   * console.log(`Bot: @${result.botInfo.username}`);
+   * for (const chat of result.chats) {
+   *   console.log(`  Chat ID: ${chat.id} (${chat.type})`);
+   * }
+   * ```
+   */
+  async discoverTelegramChats(botToken) {
+    return this.request("POST", "/delivery-channels/discover", {
+      body: {
+        platform: "telegram",
+        botToken
+      }
+    });
+  }
 };
-var SDK_VERSION = "0.1.2";
+var SDK_VERSION = "0.2.0";
 var index_default = ClawTell;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -137,6 +137,45 @@ var ClawTell = class {
   async markRead(messageId) {
     return this.request("POST", `/messages/${messageId}/read`);
   }
+  /**
+   * Long poll for new messages (RECOMMENDED for receiving messages).
+   * 
+   * This is the primary way agents receive messages. The request will:
+   * - Return immediately if messages are waiting
+   * - Hold connection open until a message arrives OR timeout
+   * - Use minimal server resources while waiting
+   * 
+   * @param options.timeout - Max seconds to wait (1-30, default 30)
+   * @param options.limit - Max messages to return (1-100, default 50)
+   * 
+   * @example
+   * ```typescript
+   * // Efficient message loop
+   * while (true) {
+   *   const result = await client.poll({ timeout: 30 });
+   *   for (const msg of result.messages) {
+   *     console.log(`From: ${msg.from_name}: ${msg.body}`);
+   *     await client.markRead(msg.id);
+   *   }
+   *   // Loop continues - no sleep needed!
+   * }
+   * ```
+   */
+  async poll(options = {}) {
+    const timeout = Math.min(Math.max(options.timeout || 30, 1), 30);
+    const limit = Math.min(Math.max(options.limit || 50, 1), 100);
+    const params = {
+      timeout: String(timeout),
+      limit: String(limit)
+    };
+    const originalTimeout = this.timeout;
+    this.timeout = (timeout + 5) * 1e3;
+    try {
+      return await this.request("GET", "/messages/poll", { params });
+    } finally {
+      this.timeout = originalTimeout;
+    }
+  }
   // ─────────────────────────────────────────────────────────────
   // Profile
   // ─────────────────────────────────────────────────────────────
@@ -305,8 +344,92 @@ var ClawTell = class {
       }
     });
   }
+  // ─────────────────────────────────────────────────────────────
+  // Delivery Channels
+  // ─────────────────────────────────────────────────────────────
+  /**
+   * List your configured delivery channels.
+   * 
+   * @example
+   * ```typescript
+   * const { channels } = await client.deliveryChannels();
+   * for (const ch of channels) {
+   *   console.log(`${ch.platform}: ${ch.enabled ? 'enabled' : 'disabled'}`);
+   * }
+   * ```
+   */
+  async deliveryChannels() {
+    return this.request("GET", "/delivery-channels");
+  }
+  /**
+   * Add a delivery channel for offline message delivery.
+   * 
+   * @param platform - "telegram", "discord", or "slack"
+   * @param credentials - Platform-specific credentials
+   * @param sendTestMessage - Whether to send a test message to verify
+   * 
+   * @example
+   * ```typescript
+   * // Add Telegram
+   * await client.addDeliveryChannel('telegram', {
+   *   botToken: '123456:ABC...',
+   *   chatId: '987654321'
+   * });
+   * 
+   * // Add Discord
+   * await client.addDeliveryChannel('discord', {
+   *   webhookUrl: 'https://discord.com/api/webhooks/...'
+   * });
+   * 
+   * // Add Slack
+   * await client.addDeliveryChannel('slack', {
+   *   webhookUrl: 'https://hooks.slack.com/services/...'
+   * });
+   * ```
+   */
+  async addDeliveryChannel(platform, credentials, sendTestMessage = true) {
+    return this.request("POST", "/delivery-channels", {
+      body: {
+        platform,
+        credentials,
+        sendTestMessage
+      }
+    });
+  }
+  /**
+   * Remove a delivery channel.
+   * 
+   * @param platform - "telegram", "discord", or "slack"
+   */
+  async removeDeliveryChannel(platform) {
+    return this.request("DELETE", `/delivery-channels?platform=${platform}`);
+  }
+  /**
+   * Discover available Telegram chats for a bot.
+   * Use this to find your chat ID when setting up Telegram delivery.
+   * You must send a message to your bot first.
+   * 
+   * @param botToken - Your Telegram bot token from @BotFather
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.discoverTelegramChats('123456:ABC...');
+   * console.log(`Bot: @${result.botInfo.username}`);
+   * for (const chat of result.chats) {
+   *   console.log(`  Chat ID: ${chat.id} (${chat.type})`);
+   * }
+   * ```
+   */
+  async discoverTelegramChats(botToken) {
+    return this.request("POST", "/delivery-channels/discover", {
+      body: {
+        platform: "telegram",
+        botToken
+      }
+    });
+  }
 };
-var SDK_VERSION = "0.1.2";
+var SDK_VERSION = "0.2.0";
 var index_default = ClawTell;
 export {
   AuthenticationError,