@kody/notion

@kody/notion — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Auth is the saved OAuth integration named notion — never paste tokens. Do not disable live webhooks or jobs. No user secrets for this package.

Import paths

Prefer static kody:@kody/notion/... imports from execute. Do not lead with packages.invoke.

Smoke test (read-only)

import smokeTest from 'kody:@kody/notion/smoke-test'

export default async function main() {
	return await smokeTest()
	// => { ok: true, tokenType, hasBotOwner } — no workspace/user PII
}

Overview (no network beyond package metadata):

import notionOverview from 'kody:@kody/notion'

export default async function main() {
	return await notionOverview()
}

dryRun / confirm (writes)

Mutating helpers and mutating request methods require confirm: true after explicit user approval of destination and content. Use dryRun: true to preview without calling Notion.

import createPage from 'kody:@kody/notion/create-page'

export default async function main() {
	return createPage({
		// database_id auto-resolves to the database's single data source
		parent: { database_id: '00000000-0000-0000-0000-000000000000' },
		properties: {
			Name: { title: [{ text: { content: 'New page' } }] },
		},
		dryRun: true,
	})
}

import search from 'kody:@kody/notion/search'

export default async function main() {
	return await search({ query: 'meeting notes', objectType: 'page' })
}

Edge cases / fork notes

• Notion-Version 2026-03-11: databases are containers; schema/rows live on data sources. get-database → data_sources; get-data-source for properties; query via data source. Helpers that take databaseId auto-resolve a single data source and error if there are several.
• Database-row pages need parent: { data_source_id } (or database_id for auto-resolve on create-page).
• Search returns data_source objects where databases used to appear — filter with objectType: 'page' | 'data_source'.
• Block position: position: { type: 'after_block' | 'start' | 'end', ... } — flat after is gone. Trash field is in_trash (no archived).
• Inline child databases: use request POST /databases with is_inline: true and initial_data_source.properties — not append-block-children.
• Do not round-trip saved formula expression values; keep the human-readable form in your source of truth.
• List helpers: pageSize 1–100, startCursor; responses include hasMore / nextCursor.
• Fork/adapt: reconnect your own public Notion integration as notion; keep dryRun / confirm guards; access stays whatever pages the consent screen shared.