matimo-examples 0.1.0-alpha.11

package/notion/README.md

@@ -0,0 +1,293 @@
+# Notion Tools Examples
+
+Example directory contains **3 example patterns** showing different ways to use Matimo's Notion 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 are **fully working** and demonstrate real Notion operations (creating pages, querying databases, updating pages, etc.).
+
+## 🚀 Quick Start
+
+### 1. Create a Notion Integration
+
+1. Go to [notion.com/my-integrations](https://www.notion.com/my-integrations)
+2. Click "Create new integration"
+3. Give it a name like "Matimo"
+4. Select "Internal Integration"
+5. Accept the guidelines and click "Create integration"
+
+OR Create an internal integration by visiting - https://www.notion.so/profile/integrations/internal
+
+### 2. Get Your API Key
+
+- Copy the **Internal Integration Token** (starts with `ntn_`)
+- This is your `NOTION_API_KEY`
+
+### 3. Share Databases with Integration
+
+1. Open any Notion database you want Matimo to access
+2. Click **Share** in the top-right
+3. Select your integration from the dropdown and click "Invite"
+4. Confirm the invitation
+
+### 4. Set Up Environment
+
+Create a `.env` file in `examples/tools/`:
+
+```env
+NOTION_API_KEY=secret_your-notion-api-key-here
+OPENAI_API_KEY=sk-your-openai-key-here
+```
+
+### 5. Run Examples
+
+```bash
+# Factory Pattern (simplest, direct API calls)
+pnpm notion:factory
+
+# Decorator Pattern (class-based OOP approach)
+pnpm notion:decorator
+
+# LangChain Pattern (AI-driven agent with OpenAI)
+pnpm notion:langchain
+```
+
+## 📚 Examples Overview
+
+### 1. Factory Pattern (`notion-factory.ts`)
+
+**Best for:** Scripts, quick tests, CLI tools
+
+**What it does:**
+- ✅ Direct tool execution with `matimo.execute()`
+- ✅ Automatically discovers accessible databases
+- ✅ Queries database for pages
+- ✅ Creates new pages with content
+- ✅ Updates pages with icons
+- ✅ Simplest implementation
+
+**Run it:**
+```bash
+pnpm notion:factory
+```
+
+**Key Code:**
+```typescript
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+// List databases
+const databases = await matimo.execute('notion_list_databases', { page_size: 10 });
+
+// Query a database
+const pages = await matimo.execute('notion_query_database', {
+  database_id: 'db-id-here'
+});
+
+// Create a page
+const newPage = await matimo.execute('notion_create_page', {
+  parent: { database_id: 'db-id-here' },
+  markdown: '# New Page\n\nContent here'
+});
+```
+
+**File:** [notion-factory.ts](notion-factory.ts)
+
+### 2. Decorator Pattern (`notion-decorator.ts`)
+
+**Best for:** Object-oriented design, class-based applications
+
+**What it does:**
+- ✅ Class methods decorated with `@tool`
+- ✅ Automatic tool execution via decorators
+- ✅ Multiple operations in organized class
+- ✅ Creates and updates pages automatically
+- ✅ OOP-friendly approach
+
+**Run it:**
+```bash
+pnpm notion:decorator
+```
+
+**Key Code:**
+```typescript
+class NotionAgent {
+  @tool('notion_list_databases')
+  async listDatabases() {
+    // Decorator auto-executes tool
+  }
+
+  @tool('notion_create_page')
+  async createPage(parent: any, markdown: string) {
+    // Also auto-executed
+  }
+}
+
+const agent = new NotionAgent();
+await agent.listDatabases();
+```
+
+**File:** [notion-decorator.ts](notion-decorator.ts)
+
+### 3. LangChain AI Agent (`notion-langchain.ts`)
+
+**Best for:** True autonomous agents with AI reasoning
+
+**What it does:**
+- ✅ AI agent (OpenAI GPT-4o-mini) decides which tools to use
+- ✅ Takes natural language instructions
+- ✅ Automatically discovers databases
+- ✅ Executes Notion tools autonomously
+- ✅ Processes results and responds naturally
+- ✅ Multi-step reasoning
+
+**Run it:**
+```bash
+pnpm notion:langchain
+```
+
+**Example Conversation:**
+```
+User: "Explore my Notion workspace and tell me what databases you find"
+AI Agent: I'll explore your workspace and list the databases...
+[AI calls notion_list_databases tool]
+AI Agent: I found 3 databases:
+  1. Product Roadmap
+  2. Projects
+  3. Tasks
+
+User: "Create a new page with the title 'Meeting Notes'"
+AI Agent: I'll create a new page for you...
+[AI calls notion_create_page tool with discovered database]
+AI Agent: Done! I've created a new page titled 'Meeting Notes'
+```
+
+**Key Code:**
+```typescript
+// Discover database first
+const listResult = await matimo.execute('notion_list_databases', { page_size: 5 });
+const selectedDatabase = listResult.data.results[0];
+
+// Create agent with database context
+const agent = await createAgent({
+  model: new ChatOpenAI({ modelName: 'gpt-4o-mini' }),
+  tools: langchainTools
+});
+
+// AI decides which tools to use
+const response = await agent.invoke({
+  messages: [{ role: 'user', content: 'Create a new page' }]
+});
+```
+
+**File:** [notion-langchain.ts](notion-langchain.ts)
+
+## 🎯 Available Notion Tools
+
+All patterns have access to these core Notion tools:
+
+### Database Operations
+- `notion_list_databases` - List all accessible databases
+- `notion_query_database` - Query pages in a database with filters
+
+### Page Operations
+- `notion_create_page` - Create new page in a database or as child page
+- `notion_update_page` - Update page properties and icon
+- `notion_get_page` - Retrieve page details
+
+### Comments
+- `notion_create_comment` - Add comments to pages
+
+### Search
+- `notion_search` - Search workspace for pages and databases
+
+## 📝 Common Patterns
+
+### Discovering Available Databases
+
+```typescript
+const result = await matimo.execute('notion_list_databases', { 
+  page_size: 10 
+});
+
+const databases = result.data.results; // Array of database objects
+databases.forEach(db => {
+  const title = db.title[0]?.plain_text || 'Untitled';
+  console.log(`📊 ${title} (${db.id})`);
+});
+```
+
+### Creating Pages with Markdown
+
+```typescript
+const newPage = await matimo.execute('notion_create_page', {
+  parent: { database_id: 'your-db-id' },
+  icon: { type: 'emoji', emoji: '✅' },
+  markdown: '# Page Title\n\n## Section\n\nContent here'
+});
+```
+
+### Querying Database for Pages
+
+```typescript
+const result = await matimo.execute('notion_query_database', {
+  database_id: 'your-db-id',
+  page_size: 10,
+  filter: {
+    property: 'Status',
+    status: { equals: 'Done' }
+  }
+});
+
+const pages = result.data.results;
+```
+
+## 🔗 Resources
+
+- **Notion API Documentation:** [developers.notion.com](https://developers.notion.com)
+- **Create Integration:** [notion.com/my-integrations](https://www.notion.com/my-integrations)
+- **Matimo Notion Tools:** [packages/notion](../../packages/notion)
+- **Matimo Documentation:** [docs/](../../docs)
+
+## ⚠️ Important Notes
+
+### 1. Database Sharing Required
+Tools can only access databases that have been **explicitly shared** with your integration. Use the Share button in Notion to grant access.
+
+### 2. Destructive Operations
+Tools like `notion_create_page` and `notion_update_page` make real changes to your Notion workspace. Be careful with credentials.
+
+### 3. LangChain Pattern Limitations
+The LangChain AI agent example:
+- Automatically discovers and uses the first available database
+- Does not support multi-step operations (e.g., create page then add comment) in a single request
+- For complex workflows, use Factory or Decorator patterns
+
+### 4. API Rate Limits
+Notion API has rate limits. Long-running operations may need to retry. See [rate limiting docs](https://developers.notion.com/reference/node-sdk#rate-limits).
+
+## 🚨 Troubleshooting
+
+### "Not Authorized to Access This Resource"
+- Ensure the database is **shared** with your integration
+- Check the integration has the correct permissions
+
+### "Notion API Error"
+- Verify `NOTION_API_KEY` is set correctly
+- Check the integration token hasn't expired
+
+### "Database Not Found"
+- Confirm the database ID is correct
+- Ensure the database is shared with the integration
+
+### No Databases Returned
+- Create a database in Notion first
+- Share it with your integration
+- Run `notion:factory` to test discovery
+
+## 📞 Support
+
+For issues with:
+- **Matimo tools:** See [packages/notion/README.md](../../packages/notion/README.md)
+- **Notion API:** Visit [developers.notion.com/reference](https://developers.notion.com/reference)
+- **LangChain:** Check [langchain.com/docs](https://docs.langchain.com)

package/notion/notion-decorator.ts

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * NOTION TOOLS - DECORATOR PATTERN EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: Class Decorator Pattern
+ * ─────────────────────────────────────────────────────────────────────────
+ * Using @tool() decorators for class-based tool execution.
+ *
+ * Use this pattern when:
+ * ✅ Building class-based agents
+ * ✅ Organizing tools by domain (NotionManager, SlackHelper, etc.)
+ * ✅ Integrating with frameworks like LangChain, CrewAI
+ * ✅ Want method signatures to match tool interfaces
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Set NOTION_API_KEY environment variable
+ * 2. Share Notion databases/pages with your integration
+ * 3. Global Matimo instance must be set: setGlobalMatimoInstance(matimo)
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export NOTION_API_KEY=secret_xxxx
+ *   npm run notion:decorator
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { MatimoInstance, setGlobalMatimoInstance, tool } from '@matimo/core';
+
+/**
+ * Notion Manager - Class-based interface to Notion tools
+ * Each method is decorated with @tool() which auto-executes via Matimo
+ *
+ * MATIMO DESIGN: Structured Parameters (Objects/Arrays)
+ * ──────────────────────────────────────────────────────
+ * Note: This example passes structured JavaScript objects and arrays
+ * (like { database_id: '123' }, [{ type: 'text', ... }]) directly to methods.
+ *
+ * The decorator converts these to matimo.execute() calls, and the HTTP executor
+ * properly embeds them as JSON in request bodies—they are NOT stringified.
+ *
+ * This works because:
+ * 1. Each parameter is defined in YAML with its type (object, array, string, etc.)
+ * 2. The HTTP executor uses this type information to decide how to embed the value
+ * 3. For type:object and type:array, values are embedded directly as JSON structures
+ * 4. For type:string, values are templated as strings
+ *
+ * Example YAML parameter definition:
+ * ```yaml
+ * parameters:
+ *   parent:
+ *     type: object
+ *     description: Parent database or page
+ *   rich_text:
+ *     type: array
+ *     description: Array of rich text objects
+ *   markdown:
+ *     type: string
+ *     description: Markdown content
+ *
+ * body:
+ *   parent: "{parent}"        # Embedded as JSON object
+ *   rich_text: "{rich_text}"  # Embedded as JSON array
+ *   markdown: "{markdown}"    # Embedded as string
+ * ```
+ *
+ * Result: The API receives proper JSON structures, not stringified "[object Object]".
+ */
+class NotionManager {
+  /**
+   * List all databases in the workspace
+   * No API knowledge needed - just call it!
+   */
+  @tool('notion_list_databases')
+  async listDatabases(page_size?: number): Promise<any> {
+    // Decorator intercepts → auto-executes via matimo.execute()
+    throw new Error('Should not be called - decorator handles execution');
+  }
+
+  /**
+   * Query a database for pages matching optional filters
+   * database_id parameter is clear and self-documenting
+   */
+  @tool('notion_query_database')
+  async queryDatabase(
+    database_id: string,
+    sorts?: Array<Record<string, any>>,
+    filter?: Record<string, any>,
+    page_size?: number
+  ): Promise<any> {
+    // Method body ignored - @tool decorator handles execution
+    throw new Error('Should not be called - decorator handles execution');
+  }
+
+  /**
+   * Create a new page with markdown content
+   * Simplest way to add content - works with any database
+   */
+  @tool('notion_create_page')
+  async createPage(
+    parent: Record<string, string>,
+    markdown?: string,
+    icon?: Record<string, string>
+  ): Promise<any> {
+    // Decorator intercepts → auto-executes via matimo.execute()
+    throw new Error('Should not be called - decorator handles execution');
+  }
+
+  /**
+   * Update an existing page (icon, status, etc.)
+   */
+  @tool('notion_update_page')
+  async updatePage(page_id: string, icon?: Record<string, string>): Promise<any> {
+    // Method body ignored - @tool decorator handles execution
+    throw new Error('Should not be called - decorator handles execution');
+  }
+
+  /**
+   * Add a comment to a page
+   */
+  @tool('notion_create_comment')
+  async addComment(
+    parent: Record<string, string>,
+    rich_text?: Array<Record<string, any>>
+  ): Promise<any> {
+    // Method body ignored - @tool decorator handles execution
+    throw new Error('Should not be called - decorator handles execution');
+  }
+}
+
+/**
+ * Demonstration of decorator pattern usage with REAL operations
+ */
+async function demonstrateDecoratorPattern() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     Notion Tools - Decorator Pattern                  ║');
+  console.info('║     (Class-based execution with REAL operations)     ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  const apiKey = process.env.NOTION_API_KEY;
+  if (!apiKey) {
+    console.error('❌ Error: NOTION_API_KEY not set in .env');
+    console.info('   Set it: export NOTION_API_KEY="secret_xxxx"');
+    console.info('   Get one from: https://www.notion.so/my-integrations');
+    process.exit(1);
+  }
+
+  try {
+    // Step 1: Initialize Matimo
+    console.info('🚀 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+    // Step 2: Set global instance for decorators to use
+    console.info('📌 Setting up decorator support...');
+    setGlobalMatimoInstance(matimo);
+
+    console.info('✅ NotionManager initialized with decorators\n');
+
+    // Step 3: Create manager instance
+    const manager = new NotionManager();
+
+    console.info('════════════════════════════════════════════════════════════\n');
+    console.info('Testing @tool() Decorator - Verifying Tool Execution:');
+    console.info('════════════════════════════════════════════════════════════\n');
+
+    // Test 1: Verify decorator intercepts and calls matimo.execute()
+    console.info('1️⃣  Testing @tool("notion_list_databases") decorator...');
+    console.info('    → Calling: manager.listDatabases(10)');
+    console.info('    → Decorator should intercept and call matimo.execute()...\n');
+
+    let listResult: any;
+    try {
+      listResult = await manager.listDatabases(10);
+      console.info(`   📨 Raw result received: ${JSON.stringify(listResult).substring(0, 100)}...`);
+      const databases = listResult.results || listResult.data?.results || [];
+      console.info(`   ✅ Decorator executed tool successfully`);
+      console.info(`   📊 Got response with ${databases.length} databases\n`);
+
+      if (databases.length > 0) {
+        const foundDatabase = databases[0];
+        console.info('2️⃣  Testing @tool("notion_query_database") decorator...');
+        console.info(`    → Calling: manager.queryDatabase("${foundDatabase.id}", ...)`);
+
+        const queryResult = await manager.queryDatabase(foundDatabase.id, undefined, undefined, 5);
+        const queryPages = queryResult.results || queryResult.data?.results || [];
+        console.info(`   ✅ Query decorator executed successfully`);
+        console.info(`   📊 Got response with ${queryPages.length} pages\n`);
+
+        // Test 3: Try creating a page
+        const timestamp = new Date().toLocaleTimeString();
+        console.info('3️⃣  Testing @tool("notion_create_page") decorator...');
+        console.info('    → Calling: manager.createPage({...}, markdown, icon)');
+        console.info(
+          '    → Note: Structured params (objects/arrays) are properly embedded in HTTP body'
+        );
+        console.info('           as JSON, not stringified—this is handled by HttpExecutor\n');
+
+        try {
+          const createResult = await manager.createPage(
+            { database_id: foundDatabase.id }, // Object param → embedded as JSON
+            `# Decorator Test Page\n\nCreated at ${timestamp}`, // String param
+            { type: 'emoji', emoji: '🔧' } // Object param → embedded as JSON
+          );
+          console.info(`   ✅ Create decorator executed`);
+          console.info(`   📨 Got response: ${JSON.stringify(createResult).substring(0, 100)}...`);
+
+          if (createResult.id) {
+            console.info(`   ✅ Successfully created page: ${createResult.id}\n`);
+
+            // Try updating
+            console.info('4️⃣  Testing @tool("notion_update_page") decorator...');
+            try {
+              const updateResult = await manager.updatePage(createResult.id, {
+                type: 'emoji',
+                emoji: '✨',
+              });
+              console.info(`   ✅ Update decorator executed\n`);
+            } catch (e) {
+              console.info(`   ⚠️  Update skipped (expected if permission limited): ${e}\n`);
+            }
+
+            // Try commenting
+            console.info('5️⃣  Testing @tool("notion_create_comment") decorator...');
+            console.info('    → Calling: manager.addComment(parent, rich_text_array)');
+            console.info(
+              '    → Note: Array param is properly embedded as JSON array in HTTP body\n'
+            );
+            try {
+              const commentResult = await manager.addComment(
+                { page_id: createResult.id }, // Object param → embedded as JSON
+                [
+                  // Array param → embedded as JSON array
+                  { type: 'text', text: { content: `Added at ${timestamp} via decorator!` } },
+                ]
+              );
+              console.info(`   ✅ Comment decorator executed\n`);
+            } catch (e) {
+              console.info(`   ⚠️  Comment skipped (expected if permission limited): ${e}\n`);
+            }
+          }
+        } catch (createError) {
+          console.info(`   ⚠️  Create failed (expected if permission limited): ${createError}\n`);
+        }
+      } else {
+        console.info('   📌 No databases accessible - cannot test further operations');
+        console.info('   📌 Share a Notion database with your integration to test full workflow\n');
+      }
+    } catch (error) {
+      console.error(`   ❌ Decorator test failed: ${error}\n`);
+      throw error;
+    }
+
+    console.info('════════════════════════════════════════════════════════════\n');
+    console.info('✅ Decorator Pattern Verification Complete!');
+    console.info('════════════════════════════════════════════════════════════\n');
+    console.info('📌 Key Points:');
+    console.info('   ✅ @tool() decorator intercepts method calls');
+    console.info('   ✅ Decorator calls matimo.execute() with the tool name');
+    console.info('   ✅ Method bodies are ignored (not executed)');
+    console.info('   ✅ Works seamlessly - developers just call methods!\n');
+  } catch (error) {
+    console.error('\n❌ Error:', error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.message.includes('NOTION_API_KEY')) {
+      console.error('\n📌 Set environment variable:');
+      console.error('   export NOTION_API_KEY=secret_xxxxx');
+    }
+    process.exit(1);
+  }
+}
+
+demonstrateDecoratorPattern().catch(console.error);