# @kentcdodds/notion

![Notion logo](./assets/notion-logo.png)

## 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`](./AGENTS.md) for import paths, smoke, and dryRun.

### Multi-workspace

| Integration | Typical use |
| --- | --- |
| `notion` | Default workspace |
| `notion-personal` | Personal |
| `notion-work` | Work |

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