Files

Andrew Yim 144a17c88d feat(notion): migrate 31+32 to API 2025-09-03 + add property writes, upsert, anchor-link fix

Phase 1 — docs alignment:
- Fix path drift in 32 CLAUDE.md (02-notion-writer → 32-notion-writer)
- Align env var to NOTION_API_KEY in 31 docs (NOTION_TOKEN still accepted)
- Document Phase 3 roadmap in 31 (metadata-aware migration, Notion-as-RAG)

Phase 2 — multi-source database support:
- New 32/scripts/_notion_compat.py: client factory, data_source resolution
  with cache, property coercion, find_existing_page (for upsert),
  explain_api_error for friendlier failure messages
- 32 notion_writer.py: drop the 2022-06-28 pin, route schema introspection
  through data_sources.retrieve, build data_source_id parent shape, accept
  arbitrary properties via --properties JSON-or-file flag, add --upsert-by
  for idempotent re-runs
- 32 markdown parser: anchor-link fix — Notion's URL validator rejects
  fragment URLs and relative paths; fragments now render as bold to preserve
  TOC nav intent, relatives drop the link, absolute URLs preserved
- 31 async_organizer.py + schema_migrator.py: same data_sources migration
  with cached resolution; pages.create now uses data_source_id parent
- 16/16 parser tests pass (was 13; +3 link-handling regression guards)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-27 09:57:20 +09:00

3.1 KiB

Raw Blame History

CLAUDE.md

Overview

Notion workspace management toolkit for database organization, schema migration, and bulk operations.

Quick Start

pip install -r scripts/requirements.txt

# Schema migration
python scripts/schema_migrator.py --source [DB_ID] --target [DB_ID] --dry-run

# Async bulk operations
python scripts/async_organizer.py --database [DB_ID] --action cleanup

Scripts

Script	Purpose
`schema_migrator.py`	Migrate data between databases with property mapping
`async_organizer.py`	Async bulk operations (cleanup, restructure, archive)

Schema Migrator

# Dry run (preview changes)
python scripts/schema_migrator.py \
  --source abc123 \
  --target def456 \
  --mapping mapping.json \
  --dry-run

# Execute migration
python scripts/schema_migrator.py \
  --source abc123 \
  --target def456 \
  --mapping mapping.json

Mapping File Format

{
  "properties": {
    "OldName": "NewName",
    "Status": "Status"
  },
  "transforms": {
    "Date": "date_to_iso"
  }
}

Async Organizer

# Cleanup empty/stale pages
python scripts/async_organizer.py --database [ID] --action cleanup

# Archive old pages
python scripts/async_organizer.py --database [ID] --action archive --days 90

# Restructure hierarchy
python scripts/async_organizer.py --database [ID] --action restructure

Rate Limits

Limit	Value
Requests/second	3 max
Items per request	100 max
Retry on 429	Exponential backoff

Configuration

Environment variables:

# Preferred (matches 32-notion-writer)
NOTION_API_KEY=secret_xxx

# Legacy fallback also accepted
# NOTION_TOKEN=secret_xxx

The scripts read NOTION_TOKEN first, then fall back to NOTION_API_KEY. Use NOTION_API_KEY for new setups so the same .env works across all Notion skills.

Notes

Always use --dry-run first for destructive operations
Large operations (1000+ pages) use async with progress reporting
Scripts implement automatic rate limiting

Roadmap (Phase 3)

The current scripts cover schema migration and async bulk ops. Two larger goals are parked for a future iteration:

Goal 1 — Metadata-aware page move/integration

Search source pages, compare their property metadata against a target database schema, and move/migrate while transforming property values to fit. Beyond the existing schema_migrator.py (which expects a hand-written mapping file), this would:

Auto-suggest property mappings using name + type similarity
Surface unmappable properties before the move (no silent data loss)
Support cross-database moves (not just same-schema migrations)

Goal 2 — Notion as personal RAG source

Treat Notion as a small, personal knowledge base for AI agents:

Search pages by query across databases, filter by property
Merge results into a single context (with source citations back to page URLs)
Summarize / distill via LLM into agent-ready snippets
Export as JSONL or markdown for fine-tuning or RAG indexing

This dovetails with 90-reference-curator (which does the same for web sources) — Phase 3 would make Notion a first-class source type for that pipeline.

3.1 KiB Raw Blame History