matimo-examples 0.1.0-alpha.11

package/notion/notion-factory.ts

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * NOTION TOOLS - FACTORY PATTERN EXAMPLE (REAL OPERATIONS)
+ * ============================================================================
+ *
+ * This example demonstrates REAL Notion API operations:
+ * 1. Search the workspace to discover databases
+ * 2. Query actual databases for real data
+ * 3. Create new pages with real data
+ * 4. Update existing pages
+ * 5. Show actual results from your Notion workspace
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { MatimoInstance } from '@matimo/core';
+
+/**
+ * Run factory pattern examples with REAL Notion operations
+ */
+async function runFactoryPatternExamples() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     NOTION - Factory Pattern (REAL OPERATIONS)        ║');
+  console.info('║     Discovering & querying your workspace             ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  const apiKey = process.env.NOTION_API_KEY;
+  if (!apiKey) {
+    console.error('❌ Error: NOTION_API_KEY not set in .env');
+    process.exit(1);
+  }
+
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+  const allTools = matimo.listTools();
+  const notionTools = allTools.filter((t) => t.name.startsWith('notion_'));
+
+  console.info(`✅ Found ${notionTools.length} Notion tools\n`);
+  console.info('DEBUG: Notion tools discovered:');
+  notionTools.forEach((tool) => {
+    console.info(`  • ${tool.name}`);
+  });
+  console.info('Debug: All available tools:');
+  allTools.forEach((tool) => {
+    console.info(`  • ${tool.name}`);
+  });
+  console.info('');
+  console.info('════════════════════════════════════════════════════════════\n');
+  console.info('REAL NOTION OPERATIONS:');
+  console.info('════════════════════════════════════════════════════════════\n');
+
+  try {
+    // STEP 1: List all databases in workspace
+    console.info('1️⃣  DISCOVERING YOUR WORKSPACE...\n');
+    const listResult = (await matimo.execute('notion_list_databases', {
+      page_size: 10,
+    })) as any;
+
+    const databases = listResult.data?.results || [];
+    if (databases.length === 0) {
+      console.info('   ℹ️  No databases found. Create and share one first.\n');
+      return;
+    }
+
+    console.info(`✅ Found ${databases.length} database(s) in workspace\n`);
+
+    const foundDatabase = databases[0];
+    const dbTitle = foundDatabase.title?.[0]?.plain_text || 'Untitled';
+    console.info(`   📊 Using database: "${dbTitle}"`);
+    console.info(`   🔑 ID: ${foundDatabase.id}\n`);
+
+    // STEP 2: Query database
+    console.info('2️⃣  QUERYING DATABASE...\n');
+    const queryResult = (await matimo.execute('notion_query_database', {
+      database_id: foundDatabase.id,
+      page_size: 5,
+    })) as any;
+
+    const queryData = queryResult.data;
+    if (queryData?.results && Array.isArray(queryData.results) && queryData.results.length > 0) {
+      console.info(`✅ Retrieved ${queryData.results.length} page(s)\n`);
+      queryData.results.slice(0, 3).forEach((page: any, idx: number) => {
+        const title =
+          (page.properties as any)?.[Object.keys(page.properties || {})[0]]?.[0]?.plain_text ??
+          'Untitled';
+        const url = page.url;
+        console.info(`   ${idx + 1}. ${title}`);
+        console.info(`      🔗 ${url}\n`);
+      });
+      if (queryData.results.length > 3) {
+        console.info(`   ... and ${queryData.results.length - 3} more\n`);
+      }
+    } else {
+      console.info('   ℹ️  Database is empty\n');
+    }
+
+    // STEP 3: Create page with markdown (simple, works with any database)
+    console.info('3️⃣  CREATING NEW PAGE...\n');
+    const pageTitle = `Matimo Test ${new Date().toLocaleTimeString()}`;
+
+    // Prefer the database_id from the query results (page parent) if available,
+    // otherwise fall back to the discovered database id from notion_list_databases.
+    const fallbackDbId = foundDatabase.id;
+    const pageParentDbId = queryData?.results?.[0]?.parent?.database_id;
+    const resolvedDatabaseId = pageParentDbId || fallbackDbId;
+
+    const createParams = {
+      parent: { database_id: resolvedDatabaseId },
+      markdown: `# ${pageTitle}\n\nCreated by Matimo at ${new Date().toLocaleString()}`,
+      icon: {
+        type: 'emoji',
+        emoji: '✅',
+      },
+    };
+
+    console.info(
+      `DEBUG: Using database id for creation: ${resolvedDatabaseId} (from ${pageParentDbId ? 'query result' : 'discovery'})`
+    );
+
+    console.info('DEBUG: Creating page with params:', JSON.stringify(createParams, null, 2));
+    const createResult = (await matimo.execute('notion_create_page', createParams)) as any;
+    console.info('DEBUG: Create result:', JSON.stringify(createResult, null, 2).substring(0, 500));
+
+    const createData = createResult.data || createResult;
+    if (createData && createData.id) {
+      console.info(`✅ Page created!\n`);
+      console.info(`   📄 Title: "${pageTitle}"`);
+      console.info(`   🔑 ID: ${createData.id}`);
+      console.info(`   🔗 URL: ${createData.url}\n`);
+
+      // STEP 4: Update page with emoji icon
+      console.info('4️⃣  UPDATING PAGE WITH ICON...\n');
+      try {
+        await matimo.execute('notion_update_page', {
+          page_id: createData.id,
+          icon: {
+            type: 'emoji',
+            emoji: '🚀',
+          },
+        });
+        console.info(`✅ Page updated with icon!\n`);
+      } catch (err) {
+        console.info(
+          `   ⚠️  Could not update: ${err instanceof Error ? err.message : String(err)}\n`
+        );
+      }
+
+      // STEP 5: Add comment
+      console.info('5️⃣  ADDING COMMENT...\n');
+      try {
+        const commentResult = (await matimo.execute('notion_create_comment', {
+          parent: { page_id: createData.id },
+          rich_text: [
+            {
+              type: 'text',
+              text: {
+                content: `Created by Matimo at ${new Date().toLocaleString()}. Real test! 🚀`,
+              },
+            },
+          ],
+        })) as any;
+
+        console.info('DEBUG: Comment result:', JSON.stringify(commentResult).substring(0, 500));
+
+        const cr = commentResult.data || commentResult;
+        if (cr && cr.id) {
+          console.info(`✅ Comment added!\n`);
+        } else if (commentResult && (commentResult.success === false || commentResult.statusCode)) {
+          console.info(
+            `   ⚠️  Comment failed: ${JSON.stringify(commentResult).substring(0, 200)}\n`
+          );
+        } else {
+          console.info(`✅ Comment added (no id returned)\n`);
+        }
+      } catch (err) {
+        try {
+          console.info('   ⚠️  Could not add comment. Error payload:', JSON.stringify(err));
+        } catch (_) {
+          console.info(
+            `   ⚠️  Could not add comment: ${err instanceof Error ? err.message : String(err)}\n`
+          );
+        }
+      }
+    } else {
+      console.info(
+        `   ⚠️  Failed to create page. Response: ${JSON.stringify(createData).substring(0, 200)}\n`
+      );
+
+      // If the database wasn't found or not shared, attempt a fallback:
+      // create a child page under an existing page returned by the query above.
+      const errCode =
+        (createData && (createData as any).error && (createData as any).error.code) || '';
+      if (errCode === 'object_not_found') {
+        console.info(
+          '   ℹ️  Notion reports the database object was not found or not shared with the integration.'
+        );
+        const firstPage = queryData?.results?.[0];
+        if (firstPage && firstPage.id) {
+          console.info(`   ℹ️  Falling back to creating a sub-page under page id ${firstPage.id}`);
+          try {
+            const fallbackResult = await matimo.execute('notion_create_page', {
+              parent: { page_id: firstPage.id },
+              properties: {
+                Name: { title: [{ text: { content: pageTitle } }] },
+              },
+              icon: {
+                type: 'emoji',
+                emoji: '✅',
+              },
+            });
+
+            const fr = (fallbackResult as any).data || fallbackResult;
+            if (fr && fr.id) {
+              console.info('   ✅ Fallback page created as child page!');
+              console.info(`      🔑 ID: ${fr.id}`);
+              console.info(`      🔗 URL: ${fr.url}\n`);
+            } else {
+              console.info(
+                '   ⚠️  Fallback creation also failed. Check integration permissions and that the target page is shared.'
+              );
+            }
+          } catch (fbErr) {
+            console.info(
+              '   ⚠️  Fallback create threw an error:',
+              fbErr instanceof Error ? fbErr.message : String(fbErr)
+            );
+          }
+        } else {
+          console.info(
+            '   ℹ️  No pages available to fall back to. Ensure your integration is shared with the target database.'
+          );
+        }
+      } else {
+        console.info(
+          '   ℹ️  Creation failed for other reasons; inspect the response above for details.'
+        );
+      }
+    }
+
+    console.info('════════════════════════════════════════════════════════════\n');
+    console.info('✨ COMPLETE!\n');
+    console.info('📝 Check your Notion workspace to see the created page!\n');
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error(`❌ Error: ${msg}`);
+    if (msg.includes('401') || msg.includes('permission')) {
+      console.error('   • Check your NOTION_API_KEY is valid');
+      console.error('   • Ensure your integration has read/write capabilities');
+      console.error('   • Share your Notion database with the integration');
+    }
+    process.exit(1);
+  }
+}
+
+runFactoryPatternExamples().catch(console.error);

package/notion/notion-langchain.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * NOTION 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 Notion 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:
+ *    NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ *    OPENAI_API_KEY=sk-xxxxxxxxxxxxx
+ *
+ * 2. Install dependencies:
+ *    npm install
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export NOTION_API_KEY=secret_xxxx
+ *   export OPENAI_API_KEY=sk-xxxx
+ *   npm run notion:langchain
+ *
+ * WHAT IT DOES:
+ * ─────────────────────────────────────────────────────────────────────────
+ * This example shows an AI agent that can:
+ * 1. Search Notion workspace
+ * 2. Query databases
+ * 3. Create pages
+ * 4. Update pages
+ * 5. Add comments
+ * 6. Respond naturally in conversation style
+ *
+ * Example conversation:
+ *   User: "Search my Notion workspace for important items"
+ *   AI Agent: "I'll search your Notion workspace..."
+ *   [AI Agent calls notion_search tool]
+ *   AI Agent: "I found 5 items. Here's what I discovered..."
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { createAgent } from 'langchain';
+import { ChatOpenAI } from '@langchain/openai';
+import { MatimoInstance, convertToolsToLangChain, ToolDefinition } from '@matimo/core';
+
+/**
+ * Notion AI Agent - Autonomous agent with LangChain
+ */
+async function runNotionAIAgent() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     NOTION AI AGENT - LangChain Agentic Loop        ║');
+  console.info('║     Autonomous Notion workspace management           ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  // Validate credentials
+  const notionKey = process.env.NOTION_API_KEY;
+  const openaiKey = process.env.OPENAI_API_KEY;
+
+  if (!notionKey) {
+    console.error('❌ Error: NOTION_API_KEY not set in .env');
+    console.info('   Get one from: https://www.notion.so/my-integrations');
+    process.exit(1);
+  }
+
+  if (!openaiKey) {
+    console.error('❌ Error: OPENAI_API_KEY not set in .env');
+    console.info('   Get one from: https://platform.openai.com/api-keys');
+    process.exit(1);
+  }
+
+  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 Notion tools and convert to LangChain format
+    console.info('💬 Loading Notion tools...');
+    const matimoTools = matimo.listTools();
+    const notionTools = matimoTools.filter((t) => t.name.startsWith('notion_'));
+    console.info(`✅ Loaded ${notionTools.length} Notion tools\n`);
+
+    // Select key Notion tools for agent (in order of typical workflow)
+    const keyNotionTools = notionTools.filter((t) =>
+      [
+        'notion_list_databases',
+        'notion_query_database',
+        'notion_create_page',
+        'notion_update_page',
+      ].includes(t.name)
+    );
+
+    // ✅ Discover a database first (required for notion_create_page parent parameter)
+    // This mirrors the factory example that queries databases before creating pages
+    console.info('🧪 Discovering accessible databases...');
+    let selectedDatabaseId: string | null = null;
+    let selectedDatabaseTitle: string | null = null;
+
+    try {
+      const listResult = (await matimo.execute('notion_list_databases', { page_size: 5 })) as any;
+      const databases = listResult.data?.results || listResult.results || [];
+      console.info(`   ✅ Direct tool call succeeded`);
+      console.info(`   📊 Found ${databases.length} accessible database(s)\n`);
+
+      if (databases && databases.length > 0) {
+        selectedDatabaseId = databases[0].id;
+        selectedDatabaseTitle = databases[0].title?.[0]?.plain_text || 'Untitled';
+        console.info(
+          `   📍 Selected database: "${selectedDatabaseTitle}" (${selectedDatabaseId})\n`
+        );
+      } else {
+        console.info('   ℹ️  No databases accessible - notion_create_page will fail\n');
+        console.info(
+          '   📌 Share a Notion database with your integration to enable full functionality\n'
+        );
+      }
+    } catch (testError) {
+      console.info(`   ⚠️  Direct tool test failed: ${testError}\n`);
+    }
+
+    // ✅ Convert Matimo tools to LangChain format
+    console.info('🔄 Converting tools to LangChain format...');
+    const langchainTools = await convertToolsToLangChain(
+      keyNotionTools as ToolDefinition[],
+      matimo,
+      {
+        NOTION_API_KEY: notionKey,
+        ...(selectedDatabaseId ? { parent: { database_id: selectedDatabaseId } } : {}),
+      } as any
+    );
+
+    console.info(`✅ Converted ${langchainTools.length} tools for LangChain\n`);
+
+    // 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 that require real API usage)
+    const userRequests = [
+      {
+        title: 'Example 1: Explore Workspace',
+        request:
+          'Explore my Notion workspace and tell me what databases you find. List them by name.',
+      },
+      {
+        title: 'Example 2: Query and Analyze',
+        request:
+          'Find a database in my workspace and query it. Tell me how many pages it contains and what you discover.',
+      },
+      {
+        title: 'Example 3: Create Page',
+        request: `Create a new page with the title "AI Agent Report - ${new Date().toLocaleTimeString()}" in the available database`,
+      },
+    ];
+
+    console.info('🧪 Running AI Agent Tasks');
+    console.info('═'.repeat(60));
+    console.info('📌 IMPORTANT: Each task shows:');
+    console.info('   1. Natural language user request');
+    console.info('   2. AI agent decision (which tools to call)');
+    console.info('   3. Actual tool execution results\n');
+
+    // 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 {
+        // Use the same invoke shape as the Slack example: supply `messages` array
+        const response = (await (agent as any).invoke({
+          messages: [
+            {
+              role: 'user',
+              content: task.request,
+            },
+          ],
+        })) as any;
+
+        // Get the output from the agent
+        const output = response.output;
+        if (output) {
+          console.info(`🤖 Agent Response:\n${output}\n`);
+        }
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.info(`⚠️  Agent error: ${errorMsg}\n`);
+        console.info('📌 Note: This is expected if you lack API permissions or database access');
+      }
+    }
+
+    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 parameters based on context');
+    console.info('  ✅ Actual tools executed in your Notion workspace');
+    console.info('  ✅ Results processed through LLM for natural response\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
+runNotionAIAgent().catch(console.error);

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "matimo-examples",
+  "version": "0.1.0-alpha.11",
+  "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.11",
+    "@matimo/slack": "0.1.0-alpha.11",
+    "@matimo/postgres": "0.1.0-alpha.11",
+    "@matimo/github": "0.1.0-alpha.11",
+    "@matimo/gmail": "0.1.0-alpha.11",
+    "@matimo/hubspot": "0.1.0-alpha.11",
+    "@matimo/notion": "0.1.0-alpha.11",
+    "@matimo/mailchimp": "0.1.0-alpha.11",
+    "@matimo/twilio": "0.1.0-alpha.11"
+  },
+  "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",
+    "postgres:factory": "tsx postgres/postgres-factory.ts",
+    "postgres:decorator": "tsx postgres/postgres-decorator.ts",
+    "postgres:langchain": "tsx postgres/postgres-langchain.ts",
+    "postgres:approval": "tsx postgres/postgres-with-approval.ts",
+    "execute:factory": "tsx execute/execute-factory.ts",
+    "execute:decorator": "tsx execute/execute-decorator.ts",
+    "execute:langchain": "tsx execute/execute-langchain.ts",
+    "read:factory": "tsx read/read-factory.ts",
+    "read:decorator": "tsx read/read-decorator.ts",
+    "read:langchain": "tsx read/read-langchain.ts",
+    "edit:factory": "tsx edit/edit-factory.ts",
+    "edit:decorator": "tsx edit/edit-decorator.ts",
+    "edit:langchain": "tsx edit/edit-langchain.ts",
+    "search:factory": "tsx search/search-factory.ts",
+    "search:decorator": "tsx search/search-decorator.ts",
+    "search:langchain": "tsx search/search-langchain.ts",
+    "web:factory": "tsx web/web-factory.ts",
+    "web:decorator": "tsx web/web-decorator.ts",
+    "web:langchain": "tsx web/web-langchain.ts",
+    "github:factory": "tsx github/github-factory.ts",
+    "github:decorator": "tsx github/github-decorator.ts",
+    "github:langchain": "tsx github/github-langchain.ts",
+    "github:approval": "tsx github/github-with-approval.ts",
+    "hubspot:factory": "tsx hubspot/hubspot-factory.ts",
+    "hubspot:decorator": "tsx hubspot/hubspot-decorator.ts",
+    "hubspot:langchain": "tsx hubspot/hubspot-langchain.ts",
+    "notion:factory": "tsx notion/notion-factory.ts",
+    "notion:decorator": "tsx notion/notion-decorator.ts",
+    "notion:langchain": "tsx notion/notion-langchain.ts",
+    "mailchimp:factory": "tsx mailchimp/mailchimp-factory.ts",
+    "mailchimp:decorator": "tsx mailchimp/mailchimp-decorator.ts",
+    "mailchimp:langchain": "tsx mailchimp/mailchimp-langchain.ts",
+    "twilio:factory": "tsx twilio/twilio-factory.ts",
+    "twilio:decorator": "tsx twilio/twilio-decorator.ts",
+    "twilio:langchain": "tsx twilio/twilio-langchain.ts",
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}