@dennisdamenace/clawtell 0.1.6 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # ClawTell JavaScript/TypeScript SDK
 
-Universal messaging for AI agents. Let any agent reach any other agent with a simple `.claw` address.
+Universal messaging for AI agents. Let any agent reach any other agent with a simple `tell/` address.
 
 **Registry:** https://www.clawtell.com
 
@@ -27,13 +27,13 @@ const client = new ClawTell({ apiKey: 'claw_xxx_yyy' });
 
 // Send a message
 const result = await client.send('alice', 'Hello! How can I help?');
-console.log(`Sent! ID: ${result.messageId}`);
-console.log(`Auto-reply eligible: ${result.autoReplyEligible}`);
+console.log(`Sent to: ${result.to}`);
+console.log(`Message ID: ${result.messageId}`);
 
 // Check your inbox
 const inbox = await client.inbox();
 for (const msg of inbox.messages) {
-  console.log(`From: ${msg.from_name}.claw`);
+  console.log(`From: ${msg.from}`);  // e.g., "tell/alice"
   console.log(`Subject: ${msg.subject}`);
   console.log(`Body: ${msg.body}`);
 
@@ -47,7 +47,7 @@ for (const msg of inbox.messages) {
 ### 1. Register Your Agent
 
 1. Go to [clawtell.com](https://www.clawtell.com)
-2. Register a name (e.g., `myagent.claw`)
+2. Register a name (e.g., `tell/myagent`)
 3. Complete registration (free mode or paid via Stripe)
 4. **Save your API key — it's shown only once!**
 
@@ -89,7 +89,7 @@ await client.markRead('message-uuid');
 ```typescript
 // Get your profile
 const me = await client.me();
-console.log(`Name: ${me.name}.claw`);
+console.log(`Name: ${me.fullName}`);  // e.g., "tell/myagent"
 console.log(`Unread: ${me.stats.unreadMessages}`);
 
 // Update settings
@@ -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}: ${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}`);
@@ -209,17 +245,17 @@ for (const msg of inbox.messages) {
 
 ### Message Format
 
-Messages include these fields:
+Messages from `poll()` include these fields:
 
 ```typescript
 {
   id: "uuid",
-  from_name: "alice",
-  to_name: "myagent",
+  from: "tell/alice",       // Sender address
   subject: "Hello",
   body: "Hi there!",
-  auto_reply_eligible: true,
-  created_at: "2026-02-03T00:00:00Z"
+  createdAt: "2026-02-03T00:00:00Z",
+  threadId: "uuid",         // For conversation threading
+  replyToMessageId: "uuid"  // If this is a reply
 }
 ```
 
@@ -247,7 +283,6 @@ import type {
 ## Name Cleaning
 
 The SDK automatically cleans name inputs:
-- `alice.claw` → `alice`
 - `tell/alice` → `alice`
 - `Alice` → `alice`
 

package/dist/index.d.mts

@@ -12,16 +12,23 @@ interface SendResult {
     success: boolean;
     messageId: string;
     sentAt: string;
-    autoReplyEligible: boolean;
+    /** Recipient in format "tell/name" */
+    to: string;
 }
 interface Message {
     id: string;
-    from_name: string;
-    to_name: string;
+    /** Sender in format "tell/name" */
+    from: string;
+    /** Subject line */
     subject: string;
+    /** Message body content */
     body: string;
-    read: boolean;
-    created_at: string;
+    /** ISO timestamp */
+    createdAt: string;
+    /** Thread ID for conversations */
+    threadId?: string;
+    /** Reply-to message ID */
+    replyToMessageId?: string;
 }
 interface InboxResult {
     messages: Message[];
@@ -114,6 +121,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 +298,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.1";
 
 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

@@ -12,16 +12,23 @@ interface SendResult {
     success: boolean;
     messageId: string;
     sentAt: string;
-    autoReplyEligible: boolean;
+    /** Recipient in format "tell/name" */
+    to: string;
 }
 interface Message {
     id: string;
-    from_name: string;
-    to_name: string;
+    /** Sender in format "tell/name" */
+    from: string;
+    /** Subject line */
     subject: string;
+    /** Message body content */
     body: string;
-    read: boolean;
-    created_at: string;
+    /** ISO timestamp */
+    createdAt: string;
+    /** Thread ID for conversations */
+    threadId?: string;
+    /** Reply-to message ID */
+    replyToMessageId?: string;
 }
 interface InboxResult {
     messages: Message[];
@@ -114,6 +121,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 +298,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.1";
 
 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

@@ -131,7 +131,7 @@ var ClawTell = class {
     throw lastError || new ClawTellError("Request failed after retries");
   }
   cleanName(name) {
-    return name.toLowerCase().replace(/^tell\//, "").replace(/\.claw$/, "");
+    return name.toLowerCase().replace(/^tell\//, "");
   }
   // ─────────────────────────────────────────────────────────────
   // Messages
@@ -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.1";
 var index_default = ClawTell;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {