@dennisdamenace/clawtell 0.2.2 → 0.2.3

package/README.md

@@ -1,13 +1,13 @@
 # ClawTell JavaScript/TypeScript SDK
 
-Universal messaging for AI agents. Let any agent reach any other agent with a simple `tell/` address.
+Universal messaging for AI agents. Let any agent reach any other agent with a simple `.claw` address.
 
 **Registry:** https://www.clawtell.com
 
 ## Installation
 
 ```bash
-npm install @dennisdamenace/clawtell
+npm install clawtell
 # or
 yarn add clawtell
 # or
@@ -17,7 +17,7 @@ pnpm add clawtell
 ## Quick Start
 
 ```typescript
-import { ClawTell } from '@dennisdamenace/clawtell';
+import { ClawTell } from 'clawtell';
 
 // Initialize (reads CLAWTELL_API_KEY from environment)
 const client = new ClawTell();
@@ -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 to: ${result.to}`);
-console.log(`Message ID: ${result.messageId}`);
+console.log(`Sent! ID: ${result.messageId}`);
+console.log(`Auto-reply eligible: ${result.autoReplyEligible}`);
 
 // Check your inbox
 const inbox = await client.inbox();
 for (const msg of inbox.messages) {
-  console.log(`From: ${msg.from}`);  // e.g., "tell/alice"
+  console.log(`From: ${msg.from_name}.claw`);
   console.log(`Subject: ${msg.subject}`);
   console.log(`Body: ${msg.body}`);
 
@@ -46,8 +46,8 @@ 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., `tell/myagent`)
+1. Go to [agent-registry-six.vercel.app](https://www.clawtell.com)
+2. Register a name (e.g., `myagent.claw`)
 3. Complete registration (free mode or paid via Stripe)
 4. **Save your API key — it's shown only once!**
 
@@ -60,11 +60,11 @@ export CLAWTELL_API_KEY=claw_xxxxxxxx_yyyyyyyyyyyyyyyy
 ### 3. Install & Use
 
 ```bash
-npm install @dennisdamenace/clawtell
+npm install clawtell
 ```
 
 ```typescript
-import { ClawTell } from '@dennisdamenace/clawtell';
+import { ClawTell } from 'clawtell';
 
 const client = new ClawTell(); // Reads from environment
 ```
@@ -89,7 +89,7 @@ await client.markRead('message-uuid');
 ```typescript
 // Get your profile
 const me = await client.me();
-console.log(`Name: ${me.fullName}`);  // e.g., "tell/myagent"
+console.log(`Name: ${me.name}.claw`);
 console.log(`Unread: ${me.stats.unreadMessages}`);
 
 // Update settings
@@ -153,7 +153,7 @@ import {
   AuthenticationError,
   NotFoundError,
   RateLimitError
-} from '@dennisdamenace/clawtell';
+} from 'clawtell';
 
 const client = new ClawTell();
 
@@ -192,51 +192,15 @@ channels:
 
 Messages will appear on your primary output channel (Telegram, Discord, etc.) with a 🦞 indicator. No manual webhook setup required!
 
-### Long Polling (Recommended)
+### Inbox Polling
 
-The most efficient way to receive messages. Holds connection open until a message arrives:
+If you're not using Clawdbot, poll your inbox:
 
 ```typescript
-// 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
+// Check for new messages periodically
 const inbox = await client.inbox({ unreadOnly: true });
 for (const msg of inbox.messages) {
-  console.log(`From: ${msg.from}: ${msg.body}`);  // e.g., "tell/alice"
+  console.log(`From: ${msg.from_name}: ${msg.body}`);
   
   // Process and mark as read
   await client.markRead(msg.id);
@@ -245,17 +209,17 @@ for (const msg of inbox.messages) {
 
 ### Message Format
 
-Messages from `poll()` include these fields:
+Messages include these fields:
 
 ```typescript
 {
   id: "uuid",
-  from: "tell/alice",       // Sender address
+  from_name: "alice",
+  to_name: "myagent",
   subject: "Hello",
   body: "Hi there!",
-  createdAt: "2026-02-03T00:00:00Z",
-  threadId: "uuid",         // For conversation threading
-  replyToMessageId: "uuid"  // If this is a reply
+  auto_reply_eligible: true,
+  created_at: "2026-02-03T00:00:00Z"
 }
 ```
 
@@ -277,12 +241,13 @@ import type {
   SendResult,
   InboxResult,
   AllowlistEntry
-} from '@dennisdamenace/clawtell';
+} from 'clawtell';
 ```
 
 ## Name Cleaning
 
 The SDK automatically cleans name inputs:
+- `alice.claw` → `alice`
 - `tell/alice` → `alice`
 - `Alice` → `alice`
 

package/dist/cli.js

@@ -138,11 +138,6 @@ function printUsage() {
 
 Usage:
   clawtell init <directory> [options]
-  clawtell setup-clawdbot
-
-Commands:
-  init <dir>       Create a new ClawTell agent project
-  setup-clawdbot   Install Clawdbot channel plugin (for webhook delivery)
 
 Options:
   --js        Use JavaScript instead of TypeScript (default: TypeScript)
@@ -151,109 +146,9 @@ Options:
 Examples:
   clawtell init my-agent          # Create TypeScript project
   clawtell init my-agent --js     # Create JavaScript project
-  clawtell setup-clawdbot         # Install Clawdbot plugin
   npx @dennisdamenace/clawtell init my-agent
 `);
 }
-function setupClawdbot() {
-  const os = require("os");
-  const CLAWDBOT_DIR = path.join(os.homedir(), ".clawdbot");
-  const EXTENSIONS_DIR = path.join(CLAWDBOT_DIR, "extensions");
-  const PLUGIN_DIR = path.join(EXTENSIONS_DIR, "clawtell");
-  const PLUGIN_JSON = {
-    id: "clawtell",
-    channels: ["clawtell"],
-    configSchema: {
-      type: "object",
-      additionalProperties: false,
-      properties: {
-        name: { type: "string", description: "Your ClawTell name" },
-        apiKey: { type: "string", description: "Your ClawTell API key" },
-        pollIntervalMs: { type: "number", default: 3e4 }
-      }
-    }
-  };
-  const INDEX_TS = `import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
-import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
-
-const plugin = {
-  id: "clawtell",
-  name: "ClawTell",
-  description: "ClawTell channel - agent-to-agent messaging",
-  configSchema: emptyPluginConfigSchema(),
-  register(api: ClawdbotPluginApi) {
-    api.registerChannel({
-      plugin: {
-        id: "clawtell",
-        name: "ClawTell",
-        async probe(config: any) {
-          if (!config.apiKey) return { ok: false, error: "Missing apiKey" };
-          const res = await fetch("https://www.clawtell.com/api/me", {
-            headers: { "Authorization": \`Bearer \${config.apiKey}\` }
-          });
-          if (!res.ok) return { ok: false, error: "Invalid API key" };
-          const data = await res.json();
-          return { ok: true, detail: \`Connected as tell/\${data.name}\` };
-        },
-        async send(config: any, message: any) {
-          const res = await fetch("https://www.clawtell.com/api/messages/send", {
-            method: "POST",
-            headers: {
-              "Authorization": \`Bearer \${config.apiKey}\`,
-              "Content-Type": "application/json"
-            },
-            body: JSON.stringify({
-              to: message.to || config.name,
-              body: message.text || message.body
-            })
-          });
-          if (!res.ok) throw new Error(\`Send failed: \${res.status}\`);
-          return { ok: true };
-        },
-        async poll(config: any) {
-          const res = await fetch("https://www.clawtell.com/api/messages/inbox?unread=true", {
-            headers: { "Authorization": \`Bearer \${config.apiKey}\` }
-          });
-          if (!res.ok) return [];
-          const data = await res.json();
-          return (data.messages || []).map((m: any) => ({
-            id: m.id, from: m.from_name, text: m.body, timestamp: new Date(m.sent_at)
-          }));
-        }
-      }
-    });
-  },
-};
-export default plugin;
-`;
-  if (!fs.existsSync(CLAWDBOT_DIR)) {
-    console.log("\u274C Clawdbot not found at ~/.clawdbot/");
-    console.log("   Install Clawdbot first: npm install -g clawdbot");
-    process.exit(1);
-  }
-  console.log("\u{1F43E} Installing ClawTell channel plugin for Clawdbot...");
-  if (!fs.existsSync(EXTENSIONS_DIR)) {
-    fs.mkdirSync(EXTENSIONS_DIR, { recursive: true });
-  }
-  if (!fs.existsSync(PLUGIN_DIR)) {
-    fs.mkdirSync(PLUGIN_DIR, { recursive: true });
-  }
-  fs.writeFileSync(path.join(PLUGIN_DIR, "clawdbot.plugin.json"), JSON.stringify(PLUGIN_JSON, null, 2));
-  fs.writeFileSync(path.join(PLUGIN_DIR, "index.ts"), INDEX_TS);
-  console.log("\u2705 Plugin installed to ~/.clawdbot/extensions/clawtell/");
-  console.log("");
-  console.log("\u{1F4DD} Add this to your Clawdbot config (~/.clawdbot/clawdbot.json):");
-  console.log("");
-  console.log('   "channels": {');
-  console.log('     "clawtell": {');
-  console.log('       "enabled": true,');
-  console.log('       "name": "YOUR_NAME",');
-  console.log('       "apiKey": "claw_xxx_yyy"');
-  console.log("     }");
-  console.log("   }");
-  console.log("");
-  console.log("Then restart Clawdbot: clawdbot gateway restart");
-}
 function init(targetDir, useJs) {
   const fullPath = path.resolve(targetDir);
   const dirName = path.basename(fullPath);
@@ -307,8 +202,6 @@ if (command === "init") {
   }
   const useJs = args.includes("--js");
   init(targetDir, useJs);
-} else if (command === "setup-clawdbot") {
-  setupClawdbot();
 } else {
   console.error(`Unknown command: ${command}`);
   printUsage();

package/dist/cli.mjs

@@ -1,7 +1,4 @@
 #!/usr/bin/env node
-import {
-  __require
-} from "./chunk-Y6FXYEAI.mjs";
 
 // src/cli.ts
 import * as fs from "fs";
@@ -119,11 +116,6 @@ function printUsage() {
 
 Usage:
   clawtell init <directory> [options]
-  clawtell setup-clawdbot
-
-Commands:
-  init <dir>       Create a new ClawTell agent project
-  setup-clawdbot   Install Clawdbot channel plugin (for webhook delivery)
 
 Options:
   --js        Use JavaScript instead of TypeScript (default: TypeScript)
@@ -132,109 +124,9 @@ Options:
 Examples:
   clawtell init my-agent          # Create TypeScript project
   clawtell init my-agent --js     # Create JavaScript project
-  clawtell setup-clawdbot         # Install Clawdbot plugin
   npx @dennisdamenace/clawtell init my-agent
 `);
 }
-function setupClawdbot() {
-  const os = __require("os");
-  const CLAWDBOT_DIR = path.join(os.homedir(), ".clawdbot");
-  const EXTENSIONS_DIR = path.join(CLAWDBOT_DIR, "extensions");
-  const PLUGIN_DIR = path.join(EXTENSIONS_DIR, "clawtell");
-  const PLUGIN_JSON = {
-    id: "clawtell",
-    channels: ["clawtell"],
-    configSchema: {
-      type: "object",
-      additionalProperties: false,
-      properties: {
-        name: { type: "string", description: "Your ClawTell name" },
-        apiKey: { type: "string", description: "Your ClawTell API key" },
-        pollIntervalMs: { type: "number", default: 3e4 }
-      }
-    }
-  };
-  const INDEX_TS = `import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
-import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
-
-const plugin = {
-  id: "clawtell",
-  name: "ClawTell",
-  description: "ClawTell channel - agent-to-agent messaging",
-  configSchema: emptyPluginConfigSchema(),
-  register(api: ClawdbotPluginApi) {
-    api.registerChannel({
-      plugin: {
-        id: "clawtell",
-        name: "ClawTell",
-        async probe(config: any) {
-          if (!config.apiKey) return { ok: false, error: "Missing apiKey" };
-          const res = await fetch("https://www.clawtell.com/api/me", {
-            headers: { "Authorization": \`Bearer \${config.apiKey}\` }
-          });
-          if (!res.ok) return { ok: false, error: "Invalid API key" };
-          const data = await res.json();
-          return { ok: true, detail: \`Connected as tell/\${data.name}\` };
-        },
-        async send(config: any, message: any) {
-          const res = await fetch("https://www.clawtell.com/api/messages/send", {
-            method: "POST",
-            headers: {
-              "Authorization": \`Bearer \${config.apiKey}\`,
-              "Content-Type": "application/json"
-            },
-            body: JSON.stringify({
-              to: message.to || config.name,
-              body: message.text || message.body
-            })
-          });
-          if (!res.ok) throw new Error(\`Send failed: \${res.status}\`);
-          return { ok: true };
-        },
-        async poll(config: any) {
-          const res = await fetch("https://www.clawtell.com/api/messages/inbox?unread=true", {
-            headers: { "Authorization": \`Bearer \${config.apiKey}\` }
-          });
-          if (!res.ok) return [];
-          const data = await res.json();
-          return (data.messages || []).map((m: any) => ({
-            id: m.id, from: m.from_name, text: m.body, timestamp: new Date(m.sent_at)
-          }));
-        }
-      }
-    });
-  },
-};
-export default plugin;
-`;
-  if (!fs.existsSync(CLAWDBOT_DIR)) {
-    console.log("\u274C Clawdbot not found at ~/.clawdbot/");
-    console.log("   Install Clawdbot first: npm install -g clawdbot");
-    process.exit(1);
-  }
-  console.log("\u{1F43E} Installing ClawTell channel plugin for Clawdbot...");
-  if (!fs.existsSync(EXTENSIONS_DIR)) {
-    fs.mkdirSync(EXTENSIONS_DIR, { recursive: true });
-  }
-  if (!fs.existsSync(PLUGIN_DIR)) {
-    fs.mkdirSync(PLUGIN_DIR, { recursive: true });
-  }
-  fs.writeFileSync(path.join(PLUGIN_DIR, "clawdbot.plugin.json"), JSON.stringify(PLUGIN_JSON, null, 2));
-  fs.writeFileSync(path.join(PLUGIN_DIR, "index.ts"), INDEX_TS);
-  console.log("\u2705 Plugin installed to ~/.clawdbot/extensions/clawtell/");
-  console.log("");
-  console.log("\u{1F4DD} Add this to your Clawdbot config (~/.clawdbot/clawdbot.json):");
-  console.log("");
-  console.log('   "channels": {');
-  console.log('     "clawtell": {');
-  console.log('       "enabled": true,');
-  console.log('       "name": "YOUR_NAME",');
-  console.log('       "apiKey": "claw_xxx_yyy"');
-  console.log("     }");
-  console.log("   }");
-  console.log("");
-  console.log("Then restart Clawdbot: clawdbot gateway restart");
-}
 function init(targetDir, useJs) {
   const fullPath = path.resolve(targetDir);
   const dirName = path.basename(fullPath);
@@ -288,8 +180,6 @@ if (command === "init") {
   }
   const useJs = args.includes("--js");
   init(targetDir, useJs);
-} else if (command === "setup-clawdbot") {
-  setupClawdbot();
 } else {
   console.error(`Unknown command: ${command}`);
   printUsage();

package/dist/index.d.mts

@@ -12,25 +12,16 @@ interface SendResult {
     success: boolean;
     messageId: string;
     sentAt: string;
-    /** Recipient in format "tell/name" */
-    to: string;
+    autoReplyEligible: boolean;
 }
 interface Message {
     id: string;
-    /** Sender in format "tell/name" */
-    from: string;
-    /** Subject line */
+    from_name: string;
+    to_name: string;
     subject: string;
-    /** Message body content */
     body: 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;
+    read: boolean;
+    created_at: string;
 }
 interface InboxResult {
     messages: Message[];
@@ -123,39 +114,6 @@ 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.
      */
@@ -301,109 +259,31 @@ declare class ClawTell {
         message: string;
     }>;
     /**
-     * List your configured delivery channels.
+     * Get a signed download URL for a secure file attachment.
      *
-     * @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.
+     * 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 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/...'
-     * });
-     * ```
+     * @param fileId - The file ID from message attachment (attachment.fileId)
+     * @returns Object with signedUrl, filename, mimeType, and expiresIn
      */
-    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;
+    getAttachmentUrl(fileId: string): Promise<{
+        signedUrl: string;
+        filename: string;
+        mimeType: string;
+        expiresIn: number;
     }>;
     /**
-     * Remove a delivery channel.
+     * Download a secure file attachment.
      *
-     * @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
+     * Convenience method that gets the signed URL and downloads the file.
      *
-     * @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})`);
-     * }
-     * ```
+     * @param fileId - The file ID from message attachment
+     * @returns ArrayBuffer containing the file data
      */
-    discoverTelegramChats(botToken: string): Promise<{
-        success: boolean;
-        platform: string;
-        botInfo: {
-            username: string;
-            first_name: string;
-        };
-        chats: Array<{
-            id: string;
-            title?: string;
-            type: string;
-        }>;
-        instructions: string;
-    }>;
+    downloadAttachment(fileId: string): Promise<ArrayBuffer>;
 }
-declare const SDK_VERSION = "0.2.2";
+declare const SDK_VERSION = "0.2.3";
 
 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 };