@kody/notion

@kody/notion

Intent

Provide reusable, account-agnostic Notion helpers that let Kody search, read, and query the pages and databases shared with the connected Notion integration, and make explicitly confirmed writes, with a generic escape hatch for the rest of the Notion API.

This official OAuth package is the preferred invoke path. Setup is harder: register a Notion public connection and connect it in Kody. For a faster first win, connect Notion MCP in Get started and use @kody/notion-mcp.

What it does

• 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
• Read-only smoke test that verifies OAuth without returning workspace/user PII

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

Prerequisites / setup

This package uses a Notion public connection (OAuth). Tokens stay on the saved notion integration. Do not paste client secrets or internal-connection tokens into chat. Do not create a Notion secret at /account/secrets/new for this package.

Redirect URI: https://kody.codes/connect/oauth

1. Create a public connection at app.notion.com/developers (notion.so/profile/integrations redirects there).
2. On Configuration, set the redirect URI exactly to https://kody.codes/connect/oauth and copy the client ID and client secret.
3. Open this prefilled connect URL while signed in to Kody. Paste the client ID and client secret only on that form:

https://kody.codes/connect/oauth?provider=notion&authorizeUrl=https%3A%2F%2Fapi.notion.com%2Fv1%2Foauth%2Fauthorize&tokenUrl=https%3A%2F%2Fapi.notion.com%2Fv1%2Foauth%2Ftoken&flow=confidential&extraAuthorizeParams=%7B%22owner%22%3A%22user%22%7D

Decoded: authorize https://api.notion.com/v1/oauth/authorize, token https://api.notion.com/v1/oauth/token, flow=confidential, extra authorize params {"owner":"user"} (the page adds response_type=code). Kody defaults api.notion.com token exchange to HTTP Basic with a JSON body. Notion has no OAuth scopes — pick pages on the consent screen.

Reconnect later at https://kody.codes/connect/oauth?provider=notion. Helpers can only see pages and databases the authorizing user shared.

Agents: see AGENTS.md for import paths, smoke, and dryRun.

Done when

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

Branding

The package logo is Notion’s official mark. Notion is a trademark of Notion Labs, Inc. This package is not affiliated with or endorsed by Notion.