database-notion

Database adapter — Notion

This is the Notion adapter. It owns every Notion-specific mechanic in one place, so the pipeline skills can speak in backend-neutral operations and a future backend can be added as a sibling adapter without touching them.

When to load (mandatory, conditional): any time a pipeline skill needs to read from or write to the database and database_backend resolves to notion (the default; from ${CAREER_DATA}/references/pipeline-preferences.json). The caller names the generic operation and the parameters (target status, properties to read, fields to write); this skill provides the how. If database_backend is ever something else, the caller loads that backend's adapter instead — never this one.

Database ID: $NOTION_DATABASE_ID, resolved from config (database_id, legacy notion_database_id) by the calling skill. Any {{NOTION_DATABASE_ID}} token in plugin text is a literal placeholder, not a value. $NOTION_DATABASE_ID/$NOTION_NEEDS_EDITING_VIEW_URL are this adapter's internal variable names.

Generic operation → Notion mechanic:

Generic operation (what callers say)	Notion mechanic (below)
Read the schema reference	§1 Schema read
Query the queue for Status = <target>	§2 Read ladder (A1 → A2 → B)
Resolve a view by name	§3 View discovery
Fetch a record's full properties	§1/§2 per-page notion-fetch
Write a field / write-if-empty	§4 Writeback
Write the page body	§4 Page-body write

---

§1 — Schema read (always first)

⛔ STOP — check this before running the fetch below. §1's fetch below is needed once per run for the property/select-option schema reference — that use is never skipped. But if the caller's need right now is only view discovery (resolving a view URL for §2 Path B or §3), and the caller already has a non-empty, non-stale fast-path view URL from config (database_edit_view_url, database_interested_view_url, database_hold_view_url, database_researched_view_url, database_cv_ready_view_url, database_new_view_url), skip straight to §2 Path B step 2 (notion-query-database-view with that URL) — do not run the full schema fetch just to discover a view you already have the URL for. Two independent live runs ran this ~60-65KB fetch anyway despite already holding a populated fast-path URL in context, and both hit context exhaustion shortly after. Only run the fetch below when you actually need the schema reference (property names / select options for a write) or when no fast-path URL is available for the view you need.