matimo-examples 0.1.0-alpha.11

package/twilio/README.md

@@ -0,0 +1,309 @@
+# Twilio Tools Examples
+
+Example directory contains **3 example patterns** showing different ways to use Matimo's Twilio tools:
+
+1. **Factory Pattern** - Direct SDK execution (simplest)
+2. **Decorator Pattern** - Class-based with `@tool` decorators
+3. **LangChain Pattern** - AI-driven with OpenAI agent
+
+All examples demonstrate real Twilio Messaging API operations (send SMS, send MMS, retrieve messages, list history).
+
+---
+
+## 🚀 Quick Start
+
+### 1. Create a Twilio Account
+
+1. Go to [twilio.com/try-twilio](https://www.twilio.com/try-twilio) and sign up for a free account
+2. After verifying your email and phone number, you'll land on the **Twilio Console** dashboard
+
+### 2. Find Your Account SID and Auth Token
+
+On the [Twilio Console dashboard](https://console.twilio.com), look for the **Account Info** section:
+
+- **Account SID** — a 34-character identifier starting with `AC`. Acts as your username for every API call.
+- **Auth Token** — a 32-character secret key. Click the **eye (👁) icon** to reveal it.
+
+> ⚠️ **Keep both values secret.** Do not commit them to version control.
+
+### 3. Get a Phone Number
+
+1. In the Console sidebar, go to **Phone Numbers → Manage → Buy a Number**
+2. Choose a number with SMS capability
+3. Click **Buy** (free trial credit covers this)
+4. This will be your `TWILIO_FROM_NUMBER`
+
+> **Trial accounts**: You can also use the number auto-assigned to your trial account, shown on the Console dashboard.
+
+### 4. Verify Your "To" Number (Trial Accounts Only)
+
+Free trial accounts can only send messages to **Verified Caller IDs**:
+
+1. Go to **Phone Numbers → Manage → Verified Caller IDs**
+2. Click **Add a new Caller ID**
+3. Enter the phone number you want to send messages to
+4. Complete the verification call or SMS
+
+### 5. Set Up Environment Variables
+
+Create or update `.env` in `examples/tools/`:
+
+```env
+TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+TWILIO_AUTH_TOKEN=your_auth_token_here
+TWILIO_FROM_NUMBER=+15557122661
+TWILIO_TO_NUMBER=+15558675310
+OPENAI_API_KEY=sk-your-openai-key-here   # Required for LangChain example only
+```
+
+> **Note:** All phone numbers must be in **E.164 format** (e.g. `+15551234567`).  
+> Matimo automatically handles Basic Auth encoding — no manual base64 encoding required.
+
+### 6. Run Examples
+
+```bash
+# From examples/tools/ directory
+
+# Factory Pattern (simplest, direct API calls)
+pnpm twilio:factory
+
+# Decorator Pattern (class-based OOP approach)
+pnpm twilio:decorator
+
+# LangChain Pattern (AI-driven agent with OpenAI)
+pnpm twilio:langchain
+```
+
+---
+
+## 📚 Examples Overview
+
+### 1. Factory Pattern (`twilio-factory.ts`)
+
+**Best for:** Scripts, quick tests, CLI tools
+
+**What it does:**
+- ✅ Direct tool execution with `matimo.execute()`
+- ✅ Validates environment variables before running
+- ✅ Sends an SMS via `twilio-send-sms`
+- ✅ Retrieves the sent message via `twilio-get-message`
+- ✅ Lists recent messages via `twilio-list-messages`
+- ✅ Simplest implementation
+
+**Run it:**
+```bash
+pnpm twilio:factory
+```
+
+**Key Code:**
+```typescript
+const matimo = await MatimoInstance.init('./tools');
+
+// Send SMS
+await matimo.execute('twilio-send-sms', {
+  account_sid: process.env.TWILIO_ACCOUNT_SID,
+  to: '+15558675310',
+  from: '+15557122661',
+  body: 'Hello from Matimo!'
+});
+
+// List recent messages
+await matimo.execute('twilio-list-messages', {
+  account_sid: process.env.TWILIO_ACCOUNT_SID,
+  page_size: 5
+});
+```
+
+**File:** [twilio-factory.ts](twilio-factory.ts)
+
+---
+
+### 2. Decorator Pattern (`twilio-decorator.ts`)
+
+**Best for:** Object-oriented design, class-based applications, service wrappers
+
+**What it does:**
+- ✅ Class methods decorated with `@tool`
+- ✅ Automatic tool execution via decorators
+- ✅ Account SID bound at construction time and reused
+- ✅ Sends SMS, retrieves messages, lists history
+- ✅ OOP-friendly approach
+
+**Run it:**
+```bash
+pnpm twilio:decorator
+```
+
+**Key Code:**
+```typescript
+class TwilioDecoratorAgent {
+  constructor(private readonly accountSid: string) {}
+
+  @tool('twilio-send-sms')
+  async sendSms(account_sid: string, to: string, from: string, body: string) {
+    // @tool decorator auto-executes via matimo.execute()
+    return undefined;
+  }
+
+  @tool('twilio-list-messages')
+  async listMessages(account_sid: string, page_size?: number) {
+    return undefined;
+  }
+}
+
+const agent = new TwilioDecoratorAgent(process.env.TWILIO_ACCOUNT_SID!);
+await agent.sendSms(accountSid, '+15558675310', '+15557122661', 'Hello!');
+```
+
+**File:** [twilio-decorator.ts](twilio-decorator.ts)
+
+---
+
+### 3. LangChain AI Agent (`twilio-langchain.ts`)
+
+**Best for:** True autonomous agents with AI reasoning
+
+**What it does:**
+- ✅ AI agent (OpenAI GPT-4o-mini) decides which Twilio tools to use
+- ✅ Takes natural language instructions
+- ✅ Autonomously executes Twilio operations
+- ✅ Processes results and responds naturally
+- ✅ Multi-step reasoning (e.g. send then verify delivery status)
+
+**Run it:**
+```bash
+pnpm twilio:langchain
+```
+
+**Example Conversation:**
+```
+User: "Send a test SMS to my verified number and check its delivery status"
+AI Agent: I'll send the SMS first using twilio-send-sms...
+[AI calls twilio-send-sms tool]
+AI Agent: Message sent with SID SM1234... Now checking delivery status...
+[AI calls twilio-get-message tool]
+AI Agent: The message was delivered successfully. Status: delivered.
+```
+
+**Key Code:**
+```typescript
+const agent = await createAgent({
+  model: new ChatOpenAI({ modelName: 'gpt-4o-mini' }),
+  tools: langchainTools  // AI picks which Twilio tools to use
+});
+
+const response = await agent.invoke({
+  messages: [{ role: 'user', content: 'Send a test SMS to my number' }]
+});
+```
+
+**File:** [twilio-langchain.ts](twilio-langchain.ts)
+
+---
+
+## 🛠️ Available Twilio Tools (4 Total)
+
+All patterns have access to these 4 Twilio tools:
+
+| Tool | Method | Description |
+|------|--------|-------------|
+| `twilio-send-sms` | POST | Send an SMS message |
+| `twilio-send-mms` | POST | Send an MMS message with media |
+| `twilio-get-message` | GET | Retrieve a message by SID |
+| `twilio-list-messages` | GET | List messages with optional filters |
+
+### Tool Parameters
+
+#### `twilio-send-sms`
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `account_sid` | string | ✅ | Your Twilio Account SID (`AC...`) |
+| `to` | string | ✅ | Recipient phone number (E.164) |
+| `from` | string | ✅ | Twilio phone number (E.164) |
+| `body` | string | ✅ | SMS message text |
+| `status_callback` | string | ❌ | URL for delivery status webhooks |
+
+#### `twilio-send-mms`
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `account_sid` | string | ✅ | Your Twilio Account SID (`AC...`) |
+| `to` | string | ✅ | Recipient phone number (E.164) |
+| `from` | string | ✅ | Twilio phone number (E.164) |
+| `media_url` | string | ✅ | Publicly accessible URL of the media file |
+| `body` | string | ❌ | Optional text caption |
+| `status_callback` | string | ❌ | URL for delivery status webhooks |
+
+#### `twilio-get-message`
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `account_sid` | string | ✅ | Your Twilio Account SID (`AC...`) |
+| `message_sid` | string | ✅ | Message SID (`SM...`) to retrieve |
+
+#### `twilio-list-messages`
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `account_sid` | string | ✅ | Your Twilio Account SID (`AC...`) |
+| `to` | string | ❌ | Filter by recipient number |
+| `from` | string | ❌ | Filter by sender number |
+| `date_sent` | string | ❌ | Filter by date (YYYY-MM-DD) |
+| `page_size` | number | ❌ | Results per page (default 50, max 1000) |
+
+---
+
+## 🧪 Trial Account Limitations
+
+| Limitation | Details |
+|-----------|---------|
+| **Daily message limit** | 50 messages/day |
+| **Recipients** | Must be Verified Caller IDs only |
+| **Trial prefix** | All outgoing messages include `"Sent from your Twilio trial account -"` |
+| **Geographic reach** | Sending to some international numbers may be restricted |
+| **Phone numbers** | 1 trial number provided free |
+| **WhatsApp** | Not available on trial |
+
+To remove these limitations, [upgrade to a paid account](https://console.twilio.com/us1/billing/upgrade).
+
+---
+
+## 🔧 Troubleshooting
+
+### `❌ Error 21659: From number is not a valid, SMS-capable Twilio number`
+Your `TWILIO_FROM_NUMBER` is not a Twilio number on your account, or it doesn't have SMS capability.  
+**Fix:** Go to [Phone Numbers → Manage → Active Numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/active) and confirm the number is SMS-capable.
+
+### `❌ Error 21211: Invalid To phone number`
+The `to` number is not in E.164 format or is not a valid phone number.  
+**Fix:** Use format `+15551234567` (country code + number, no dashes or spaces).
+
+### `❌ Error 21408: Permission to send to this region is not enabled`
+Your account doesn't have permission to send to that country.  
+**Fix:** Go to [Messaging → Settings → Geo Permissions](https://console.twilio.com/us1/develop/sms/settings/geo-permissions) and enable the target region.
+
+### `❌ Error 21266: Unverified phone number in To field during trial`
+You're on a trial account and the recipient number is not a Verified Caller ID.  
+**Fix:** Add the number at [Phone Numbers → Manage → Verified Caller IDs](https://console.twilio.com/us1/develop/phone-numbers/manage/verified).
+
+### `❌ 401 Unauthorized / Error 20003: Authentication Failed`
+Your `TWILIO_ACCOUNT_SID` or `TWILIO_AUTH_TOKEN` is incorrect.  
+**Fix:** Copy both values directly from the [Console dashboard](https://console.twilio.com). Matimo handles Basic Auth encoding automatically.
+
+### `TWILIO_ACCOUNT_SID not set in .env`
+The `account_sid` parameter is required for all Twilio tools.  
+**Fix:** Add `TWILIO_ACCOUNT_SID=ACxxxxxxxx` to `examples/tools/.env`.
+
+### Messages have an unexpected prefix
+Trial accounts automatically prepend `"Sent from your Twilio trial account - "` to all messages. This is removed when you upgrade to a paid account.
+
+### `OPENAI_API_KEY not set` (LangChain example only)
+The LangChain agent requires an OpenAI API key.  
+**Fix:** Get one at [platform.openai.com/api-keys](https://platform.openai.com/api-keys) and add `OPENAI_API_KEY=sk-...` to your `.env`.
+
+---
+
+## 🔗 Related Documentation
+
+- [Matimo Twilio Package](../../../packages/twilio/README.md)
+- [Twilio Messages API Reference](https://www.twilio.com/docs/messaging/api/message-resource)
+- [Twilio Console](https://console.twilio.com)
+- [Twilio Free Trial Guide](https://www.twilio.com/docs/messaging/guides/how-to-use-your-free-trial-account)
+- [Matimo SDK Docs](../../../packages/core/README.md)

package/twilio/twilio-decorator.ts

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * TWILIO TOOLS - DECORATOR PATTERN EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: Decorator Pattern with @tool
+ * ─────────────────────────────────────────────────────────────────────────
+ * Uses TypeScript @tool decorators to wrap Twilio tool calls in a class.
+ *
+ * Use this pattern when:
+ * ✅ Building class-based applications
+ * ✅ Encapsulating tool logic in services
+ * ✅ Adding custom methods that combine multiple tools
+ * ✅ Need reusable tool wrappers
+ * ✅ Object-oriented design preferred
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Create .env file:
+ *    TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ *    TWILIO_AUTH_TOKEN=your_auth_token_here
+ *    TWILIO_FROM_NUMBER=+15557122661
+ *    TWILIO_TO_NUMBER=+15558675310
+ *
+ *    Matimo automatically handles base64 Basic Auth encoding — no extra steps!
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   pnpm twilio:decorator
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { MatimoInstance, tool, setGlobalMatimoInstance } from 'matimo';
+
+/**
+ * Decorator Pattern Agent - Uses @tool decorators for Twilio messaging operations.
+ * The account_sid is bound at construction time and reused in all tool calls.
+ */
+class TwilioDecoratorAgent {
+  constructor(private readonly accountSid: string) {}
+
+  /**
+   * Send an SMS message - automatically executes via @tool decorator
+   */
+  @tool('twilio-send-sms')
+  async sendSms(
+    account_sid: string,
+    to: string,
+    from: string,
+    body: string,
+    status_callback?: string
+  ): Promise<unknown> {
+    // Decorator automatically calls: matimo.execute('twilio-send-sms', { account_sid, to, from, body, status_callback })
+    return undefined;
+  }
+
+  /**
+   * Send an MMS message with media - automatically executes via @tool decorator
+   */
+  @tool('twilio-send-mms')
+  async sendMms(
+    account_sid: string,
+    to: string,
+    from: string,
+    media_url: string,
+    body?: string
+  ): Promise<unknown> {
+    // Decorator automatically calls: matimo.execute('twilio-send-mms', { account_sid, to, from, media_url, body })
+    return undefined;
+  }
+
+  /**
+   * Fetch a message by SID - automatically executes via @tool decorator
+   */
+  @tool('twilio-get-message')
+  async getMessage(account_sid: string, message_sid: string): Promise<unknown> {
+    // Decorator automatically calls: matimo.execute('twilio-get-message', { account_sid, message_sid })
+    return undefined;
+  }
+
+  /**
+   * List messages with optional filters - automatically executes via @tool decorator
+   */
+  @tool('twilio-list-messages')
+  async listMessages(
+    account_sid: string,
+    to?: string,
+    from?: string,
+    date_sent?: string,
+    page_size?: number
+  ): Promise<unknown> {
+    // Decorator automatically calls: matimo.execute('twilio-list-messages', { account_sid, to, from, date_sent, page_size })
+    return undefined;
+  }
+
+  // ── Convenience helpers that bind account_sid automatically ──────────────
+
+  /** Send SMS using the bound account SID */
+  async sms(to: string, from: string, body: string): Promise<unknown> {
+    return this.sendSms(this.accountSid, to, from, body);
+  }
+
+  /** Send MMS using the bound account SID */
+  async mms(to: string, from: string, mediaUrl: string, body?: string): Promise<unknown> {
+    return this.sendMms(this.accountSid, to, from, mediaUrl, body);
+  }
+
+  /** Fetch a message using the bound account SID */
+  async fetch(messageSid: string): Promise<unknown> {
+    return this.getMessage(this.accountSid, messageSid);
+  }
+
+  /** List recent messages using the bound account SID */
+  async list(
+    options: { to?: string; from?: string; dateSent?: string; pageSize?: number } = {}
+  ): Promise<unknown> {
+    return this.listMessages(
+      this.accountSid,
+      options.to,
+      options.from,
+      options.dateSent,
+      options.pageSize
+    );
+  }
+}
+
+/**
+ * Run decorator pattern examples
+ */
+async function runTwilioDecoratorExamples() {
+  console.info('╔════════════════════════════════════════════════════════╗');
+  console.info('║     Twilio Tools - Decorator Pattern                   ║');
+  console.info('║     (Uses @tool decorators for automatic execution)    ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  // Validate required environment variables
+  const accountSid = process.env.TWILIO_ACCOUNT_SID;
+  const authToken = process.env.TWILIO_AUTH_TOKEN;
+  const fromNumber = process.env.TWILIO_FROM_NUMBER;
+  const toNumber = process.env.TWILIO_TO_NUMBER;
+
+  if (!accountSid) {
+    console.info('🔐 Warning: TWILIO_ACCOUNT_SID not set in environment');
+    console.info('   Set it: export TWILIO_ACCOUNT_SID="ACxxxxxxxxxx"');
+    console.info('   Get it from: https://console.twilio.com\n');
+  }
+
+  if (!authToken) {
+    console.info('🔐 Warning: TWILIO_AUTH_TOKEN not set');
+    console.info('   Set it: export TWILIO_AUTH_TOKEN="your_auth_token"\n');
+  }
+
+  if (!fromNumber || !toNumber) {
+    console.info('📱 Warning: TWILIO_FROM_NUMBER or TWILIO_TO_NUMBER not set\n');
+  }
+
+  if (!accountSid || !authToken || !fromNumber || !toNumber) {
+    console.info('⚠️  Missing credentials — skipping live API calls.\n');
+  }
+
+  console.info(`🔑 Account SID: ${accountSid ? 'Configured' : '(not set)'}`);
+  console.info(`📤 From: ${fromNumber || '(not set)'}`);
+  console.info(`📥 To:   ${toNumber || '(not set)'}\n`);
+
+  try {
+    // Initialize Matimo with auto-discovery
+    console.info('🚀 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+    setGlobalMatimoInstance(matimo);
+
+    const allTools = matimo.listTools();
+    const twilioTools = allTools.filter((t) => t.name.startsWith('twilio-'));
+    console.info(`📦 Loaded ${allTools.length} total tools, ${twilioTools.length} Twilio tools\n`);
+
+    // Create agent with bound account SID
+    const agent = new TwilioDecoratorAgent(accountSid || 'ACxxxxxxxx');
+
+    console.info('🧪 Testing Twilio Tools with Decorator Pattern');
+    console.info('═'.repeat(60) + '\n');
+
+    // ── Example 1: List recent messages ─────────────────────────────────
+    console.info('📋 Example 1: List Recent Messages');
+    console.info('─'.repeat(60));
+    try {
+      const listResult = await agent.list({ pageSize: 5 });
+      const listData = (listResult as any).data || listResult;
+
+      if (listData.messages && Array.isArray(listData.messages)) {
+        console.info(`✅ Found ${listData.messages.length} recent message(s):`);
+        listData.messages.slice(0, 3).forEach((msg: any, idx: number) => {
+          console.info(
+            `   ${idx + 1}. ${msg.sid} — ${msg.status} — "${msg.body?.substring(0, 40)}"`
+          );
+        });
+      } else {
+        console.info(`ℹ️  Response: ${JSON.stringify(listData).substring(0, 100)}`);
+      }
+    } catch (error) {
+      console.info(`❌ Error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    console.info();
+
+    // ── Example 2: Send SMS ──────────────────────────────────────────────
+    console.info('💬 Example 2: Send SMS Message');
+    console.info('─'.repeat(60));
+
+    if (!accountSid || !fromNumber || !toNumber) {
+      console.info('⏭️  Skipping — credentials not set');
+    } else {
+      try {
+        const smsResult = await agent.sms(
+          toNumber,
+          fromNumber,
+          `👋 Hello from Matimo! Decorator pattern test at ${new Date().toISOString()}`
+        );
+        const smsData = (smsResult as any).data || smsResult;
+
+        if (smsData.sid) {
+          console.info(`✅ SMS queued successfully!`);
+          console.info(`   SID:    ${smsData.sid}`);
+          console.info(`   Status: ${smsData.status}`);
+          console.info(`   To:     ${smsData.to}`);
+
+          // ── Example 3: Fetch the sent message ────────────────────────────
+          console.info();
+          console.info('🔍 Example 3: Fetch the Sent Message');
+          console.info('─'.repeat(60));
+          const fetchResult = await agent.fetch(smsData.sid);
+          const fetchData = (fetchResult as any).data || fetchResult;
+
+          if (fetchData.sid) {
+            console.info(`✅ Message fetched!`);
+            console.info(`   Status:       ${fetchData.status}`);
+            console.info(`   Direction:    ${fetchData.direction}`);
+            console.info(`   Num Segments: ${fetchData.num_segments}`);
+          } else {
+            console.info(`❌ Failed: ${JSON.stringify(fetchData).substring(0, 100)}`);
+          }
+        } else {
+          console.info(`❌ SMS failed: ${JSON.stringify(smsData).substring(0, 100)}`);
+        }
+      } catch (error) {
+        console.info(`❌ Error: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    console.info();
+
+    // ── Example 4: List messages filtered by sender ──────────────────────
+    console.info('📊 Example 4: List Messages Filtered by Sender');
+    console.info('─'.repeat(60));
+
+    if (!accountSid || !fromNumber) {
+      console.info('⏭️  Skipping — credentials not set');
+    } else {
+      try {
+        const fromResult = await agent.list({ from: fromNumber, pageSize: 5 });
+        const fromData = (fromResult as any).data || fromResult;
+
+        if (fromData.messages && Array.isArray(fromData.messages)) {
+          console.info(`✅ Found ${fromData.messages.length} message(s) from ${fromNumber}`);
+          fromData.messages.slice(0, 3).forEach((msg: any, idx: number) => {
+            console.info(`   ${idx + 1}. ${msg.sid} — ${msg.status}`);
+          });
+        } else {
+          console.info(`ℹ️  Response: ${JSON.stringify(fromData).substring(0, 100)}`);
+        }
+      } catch (error) {
+        console.info(`❌ Error: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    console.info('\n' + '═'.repeat(60));
+    console.info('✨ Decorator Pattern Example Complete!');
+    console.info('═'.repeat(60) + '\n');
+  } catch (error) {
+    console.error('❌ Fatal error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+// Run the example
+runTwilioDecoratorExamples().catch((error) => {
+  console.error('❌ Unhandled error:', error);
+  process.exit(1);
+});