matimo-examples 1.0.0

package/gmail/gmail-factory.ts

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * GMAIL 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:
+ *    GMAIL_ACCESS_TOKEN=ya29.xxxxxxxxxxxxx
+ *
+ * 2. Get a Gmail access token:
+ *    - Use OAuth2Handler to authenticate with Google
+ *    - Request these scopes:
+ *      • https://www.googleapis.com/auth/gmail.send (send emails)
+ *      • https://www.googleapis.com/auth/gmail.readonly (read emails)
+ *      • https://www.googleapis.com/auth/gmail.modify (drafts, delete)
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export GMAIL_ACCESS_TOKEN=your_token_here
+ *   npm run gmail:factory
+ *
+ * AVAILABLE TOOLS:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. gmail-send-email
+ *    Parameters: to (required), subject (required), body (required), [cc], [bcc]
+ *    Returns: { id, threadId, labelIds }
+ *    Example: Send an email to someone@example.com
+ *
+ * 2. gmail-list-messages
+ *    Parameters: [query], [maxResults], [pageToken]
+ *    Returns: { messages[], nextPageToken }
+ *    Example queries: "is:unread", "from:someone@example.com", "has:attachment"
+ *
+ * 3. gmail-get-message
+ *    Parameters: message_id, [format]
+ *    Format options: "minimal" (lightweight), "full" (complete with headers)
+ *    Returns: { payload { headers, body }, snippet }
+ *
+ * 4. gmail-create-draft
+ *    Parameters: to, subject, body, [cc], [bcc]
+ *    Returns: { id, message { id, threadId } }
+ *    Note: Draft is created but not sent - user edits then sends manually
+ *
+ * 5. gmail-delete-message
+ *    Parameters: message_id
+ *    Returns: { success }
+ *    Note: Permanently deletes the message
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { MatimoInstance } from 'matimo';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Run factory pattern examples
+ */
+async function runFactoryPatternExamples() {
+  // Parse CLI arguments
+  const args = process.argv.slice(2);
+  let userEmail = process.env.TEST_EMAIL || 'test@example.com';
+
+  for (const arg of args) {
+    if (arg.startsWith('--email:')) {
+      userEmail = arg.split(':')[1];
+    } else if (arg.startsWith('--email=')) {
+      userEmail = arg.split('=')[1];
+    }
+  }
+
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     Gmail Tools - Factory Pattern                      ║');
+  console.info('║     (Direct execution - simplest approach)             ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  const accessToken = process.env.GMAIL_ACCESS_TOKEN;
+  if (!accessToken) {
+    console.error('❌ Error: GMAIL_ACCESS_TOKEN not set in .env');
+    console.info('   Set it: export GMAIL_ACCESS_TOKEN="ya29...."');
+    console.info('   Or get a token from: https://developers.google.com/oauthplayground');
+    process.exit(1);
+  }
+
+  console.info(`📧 User Email: ${userEmail}\n`);
+
+  try {
+    // Initialize Matimo
+    console.info('🚀 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+    const matimoTools = matimo.listTools();
+    console.info(`📦 Loaded ${matimoTools.length} tools:\n`);
+    matimoTools.forEach((t) => {
+      console.info(`  • ${t.name}`);
+      console.info(`    ${t.description}\n`);
+    });
+
+    // Filter to Gmail tools
+    const gmailTools = matimoTools.filter((t) => t.name.startsWith('gmail-'));
+    console.info(`📧 Found ${gmailTools.length} Gmail tools\n`);
+
+    console.info('🧪 Testing Gmail Tools with Factory Pattern');
+    console.info('═'.repeat(60));
+
+    // Example 1: List Messages (GET emails)
+    console.info('\n📬 Example 1: List Your Recent Messages');
+    console.info('─'.repeat(60));
+    try {
+      const listResult = await matimo.execute('gmail-list-messages', {
+        maxResults: 5,
+        GMAIL_ACCESS_TOKEN: accessToken,
+      });
+      console.info('📤 Raw Result:', JSON.stringify(listResult, null, 2));
+
+      if (typeof listResult === 'object' && listResult !== null) {
+        const data = listResult as any;
+        if (data.data?.messages && Array.isArray(data.data.messages)) {
+          console.info(`✅ Found ${data.data.messages.length} recent messages:`);
+          data.data.messages.slice(0, 3).forEach((msg: any, idx: number) => {
+            console.info(`   ${idx + 1}. ID: ${msg.id}`);
+            console.info(`      Thread: ${msg.threadId}`);
+          });
+        } else if (data.messages && Array.isArray(data.messages)) {
+          console.info(`✅ Found ${data.messages.length} recent messages:`);
+          data.messages.slice(0, 3).forEach((msg: any, idx: number) => {
+            console.info(`   ${idx + 1}. ID: ${msg.id}`);
+            console.info(`      Thread: ${msg.threadId}`);
+          });
+        } else {
+          console.info('❌ Unexpected response format');
+        }
+      }
+    } catch (error) {
+      console.info(`❌ List failed: ${error instanceof Error ? error.message : String(error)}`);
+      console.info(JSON.stringify(error, null, 2));
+    }
+
+    // Example 2: Send Email
+    console.info('\n📧 Example 2: Send Email');
+    console.info('─'.repeat(60));
+    try {
+      // Simple API - just pass to, subject, body
+      // Matimo automatically converts to MIME format (defined in YAML)
+      const sendResult = await matimo.execute('gmail-send-email', {
+        to: userEmail,
+        subject: 'Hello from Matimo Factory Pattern',
+        body: 'This is a test email from the Factory pattern',
+        GMAIL_ACCESS_TOKEN: accessToken,
+      });
+      console.info('📤 Raw Result:', JSON.stringify(sendResult, null, 2));
+
+      if (typeof sendResult === 'object' && sendResult !== null) {
+        const data = sendResult as any;
+        if (data.data?.id) {
+          console.info(`✅ Email sent successfully!`);
+          console.info(`   Message ID: ${data.data.id}`);
+          console.info(`   Thread ID: ${data.data.threadId || 'N/A'}`);
+        } else if (data.id) {
+          console.info(`✅ Email sent successfully!`);
+          console.info(`   Message ID: ${data.id}`);
+          console.info(`   Thread ID: ${data.threadId || 'N/A'}`);
+        } else {
+          console.info('❌ Unexpected response format');
+        }
+      }
+    } catch (error) {
+      console.info(`❌ Send failed: ${error instanceof Error ? error.message : String(error)}`);
+      console.info(JSON.stringify(error, null, 2));
+    }
+
+    // Example 3: Create Draft
+    console.info('\n✏️  Example 3: Create Draft');
+    console.info('─'.repeat(60));
+    try {
+      // Simple API - just pass to, subject, body
+      // Matimo automatically converts to MIME format (defined in YAML)
+      const draftResult = await matimo.execute('gmail-create-draft', {
+        to: userEmail,
+        subject: 'Factory Pattern Draft',
+        body: 'This is a draft created by the Factory pattern',
+        GMAIL_ACCESS_TOKEN: accessToken,
+      });
+      console.info('📤 Raw Result:', JSON.stringify(draftResult, null, 2));
+
+      if (typeof draftResult === 'object' && draftResult !== null) {
+        const data = draftResult as any;
+        if (data.data?.id) {
+          console.info(`✅ Draft created successfully!`);
+          console.info(`   Draft ID: ${data.data.id}`);
+          console.info(`   Message ID: ${data.data.message?.id || 'N/A'}`);
+        } else if (data.id) {
+          console.info(`✅ Draft created successfully!`);
+          console.info(`   Draft ID: ${data.id}`);
+        } else {
+          console.info('❌ Unexpected response format');
+        }
+      }
+    } catch (error) {
+      console.info(`❌ Draft failed: ${error instanceof Error ? error.message : String(error)}`);
+      console.info(JSON.stringify(error, null, 2));
+    }
+
+    console.info('\n' + '═'.repeat(60));
+    console.info('✨ Factory Pattern Examples Complete!\n');
+    console.info('Usage:');
+    console.info('  npm run gmail:factory');
+    console.info('  npm run gmail:factory -- --email:your-email@gmail.com\n');
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+// Run the examples
+runFactoryPatternExamples().catch(console.error);

package/gmail/gmail-langchain.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * GMAIL 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 Gmail 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:
+ *    GMAIL_ACCESS_TOKEN=ya29.xxxxxxxxxxxxx
+ *    OPENAI_API_KEY=sk-xxxxxxxxxxxxx
+ *
+ * 2. Install dependencies:
+ *    npm install
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export GMAIL_ACCESS_TOKEN=your_token_here
+ *   export OPENAI_API_KEY=your_openai_key_here
+ *   npm run gmail:langchain
+ *
+ * WHAT IT DOES:
+ * ─────────────────────────────────────────────────────────────────────────
+ * This example shows an AI agent that can:
+ * 1. Check your recent emails
+ * 2. Send emails to you based on LLM reasoning
+ * 3. Create draft emails with AI-generated content
+ * 4. Respond naturally in conversation style
+ *
+ * Example conversation:
+ *   User: "Send me a test email"
+ *   Claude: "I'll send you a test email now..."
+ *   [Claude calls gmail-send-email tool]
+ *   Claude: "Done! Email sent to your address."
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createAgent } from 'langchain';
+import { ChatOpenAI } from '@langchain/openai';
+import { MatimoInstance, convertToolsToLangChain } from 'matimo';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Run AI Agent with Gmail tools
+ * The agent receives natural language requests and decides which Gmail tools to use
+ */
+async function runGmailAIAgent() {
+  // Parse CLI arguments
+  const args = process.argv.slice(2);
+  let userEmail = process.env.TEST_EMAIL || 'test@example.com';
+
+  for (const arg of args) {
+    if (arg.startsWith('--email:')) {
+      userEmail = arg.split(':')[1];
+    } else if (arg.startsWith('--email=')) {
+      userEmail = arg.split('=')[1];
+    }
+  }
+
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     Gmail AI Agent - LangChain + OpenAI               ║');
+  console.info('║     True autonomous agent with LLM reasoning          ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  // Check required environment variables
+  const accessToken = process.env.GMAIL_ACCESS_TOKEN;
+  if (!accessToken) {
+    console.error('❌ Error: GMAIL_ACCESS_TOKEN not set in .env');
+    console.info('   Set it: export GMAIL_ACCESS_TOKEN="ya29...."');
+    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(`📧 User Email: ${userEmail}`);
+  console.info(`🤖 Using OpenAI (GPT-4o-mini) as the AI agent\n`);
+
+  try {
+    // Initialize Matimo
+    console.info('🚀 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+    // Get Gmail tools and convert to LangChain format
+    console.info('📬 Loading Gmail tools...');
+    const matimoTools = matimo.listTools();
+    const gmailTools = matimoTools.filter((t) => t.name.startsWith('gmail-'));
+    console.info(`✅ Loaded ${gmailTools.length} Gmail tools\n`);
+
+    // Convert to LangChain tools
+    const langchainTools = await convertToolsToLangChain(gmailTools, matimo, {
+      GMAIL_ACCESS_TOKEN: accessToken,
+    });
+
+    // 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,
+    });
+
+    // Define agent tasks (natural language requests)
+    const userRequests = [
+      {
+        title: 'Example 1: Check recent emails',
+        request: 'How many recent emails do I have? List the first 3.',
+      },
+      {
+        title: 'Example 2: Send a test email',
+        request: `Please send a test email to ${userEmail} with subject "Hello from AI Agent" and body "This email was sent by an AI agent using Matimo tools."`,
+      },
+      {
+        title: 'Example 3: Create an automated draft',
+        request: `Create a draft email to ${userEmail} about "Weekly Summary" with a professional greeting and a summary of what this example demonstrated.`,
+      },
+    ];
+
+    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
+runGmailAIAgent().catch(console.error);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "matimo-examples",
+  "version": "1.0.0",
+  "description": "Matimo SDK examples - Factory Pattern, Decorator Pattern, and LangChain integration with Slack and Gmail",
+  "type": "module",
+  "dependencies": {
+    "@langchain/core": "^1.1.18",
+    "@langchain/openai": "^1.2.4",
+    "langchain": "^1.2.16",
+    "dotenv": "^17.2.3",
+    "zod": "^4.3.6",
+    "matimo": "0.1.0-alpha.4",
+    "@matimo/gmail": "0.1.0-alpha.4",
+    "@matimo/slack": "0.1.0-alpha.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "better-sqlite3": "^12.6.2",
+    "typescript": "^5.9.3",
+    "tsx": "^4.21.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "agent:decorator": "tsx agents/decorator-pattern-agent.ts",
+    "agent:factory": "tsx agents/factory-pattern-agent.ts",
+    "agent:langchain": "tsx agents/langchain-agent.ts",
+    "gmail:factory": "tsx gmail/gmail-factory.ts",
+    "gmail:decorator": "tsx gmail/gmail-decorator.ts",
+    "gmail:langchain": "tsx gmail/gmail-langchain.ts",
+    "slack:factory": "tsx slack/slack-factory.ts",
+    "slack:decorator": "tsx slack/slack-decorator.ts",
+    "slack:langchain": "tsx slack/slack-langchain.ts",
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}