@matimo/notion 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tallclub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,335 @@
+# @matimo/notion — Notion Tools for Matimo
+
+Notion workspace integration tools for Matimo's universal AI tools ecosystem. Query databases, create pages, manage content, search workspaces, add comments, and retrieve user information through YAML-defined tools that work with any AI framework.
+
+## 📦 Installation
+
+```bash
+npm install @matimo/notion
+# or
+pnpm add @matimo/notion
+```
+
+## 🛠️ Available Tools (7 Total)
+
+| Tool | Method | Description |
+|------|--------|-------------|
+| **notion_list_databases** | POST | List all databases (data sources) in workspace |
+| **notion_query_database** | POST | Query pages from database with filters and sorting |
+| **notion_create_page** | POST | Create new page in database or as child page |
+| **notion_update_page** | PATCH | Update page properties, icon, status, archive |
+| **notion_search** | POST | Search workspace pages and databases by title |
+| **notion_create_comment** | POST | Add comments to pages, blocks, or discussions |
+| **notion_get_user** | GET | Retrieve user information and profile details |
+
+## 🚀 Quick Start
+
+```typescript
+import { MatimoInstance } from '@matimo/core';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+// Query a database
+const results = await matimo.execute('notion_query_database', {
+  database_id: 'a1d8501e-1ac1-43e9-a6bd-ea9fe6c8822b'
+});
+
+console.log('Found pages:', results.results.length);
+```
+
+## 🔐 Authentication Setup
+
+### Get Your Notion API Token
+
+1. Go to [Notion Integrations](https://www.notion.so/my-integrations)
+2. Click "Create new integration"
+3. Set workspace and name your integration
+4. Grant required capabilities:
+   - ✅ Read content
+   - ✅ Update content
+   - ✅ Insert content
+   - ✅ Read user information
+   - ✅ Insert comments
+5. Copy your "Internal Integration Secret" (token)
+6. Set environment variable:
+   ```bash
+   export NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+   ```
+
+### Share Resources with Your Integration
+
+For each database/page you want to access:
+1. Click the ••• menu (top-right)
+2. Scroll to "Add connections"
+3. Search for and select your integration
+
+## 🤖 How AI Agents Use These Tools
+
+AI agents (Claude, ChatGPT, etc.) don't need to know internal API details. They discover tools automatically:
+
+```typescript
+// AI agent discovers all available tools
+const tools = matimo.listTools();
+
+// Each tool has:
+// - name: "notion_list_databases"  ← Tool identifier
+// - description: "List all databases..."  ← What it does
+// - parameters: {  ← What inputs it accepts
+//     database_id: { type: "string", description: "Get from notion_list_databases..." }
+//   }
+// - examples: [...]  ← How to use it
+
+// AI agent reads descriptions and automatically knows:
+// 1. Use notion_list_databases() first to get database IDs
+// 2. Pass those IDs to notion_query_database() for queries
+// 3. Use returned page IDs with notion_create_page(), etc.
+```
+
+**No memorization needed.** Tools are self-describing through their schemas, descriptions, and examples.
+
+## 📖 Integration Examples
+
+### Factory Pattern (Simple)
+
+```typescript
+import { MatimoInstance } from '@matimo/core';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+// AI agent autonomously discovers and uses tools
+// Step 1: List databases
+const databases = await matimo.execute('notion_list_databases', { page_size: 10 });
+const myDb = databases.data.results[0];
+
+// Step 2: Query the database
+const pages = await matimo.execute('notion_query_database', {
+  database_id: myDb.id,
+  page_size: 5
+});
+
+// Step 3: Create a new page
+const newPage = await matimo.execute('notion_create_page', {
+  parent: { database_id: myDb.id },
+  markdown: '# New Page\n\nContent here'
+});
+
+console.log('Created:', newPage.data.url);
+```
+
+### Decorator Pattern (Class-Based)
+
+```typescript
+import { MatimoInstance, setGlobalMatimoInstance, tool } from '@matimo/core';
+
+const matimo = await MatimoInstance.init('./tools');
+setGlobalMatimoInstance(matimo);
+
+class NotionManager {
+  @tool('notion_query_database')
+  async queryDatabase(database_id: string, filter?: Record<string, any>) {
+    // Auto-executed by decorator
+  }
+
+  @tool('notion_create_page')
+  async createPage(
+    parent: Record<string, string>, // e.g., { database_id: '...' } or { page_id: '...' }
+    markdown?: string,
+    icon?: Record<string, string>
+  ) {
+    // Auto-executed by decorator
+  }
+
+  @tool('notion_search')
+  async search(query: string, sort_by?: string) {
+    // Auto-executed by decorator
+  }
+}
+
+const manager = new NotionManager();
+const results = await manager.queryDatabase('db-id');
+```
+
+### LangChain Integration (AI Framework)
+
+```typescript
+import { MatimoInstance } from '@matimo/core';
+
+const matimo = await MatimoInstance.init('./tools');
+
+// Get tool schemas for LangChain
+const notionTools = matimo.listTools()
+  .filter(t => t.name.startsWith('notion_'))
+  .map(tool => ({
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: {
+        type: 'object',
+        properties: tool.parameters || {},
+        required: Object.entries(tool.parameters || {})
+          .filter(([_, p]: [string, any]) => p.required)
+          .map(([name]) => name),
+      },
+    },
+  }));
+
+// Use with your LLM/agent
+console.log('Available tools for LangChain:', notionTools.map(t => t.function.name));
+```
+
+## 📚 API Reference
+
+### notion_query_database
+
+Query pages in a Notion database with optional filtering and sorting.
+
+**Parameters:**
+- `database_id` (required): UUID of the database
+- `filter` (optional): JSON filter object (e.g., `{"property": "Status", "status": {"equals": "Done"}}`)
+- `sort` (optional): Array of sort objects
+- `page_size` (optional): Results per page (1-100, default 100)
+- `start_cursor` (optional): Pagination cursor
+
+**Returns:** Paginated list of pages with `results`, `has_more`, `next_cursor`
+
+---
+
+### notion_create_page
+
+Create a new page, optionally with properties and content.
+
+**Parameters:**
+- `parent` (required): Object describing where to create the page. Provide ONE of:
+  - `{ "database_id": "..." }` to create inside a database
+  - `{ "page_id": "..." }` to create as a child page
+- `properties` (optional): JSON properties matching parent schema
+- `markdown` (optional): String content using Markdown (easiest way to add content)
+- `icon` (optional): Object for page icon, e.g. `{ type: 'emoji', emoji: '✅' }`
+- `children` (optional): Array of Notion block objects to add to the page
+
+> **Note:** This tool accepts a single `parent` object (for example `{ "database_id": "..." }` or `{ "page_id": "..."`) — do not pass separate `parent_id` / `parent_type` parameters. This matches the tool's YAML definition (`packages/notion/tools/notion_create_page/definition.yaml`).
+
+**Returns:** Created page object with `id`, `url`, and `properties`
+
+---
+
+### notion_update_page
+
+Update page properties, status, archive status, or icon.
+
+**Parameters:**
+- `page_id` (required): UUID of page to update
+- `properties` (optional): JSON properties to update
+- `icon` (optional): Object for page icon (e.g., { "type": "emoji", "emoji": "✅" } or { "type": "external", "external": { "url": "https://..." } })
+- `archived` (optional): Archive/unarchive page (boolean)
+- `in_trash` (optional): Move to/restore from trash
+- `is_locked` (optional): Lock/unlock page editing
+
+**Returns:** Updated page object
+
+---
+
+### notion_search
+
+Search workspace pages and databases by title.
+
+**Parameters:**
+- `query` (optional): Search text (omit to return all items)
+- `filter_object` (optional): 'page' or 'data_source'
+- `sort_timestamp` (optional): 'last_edited_time' or 'created_time'
+- `sort_direction` (optional): 'ascending' or 'descending'
+- `page_size` (optional): Results per page (1-100)
+- `start_cursor` (optional): Pagination cursor
+
+**Returns:** Paginated list of pages/databases matching search
+
+---
+
+### notion_create_comment
+
+Add a comment to a page, block, or discussion thread.
+
+**Parameters:**
+- `parent` (optional): Object describing the comment target. Provide ONE of:
+  - `{ "page_id": "..." }` — comment on a page
+  - `{ "block_id": "..." }` — comment on a block
+  - omit to reply to a `discussion_id` (use `discussion_id` parameter)
+- `discussion_id` (optional): Discussion thread to reply to (alternative to `parent`)
+- `rich_text` (required): Array of rich text objects representing the comment content
+- `attachments` (optional): Array of file objects to attach to the comment
+- Formatting/annotations should be provided within the `rich_text` objects (bold/italic/code via annotations)
+
+**Returns:** Created comment object with `id` and `created_time`
+
+---
+
+### notion_get_user
+
+Retrieve user information including name, avatar, and email.
+
+**Parameters:**
+- `user_id` (required): UUID of user to retrieve
+
+**Returns:** User object with `id`, `name`, `avatar_url`, `email`
+
+## ⚙️ Environment Variables
+
+```bash
+# Required
+NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Optional (for OAuth2 - Phase 2)
+NOTION_OAUTH_CLIENT_ID=your_client_id
+NOTION_OAUTH_CLIENT_SECRET=your_client_secret
+NOTION_OAUTH_REDIRECT_URI=https://yourdomain.com/callback
+```
+
+## 🔧 Troubleshooting
+
+### "403 Forbidden" Error
+
+**Cause:** Integration lacks required capability or resource not shared.
+
+**Solutions:**
+1. Check integration has "Read/Update/Insert content" capabilities in Notion dashboard
+2. Share the database/page with your integration (•••  → Add connections → select integration)
+3. Verify token is current (refresh in Notion integrations dashboard)
+
+### "404 Not Found" Error
+
+**Cause:** Database/page ID is incorrect or integration doesn't have access.
+
+**Solutions:**
+1. Verify database ID from Notion URL: `https://www.notion.so/{database_id}`
+2. Ensure resource is shared with integration
+3. Check API key is correct
+
+### Filters Not Working
+
+**Cause:** Incorrect filter syntax for property type.
+
+**Solutions:**
+- Use Notion's property filtering UI as reference
+- Filters depend on property type (status, checkbox, date, etc.)
+- See [Notion Filter Reference](https://developers.notion.com/reference/post-database-query-filter)
+
+### Rate Limiting
+
+**Info:** Notion API has rate limits (~3-4 requests/second per integration). Implement exponential backoff for production systems.
+
+## 📖 Learning Resources
+
+- [Notion API Docs](https://developers.notion.com)
+- [Notion Integrations Dashboard](https://www.notion.so/my-integrations)
+- [Working with Databases](https://developers.notion.com/guides/data-apis/working-with-databases)
+- [Creating Pages](https://developers.notion.com/guides/data-apis/working-with-page-content)
+- [Notion Developers Slack](https://join.slack.com/t/notiondevs/shared_invite/zt-20b5996xv-DzJdLiympy6jP0GGzu3AMg)
+
+## 🤝 Contributing
+
+Found a bug or want to suggest a feature? See [CONTRIBUTING.md](/CONTRIBUTING.md).
+
+---
+
+**Part of the Matimo ecosystem** — Write YAML once, use everywhere.

package/definition.yaml

@@ -0,0 +1,34 @@
+name: notion-provider
+type: provider
+version: '1.0.0'
+description: |
+  Notion Provider Configuration and authentication metadata.
+  This file is used by the OAuth2ProviderLoader to register Notion as an
+  OAuth2 provider and to document runtime environment variables.
+
+provider:
+  name: notion
+  displayName: Notion
+  endpoints:
+    authorizationUrl: https://api.notion.com/v1/oauth/authorize
+    tokenUrl: https://api.notion.com/v1/oauth/token
+  defaultScopes:
+    - read
+    - write
+  documentation: https://developers.notion.com/docs
+
+# Legacy/auxiliary OAuth metadata (kept for backward compatibility with earlier tooling)
+oauth2:
+  client_id_env: NOTION_OAUTH_CLIENT_ID
+  client_secret_env: NOTION_OAUTH_CLIENT_SECRET
+  redirect_uri_env: NOTION_OAUTH_REDIRECT_URI
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+
+notes:
+  env: NOTION_API_KEY
+  setup_docs: "https://developers.notion.com/guides/get-started/getting-started"
+  caution: "Notion API requires Bearer token authentication. Ensure your integration has the necessary capabilities enabled in the Notion dashboard."

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@matimo/notion",
+  "version": "0.1.0-alpha.10",
+  "description": "Notion workspace tools for Matimo",
+  "type": "module",
+  "files": [
+    "tools",
+    "README.md",
+    "definition.yaml"
+  ],
+  "peerDependencies": {
+    "matimo": "0.1.0-alpha.10"
+  },
+  "devDependencies": {
+    "axios": "^1.13.4",
+    "@matimo/core": "0.1.0-alpha.10"
+  }
+}

package/tools/notion_create_comment/definition.yaml

@@ -0,0 +1,97 @@
+name: notion_create_comment
+description: Add a comment to a Notion page, block, or discussion thread
+version: "1.0.0"
+parameters:
+  parent:
+    type: object
+    required: false
+    description: Parent target - provide one of page_id, block_id, or neither if using discussion_id
+  discussion_id:
+    type: string
+    required: false
+    description: The ID of existing discussion thread to respond to (alternative to parent)
+  rich_text:
+    type: array
+    required: true
+    description: Array of rich text objects representing comment content
+  attachments:
+    type: array
+    required: false
+    description: Array of file objects to attach to comment (max 3 allowed)
+  display_name:
+    type: object
+    required: false
+    description: Display name configuration for the comment author
+
+execution:
+  type: http
+  method: POST
+  url: "https://api.notion.com/v1/comments"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2025-09-03"
+    Content-Type: application/json
+  body:
+    parent: "{parent}"
+    discussion_id: "{discussion_id}"
+    rich_text: "{rich_text}"
+    attachments: "{attachments}"
+    display_name: "{display_name}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Ensure 'Insert comments' capability is enabled. Either page_id, block_id, or discussion_id required. Cannot start new inline discussions via API - must respond to existing threads or comment on pages/blocks."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    id:
+      type: string
+    created_time:
+      type: string
+    last_edited_time:
+      type: string
+    rich_text:
+      type: array
+    parent:
+      type: object
+  required: ["object", "id"]
+
+examples:
+  - name: "Comment on page with simple text"
+    params:
+      parent:
+        page_id: be633bf1-dfa0-436d-b259-571129a590e5
+      rich_text:
+        - type: text
+          text:
+            content: "This looks great! Consider adding more examples."
+    expected_result: "Comment posted on the page"
+  - name: "Reply to discussion thread"
+    params:
+      discussion_id: "discussion-thread-id"
+      rich_text:
+        - type: text
+          text:
+            content: "I agree with this suggestion"
+          annotations:
+            bold: true
+    expected_result: "Reply added to existing discussion thread"
+  - name: "Comment on block with attachment"
+    params:
+      parent:
+        block_id: block-id-uuid
+      rich_text:
+        - type: text
+          text:
+            content: "Attached document:"
+      attachments:
+        - url: https://example.com/document.pdf
+    expected_result: "Comment posted on block with file attachment"

package/tools/notion_create_page/definition.yaml

@@ -0,0 +1,127 @@
+name: notion_create_page
+description: Create a new page in a Notion database or as a child of an existing page
+version: "1.0.0"
+parameters:
+  parent:
+    type: object
+    required: true
+    description: |
+      Where to create the page. Provide ONE of:
+      - {"database_id": "..."}  to create in a database
+      - {"page_id": "..."}  to create as a sub-page
+      Get database_id from notion_list_databases.
+  properties:
+    type: object
+    required: false
+    description: |
+      Optional page properties (title, fields, etc).
+      Properties must match the parent database schema.
+      Simpler: just use 'markdown' parameter instead for content.
+  icon:
+    type: object
+    required: false
+    description: Page icon - object with type (emoji, external, file) and icon content
+  cover:
+    type: object
+    required: false
+    description: Page cover image - object with type (file, external) and image details
+  children:
+    type: array
+    required: false
+    description: Array of block objects to add to the page. Max 100 items
+  markdown:
+    type: string
+    required: false
+    description: |
+      Page content using Markdown syntax. Simple and works anywhere.
+      Example: "# My Title\n\nSome content here"
+      EASIEST WAY TO ADD CONTENT - use this instead of 'properties' for simplicity.
+  template:
+    type: object
+    required: false
+    description: Template to use for the page. Specify type and optional template_id
+  position:
+    type: object
+    required: false
+    description: Position of page in parent. Can specify before_id or after_id
+
+execution:
+  type: function
+  code: './index.ts'
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Ensure 'Insert content' capability is enabled on the parent. Properties must match parent database schema. For database parents, properties are required. For page parents, only title is supported via properties. Either children or markdown can be used, not both. When using template, children parameter is not allowed."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    id:
+      type: string
+    created_time:
+      type: string
+    last_edited_time:
+      type: string
+    archived:
+      type: boolean
+    in_trash:
+      type: boolean
+    is_locked:
+      type: boolean
+    url:
+      type: string
+    public_url:
+      type: string
+    parent:
+      type: object
+    properties:
+      type: object
+    icon:
+      type: object
+    cover:
+      type: object
+  required: ["object", "id", "url"]
+
+examples:
+  - name: "Create page in database"
+    params:
+      parent:
+        database_id: a1d8501e-1ac1-43e9-a6bd-ea9fe6c8822b
+      properties:
+        Name:
+          title:
+            - text:
+                content: "New Page"
+    expected_result: "Creates a new page in the database with the specified properties"
+  - name: "Create page under existing page"
+    params:
+      parent:
+        page_id: be633bf1-dfa0-436d-b259-571129a590e5
+      children:
+        - object: block
+          type: paragraph
+          paragraph:
+            rich_text:
+              - type: text
+                text:
+                  content: "Page content"
+    expected_result: "Creates a subpage with content blocks"
+  - name: "Create page with emoji icon"
+    params:
+      parent:
+        database_id: a1d8501e-1ac1-43e9-a6bd-ea9fe6c8822b
+      properties:
+        Name:
+          title:
+            - text:
+                content: "Task"
+      icon:
+        type: emoji
+        emoji: "✅"
+    expected_result: "Creates a page with an emoji icon"

package/tools/notion_create_page/index.ts

@@ -0,0 +1,259 @@
+import axios from 'axios';
+import { MatimoError, ErrorCode } from '@matimo/core';
+
+interface Params {
+  parent?: Record<string, unknown>;
+  properties?: Record<string, unknown>;
+  icon?: Record<string, unknown>;
+  cover?: Record<string, unknown>;
+  children?: unknown[];
+  markdown?: string;
+  template?: Record<string, unknown>;
+  position?: Record<string, unknown>;
+}
+
+function markdownToChildren(md: string): unknown[] {
+  // Very small converter: split paragraphs and handle headings (#, ##, ###)
+  const parts = md.split(/\n\n+/).map((p) => p.trim()).filter(Boolean);
+  const blocks: unknown[] = [];
+
+  for (const part of parts) {
+    if (part.startsWith('# ')) {
+      blocks.push({
+        object: 'block',
+        type: 'heading_1',
+        heading_1: { rich_text: [{ type: 'text', text: { content: part.replace(/^#\s+/, '') } }] },
+      });
+    } else if (part.startsWith('## ')) {
+      blocks.push({
+        object: 'block',
+        type: 'heading_2',
+        heading_2: { rich_text: [{ type: 'text', text: { content: part.replace(/^##\s+/, '') } }] },
+      });
+    } else if (part.startsWith('### ')) {
+      blocks.push({
+        object: 'block',
+        type: 'heading_3',
+        heading_3: { rich_text: [{ type: 'text', text: { content: part.replace(/^###\s+/, '') } }] },
+      });
+    } else {
+      blocks.push({
+        object: 'block',
+        type: 'paragraph',
+        paragraph: { rich_text: [{ type: 'text', text: { content: part } }] },
+      });
+    }
+  }
+
+  return blocks;
+}
+
+export default async function createPage(params: Params) {
+  const {
+    parent: userProvidedParent,
+    properties,
+    icon,
+    cover,
+    children,
+    markdown,
+    template,
+    position,
+  } = params as Params;
+
+  const apiKey = process.env.NOTION_API_KEY;
+  if (!apiKey) {
+    throw new MatimoError('NOTION_API_KEY not set', ErrorCode.AUTH_FAILED, {
+      envVar: 'NOTION_API_KEY',
+    });
+  }
+
+  // If no parent provided, auto-discover a database
+  let parent = userProvidedParent;
+  if (!parent || typeof parent !== 'object') {
+    try {
+      const response = await axios.get('https://api.notion.com/v1/databases', {
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          'Notion-Version': '2025-09-03',
+        },
+        timeout: 15000,
+        params: { page_size: 1 },
+      });
+      const databases = response.data?.results || [];
+      if (databases.length > 0) {
+        parent = { database_id: databases[0].id };
+      } else {
+        throw new MatimoError(
+          'No databases found in workspace. Create a database first or provide `parent` parameter.',
+          ErrorCode.VALIDATION_FAILED
+        );
+      }
+    } catch (err) {
+      if (axios.isAxiosError(err)) {
+        throw new MatimoError(
+          `Failed to auto-discover database: ${(err.response?.data as Record<string, unknown>)?.message || err.message}`,
+          ErrorCode.EXECUTION_FAILED
+        );
+      }
+      throw new MatimoError('Failed to auto-discover database', ErrorCode.EXECUTION_FAILED);
+    }
+  }
+
+  // Validate parameters according to tool contract:
+  // - If creating inside a database (`parent.database_id`), `properties` is required
+  // - Either `children` or `markdown` can be provided, not both (empty children array is treated as not provided)
+  // - When using `template`, `children` is not allowed
+  const isDatabaseParent = parent && typeof parent === 'object' && Object.prototype.hasOwnProperty.call(parent, 'database_id');
+
+  if (Array.isArray(children) && children.length > 0 && typeof markdown === 'string' && markdown.trim().length > 0) {
+    throw new MatimoError('Provide either `children` or `markdown`, not both', ErrorCode.VALIDATION_FAILED, {
+      parameters: { children: children.length, markdown: markdown.length },
+    });
+  }
+
+  if (template && Array.isArray(children) && children.length > 0) {
+    throw new MatimoError('`template` cannot be used together with `children`. Omit `children` when using `template`', ErrorCode.VALIDATION_FAILED, {
+      parameters: { template: !!template, children: children.length },
+    });
+  }
+
+  // Allow generating a minimal title property from `markdown` when creating in a database.
+  // If caller didn't provide `properties`, we'll attempt several common title property names
+  // (e.g., 'Name', 'Title') derived from the first markdown line. If none succeed,
+  // we return the API error to the caller.
+  const resolvedProperties = properties as Record<string, unknown> | undefined;
+  let titleCandidates: string[] | undefined;
+
+  if (isDatabaseParent) {
+    const hasProperties = resolvedProperties && typeof resolvedProperties === 'object' && Object.keys(resolvedProperties).length > 0;
+
+    if (!hasProperties) {
+      if (typeof markdown === 'string' && markdown.trim().length > 0) {
+        // Candidate property names to try when the database title property name is unknown
+        titleCandidates = ['Name', 'Title', 'title', 'name'].map((k) => k);
+
+        // We'll construct properties later per candidate when sending the request.
+        // Use resolvedProperties only if caller provided it explicitly.
+      } else {
+        throw new MatimoError('Creating a page in a database requires `properties` (at minimum a title property)', ErrorCode.VALIDATION_FAILED, {
+          parent,
+        });
+      }
+    }
+  }
+
+  // Convert markdown to children if provided and children not explicitly set
+  let resolvedChildren = children;
+  if ((!resolvedChildren || (Array.isArray(resolvedChildren) && resolvedChildren.length === 0)) && markdown) {
+    resolvedChildren = markdownToChildren(markdown);
+  }
+
+  const baseBody: Record<string, unknown> = {
+    parent,
+  };
+
+  if (resolvedProperties) baseBody.properties = resolvedProperties;
+  if (icon) baseBody.icon = icon;
+  if (cover) baseBody.cover = cover;
+  if (resolvedChildren) baseBody.children = resolvedChildren;
+  if (template) baseBody.template = template;
+  if (position) baseBody.position = position;
+
+  // Helper to send request with a given body
+  const sendRequest = async (requestBody: Record<string, unknown>) => {
+    return axios.post('https://api.notion.com/v1/pages', requestBody, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Notion-Version': '2025-09-03',
+        'Content-Type': 'application/json',
+      },
+      timeout: 15000,
+    });
+  };
+
+  // If we have title candidates, try each one until a request succeeds.
+  if (titleCandidates && titleCandidates.length > 0) {
+    let lastError: unknown = null;
+    const firstLine = markdown!.split(/\r?\n/)[0].replace(/^#+\s*/, '').trim() || 'New Page';
+
+    for (const candidate of titleCandidates) {
+      const candidateProps: Record<string, unknown> = {
+        [candidate]: {
+          title: [
+            {
+              text: { content: firstLine },
+            },
+          ],
+        },
+      };
+
+      const tryBody = { ...baseBody, ...{ properties: candidateProps } } as Record<string, unknown>;
+
+      try {
+        const resp = await sendRequest(tryBody);
+        return {
+          success: true,
+          statusCode: resp.status,
+          data: resp.data,
+        };
+      } catch (err: unknown) {
+        lastError = err;
+        // If API returns validation error about missing property name, continue to next candidate.
+          if (axios.isAxiosError(err)) {
+            type NotionError = { message?: string; code?: string; request_id?: string };
+            const errData = err.response?.data as NotionError | undefined;
+            const message = errData?.message || '';
+            if (typeof message === 'string' && /is not a property that exists/i.test(message)) {
+              // try next candidate
+              continue;
+            }
+          }
+        // For other errors, break and return immediately
+        break;
+      }
+    }
+
+    // All candidates failed — return last error in a structured form
+    if (axios.isAxiosError(lastError)) {
+      type NotionError = { message?: string; code?: string; request_id?: string };
+      const errData = lastError.response?.data as NotionError | undefined;
+      const statusCode = lastError.response?.status || 0;
+      return {
+        success: false,
+        statusCode,
+        error: errData || (lastError as Error).message,
+      };
+    }
+
+    return {
+      success: false,
+      statusCode: 0,
+      error: String(lastError),
+    };
+  }
+
+  // No candidate loop — send single request using baseBody (which may include provided properties)
+  try {
+    const resp = await sendRequest(baseBody);
+    return {
+      success: true,
+      statusCode: resp.status,
+      data: resp.data,
+    };
+  } catch (err: unknown) {
+    if (axios.isAxiosError(err)) {
+      // Wrap HTTP error from Notion in a MatimoError so callers can programmatically inspect it
+      type NotionError = { message?: string; code?: string; request_id?: string };
+      const errData = err.response?.data as NotionError | undefined;
+      const details: Record<string, unknown> = {
+        status: err.response?.status,
+        code: errData?.code,
+        request_id: errData?.request_id,
+      };
+      throw new MatimoError(errData?.message || 'Notion API error', ErrorCode.EXECUTION_FAILED, details);
+    }
+
+    // Non-HTTP error (network, unexpected) — wrap and throw
+    throw new MatimoError(String(err), ErrorCode.UNKNOWN_ERROR);
+  }
+}

package/tools/notion_get_user/definition.yaml

@@ -0,0 +1,55 @@
+name: notion_get_user
+description: Retrieve information about a Notion user
+version: "1.0.0"
+parameters:
+  user_id:
+    type: string
+    required: true
+    description: The UUID of the user to retrieve
+
+execution:
+  type: http
+  method: GET
+  url: "https://api.notion.com/v1/users/{user_id}"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2025-09-03"
+  timeout: 10000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Ensure 'Read user information' capability is enabled. Returns user details including name, avatar, email (if available). User IDs can be obtained from page.created_by, page.last_edited_by, or database results."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    id:
+      type: string
+    type:
+      type: string
+    name:
+      type: string
+    avatar_url:
+      type: string
+    person:
+      type: object
+      properties:
+        email:
+          type: string
+  required: ["object", "id", "type"]
+
+examples:
+  - name: "Get user information"
+    params:
+      user_id: "e79a0b74-3aba-4149-9f74-0bb5791a6ee6"
+    expected_result: "Returns user details with name, avatar, email"
+  - name: "Get bot user info"
+    params:
+      user_id: "c2f20311-9e54-4d11-8c79-7398424ae41e"
+    expected_result: "Returns bot/integration user information"

package/tools/notion_list_databases/definition.yaml

@@ -0,0 +1,70 @@
+name: notion_list_databases
+description: |
+  List all databases (data sources) available in your Notion workspace.
+  Use this to discover what databases exist before querying them.
+  Each database has an id, title, icon, and URL that you can use for further operations.
+version: "1.0.0"
+
+parameters:
+  page_size:
+    type: number
+    required: true
+    description: How many databases to return (1-100). Set this explicitly to avoid sending a literal placeholder when omitted.
+
+execution:
+  type: http
+  method: POST
+  url: "https://api.notion.com/v1/search"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2025-09-03"
+    Content-Type: application/json
+  body:
+    filter:
+      property: object
+      value: data_source
+    page_size: "{page_size}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Lists only databases shared with your integration. Respects integration's read capabilities."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    results:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          title:
+            type: array
+          icon:
+            type: object
+          url:
+            type: string
+    has_more:
+      type: boolean
+    next_cursor:
+      type:
+        - string
+        - "null"
+
+examples:
+  - name: "List all databases in workspace"
+    params:
+      page_size: 10
+    expected_result: "Returns array of database objects with id, title, icon, and url"
+  - name: "List first database only"
+    params:
+      page_size: 1
+    expected_result: "Returns single database object"

package/tools/notion_query_database/definition.yaml

@@ -0,0 +1,100 @@
+name: notion_query_database
+description: Query pages from a Notion database to retrieve content. Use notion_list_databases first to get the database ID.
+version: "1.0.0"
+parameters:
+  database_id:
+    type: string
+    required: true
+    description: The ID of the database to query. Get from notion_list_databases (item.id)
+  sorts:
+    type: array
+    required: false
+    description: Array of sort objects to order results by properties or timestamps
+  filter:
+    type: object
+    required: false
+    description: Filter criteria as JSON object to narrow results
+  page_size:
+    type: number
+    required: false
+    description: Number of results per request (default 100, max 100)
+  start_cursor:
+    type: string
+    required: false
+    description: Cursor for pagination to retrieve next set of results
+  archived:
+    type: boolean
+    required: false
+    description: If true, include archived pages in results
+  in_trash:
+    type: boolean
+    required: false
+    description: If true, include pages in trash in results
+  result_type:
+    type: string
+    required: false
+    description: Filter results by type - page or data_source (for wikis only)
+
+execution:
+  type: http
+  method: POST
+  url: "https://api.notion.com/v1/data_sources/{database_id}/query"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2025-09-03"
+    Content-Type: application/json
+  body:
+    sorts: "{sorts}"
+    filter: "{filter}"
+    page_size: "{page_size}"
+    start_cursor: "{start_cursor}"
+    archived: "{archived}"
+    in_trash: "{in_trash}"
+    result_type: "{result_type}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  api_version: "2025-09-03"
+  caution: "Uses current Notion API (2025-09-03). Ensure 'Read content' capability is enabled on the integration. Filter and sort are optional - omit if not needed. API returns max 100 items per call."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    type:
+      type: string
+    results:
+      type: array
+    has_more:
+      type: boolean
+    next_cursor:
+      type: string
+  required: ["object", "results", "has_more"]
+
+examples:
+  - name: "Query data source - all pages"
+    params:
+      database_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
+    expected_result: "Returns paginated list of all pages in the database"
+  - name: "Query data source - with filter"
+    params:
+      database_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
+      filter:
+        property: Status
+        status:
+          equals: Done
+    expected_result: "Returns pages where the Status property equals 'Done'"
+  - name: "Query data source - with sorting"
+    params:
+      database_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
+      sorts:
+        - property: Created
+          direction: descending
+      page_size: 25
+    expected_result: "Returns up to 25 pages sorted by creation date (descending)"

package/tools/notion_search/definition.yaml

@@ -0,0 +1,87 @@
+name: notion_search
+description: Search across all pages and data sources in Notion workspace by title
+version: "1.0.0"
+parameters:
+  query:
+    type: string
+    required: false
+    description: Search text to find in page/data_source titles - omit to return all shared items
+  filter_object:
+    type: object
+    required: false
+    description: Filter results by object type - page or data_source
+  sort_direction:
+    type: string
+    required: false
+    description: Sort direction - ascending or descending
+  sort_timestamp:
+    type: string
+    required: false
+    description: Sort by timestamp - last_edited_time (default) or created_time
+  page_size:
+    type: number
+    required: false
+    description: Number of results per request
+  start_cursor:
+    type: string
+    required: false
+    description: Cursor for pagination to retrieve next set of results
+
+execution:
+  type: http
+  method: POST
+  url: "https://api.notion.com/v1/search"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2025-09-03"
+    Content-Type: application/json
+  body:
+    query: "{query}"
+    filter: "{filter_object}"
+    sort:
+      direction: "{sort_direction}"
+      timestamp: "{sort_timestamp}"
+    page_size: "{page_size}"
+    start_cursor: "{start_cursor}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Omit 'query' parameter to return all pages/data sources shared with integration. Filter and sort are optional. Results respect integration's read capabilities. API version 2025-09-03."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    type:
+      type: string
+    page_or_data_source:
+      type: object
+    results:
+      type: array
+    has_more:
+      type: boolean
+    next_cursor:
+      type: string
+  required: ["object", "type", "results", "has_more"]
+
+examples:
+  - name: "Search for pages by title"
+    params:
+      query: "meeting notes"
+    expected_result: "Returns all pages with 'meeting notes' in title"
+  - name: "Search data sources only"
+    params:
+      filter_object: "data_source"
+      sort_timestamp: "last_edited_time"
+      sort_direction: "descending"
+    expected_result: "Returns recently edited data sources only"
+  - name: "Get all shared items"
+    params:
+      page_size: 50
+    expected_result: "Returns first 50 pages and data sources shared with integration"

package/tools/notion_update_page/definition.yaml

@@ -0,0 +1,117 @@
+name: notion_update_page
+description: Update properties, icon, cover, or other attributes of an existing Notion page
+version: "1.0.0"
+parameters:
+  page_id:
+    type: string
+    required: true
+    description: The ID of the page to update (UUID format, dashes optional)
+  properties:
+    type: object
+    required: false
+    description: Page properties to update as JSON object - must match parent data source schema
+  icon:
+    type: object
+    required: false
+    description: Page icon object with type and content (emoji, external URL, or file)
+  cover:
+    type: object
+    required: false
+    description: Page cover image object with type and file/external URL details
+  is_locked:
+    type: boolean
+    required: false
+    description: Whether to lock page from editing in Notion UI
+  template:
+    type: object
+    required: false
+    description: Template object to apply - type default or template_id with specific template ID
+  erase_content:
+    type: boolean
+    required: false
+    description: Whether to erase all existing page content (use with template to replace content)
+  archived:
+    type: boolean
+    required: false
+    description: Whether to archive or restore the page
+  in_trash:
+    type: boolean
+    required: false
+    description: Whether to move page to trash or restore it
+
+execution:
+  type: http
+  method: PATCH
+  url: "https://api.notion.com/v1/pages/{page_id}"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2025-09-03"
+    Content-Type: application/json
+  body:
+    properties: "{properties}"
+    icon: "{icon}"
+    cover: "{cover}"
+    is_locked: "{is_locked}"
+    template: "{template}"
+    erase_content: "{erase_content}"
+    archived: "{archived}"
+    in_trash: "{in_trash}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Ensure 'Update content' capability is enabled. Only include parameters you want to change. Cannot update parent, created_by, created_time, last_edited_by, last_edited_time, or rollup properties via API."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    id:
+      type: string
+    created_time:
+      type: string
+    last_edited_time:
+      type: string
+    archived:
+      type: boolean
+    in_trash:
+      type: boolean
+    is_locked:
+      type: boolean
+    properties:
+      type: object
+  required: ["object", "id", "last_edited_time"]
+
+examples:
+  - name: "Update page title"
+    params:
+      page_id: "be633bf1-dfa0-436d-b259-571129a590e5"
+      properties:
+        Name:
+          title:
+            - text:
+                content: Updated Title
+    expected_result: "Page title updated to 'Updated Title'"
+  - name: "Update page icon"
+    params:
+      page_id: "be633bf1-dfa0-436d-b259-571129a590e5"
+      icon:
+        type: emoji
+        emoji: "🎉"
+    expected_result: "Page icon changed to celebration emoji"
+  - name: "Update page with cover and apply template"
+    params:
+      page_id: "be633bf1-dfa0-436d-b259-571129a590e5"
+      cover:
+        type: external
+        external:
+          url: https://example.com/image.png
+      template:
+        type: default
+      erase_content: true
+    expected_result: "Page cover set, default template applied, existing content replaced"