Migrate 'db' surface to the 2025-09-03 data_sources API

[4ier]

Summary

Notion's 2025-09-03 API introduced a breaking change: database endpoints like /v1/databases/:id/query are being replaced with /v1/data_sources/:id/query. A single database can now have multiple "data sources" (views or variants), and queries/templates/etc. are scoped to a data source rather than the database directly.

The CLI currently pins Notion-Version: 2022-06-28, so nothing breaks today. But the shift is ongoing and the old endpoints will eventually be deprecated. This issue tracks the migration work.

Affected CLI commands (today)

All of these use /v1/databases/:id/... and will need re-plumbing or a compat shim:

Command	Old endpoint	New endpoint (2025-09-03)
db query <id>	POST /v1/databases/:id/query	POST /v1/data_sources/:id/query
db add / add-bulk	POST /v1/pages with parent.database_id	POST /v1/pages with parent.data_source_id
db export	walks db query	follows db query change
db view	GET /v1/databases/:id	GET /v1/data_sources/:id (schema moved here)
db update	PATCH /v1/databases/:id	PATCH /v1/data_sources/:id (properties moved)
db create	POST /v1/databases	POST /v1/data_sources
db list	POST /v1/search?filter=database	unchanged (search still returns databases as a resource)

Plus the new endpoint with no current CLI coverage:

• GET /v1/data_sources/:id/templates — list page templates in a data source.

Migration plan (proposed)

Do this in stages so we don't break users who are on older Notion API versions:

Stage 1 — Introduce version awareness (non-breaking)

• Bump NotionVersion constant to "2025-09-03" in a dedicated PR.
• Add an auto-resolver: when a user passes a database_id to db query, fetch the database once, read its data_sources[0].id, cache it, and call the new endpoint. Single-data-source databases (the common case) work transparently.
• Users with multi-data-source databases gain an optional --data-source <id> flag.

Stage 2 — First-class db datasource subcommands

notion db datasource list <db-id>        # list data sources on a database
notion db datasource view <ds-id>        # schema
notion db datasource query <ds-id> ...   # query
notion db datasource templates <ds-id>   # new endpoint

Alias: notion ds ... as a short prefix if name collisions permit.

Stage 3 — Deprecation messaging

• db query <id> keeps working (via auto-resolve) but prints a one-line stderr note the first time it's used in a session: note: routing via data source <ds-id> — use 'notion db datasource query' to target directly.
• This flips to a warning, then (much later) is removed once Notion sunsets the 2022-06-28 endpoints.

Risk / test coverage

• Fixture tests for both old and new response shapes.
• Live smoke against at least two real databases: single-data-source (the common case) and multi (constructed via Notion's UI for verification).
• Careful handling of parent.database_id vs parent.data_source_id in page creation — both forms appear in the wild during the transition window.

References

• Notion API 2025-09-03 release notes: https://developers.notion.com/reference/changes-by-version
• notion-sdk-js per-module endpoints: https://github.com/makenotion/notion-sdk-js/tree/main/src/api-endpoints

Priority

Medium-term. Not urgent (2022-06-28 endpoints still work), but not something to put off indefinitely either. Reasonable target: do Stage 1 + 2 before Notion marks the old endpoints EOL (currently no concrete date published).

[4ier]

Tracked in the post-v0.6.0 roadmap: #41