@dennisdamenace/clawtell 0.2.3 → 0.2.5

package/dist/index.d.mts

@@ -12,16 +12,25 @@ 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;
+    /** Whether message has been read (inbox only) */
+    read?: boolean;
+    /** Thread ID for conversations (poll only) */
+    threadId?: string;
+    /** Reply-to message ID (poll only) */
+    replyToMessageId?: string;
 }
 interface InboxResult {
     messages: Message[];
@@ -114,6 +123,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.
      */
@@ -259,31 +301,109 @@ declare class ClawTell {
         message: string;
     }>;
     /**
-     * Get a signed download URL for a secure file attachment.
+     * List your configured delivery channels.
      *
-     * Files uploaded via messages are stored in secure private storage.
-     * This method returns a time-limited signed URL (5 minutes) for download.
-     * Only the sender and recipient can access the file.
+     * @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 fileId - The file ID from message attachment (attachment.fileId)
-     * @returns Object with signedUrl, filename, mimeType, and expiresIn
+     * @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/...'
+     * });
+     * ```
      */
-    getAttachmentUrl(fileId: string): Promise<{
-        signedUrl: string;
-        filename: string;
-        mimeType: string;
-        expiresIn: number;
+    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;
     }>;
     /**
-     * Download a secure file attachment.
+     * Remove a delivery channel.
      *
-     * Convenience method that gets the signed URL and downloads the file.
+     * @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
      *
-     * @param fileId - The file ID from message attachment
-     * @returns ArrayBuffer containing the file data
+     * @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})`);
+     * }
+     * ```
      */
-    downloadAttachment(fileId: string): Promise<ArrayBuffer>;
+    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.2.3";
+declare const SDK_VERSION = "0.2.2";
 
 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,25 @@ 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;
+    /** Whether message has been read (inbox only) */
+    read?: boolean;
+    /** Thread ID for conversations (poll only) */
+    threadId?: string;
+    /** Reply-to message ID (poll only) */
+    replyToMessageId?: string;
 }
 interface InboxResult {
     messages: Message[];
@@ -110,10 +119,57 @@ declare class ClawTell {
     }): Promise<InboxResult>;
     /**
      * Mark a message as read.
+     * @deprecated Use ack([messageId]) instead for batch acknowledgment.
      */
     markRead(messageId: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * Acknowledge messages (batch). Marks messages as delivered and schedules deletion.
+     *
+     * Use this after processing messages from poll() to confirm receipt.
+     * Messages are deleted 1 hour after acknowledgment.
+     *
+     * @param messageIds - Array of message UUIDs to acknowledge
+     * @returns Object with success status and count of acknowledged messages
+     */
+    ack(messageIds: string[]): Promise<{
+        success: boolean;
+        acked: number;
+    }>;
+    /**
+     * 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,32 +314,7 @@ declare class ClawTell {
         }>;
         message: string;
     }>;
-    /**
-     * Get a signed download URL for a secure file attachment.
-     *
-     * Files uploaded via messages are stored in secure private storage.
-     * This method returns a time-limited signed URL (5 minutes) for download.
-     * Only the sender and recipient can access the file.
-     *
-     * @param fileId - The file ID from message attachment (attachment.fileId)
-     * @returns Object with signedUrl, filename, mimeType, and expiresIn
-     */
-    getAttachmentUrl(fileId: string): Promise<{
-        signedUrl: string;
-        filename: string;
-        mimeType: string;
-        expiresIn: number;
-    }>;
-    /**
-     * Download a secure file attachment.
-     *
-     * Convenience method that gets the signed URL and downloads the file.
-     *
-     * @param fileId - The file ID from message attachment
-     * @returns ArrayBuffer containing the file data
-     */
-    downloadAttachment(fileId: string): Promise<ArrayBuffer>;
 }
-declare const SDK_VERSION = "0.2.3";
+declare const SDK_VERSION = "0.2.5";
 
 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
@@ -160,10 +160,81 @@ var ClawTell = class {
   }
   /**
    * Mark a message as read.
+   * @deprecated Use ack([messageId]) instead for batch acknowledgment.
    */
   async markRead(messageId) {
+    console.warn("markRead() is deprecated, use ack([messageId]) instead");
     return this.request("POST", `/messages/${messageId}/read`);
   }
+  /**
+   * Acknowledge messages (batch). Marks messages as delivered and schedules deletion.
+   * 
+   * Use this after processing messages from poll() to confirm receipt.
+   * Messages are deleted 1 hour after acknowledgment.
+   * 
+   * @param messageIds - Array of message UUIDs to acknowledge
+   * @returns Object with success status and count of acknowledged messages
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.poll({ timeout: 30 });
+   * const processedIds = [];
+   * for (const msg of result.messages) {
+   *   await process(msg);
+   *   processedIds.push(msg.id);
+   * }
+   * if (processedIds.length > 0) {
+   *   await client.ack(processedIds);
+   * }
+   * ```
+   */
+  async ack(messageIds) {
+    if (!messageIds || messageIds.length === 0) {
+      return { success: true, acked: 0 };
+    }
+    return this.request("POST", "/messages/ack", { json: { messageIds } });
+  }
+  /**
+   * 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 });
+   *   const ids = [];
+   *   for (const msg of result.messages) {
+   *     console.log(`From: ${msg.from_name}: ${msg.body}`);
+   *     ids.push(msg.id);
+   *   }
+   *   if (ids.length > 0) await client.ack(ids);  // Batch acknowledge
+   *   // 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,40 +403,11 @@ var ClawTell = class {
       }
     });
   }
-  // ─────────────────────────────────────────────────────────────
-  // File Attachments
-  // ─────────────────────────────────────────────────────────────
-  /**
-   * Get a signed download URL for a secure file attachment.
-   * 
-   * Files uploaded via messages are stored in secure private storage.
-   * This method returns a time-limited signed URL (5 minutes) for download.
-   * Only the sender and recipient can access the file.
-   * 
-   * @param fileId - The file ID from message attachment (attachment.fileId)
-   * @returns Object with signedUrl, filename, mimeType, and expiresIn
-   */
-  async getAttachmentUrl(fileId) {
-    return this.request("GET", `/files/${fileId}`);
-  }
-  /**
-   * Download a secure file attachment.
-   * 
-   * Convenience method that gets the signed URL and downloads the file.
-   * 
-   * @param fileId - The file ID from message attachment
-   * @returns ArrayBuffer containing the file data
-   */
-  async downloadAttachment(fileId) {
-    const { signedUrl } = await this.getAttachmentUrl(fileId);
-    const response = await fetch(signedUrl);
-    if (!response.ok) {
-      throw new ClawTellError(`Failed to download file: ${response.statusText}`, response.status);
-    }
-    return response.arrayBuffer();
-  }
+  // Delivery Channels - REMOVED
+  // These methods were removed in v0.2.5 as ClawTell now uses long polling.
+  // Messages are delivered via poll() instead of push delivery channels.
 };
-var SDK_VERSION = "0.2.3";
+var SDK_VERSION = "0.2.5";
 var index_default = ClawTell;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import "./chunk-Y6FXYEAI.mjs";
+
 // src/index.ts
 var ClawTellError = class extends Error {
   constructor(message, statusCode) {
@@ -102,7 +104,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
@@ -135,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
   // ─────────────────────────────────────────────────────────────
@@ -304,39 +345,91 @@ var ClawTell = class {
     });
   }
   // ─────────────────────────────────────────────────────────────
-  // File Attachments
+  // Delivery Channels
   // ─────────────────────────────────────────────────────────────
   /**
-   * Get a signed download URL for a secure file attachment.
+   * 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'
+   * });
    * 
-   * Files uploaded via messages are stored in secure private storage.
-   * This method returns a time-limited signed URL (5 minutes) for download.
-   * Only the sender and recipient can access the file.
+   * // Add Discord
+   * await client.addDeliveryChannel('discord', {
+   *   webhookUrl: 'https://discord.com/api/webhooks/...'
+   * });
    * 
-   * @param fileId - The file ID from message attachment (attachment.fileId)
-   * @returns Object with signedUrl, filename, mimeType, and expiresIn
+   * // Add Slack
+   * await client.addDeliveryChannel('slack', {
+   *   webhookUrl: 'https://hooks.slack.com/services/...'
+   * });
+   * ```
    */
-  async getAttachmentUrl(fileId) {
-    return this.request("GET", `/files/${fileId}`);
+  async addDeliveryChannel(platform, credentials, sendTestMessage = true) {
+    return this.request("POST", "/delivery-channels", {
+      body: {
+        platform,
+        credentials,
+        sendTestMessage
+      }
+    });
   }
   /**
-   * Download a secure file attachment.
+   * Remove a delivery channel.
    * 
-   * Convenience method that gets the signed URL and downloads the file.
+   * @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
    * 
-   * @param fileId - The file ID from message attachment
-   * @returns ArrayBuffer containing the file data
+   * @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 downloadAttachment(fileId) {
-    const { signedUrl } = await this.getAttachmentUrl(fileId);
-    const response = await fetch(signedUrl);
-    if (!response.ok) {
-      throw new ClawTellError(`Failed to download file: ${response.statusText}`, response.status);
-    }
-    return response.arrayBuffer();
+  async discoverTelegramChats(botToken) {
+    return this.request("POST", "/delivery-channels/discover", {
+      body: {
+        platform: "telegram",
+        botToken
+      }
+    });
   }
 };
-var SDK_VERSION = "0.2.3";
+var SDK_VERSION = "0.2.2";
 var index_default = ClawTell;
 export {
   AuthenticationError,