matimo-examples 0.1.0-alpha.11

package/twilio/twilio-factory.ts

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * TWILIO TOOLS - FACTORY PATTERN EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: SDK Factory Pattern
+ * ─────────────────────────────────────────────────────────────────────────
+ * Direct tool execution via MatimoInstance - the simplest way to use tools.
+ *
+ * Use this pattern when:
+ * ✅ Building simple scripts or CLI tools
+ * ✅ Direct API calls without abstraction
+ * ✅ Quick prototyping
+ * ✅ One-off tool execution
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Create .env file in project root:
+ *    TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ *    TWILIO_AUTH_TOKEN=your_auth_token_here
+ *    TWILIO_FROM_NUMBER=+15557122661
+ *    TWILIO_TO_NUMBER=+15558675310
+ *
+ * 2. Get Twilio credentials:
+ *    - Go to: https://console.twilio.com
+ *    - Account SID and Auth Token are on the dashboard
+ *    - Buy a phone number or use your trial number as TWILIO_FROM_NUMBER
+ *    - In trial mode, TWILIO_TO_NUMBER must be a verified caller ID
+ *    - Matimo automatically handles base64 encoding — no extra steps required!
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   pnpm twilio:factory
+ *
+ * AVAILABLE TOOLS:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. twilio-send-sms
+ *    Parameters: account_sid (required), to (required), from (required), body (required)
+ *    Optional: status_callback
+ *    Returns: Message resource with sid and status: queued
+ *
+ * 2. twilio-send-mms
+ *    Parameters: account_sid (required), to (required), from (required), media_url (required)
+ *    Optional: body, status_callback
+ *    Returns: Message resource with sid and num_media: "1"
+ *
+ * 3. twilio-get-message
+ *    Parameters: account_sid (required), message_sid (required)
+ *    Returns: Full Message resource with current status
+ *
+ * 4. twilio-list-messages
+ *    Parameters: account_sid (required)
+ *    Optional: to, from, date_sent, page_size
+ *    Returns: Paginated list of Message resources
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { MatimoInstance } from 'matimo';
+
+/**
+ * Run factory pattern examples for Twilio messaging tools
+ */
+async function runTwilioFactoryExamples() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     Twilio Tools - Factory Pattern                     ║');
+  console.info('║     (Direct execution - simplest approach)             ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  // Validate required environment variables
+  const accountSid = process.env.TWILIO_ACCOUNT_SID;
+  if (!accountSid) {
+    console.error('❌ Error: TWILIO_ACCOUNT_SID not set in .env');
+    console.info('   Set it: export TWILIO_ACCOUNT_SID="ACxxxxxxxxxx"');
+    console.info('   Get it from: https://console.twilio.com');
+    process.exit(1);
+  }
+
+  const authToken = process.env.TWILIO_AUTH_TOKEN;
+  if (!authToken) {
+    console.error('❌ Error: TWILIO_AUTH_TOKEN not set in .env');
+    console.info('   Set it: export TWILIO_AUTH_TOKEN="your_auth_token"');
+    console.info('   Get it from: https://console.twilio.com');
+    process.exit(1);
+  }
+
+  const fromNumber = process.env.TWILIO_FROM_NUMBER;
+  if (!fromNumber) {
+    console.error('❌ Error: TWILIO_FROM_NUMBER not set in .env');
+    console.info('   Set it: export TWILIO_FROM_NUMBER="+15557122661"');
+    console.info('   (Your Twilio phone number in E.164 format)');
+    process.exit(1);
+  }
+
+  const toNumber = process.env.TWILIO_TO_NUMBER;
+  if (!toNumber) {
+    console.error('❌ Error: TWILIO_TO_NUMBER not set in .env');
+    console.info('   Set it: export TWILIO_TO_NUMBER="+15558675310"');
+    console.info('   (In trial mode, must be a verified caller ID)');
+    process.exit(1);
+  }
+
+  console.info(`🔑 Account SID: Configured.`);
+  console.info(`📤 From: ${fromNumber}`);
+  console.info(`📥 To:   ${toNumber}\n`);
+
+  // Initialize Matimo with auto-discovery to find all @matimo/* packages
+  console.info('🚀 Initializing Matimo...');
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+  const allTools = matimo.listTools();
+  const twilioTools = allTools.filter((t) => t.name.startsWith('twilio-'));
+  console.info(`✅ Loaded ${allTools.length} tools total`);
+  console.info(
+    `🔧 Found ${twilioTools.length} Twilio tools: ${twilioTools.map((t) => t.name).join(', ')}\n`
+  );
+
+  console.info('════════════════════════════════════════════════════════════\n');
+  console.info('Running Examples:');
+  console.info('════════════════════════════════════════════════════════════\n');
+
+  try {
+    // ── EXAMPLE 1: List recent messages ──────────────────────────────────
+    console.info('1️⃣  Listing recent messages...');
+    const listResult = await matimo.execute('twilio-list-messages', {
+      account_sid: accountSid,
+      page_size: 5,
+    });
+    const listData = (listResult as any).data || listResult;
+
+    if (listData.messages && Array.isArray(listData.messages)) {
+      const messages = listData.messages;
+      console.info(`   ✅ Found ${messages.length} recent message(s)`);
+      messages.slice(0, 3).forEach((msg: any, idx: number) => {
+        console.info(
+          `      ${idx + 1}. ${msg.sid} — ${msg.direction} — ${msg.status} — "${msg.body?.substring(0, 40)}"`
+        );
+      });
+    } else {
+      console.info(
+        `   ℹ️  No messages found or unexpected response: ${JSON.stringify(listData).substring(0, 100)}`
+      );
+    }
+    console.info();
+
+    // ── EXAMPLE 2: Send SMS ───────────────────────────────────────────────
+    console.info('2️⃣  Sending SMS message...');
+    let sentMessageSid: string | undefined;
+    try {
+      const smsResult = await matimo.execute('twilio-send-sms', {
+        account_sid: accountSid,
+        to: toNumber,
+        from: fromNumber,
+        body: `Hello from Matimo! Factory pattern test at ${new Date().toISOString()}`,
+      });
+      const smsData = (smsResult as any).data || smsResult;
+
+      if (smsData.sid) {
+        sentMessageSid = smsData.sid;
+        console.info(`   ✅ SMS queued successfully!`);
+        console.info(`      SID:    ${smsData.sid}`);
+        console.info(`      Status: ${smsData.status}`);
+        console.info(`      To:     ${smsData.to}`);
+        console.info(`      From:   ${smsData.from}`);
+      } else {
+        console.info(`   ❌ SMS failed: ${JSON.stringify(smsData).substring(0, 100)}`);
+      }
+    } catch (smsErr: any) {
+      const msg = smsErr?.message || String(smsErr);
+      console.info(`   ⚠️  SMS skipped: ${msg}`);
+      if (fromNumber === toNumber) {
+        console.info(
+          `   ℹ️  Tip: TWILIO_FROM_NUMBER and TWILIO_TO_NUMBER must be different numbers.`
+        );
+        console.info(`          In trial mode, TWILIO_TO_NUMBER must be a verified caller ID.`);
+      }
+    }
+    console.info();
+
+    // ── EXAMPLE 3: Fetch the sent message ──────────────────────────────────
+    if (sentMessageSid) {
+      console.info('3️⃣  Fetching the sent message...');
+      try {
+        const fetchResult = await matimo.execute('twilio-get-message', {
+          account_sid: accountSid,
+          message_sid: sentMessageSid,
+        });
+        const fetchData = (fetchResult as any).data || fetchResult;
+
+        if (fetchData.sid) {
+          console.info(`   ✅ Message fetched!`);
+          console.info(`      SID:          ${fetchData.sid}`);
+          console.info(`      Status:       ${fetchData.status}`);
+          console.info(`      Direction:    ${fetchData.direction}`);
+          console.info(`      Num Segments: ${fetchData.num_segments}`);
+          console.info(`      Date Created: ${fetchData.date_created}`);
+        } else {
+          console.info(
+            `   ❌ Failed to fetch message: ${JSON.stringify(fetchData).substring(0, 100)}`
+          );
+        }
+      } catch (fetchErr: any) {
+        console.info(`   ⚠️  Fetch skipped: ${fetchErr?.message || fetchErr}`);
+      }
+      console.info();
+    } else {
+      console.info('3️⃣  Fetching sent message — skipped (no SMS was queued)');
+      console.info();
+    }
+
+    // ── EXAMPLE 4: List messages filtered by recipient ────────────────────
+    console.info('4️⃣  Listing messages filtered by recipient...');
+    const filteredResult = await matimo.execute('twilio-list-messages', {
+      account_sid: accountSid,
+      to: toNumber,
+      page_size: 5,
+    });
+    const filteredData = (filteredResult as any).data || filteredResult;
+
+    if (filteredData.messages && Array.isArray(filteredData.messages)) {
+      console.info(`   ✅ Found ${filteredData.messages.length} message(s) sent to ${toNumber}`);
+    } else {
+      console.info(`   ℹ️  Response: ${JSON.stringify(filteredData).substring(0, 100)}`);
+    }
+    console.info();
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+
+  console.info('════════════════════════════════════════════════════════════');
+  console.info('✨ Factory Pattern Example Complete!');
+  console.info('════════════════════════════════════════════════════════════\n');
+}
+
+runTwilioFactoryExamples().catch(console.error);

package/twilio/twilio-langchain.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * TWILIO TOOLS - LANGCHAIN AI AGENT EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: True AI Agent with OpenAI + LangChain
+ * ─────────────────────────────────────────────────────────────────────────
+ * This is a REAL AI agent that:
+ * 1. Takes natural language user requests
+ * 2. Uses OpenAI LLM (GPT-4o-mini) to decide which Twilio tools to use
+ * 3. Generates appropriate parameters based on context
+ * 4. Executes tools autonomously
+ * 5. Processes results and responds naturally
+ *
+ * Use this pattern when:
+ * ✅ Building true autonomous AI agents
+ * ✅ LLM should decide which tools to use
+ * ✅ Complex workflows with LLM reasoning
+ * ✅ Multi-step agentic processes
+ * ✅ User gives high-level instructions (not low-level API calls)
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Create .env file:
+ *    TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ *    TWILIO_AUTH_TOKEN=your_auth_token_here
+ *    TWILIO_FROM_NUMBER=+15557122661
+ *    TWILIO_TO_NUMBER=+15558675310
+ *    OPENAI_API_KEY=sk-xxxxxxxxxxxxx
+ *
+ *    Matimo automatically handles base64 Basic Auth encoding — no extra steps!
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   pnpm twilio:langchain
+ *
+ * WHAT IT DOES:
+ * ─────────────────────────────────────────────────────────────────────────
+ * This example shows an AI agent that can:
+ * 1. Check recent message history
+ * 2. Send SMS messages based on instructions
+ * 3. Retrieve message delivery status
+ * 4. Filter and search messages
+ *
+ * Example conversation:
+ *   User: "Send a test SMS to my phone number"
+ *   AI Agent: "I'll send a test SMS using twilio-send-sms..."
+ *   [AI Agent calls twilio-send-sms tool]
+ *   AI Agent: "Done! SMS sent successfully with SID: SM..."
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { createAgent } from 'langchain';
+import { ChatOpenAI } from '@langchain/openai';
+import { MatimoInstance, convertToolsToLangChain, ToolDefinition } from 'matimo';
+
+/**
+ * Run Twilio AI Agent with LangChain
+ * The agent receives natural language requests and decides which Twilio tools to use
+ */
+async function runTwilioAIAgent() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     Twilio AI Agent - LangChain + OpenAI               ║');
+  console.info('║     True autonomous agent with LLM reasoning           ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  // Check required environment variables
+  const accountSid = process.env.TWILIO_ACCOUNT_SID;
+  if (!accountSid) {
+    console.error('❌ Error: TWILIO_ACCOUNT_SID not set in .env');
+    console.info('   Set it: export TWILIO_ACCOUNT_SID="ACxxxxxxxxxx"');
+    console.info('   Get it from: https://console.twilio.com');
+    process.exit(1);
+  }
+
+  const authToken = process.env.TWILIO_AUTH_TOKEN;
+  if (!authToken) {
+    console.error('❌ Error: TWILIO_AUTH_TOKEN not set in .env');
+    console.info('   Set it: export TWILIO_AUTH_TOKEN="your_auth_token"');
+    console.info('   Get it from: https://console.twilio.com');
+    process.exit(1);
+  }
+
+  const fromNumber = process.env.TWILIO_FROM_NUMBER;
+  if (!fromNumber) {
+    console.error('❌ Error: TWILIO_FROM_NUMBER not set in .env');
+    console.info('   Set it: export TWILIO_FROM_NUMBER="+15557122661"');
+    process.exit(1);
+  }
+
+  const toNumber = process.env.TWILIO_TO_NUMBER;
+  if (!toNumber) {
+    console.error('❌ Error: TWILIO_TO_NUMBER not set in .env');
+    console.info('   Set it: export TWILIO_TO_NUMBER="+15558675310"');
+    process.exit(1);
+  }
+
+  const openaiKey = process.env.OPENAI_API_KEY;
+  if (!openaiKey) {
+    console.error('❌ Error: OPENAI_API_KEY not set in .env');
+    console.info('   Set it: export OPENAI_API_KEY="sk-..."');
+    process.exit(1);
+  }
+
+  console.info(`🔑 Account SID: Configured`);
+  console.info(`📤 From Number: ${fromNumber}`);
+  console.info(`📥 To Number:   ${toNumber}`);
+  console.info(`🤖 Using OpenAI (GPT-4o-mini) as the AI agent\n`);
+
+  try {
+    // Initialize Matimo with auto-discovery
+    console.info('🚀 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+    // Get Twilio tools and convert to LangChain format
+    console.info('📱 Loading Twilio tools...');
+    const allTools = matimo.listTools();
+    const twilioTools = allTools.filter((t) => t.name.startsWith('twilio-'));
+    console.info(`✅ Loaded ${twilioTools.length} Twilio tools\n`);
+
+    // List recent messages first to give agent context
+    console.info('📋 Fetching recent messages for agent context...');
+    const listResult = await matimo.execute('twilio-list-messages', {
+      account_sid: accountSid,
+      page_size: 5,
+    });
+    const listData = (listResult as any).data || listResult;
+    const recentCount = listData.messages?.length ?? 0;
+    console.info(`   ${recentCount} recent message(s) in account\n`);
+
+    // Convert Twilio tools to LangChain format using the Matimo integration
+    const langchainTools = await convertToolsToLangChain(twilioTools as ToolDefinition[], matimo);
+
+    // Initialize OpenAI LLM
+    console.info('🤖 Initializing OpenAI (GPT-4o-mini) LLM...');
+    const model = new ChatOpenAI({
+      modelName: 'gpt-4o-mini',
+      temperature: 0.7,
+    });
+
+    // Create agent
+    console.info('🔧 Creating agent...\n');
+    const agent = await createAgent({
+      model,
+      tools: langchainTools as any[], // Type casting for LangChain tools
+    });
+
+    // Define agent tasks (natural language requests)
+    const userRequests = [
+      {
+        title: 'Example 1: Check message history',
+        request: `Check my recent Twilio message history. How many messages are there and what are their statuses?`,
+      },
+      {
+        title: 'Example 2: Send a test SMS',
+        request: `Send a test SMS from ${fromNumber} to ${toNumber} saying "Hello from the Matimo AI Agent! LangChain integration test." Use account SID  .`,
+      },
+      {
+        title: 'Example 3: Check sent message status',
+        request: `List the 3 most recent messages sent from ${fromNumber} on my account    and describe their delivery status.`,
+      },
+    ];
+
+    console.info('🧪 Running AI Agent Tasks');
+    console.info('═'.repeat(60));
+
+    // Run each task through the agent
+    for (const task of userRequests) {
+      console.info(`\n${task.title}`);
+      console.info('─'.repeat(60));
+      console.info(`👤 User: "${task.request}"\n`);
+
+      try {
+        const response = await agent.invoke({
+          messages: [
+            {
+              role: 'user',
+              content: task.request,
+            },
+          ],
+        });
+
+        // Get the last message from the agent
+        const lastMessage = response.messages[response.messages.length - 1];
+        if (lastMessage) {
+          if (typeof lastMessage.content === 'string') {
+            console.info(`🤖 Agent: ${lastMessage.content}\n`);
+          } else {
+            console.info(`🤖 Agent:`, lastMessage.content, '\n');
+          }
+        }
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.info(`⚠️  Agent error: ${errorMsg}\n`);
+      }
+    }
+
+    console.info('═'.repeat(60));
+    console.info('✨ AI Agent Examples Complete!\n');
+    console.info('Key Features:');
+    console.info('  ✅ Real LLM (OpenAI) decides which tools to use');
+    console.info('  ✅ Natural language requests, not API calls');
+    console.info('  ✅ LLM generates tool parameters based on context');
+    console.info('  ✅ Agentic reasoning and decision-making\n');
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) {
+      console.error('Stack:', error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run the AI agent
+runTwilioAIAgent().catch(console.error);

package/web/web-decorator.ts

@@ -0,0 +1,52 @@
+import { MatimoInstance, setGlobalMatimoInstance, tool } from '@matimo/core';
+
+/**
+ * Example: Web tool using @tool decorator pattern
+ * Demonstrates class-based HTTP requests with automatic decoration
+ */
+class WebClient {
+  @tool('web')
+  async fetchUrl(url: string, timeout?: number): Promise<unknown> {
+    // Decorator automatically intercepts and executes via Matimo
+    return undefined;
+  }
+
+  @tool('web')
+  async postData(url: string, body: string, headers?: Record<string, string>): Promise<unknown> {
+    // Decorator automatically intercepts and executes via Matimo
+    return undefined;
+  }
+}
+
+async function decoratorExample() {
+  // Set up decorator support with autoDiscover
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+  setGlobalMatimoInstance(matimo);
+
+  console.info('=== Web Tool - Decorator Pattern ===\n');
+
+  const client = new WebClient();
+
+  try {
+    // Example 1: Fetch through decorated method
+    console.info('1. Fetching content via decorator\n');
+    const result1 = await client.fetchUrl('https://api.github.com/repos/tallclub/matimo');
+    console.info('Status:', (result1 as any).statusCode);
+    console.info('Size:', (result1 as any).contentLength);
+    console.info('---\n');
+
+    // Example 2: POST through decorated method
+    console.info('2. Posting data via decorator\n');
+    const result2 = await client.postData(
+      'https://httpbin.org/post',
+      JSON.stringify({ test: 'data' }),
+      { 'Content-Type': 'application/json' }
+    );
+    console.info('Status:', (result2 as any).statusCode);
+    console.info('---\n');
+  } catch (error: any) {
+    console.error('Error:', error.message);
+  }
+}
+
+decoratorExample();

package/web/web-factory.ts

@@ -0,0 +1,70 @@
+import { MatimoInstance } from '@matimo/core';
+
+/**
+ * Example: Web tool using factory pattern
+ * Demonstrates making HTTP requests and fetching web content
+ */
+async function webExample() {
+  // Initialize Matimo with autoDiscover to find all tools (core + providers)
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+  console.info('=== Web Tool - Factory Pattern ===\n');
+
+  try {
+    // Example 1: Fetch GitHub API
+    console.info('1. Fetching GitHub API (public endpoint)\n');
+    const github = await matimo.execute('web', {
+      url: 'https://api.github.com/repos/tallclub/matimo',
+    });
+
+    console.info('Status Code:', (github as any).statusCode);
+    console.info('Content size:', (github as any).size);
+    // Content is already parsed as an object
+    const githubData =
+      typeof (github as any).content === 'string'
+        ? JSON.parse((github as any).content)
+        : (github as any).content;
+    console.info('Repository:', githubData.full_name);
+    console.info('Description:', githubData.description);
+    console.info('---\n');
+
+    // Example 2: Fetch HTML content
+    console.info('2. Fetching HTML content\n');
+    const html = await matimo.execute('web', {
+      url: 'https://www.example.com',
+      timeout: 15000,
+    });
+
+    console.info('Status Code:', (html as any).statusCode);
+    console.info('Content type:', (html as any).contentType);
+    console.info('Content size:', (html as any).size);
+    const htmlContent =
+      typeof (html as any).content === 'string'
+        ? (html as any).content
+        : JSON.stringify((html as any).content);
+    console.info('Content preview:');
+    console.info(htmlContent.substring(0, 200));
+    console.info('---\n');
+
+    // Example 3: POST request
+    console.info('3. POST request (echo service)\n');
+    const post = await matimo.execute('web', {
+      url: 'https://httpbin.org/post',
+      method: 'POST',
+      body: JSON.stringify({ message: 'Hello from Matimo' }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    console.info('Status Code:', (post as any).statusCode);
+    const postContent =
+      typeof (post as any).content === 'string'
+        ? (post as any).content
+        : JSON.stringify((post as any).content);
+    console.info('Response:', postContent.substring(0, 200));
+    console.info('---\n');
+  } catch (error: any) {
+    console.error('Error fetching web content:', error.message);
+  }
+}
+
+webExample();