ericrisco/rsc-harness / skills/notion-connector
notion-connector
VerifiedUse when wiring server code or a cron job to Notion as an ops backend over its HTTP API: pushing or mirroring database rows, two-way sync without duplicates, page blocks, or an integration broken by the 2025-09-03 data-source split. NOT generic REST wiring (that is `api-connector-builder`), NOT inbound Notion webhook events (that is `webhooks`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.6 KB |
| evals/README.md | markdown | 1002 B |
| evals/cases.yaml | config | 4.1 KB |
| references/api-versions.md | markdown | 2.9 KB |
| references/property-shapes.md | markdown | 3.8 KB |
| references/sync-patterns.md | markdown | 3.7 KB |
| scripts/verify.shexecutable | script | 6.0 KB |
references/sync-patterns.md
View on GitHub# Sync patterns — idempotent upsert, dedupe, two-way reconcile, checkpointing
The Notion API has no native "upsert by my key" call. You build idempotency
yourself by keying every row on an **external id you control** and looking it up
before deciding create vs update.
## 1. Upsert by external key (one-way: app → Notion)
Store your external id in a dedicated `rich_text` property (e.g. `ExternalId`).
Look up by exact match, then branch.
```ts
async function upsert(dataSourceId: string, extId: string, props: object) {
const found = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: { property: "ExternalId", rich_text: { equals: extId } },
page_size: 1,
});
if (found.results.length > 0) {
await notion.pages.update({ page_id: found.results[0].id, properties: props });
return found.results[0].id;
}
const created = await notion.pages.create({
parent: { type: "data_source_id", data_source_id: dataSourceId },
properties: { ...props, ExternalId: { rich_text: [{ text: { content: extId } }] } },
});
return created.id;
}
```
Better still: persist the returned Notion `page_id` next to the external id in
your own DB. Then most syncs skip the lookup query entirely (saves you against
the 3 req/s ceiling) and only fall back to query-by-key when the mapping is
missing.
## 2. Dedupe an already-duplicated table
If a prior blind-create run left duplicates: pull every row, group by
`ExternalId`, keep the newest by `last_edited_time`, archive the rest.
```ts
const rows = await queryAll(dataSourceId); // the has_more loop from SKILL.md
const byKey = new Map<string, any[]>();
for (const r of rows) {
const k = r.properties.ExternalId?.rich_text?.[0]?.plain_text ?? "";
if (!k) continue;
(byKey.get(k) ?? byKey.set(k, []).get(k)!).push(r);
}
for (const [, group] of byKey) {
if (group.length < 2) continue;
group.sort((a, b) => b.last_edited_time.localeCompare(a.last_edited_time));
for (const dup of group.slice(1)) {
await notion.pages.update({ page_id: dup.id, archived: true }); // in_trash on 2026-03-11
}
}
```
## 3. Two-way reconcile
Keep a `last_edited_time` watermark per row on each side.
- Pull rows from Notion changed since the last watermark (filter on
`last_edited_time` `on_or_after`).
- Pull rows from your DB changed since the same checkpoint.
- For a row changed on **both** sides since the last sync → conflict. Default to
last-writer-wins by comparing timestamps; for anything money/state-critical,
do not auto-resolve — write both versions to a review queue and stop.
- Advance the watermark only after a clean pass commits.
A pure mirror (Notion → app, read-only) skips all of this: just pull and
overwrite your local copy.
## 4. Cursor checkpointing for large pulls
A pull of thousands of rows spans many cursor pages and may hit a 429 partway.
Persist the `next_cursor` after each page so a crashed job resumes instead of
restarting from row 0.
```ts
let cursor = await loadCheckpoint(); // undefined on first run
do {
const res = await withRetry(() => // withRetry from SKILL.md
notion.dataSources.query({ data_source_id: dataSourceId, start_cursor: cursor, page_size: 100 }));
await handle(res.results);
cursor = res.has_more ? res.next_cursor ?? undefined : undefined;
await saveCheckpoint(cursor); // durable between pages
} while (cursor);
```
## Rules of thumb
- One external id ⇒ exactly one Notion page. Enforce it in your own store.
- Never trust row order or array index to identify a row; key on `ExternalId`.
- Batch reads, serialize writes; respect the per-integration ~3 req/s average.
- Treat `archived`/`in_trash` as soft delete, then reconcile, before hard delete.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |