API

This repo is a CLI + module library rather than a hosted API. The "API surface" is the set of Python modules and CLI contracts used by automation.

CLI entrypoints

Sync GitHub -> Notion

• python scripts/sync.py
• Flags: --repos-file, --repo, --projects-only, --window-days, --cap-issues, --cap-prs, --cap-commits, --cap-releases, --cap-workflow-runs

Log conversation + tasks

• python scripts/log_convo.py --provider ChatGPT|Codex|Claude --repo owner/name --title "..." --summary "..."
• Optional: --url, --tasks (semicolon-separated todo tasks), --tasks-done (semicolon-separated completed tasks), --date, --tags, --ensure-project

Batch log conversations + tasks

• python scripts/log_convos.py --input input/conversations.csv --ensure-projects
• Input supports .csv, .tsv, or .jsonl with fields: provider, repo, title, summary, url, date, tags, tasks_todo, tasks_done

Export snapshot

• python scripts/export_snapshot.py

Core modules

NotionClient (src/dashboard/notion_client.py)

• Low-level Notion REST client used by sync/export/logging.
• Helpers for common property types: properties_title, properties_rich_text, properties_select, etc.

GitHubClient (src/dashboard/github_client.py)

• Pulls repo metadata and activity (issues, PRs, commits, releases, workflow runs).
• Accepts since_days + cap for bounded queries.

HttpClient (src/dashboard/http.py)

• Thin wrapper around urllib with retry/backoff on transient failures.
• Raises HttpError(status_code, message, details) on errors.

ensure_notion_schema (src/dashboard/bootstrap_notion.py)

• Idempotently creates the "Project Dashboard" page and its databases.
• Returns NotionIds for downstream operations.

sync_all (src/dashboard/sync_github_to_notion.py)

• Upserts Projects and GitHub Activity into Notion.
• Uses stable Key fields for idempotency.

export_snapshot (src/dashboard/export_snapshot.py)

• Produces snapshot.json and snapshot.csv under output/observable/.
• Output payload includes generated_at, window_days, and the four data arrays.
• When enabled via the CLI entrypoint, it also includes codex_wrapped usage stats/report text and writes codex_wrapped_stats.json.

log_conversation (src/dashboard/log_conversation.py)

• Creates a Conversation row and optional Tasks linked to an existing Project.