@kentcdodds/notion

@kentcdodds/notion

Intent

Reusable, account-agnostic Notion helpers so Kody can search, read, and query pages and databases shared with a connected Notion integration, and make explicitly confirmed writes, with a generic escape hatch for the rest of the Notion API. Multiple workspaces use Kody’s <provider>-<purpose> integration naming (notion, notion-work, …).

What it does

• List connected notion / notion-* OAuth integrations
• Search shared pages and data sources
• Read pages, block children, database containers, and data-source schemas
• Query database rows (by dataSourceId or single-source databaseId)
• Preview or create pages; preview or append blocks (dryRun / confirm)
• Generic authenticated request for any other Notion path

Pinned Notion-Version: 2026-03-11 (databases are containers; data sources hold schema and rows).

Prerequisites / setup

Create a Notion public integration and save a Kody OAuth integration named notion (plus optional notion-<purpose> per extra workspace).

1. Create an integration at https://www.notion.so/profile/integrations → type Public.
2. Redirect URI: https://kody.codes/connect/oauth.
3. Save in Kody with:
   • Authorize URL: https://api.notion.com/v1/oauth/authorize
   • Token URL: https://api.notion.com/v1/oauth/token
   • API base: https://api.notion.com/v1
   • API host: api.notion.com
   • Flow: confidential (Basic auth + JSON body on token exchange)
   • Extra authorize params: owner=user, response_type=code
   • Scopes: none (access is chosen on Notion’s consent screen)
4. Connect: https://kody.codes/connect/oauth?provider=notion (or ...?provider=notion-<purpose>).
5. Agents: see AGENTS.md for import paths, smoke, and dryRun.

Multi-workspace

Helpers accept optional account / integration (account: 'work' → notion-work). Access is whatever pages/teamspaces the user shared on Notion’s consent screen — reconnect to widen.

Done when

• At least one notion / notion-* OAuth connection works
• Smoke test returns { ok: true } without workspace/user PII
• Mutations refuse without confirm: true; dryRun: true never calls Notion