@commandable/integration-data 0.4.0 → 0.4.1

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

@@ -0,0 +1,156 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import { IntegrationProxy } from '../../../../core/src/integrations/proxy.js'
+import { loadIntegrationTools } from '../../../../core/src/integrations/dataLoader.js'
+
+// LIVE Notion integration tests using credentials
+// Required env vars:
+// - NOTION_TOKEN
+
+interface Ctx {
+  database_id?: string
+  page_id?: string
+  block_id?: 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(
+  'NOTION_TOKEN',
+)
+  ? describe
+  : describe.skip
+
+suite('notion read handlers (live)', () => {
+  const ctx: Ctx = {}
+  let buildHandler: (name: string) => ((input: any) => Promise<any>)
+
+  beforeAll(async () => {
+    const credentialStore = {
+      getCredentials: async () => ({ token: env.NOTION_TOKEN || '' }),
+    }
+
+    const proxy = new IntegrationProxy({ credentialStore })
+    const integrationNode = {
+      spaceId: 'ci',
+      id: 'node-notion',
+      referenceId: 'node-notion',
+      type: 'notion',
+      label: 'Notion',
+      connectionMethod: 'credentials',
+      credentialId: 'notion-creds',
+    } as any
+
+    const tools = loadIntegrationTools('notion')
+    expect(tools).toBeTruthy()
+
+    buildHandler = (name: string) => {
+      const tool = tools!.read.find(t => t.name === name)
+      expect(tool, `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 discover some IDs via search
+    const search = buildHandler('search')
+    const searchRes = await search({ query: '' })
+    const page = searchRes?.results?.find((r: any) => r.object === 'page')
+    const database = searchRes?.results?.find((r: any) => r.object === 'database')
+    ctx.page_id = page?.id
+    ctx.database_id = database?.id
+    if (ctx.page_id)
+      ctx.block_id = ctx.page_id
+  }, 60000)
+
+  it('search returns results', async () => {
+    const handler = buildHandler('search')
+    const result = await handler({ query: '' })
+    expect(result).toBeTruthy()
+  }, 30000)
+
+  it('retrieve_page returns a page', async () => {
+    if (!ctx.page_id)
+      return expect(true).toBe(true)
+    const handler = buildHandler('retrieve_page')
+    const result = await handler({ page_id: ctx.page_id })
+    expect(result?.object).toBe('page')
+  }, 30000)
+
+  it('retrieve_database returns a database', async () => {
+    if (!ctx.database_id)
+      return expect(true).toBe(true)
+    const handler = buildHandler('retrieve_database')
+    const result = await handler({ database_id: ctx.database_id })
+    expect(result?.object).toBe('database')
+  }, 30000)
+
+  it('query_database returns results', async () => {
+    if (!ctx.database_id)
+      return expect(true).toBe(true)
+    const handler = buildHandler('query_database')
+    const result = await handler({ database_id: ctx.database_id, page_size: 3 })
+    expect(result?.results).toBeTruthy()
+  }, 30000)
+
+  it('retrieve_block returns a block', async () => {
+    if (!ctx.block_id)
+      return expect(true).toBe(true)
+    const handler = buildHandler('retrieve_block')
+    const result = await handler({ block_id: ctx.block_id })
+    expect(result?.object).toBeTruthy()
+  }, 30000)
+
+  it('list_block_children returns children', async () => {
+    if (!ctx.block_id)
+      return expect(true).toBe(true)
+    const handler = buildHandler('list_block_children')
+    const result = await handler({ block_id: ctx.block_id, page_size: 5 })
+    expect(Array.isArray(result?.results)).toBe(true)
+  }, 30000)
+
+  it('list_users returns users', async () => {
+    const handler = buildHandler('list_users')
+    const result = await handler({ page_size: 5 })
+    expect(result).toBeTruthy()
+  }, 30000)
+
+  it('get_me returns current user', async () => {
+    const handler = buildHandler('get_me')
+    const result = await handler({})
+    expect(result).toBeTruthy()
+  }, 30000)
+
+  it('retrieve_user returns a user', async () => {
+    const list = buildHandler('list_users')
+    const users = await list({ page_size: 1 })
+    const uid = users?.results?.[0]?.id
+    if (!uid)
+      return expect(true).toBe(true)
+    const handler = buildHandler('retrieve_user')
+    const result = await handler({ user_id: uid })
+    expect(result?.id).toBe(uid)
+  }, 30000)
+
+  it('retrieve_page_property_item returns property data', async () => {
+    if (!ctx.page_id)
+      return expect(true).toBe(true)
+    const page = buildHandler('retrieve_page')
+    const p = await page({ page_id: ctx.page_id })
+    const propId = Object.values(p?.properties || {})?.[0]?.id
+    if (!propId)
+      return expect(true).toBe(true)
+    const handler = buildHandler('retrieve_page_property_item')
+    const result = await handler({ page_id: ctx.page_id, property_id: propId, page_size: 5 })
+    expect(result).toBeTruthy()
+  }, 30000)
+
+  it('list_comments returns comments for page or block', async () => {
+    if (!ctx.page_id)
+      return expect(true).toBe(true)
+    const handler = buildHandler('list_comments')
+    const result = await handler({ block_id: ctx.page_id })
+    expect(result).toBeTruthy()
+  }, 30000)
+})

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

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+import { getMissingToolUsages } from '../../__tests__/usageParity.js'
+
+describe('notion static usage parity', () => {
+  it('every manifest tool is referenced in tests', () => {
+    const missing = getMissingToolUsages({ integrationName: 'notion', importMetaUrl: import.meta.url })
+    expect(missing, `Missing handler usages in tests: ${missing.join(', ')}`).toEqual([])
+  })
+})

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

@@ -0,0 +1,186 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { createCredentialStore, createIntegrationNode, createProxy, createToolbox, hasEnv, safeCleanup } from '../../__tests__/liveHarness.js'
+
+interface Ctx {
+  createdPageId?: string
+  testDatabaseId?: string
+  createdDatabaseId?: string
+}
+
+const suite = hasEnv(
+  'NOTION_TOKEN',
+  'NOTION_TEST_PARENT_PAGE_ID',
+)
+  ? describe
+  : describe.skip
+
+suite('notion write handlers (live)', () => {
+  const ctx: Ctx = {}
+  let notion: ReturnType<typeof createToolbox>
+
+  beforeAll(async () => {
+    const env = process.env as Record<string, string | undefined>
+    const credentialStore = createCredentialStore(async () => ({ token: env.NOTION_TOKEN || '' }))
+    const proxy = createProxy(credentialStore)
+    notion = createToolbox('notion', proxy, createIntegrationNode('notion', { label: 'Notion', credentialId: 'notion-creds' }))
+
+    // Create a dedicated database under a known parent page for this run
+    const create_database = notion.write('create_database')
+    const createdDb = await create_database({
+      parent: { page_id: env.NOTION_TEST_PARENT_PAGE_ID },
+      title: [{ type: 'text', text: { content: `CmdTest DB ${Date.now()}` } }],
+      properties: {
+        Name: { title: {} },
+        Status: { select: { options: [{ name: 'Open' }, { name: 'Done' }] } },
+      },
+    })
+    ctx.testDatabaseId = createdDb?.id
+    expect(ctx.testDatabaseId).toBeTruthy()
+  }, 60000)
+
+  afterAll(async () => {
+    // Archive any created page + any created databases from this run
+    await safeCleanup(async () => {
+      if (!ctx.createdPageId)
+        return
+      const update_page_properties = notion.write('update_page_properties')
+      await update_page_properties({ page_id: ctx.createdPageId, properties: {}, archived: true })
+    })
+
+    await safeCleanup(async () => {
+      const update_database = notion.write('update_database')
+      if (ctx.createdDatabaseId)
+        await update_database({ database_id: ctx.createdDatabaseId, archived: true })
+      if (ctx.testDatabaseId)
+        await update_database({ database_id: ctx.testDatabaseId, archived: true })
+    })
+  }, 60_000)
+
+  it('create_page -> retrieve_page -> update_page_properties', async () => {
+    if (!ctx.testDatabaseId)
+      return expect(true).toBe(true)
+
+    const create_page = notion.write('create_page')
+    const titleText = `CmdTest ${Date.now()}`
+    const created = await create_page({
+      parent: { database_id: ctx.testDatabaseId },
+      properties: {
+        Name: { title: [{ type: 'text', text: { content: titleText } }] },
+      },
+    })
+    const pageId = created?.id
+    expect(pageId).toBeTruthy()
+    ctx.createdPageId = pageId
+
+    const retrieve_page = notion.read('retrieve_page')
+    const got = await retrieve_page({ page_id: pageId })
+    expect(got?.id).toBe(pageId)
+
+    const update_page_properties = notion.write('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 = notion.write('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 = notion.read('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 = notion.write('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 = notion.read('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 = notion.write('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 = notion.write('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 = notion.read('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 = notion.write('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 = notion.write('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 = notion.write('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 = notion.read('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,27 @@
+{
+  "variants": {
+    "internal_integration": {
+      "label": "Internal Integration Token",
+      "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"
+        }
+      },
+      "healthCheck": { "path": "/users/me" }
+    }
+  },
+  "default": "internal_integration"
+}

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()
+}