@commandable/integration-data 0.0.1

package/integrations/notion/__tests__/usage_parity.test.ts

@@ -0,0 +1,34 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { loadIntegrationManifest } from '../../../src/integrations/dataLoader.js'
+
+function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+describe('notion static usage parity', () => {
+  it('every manifest tool is referenced in tests via build*(name)', () => {
+    const manifest = loadIntegrationManifest('notion')!
+    const toolNames = (manifest.tools as any[]).map(t => t.name)
+
+    const testsDir = fileURLToPath(new URL('.', import.meta.url))
+    expect(existsSync(testsDir)).toBe(true)
+    const testFiles = readdirSync(testsDir)
+      .filter(f => /\.test\.(t|j)s$/.test(f) && !f.includes('usage_parity.test'))
+      .map(f => resolve(testsDir, f))
+
+    const fileContents = testFiles.map(f => readFileSync(f, 'utf8'))
+
+    const missing: string[] = []
+    for (const name of toolNames) {
+      const nameRe = new RegExp(`build(?:Read|Write|Admin)?(?:Handler)?\\(\\s*['\"\`]${escapeRegExp(name)}['\"\`]\\s*\\)`, 'm')
+      const found = fileContents.some(src => nameRe.test(src))
+      if (!found)
+        missing.push(name)
+    }
+
+    expect(missing, `Missing handler usages in tests: ${missing.join(', ')}`).toEqual([])
+  })
+})

package/integrations/notion/__tests__/write_and_admin_handlers.test.ts

@@ -0,0 +1,190 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import { IntegrationProxy } from '../../../src/integrations/proxy.js'
+import { loadIntegrationTools } from '../../../src/integrations/dataLoader.js'
+
+interface Ctx {
+  createdPageId?: string
+  parentDatabaseId?: string
+  createdDatabaseId?: string
+}
+
+const env = process.env as Record<string, string>
+const hasEnv = (...keys: string[]) => keys.every(k => !!env[k] && env[k].trim().length > 0)
+const suite = hasEnv(
+  'COMMANDABLE_MANAGED_OAUTH_BASE_URL',
+  'COMMANDABLE_MANAGED_OAUTH_SECRET_KEY',
+  'NOTION_TEST_CONNECTION_ID',
+)
+  ? describe
+  : describe.skip
+
+suite('notion write handlers (live)', () => {
+  const ctx: Ctx = {}
+  let buildWrite: (name: string) => ((input: any) => Promise<any>)
+  let buildRead: (name: string) => ((input: any) => Promise<any>)
+
+  beforeAll(async () => {
+    const { COMMANDABLE_MANAGED_OAUTH_BASE_URL, COMMANDABLE_MANAGED_OAUTH_SECRET_KEY, NOTION_TEST_CONNECTION_ID } = env
+
+    const proxy = new IntegrationProxy({
+      managedOAuthBaseUrl: COMMANDABLE_MANAGED_OAUTH_BASE_URL,
+      managedOAuthSecretKey: COMMANDABLE_MANAGED_OAUTH_SECRET_KEY,
+    })
+    const integrationNode = { id: 'node-notion', type: 'notion', label: 'Notion', connectionId: NOTION_TEST_CONNECTION_ID } as any
+
+    const tools = loadIntegrationTools('notion')
+    expect(tools).toBeTruthy()
+
+    buildWrite = (name: string) => {
+      const tool = tools!.write.find(t => t.name === name)
+      expect(tool, `write tool ${name} exists`).toBeTruthy()
+      const integration = { fetch: (path: string, init?: RequestInit) => proxy.call(integrationNode, path, init) }
+      const build = new Function('integration', `return (${tool!.handlerCode});`)
+      return build(integration) as (input: any) => Promise<any>
+    }
+
+    buildRead = (name: string) => {
+      const tool = tools!.read.find(t => t.name === name)
+      expect(tool, `read tool ${name} exists`).toBeTruthy()
+      const integration = { fetch: (path: string, init?: RequestInit) => proxy.call(integrationNode, path, init) }
+      const build = new Function('integration', `return (${tool!.handlerCode});`)
+      return build(integration) as (input: any) => Promise<any>
+    }
+
+    // Try to find a database to create a page in by searching
+    try {
+      const search = buildRead('search')
+      const res = await search({ query: '', filter: { value: 'database', property: 'object' }, page_size: 1 })
+      ctx.parentDatabaseId = res?.results?.[0]?.id
+    }
+    catch {}
+  }, 60000)
+
+  it('create_page -> retrieve_page -> update_page_properties', async () => {
+    if (!ctx.parentDatabaseId)
+      return expect(true).toBe(true)
+
+    const create_page = buildWrite('create_page')
+    const titleText = `CmdTest ${Date.now()}`
+    const created = await create_page({
+      parent: { database_id: ctx.parentDatabaseId },
+      properties: {
+        Name: { title: [{ type: 'text', text: { content: titleText } }] },
+      },
+    })
+    const pageId = created?.id
+    expect(pageId).toBeTruthy()
+    ctx.createdPageId = pageId
+
+    const retrieve_page = buildRead('retrieve_page')
+    const got = await retrieve_page({ page_id: pageId })
+    expect(got?.id).toBe(pageId)
+
+    const update_page_properties = buildWrite('update_page_properties')
+    const newTitle = `${titleText} Updated`
+    const updated = await update_page_properties({ page_id: pageId, properties: { Name: { title: [{ type: 'text', text: { content: newTitle } }] } } })
+    expect(updated?.id).toBe(pageId)
+
+    // Verify via retrieve
+    const gotAfter = await retrieve_page({ page_id: pageId })
+    const gotTitle = gotAfter?.properties?.Name?.title?.[0]?.plain_text || gotAfter?.properties?.Name?.title?.[0]?.text?.content
+    expect(gotTitle?.includes('Updated')).toBe(true)
+  }, 90000)
+
+  it('append_block_children on created page', async () => {
+    if (!ctx.createdPageId)
+      return expect(true).toBe(true)
+    const append_block_children = buildWrite('append_block_children')
+    const contentText = 'Hello from test'
+    const res = await append_block_children({
+      block_id: ctx.createdPageId,
+      children: [
+        { object: 'block', type: 'paragraph', paragraph: { rich_text: [{ type: 'text', text: { content: contentText } }] } },
+      ],
+    })
+    expect(res).toBeTruthy()
+
+    // Verify via list_block_children
+    const list_block_children = buildRead('list_block_children')
+    const listed = await list_block_children({ block_id: ctx.createdPageId })
+    const found = (listed?.results || listed || []).some((b: any) => b?.paragraph?.rich_text?.some((t: any) => (t?.plain_text || t?.text?.content) === contentText))
+    expect(found).toBe(true)
+  }, 60000)
+
+  it('create_comment on created page', async () => {
+    if (!ctx.createdPageId)
+      return expect(true).toBe(true)
+    const create_comment = buildWrite('create_comment')
+    const commentText = 'Test comment'
+    const res = await create_comment({ parent: { block_id: ctx.createdPageId }, rich_text: [{ type: 'text', text: { content: commentText } }] })
+    expect(res?.object === 'comment' || res?.results).toBeTruthy()
+
+    // Verify via list_comments
+    const list_comments = buildRead('list_comments')
+    const comments = await list_comments({ block_id: ctx.createdPageId })
+    const hasComment = (comments?.results || comments || []).some((c: any) => c?.rich_text?.some((t: any) => (t?.plain_text || t?.text?.content)?.includes(commentText)))
+    expect(hasComment).toBe(true)
+  }, 60000)
+
+  it('update_block and delete_block on appended paragraph', async () => {
+    if (!ctx.createdPageId)
+      return expect(true).toBe(true)
+    // Create a specific block to edit
+    const append_block_children = buildWrite('append_block_children')
+    const appended = await append_block_children({
+      block_id: ctx.createdPageId,
+      children: [
+        { object: 'block', type: 'paragraph', paragraph: { rich_text: [{ type: 'text', text: { content: 'Edit me' } }] } },
+      ],
+    })
+    const blockId = appended?.results?.[0]?.id || appended?.id
+    if (!blockId)
+      return expect(true).toBe(true)
+
+    const update_block = buildWrite('update_block')
+    const editedText = 'Edited'
+    const updated = await update_block({ block_id: blockId, body: { paragraph: { rich_text: [{ type: 'text', text: { content: editedText } }] } } })
+    expect(updated?.id).toBe(blockId)
+
+    // Verify via retrieve_block
+    const retrieve_block = buildRead('retrieve_block')
+    const gotBlock = await retrieve_block({ block_id: blockId })
+    const gotEdited = gotBlock?.paragraph?.rich_text?.some((t: any) => (t?.plain_text || t?.text?.content) === editedText)
+    expect(gotEdited).toBe(true)
+
+    const delete_block = buildWrite('delete_block')
+    const del = await delete_block({ block_id: blockId })
+    expect(del?.archived === true || del?.id === blockId).toBe(true)
+
+    // Verify archived via retrieve_block
+    const gotAfterDelete = await retrieve_block({ block_id: blockId })
+    expect(gotAfterDelete?.archived === true).toBe(true)
+  }, 90000)
+
+  it('create_database then update_database under created page (optional)', async () => {
+    if (!ctx.createdPageId)
+      return expect(true).toBe(true)
+    const create_database = buildWrite('create_database')
+    const created = await create_database({
+      parent: { page_id: ctx.createdPageId },
+      title: [{ type: 'text', text: { content: `CmdDB ${Date.now()}` } }],
+      properties: {
+        Name: { title: {} },
+        Status: { select: { options: [{ name: 'Open' }, { name: 'Done' }] } },
+      },
+    })
+    const dbId = created?.id
+    ctx.createdDatabaseId = dbId
+    expect(dbId).toBeTruthy()
+
+    const update_database = buildWrite('update_database')
+    const updated = await update_database({ database_id: dbId, title: [{ type: 'text', text: { content: 'CmdDB Updated' } }] })
+    expect(updated?.id).toBe(dbId)
+
+    // Verify via retrieve_database
+    const retrieve_database = buildRead('retrieve_database')
+    const gotDb = await retrieve_database({ database_id: dbId })
+    const titleText = gotDb?.title?.[0]?.plain_text || gotDb?.title?.[0]?.text?.content
+    expect(titleText?.includes('Updated')).toBe(true)
+  }, 120000)
+})

package/integrations/notion/credentials.json

@@ -0,0 +1,21 @@
+{
+  "schema": {
+    "type": "object",
+    "properties": {
+      "token": {
+        "type": "string",
+        "title": "Internal Integration Token",
+        "description": "Notion internal integration token (starts with \"secret_\")."
+      }
+    },
+    "required": ["token"],
+    "additionalProperties": false
+  },
+  "injection": {
+    "headers": {
+      "Authorization": "Bearer {{token}}",
+      "Notion-Version": "2022-06-28"
+    }
+  }
+}
+

package/integrations/notion/credentials_hint.md

@@ -0,0 +1,5 @@
+1. Go to `https://www.notion.so/profile/integrations/internal`
+2. Create a Notion integration in Notion’s developer settings
+3. Share your target pages/databases with that integration so it has access
+4. Copy the **Internal Integration Token** (usually starts with `secret_`)
+

package/integrations/notion/handlers/append_block_children.js

@@ -0,0 +1,7 @@
+async (input) => {
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}/children`, {
+    method: 'PATCH',
+    body: { children: input.children },
+  })
+  return await res.json()
+}

package/integrations/notion/handlers/create_comment.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const res = await integration.fetch(`/comments`, {
+    method: 'POST',
+    body: {
+      parent: input.parent,
+      rich_text: input.rich_text,
+    },
+  })
+  return await res.json()
+}

package/integrations/notion/handlers/create_database.js

@@ -0,0 +1,11 @@
+async (input) => {
+  const res = await integration.fetch(`/databases`, {
+    method: 'POST',
+    body: {
+      parent: input.parent,
+      title: input.title,
+      properties: input.properties,
+    },
+  })
+  return await res.json()
+}

package/integrations/notion/handlers/create_page.js

@@ -0,0 +1,13 @@
+async (input) => {
+  const res = await integration.fetch(`/pages`, {
+    method: 'POST',
+    body: {
+      parent: input.parent,
+      properties: input.properties,
+      children: input.children || undefined,
+      icon: input.icon || undefined,
+      cover: input.cover || undefined,
+    },
+  })
+  return await res.json()
+}

package/integrations/notion/handlers/delete_block.js

@@ -0,0 +1,8 @@
+async (input) => {
+  // Notion 'delete' is archive block
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}`, {
+    method: 'PATCH',
+    body: { archived: true },
+  })
+  return await res.json()
+}

package/integrations/notion/handlers/get_me.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/users/me`)
+  return await res.json()
+}

package/integrations/notion/handlers/list_block_children.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.start_cursor)
+    params.set('start_cursor', input.start_cursor)
+  if (input.page_size)
+    params.set('page_size', String(input.page_size))
+  const qs = params.toString()
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}/children${qs ? `?${qs}` : ''}`)
+  return await res.json()
+}

package/integrations/notion/handlers/list_comments.js

@@ -0,0 +1,14 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.block_id)
+    params.set('block_id', input.block_id)
+  if (input.discussion_id)
+    params.set('discussion_id', input.discussion_id)
+  if (input.start_cursor)
+    params.set('start_cursor', input.start_cursor)
+  if (input.page_size)
+    params.set('page_size', String(input.page_size))
+  const qs = params.toString()
+  const res = await integration.fetch(`/comments${qs ? `?${qs}` : ''}`)
+  return await res.json()
+}

package/integrations/notion/handlers/list_users.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.start_cursor)
+    params.set('start_cursor', input.start_cursor)
+  if (input.page_size)
+    params.set('page_size', String(input.page_size))
+  const qs = params.toString()
+  const res = await integration.fetch(`/users${qs ? `?${qs}` : ''}`)
+  return await res.json()
+}

package/integrations/notion/handlers/query_database.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const body = {
+    filter: input.filter || undefined,
+    sorts: input.sorts || undefined,
+    start_cursor: input.start_cursor || undefined,
+    page_size: input.page_size || undefined,
+  }
+  const res = await integration.fetch(`/databases/${encodeURIComponent(input.database_id)}/query`, { method: 'POST', body })
+  return await res.json()
+}

package/integrations/notion/handlers/retrieve_block.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}`)
+  return await res.json()
+}

package/integrations/notion/handlers/retrieve_database.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/databases/${encodeURIComponent(input.database_id)}`)
+  return await res.json()
+}

package/integrations/notion/handlers/retrieve_page.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/pages/${encodeURIComponent(input.page_id)}`)
+  return await res.json()
+}

package/integrations/notion/handlers/retrieve_page_property_item.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.start_cursor)
+    params.set('start_cursor', input.start_cursor)
+  if (input.page_size)
+    params.set('page_size', String(input.page_size))
+  const qs = params.toString()
+  const res = await integration.fetch(`/pages/${encodeURIComponent(input.page_id)}/properties/${encodeURIComponent(input.property_id)}${qs ? `?${qs}` : ''}`)
+  return await res.json()
+}

package/integrations/notion/handlers/retrieve_user.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/users/${encodeURIComponent(input.user_id)}`)
+  return await res.json()
+}

package/integrations/notion/handlers/search.js

@@ -0,0 +1,11 @@
+async (input) => {
+  const body = {
+    query: input.query || '',
+    filter: input.filter || undefined,
+    sort: input.sort || undefined,
+    start_cursor: input.start_cursor || undefined,
+    page_size: input.page_size || undefined,
+  }
+  const res = await integration.fetch(`/search`, { method: 'POST', body })
+  return await res.json()
+}

package/integrations/notion/handlers/update_block.js

@@ -0,0 +1,7 @@
+async (input) => {
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}`, {
+    method: 'PATCH',
+    body: input.body || {},
+  })
+  return await res.json()
+}

package/integrations/notion/handlers/update_database.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const body = {
+    title: input.title || undefined,
+    description: input.description || undefined,
+    properties: input.properties || undefined,
+    archived: input.archived === undefined ? undefined : input.archived,
+  }
+  const res = await integration.fetch(`/databases/${encodeURIComponent(input.database_id)}`, { method: 'PATCH', body })
+  return await res.json()
+}

package/integrations/notion/handlers/update_page_properties.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const body = {
+    properties: input.properties,
+    archived: input.archived === undefined ? undefined : input.archived,
+    icon: input.icon || undefined,
+    cover: input.cover || undefined,
+  }
+  const res = await integration.fetch(`/pages/${encodeURIComponent(input.page_id)}`, { method: 'PATCH', body })
+  return await res.json()
+}

package/integrations/notion/manifest.json

@@ -0,0 +1,139 @@
+{
+  "name": "notion",
+  "version": "0.1.0",
+  "tools": [
+    {
+      "name": "search",
+      "description": "Search across all accessible Notion content (pages, databases).",
+      "inputSchema": "schemas/search.json",
+      "handler": "handlers/search.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_page",
+      "description": "Retrieve a page by ID.",
+      "inputSchema": "schemas/id_page.json",
+      "handler": "handlers/retrieve_page.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_database",
+      "description": "Retrieve a database by ID.",
+      "inputSchema": "schemas/id_database.json",
+      "handler": "handlers/retrieve_database.js",
+      "scope": "read"
+    },
+    {
+      "name": "query_database",
+      "description": "Query a database with optional filter, sorts, and pagination.",
+      "inputSchema": "schemas/query_database.json",
+      "handler": "handlers/query_database.js",
+      "scope": "read"
+    },
+    {
+      "name": "list_block_children",
+      "description": "List child blocks for a block (including page blocks).",
+      "inputSchema": "schemas/list_block_children.json",
+      "handler": "handlers/list_block_children.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_block",
+      "description": "Retrieve a block by ID.",
+      "inputSchema": "schemas/id_block.json",
+      "handler": "handlers/retrieve_block.js",
+      "scope": "read"
+    },
+    {
+      "name": "list_users",
+      "description": "List users in the workspace.",
+      "inputSchema": "schemas/list_users.json",
+      "handler": "handlers/list_users.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_user",
+      "description": "Retrieve a user by ID.",
+      "inputSchema": "schemas/id_user.json",
+      "handler": "handlers/retrieve_user.js",
+      "scope": "read"
+    },
+    {
+      "name": "list_comments",
+      "description": "List comments for a given discussion or page block.",
+      "inputSchema": "schemas/list_comments.json",
+      "handler": "handlers/list_comments.js",
+      "scope": "read"
+    },
+    {
+      "name": "get_me",
+      "description": "Retrieve the authenticated user (bot) profile.",
+      "inputSchema": "schemas/empty.json",
+      "handler": "handlers/get_me.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_page_property_item",
+      "description": "Retrieve a specific page property item (handles rollups and pagination).",
+      "inputSchema": "schemas/retrieve_page_property_item.json",
+      "handler": "handlers/retrieve_page_property_item.js",
+      "scope": "read"
+    },
+    {
+      "name": "create_page",
+      "description": "Create a new page in a database or as a child of a page.",
+      "inputSchema": "schemas/create_page.json",
+      "handler": "handlers/create_page.js",
+      "scope": "write"
+    },
+    {
+      "name": "update_page_properties",
+      "description": "Update page properties, archive/unarchive, icon and cover.",
+      "inputSchema": "schemas/update_page_properties.json",
+      "handler": "handlers/update_page_properties.js",
+      "scope": "write"
+    },
+    {
+      "name": "append_block_children",
+      "description": "Append child blocks to a block (including page blocks).",
+      "inputSchema": "schemas/append_block_children.json",
+      "handler": "handlers/append_block_children.js",
+      "scope": "write"
+    },
+    {
+      "name": "update_block",
+      "description": "Update a block (content, archived state, etc).",
+      "inputSchema": "schemas/update_block.json",
+      "handler": "handlers/update_block.js",
+      "scope": "write"
+    },
+    {
+      "name": "delete_block",
+      "description": "Archive a block (soft delete).",
+      "inputSchema": "schemas/delete_block.json",
+      "handler": "handlers/delete_block.js",
+      "scope": "write"
+    },
+    {
+      "name": "create_comment",
+      "description": "Create a comment on a discussion or block.",
+      "inputSchema": "schemas/create_comment.json",
+      "handler": "handlers/create_comment.js",
+      "scope": "write"
+    },
+    {
+      "name": "create_database",
+      "description": "Create a new database under a page.",
+      "inputSchema": "schemas/create_database.json",
+      "handler": "handlers/create_database.js",
+      "scope": "write"
+    },
+    {
+      "name": "update_database",
+      "description": "Update database title, description, properties, or archived state.",
+      "inputSchema": "schemas/update_database.json",
+      "handler": "handlers/update_database.js",
+      "scope": "write"
+    }
+  ]
+}

package/integrations/notion/prompt.md

@@ -0,0 +1,26 @@
+## Appending paragraph blocks
+
+When appending a paragraph block to a Notion page, ensure the `rich_text` field is correctly defined within the `paragraph` type. Example format:
+
+```json
+{
+  "block_id": "<page_id>",
+  "children": [
+    {
+      "object": "block",
+      "type": "paragraph",
+      "paragraph": {
+        "rich_text": [
+          {
+            "type": "text",
+            "text": {
+              "content": "Your text here"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+

package/integrations/notion/schemas/append_block_children.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["block_id", "children"],
+  "additionalProperties": false,
+  "properties": {
+    "block_id": { "type": "string" },
+    "children": { "type": "array", "items": { "type": "object" } }
+  }
+}

package/integrations/notion/schemas/create_comment.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["parent", "rich_text"],
+  "additionalProperties": false,
+  "properties": {
+    "parent": {
+      "type": "object",
+      "description": "Parent discussion_id or block_id.",
+      "additionalProperties": false,
+      "properties": {
+        "discussion_id": { "type": "string" },
+        "block_id": { "type": "string" }
+      }
+    },
+    "rich_text": { "type": "array", "items": { "type": "object" } }
+  }
+}