rsc-universal 0.1.1

package/skills/nodejs/references/graceful-shutdown.md

@@ -0,0 +1,73 @@
+# Graceful shutdown — complete server.ts
+
+Copy-pasteable. Threads an `AbortController` so in-flight long ops are cancelled, gates readiness so the load balancer stops routing before drain, and keeps a force-exit backstop so a stuck connection can't hang the deploy. Sources: AbortController guides (AppSignal 2025-02-12, BetterStack), Node SIGTERM semantics (accessed 2026-06-02).
+
+## Why a readiness gate, not just `server.close()`
+
+`server.close()` stops accepting *new* connections but in-flight requests keep going. If the load balancer is still routing new traffic at you while you close, those new connections are refused. So you flip `/readyz` to 503 *first*, give the LB a moment to deregister, then close. `/healthz` stays 200 the whole time — the process is alive, just draining.
+
+```ts
+// server.ts
+import { buildApp } from "./app.ts";
+import { config } from "./config/env.ts";
+import { logger } from "./logger.ts";
+import { closePool } from "./repositories/pool.ts";
+
+let ready = true;
+const controller = new AbortController(); // pass controller.signal into fetch/DB/long ops
+
+const app = buildApp();
+app.get("/healthz", (_req, res) => res.json({ status: "up" }));        // liveness
+app.get("/readyz", (_req, res) =>                                       // readiness
+  ready ? res.json({ status: "ready" }) : res.status(503).json({ status: "draining" }),
+);
+
+const server = app.listen(config.PORT, () =>
+  logger.info({ port: config.PORT }, "listening"),
+);
+
+let shuttingDown = false;
+async function shutdown(signal: string) {
+  if (shuttingDown) return;            // ignore a second signal
+  shuttingDown = true;
+  logger.info({ signal }, "shutting down");
+
+  ready = false;                       // 1. /readyz → 503, LB deregisters
+
+  const backstop = setTimeout(() => {  // 5. backstop: never hang the deploy
+    logger.error("drain timed out, forcing exit");
+    process.exit(1);
+  }, 10_000);
+  backstop.unref();
+
+  server.close(async () => {           // 2. stop accepting; wait for in-flight
+    controller.abort();                // 3. cancel long-running ops
+    await closePool();                 // 4. release DB/other resources
+    clearTimeout(backstop);
+    logger.info("clean exit");
+    process.exit(0);
+  });
+}
+
+process.on("SIGTERM", () => void shutdown("SIGTERM"));
+process.on("SIGINT", () => void shutdown("SIGINT"));
+
+// last-resort: log and exit, never keep running on a detached failure
+process.on("unhandledRejection", (reason) => {
+  logger.error({ reason }, "unhandled rejection");
+  void shutdown("unhandledRejection");
+});
+```
+
+## Threading the signal into work
+
+The `AbortController` only helps if operations actually receive `controller.signal`:
+
+```ts
+// in a repository / service
+const res = await fetch(url, { signal: controller.signal });
+// or compose a per-request deadline with a shutdown abort:
+const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(5_000)]);
+```
+
+`AbortSignal.timeout(ms)` returns an auto-aborting signal; `AbortSignal.any([...])` aborts when any input aborts — so the op dies on either the 5s deadline or process shutdown.

package/skills/nodejs/scripts/verify.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# verify.sh — static lint for a plain Node.js / Express service scaffold.
+# Read-only. No install or run required. Heuristic and advisory.
+#
+# HARD-FAILS (exit 1) only on:
+#   - app.ts calls .listen( (app construction not split from server)
+#   - no 4-arg (err,req,res,next) error middleware found anywhere
+# Everything else is a WARNING. Exits 0 on a clean/empty target (no false failure).
+#
+# Usage: scripts/verify.sh [dir]   (defaults to current directory)
+set -euo pipefail
+
+DIR="${1:-.}"
+HARD_FAIL=0
+WARN=0
+
+if [ ! -d "$DIR" ]; then
+  echo "verify.sh: '$DIR' is not a directory" >&2
+  exit 2
+fi
+
+warn() { echo "WARN: $*"; WARN=$((WARN + 1)); }
+fail() { echo "FAIL: $*"; HARD_FAIL=$((HARD_FAIL + 1)); }
+
+# Collect JS/TS source files, skipping deps, build output and test files.
+# bash 3.2 (macOS) friendly: newline-delimited, no mapfile.
+SRC_FILES="$(
+  find "$DIR" -type f \( -name '*.ts' -o -name '*.js' -o -name '*.mjs' \) \
+    -not -path '*/node_modules/*' \
+    -not -path '*/dist/*' \
+    -not -path '*/build/*' \
+    -not -path '*/.git/*' \
+    2>/dev/null
+)"
+
+if [ -z "$SRC_FILES" ]; then
+  echo "verify.sh: no JS/TS source files under '$DIR' — nothing to check."
+  exit 0
+fi
+
+is_test_file() {
+  case "$1" in
+    *.spec.*|*.test.*|*/test/*|*/tests/*|*/__tests__/*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+ERROR_HANDLER_FOUND=0
+ERROR_HANDLER_LAST=1   # assume ok until a route appears after it in any app file
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  is_test_file "$f" && continue
+
+  base="$(basename "$f")"
+
+  # 1. HARD: app.ts (or app.js/mjs) must not call .listen(
+  case "$base" in
+    app.ts|app.js|app.mjs)
+      if grep -Eq '\.listen\(' "$f"; then
+        fail "$f calls .listen() — split app construction from server.ts (server should listen, not app)."
+      fi
+      ;;
+  esac
+
+  # 2. Detect a 4-arg error middleware: (err, req, res, next) used with app.use.
+  if grep -Eq '\(\s*err\s*,\s*[A-Za-z_]+\s*,\s*[A-Za-z_]+\s*,\s*[A-Za-z_]+\s*\)' "$f"; then
+    ERROR_HANDLER_FOUND=1
+    # Heuristic: warn if a 4-arg error handler line precedes a route registration
+    # in the same file (app.get/post/.../use("/...")) — handler should be LAST.
+    err_line="$(grep -nE 'use\(\s*\(\s*err\s*,' "$f" | head -1 | cut -d: -f1 || true)"
+    if [ -n "${err_line:-}" ]; then
+      route_after="$(grep -nE 'app\.(get|post|put|patch|delete|use\("/)' "$f" \
+        | awk -F: -v e="$err_line" '$1 > e {print; exit}' || true)"
+      if [ -n "${route_after:-}" ]; then
+        warn "$f registers a route AFTER the 4-arg error handler — the error handler must be LAST."
+      fi
+    fi
+  fi
+
+  # 3. WARN: global unhandledRejection that does not exit/shutdown (used as control flow).
+  if grep -Eq "on\(\s*['\"]unhandledRejection['\"]" "$f"; then
+    if ! grep -Eq "(process\.exit|shutdown)" "$f"; then
+      warn "$f handles 'unhandledRejection' but never exits/shuts down — do not use it as control flow."
+    fi
+  fi
+
+  # 4. WARN: floating-promise heuristic in controllers/routes/services — a statement-position
+  # call to an async-looking name with no await/return/.then/.catch on the line.
+  case "$f" in
+    */controllers/*|*/routes/*|*/services/*)
+      if grep -nE '^[[:space:]]*[A-Za-z_][A-Za-z0-9_.]*\(' "$f" \
+        | grep -vE '(await|return|=>|\.then|\.catch|=|const|let|var|if|for|while|res\.|console\.|logger\.|app\.|router\.)' \
+        | grep -qE '(save|fetch|find|create|update|delete|send|publish|notify|query)[A-Za-z]*\('; then
+        warn "$f has a statement-position call to an async-looking function with no await/return — possible floating promise."
+      fi
+      ;;
+  esac
+done <<EOF
+$SRC_FILES
+EOF
+
+if [ "$ERROR_HANDLER_FOUND" -eq 0 ]; then
+  fail "no 4-arg (err,req,res,next) error middleware found — register exactly one, LAST."
+fi
+
+# 5. WARN: engines.node should pin a supported LTS (>=22).
+PKG="$(find "$DIR" -maxdepth 2 -name package.json -not -path '*/node_modules/*' 2>/dev/null | head -1 || true)"
+if [ -n "${PKG:-}" ]; then
+  if grep -Eq '"engines"' "$PKG"; then
+    if ! grep -Eq '"node"\s*:\s*"[^"]*(2[2-9]|[3-9][0-9])' "$PKG"; then
+      warn "$PKG engines.node does not clearly pin a supported LTS (>=22; prefer 24)."
+    fi
+  else
+    warn "$PKG has no engines.node — pin a supported Node LTS (>=24)."
+  fi
+fi
+
+echo
+echo "verify.sh: $HARD_FAIL hard failure(s), $WARN warning(s)."
+[ "$HARD_FAIL" -gt 0 ] && exit 1
+exit 0

package/skills/notion-connector/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: notion-connector
+description: "Use when wiring an app, cron job, or service to Notion as an ops backend over the official HTTP API — pushing rows into a Notion database, mirroring a database into your app, syncing both ways without duplicates, building or reading page block content, or fixing an integration that broke after the 2025-09-03 data-source split. Triggers: 'store our tasks in a Notion database from code', 'use Notion as a CRM/content calendar', 'sync our CRM into Notion nightly without duplicates', 'why does POST /v1/databases/:id/query return 404 now', 'integration broke after a teammate added a second data source', 'guardar registros en una base de datos de Notion desde código', 'desar files a una base de dades de Notion'. NOT a generic call-any-REST-API integration (that is api-connector-builder), NOT receiving/verifying inbound Notion webhook events (that is webhooks)."
+tags: [notion, ops-backend, api-integration, databases, sync]
+recommends: [api-connector-builder, webhooks, automation-flows, spreadsheet-ops, secure-coding]
+origin: risco
+---
+
+# Notion connector — Notion as a code-backed ops store
+
+Wire server code to the Notion HTTP API so a database behaves like a small
+operational store: push rows, pull rows, sync both ways idempotently, read and
+write page blocks. This skill owns the **outbound** Notion API surface only —
+the database/data-source data model, property-type write shapes, and the
+rate-limit/pagination discipline that the API forces on you.
+
+## The one rule
+
+**Pin the `Notion-Version` per request, and resolve the data source before you
+query.** Post `2025-09-03` a database is a *container* of one or more data
+sources — not a queryable table. Skip either half and you get silent 404s on
+code that worked last year.
+
+- Current major version: **`2025-09-03`** (the SDK default). Latest: **`2026-03-11`**.
+- Behavior differs across versions; an unpinned client drifts when the default moves.
+
+## When to use / when NOT to use
+
+**Use when:** treating a Notion database as a CRM / task tracker / content
+calendar from code; pushing or pulling rows on a schedule; two-way sync that
+must not duplicate on re-run; building or reading page block content; migrating
+a `2022-06-28` integration that broke when someone added a second data source.
+
+**Route elsewhere:**
+
+| Situation | Route to |
+|---|---|
+| Generic "call any REST API", nothing Notion-specific | `../api-connector-builder/SKILL.md` |
+| Receiving + verifying *inbound* Notion webhook events | `../webhooks/SKILL.md` |
+| Notion is one node in a multi-tool sequence | `../automation-flows/SKILL.md` |
+| CSV/tabular bulk transforms, column mechanics | `../spreadsheet-ops/SKILL.md` |
+| Token handling, secret rotation, never-client-side rules | `../secure-coding/SKILL.md` |
+
+## Setup (4 steps)
+
+1. **Create an internal integration** in Notion → Settings → Integrations. Copy
+   the secret — it looks like `ntn_...` (older ones `secret_...`).
+2. **Put the token in an env var**, never in client-side JS, never committed. It
+   is a bearer secret; treat it like a password. See `../secure-coding/SKILL.md`.
+3. **Share the target database/page with the integration** in the Notion UI
+   (the page `•••` menu → Connections). *Skip this and every call 404s or
+   returns empty* — the integration sees nothing it was not explicitly granted.
+4. **Construct the SDK client with a pinned version.** Official JS SDK is
+   `@notionhq/client` v5.12.0+ (latest 5.22.0, 2026-05-19); its default
+   `notionVersion` is `2025-09-03`, and it supports `2026-03-11` if you opt in.
+   The default and method names below are stable across the whole 5.x line.
+
+```ts
+import { Client } from "@notionhq/client"; // v5.12.0+ (latest 5.22.0)
+
+const notion = new Client({
+  auth: process.env.NOTION_TOKEN,          // ntn_... — env only, never inlined
+  notionVersion: "2025-09-03",             // pin it; do not ride the default
+});
+```
+
+## The database → data source model (biggest gotcha)
+
+A database now holds a `data_sources` array; each data source has its **own
+schema**. One database can have several. You query and read schema against the
+*data source*, not the database.
+
+| You have… | Do this |
+|---|---|
+| A `database_id` | `GET /v1/databases/:id` → read `data_sources[]` ({id,name}) → use that `id` |
+| Already a `data_source_id` | Use it directly for query/schema/pages |
+| A DB with >1 data source | Pick the right one by `name`; never assume index 0 |
+
+Endpoints moved to `/v1/data_sources`:
+
+```diff
+- POST /v1/databases/:database_id/query        # 2022-06-28 — 404s on 2025-09-03+
++ POST /v1/data_sources/:data_source_id/query  # query rows
++ GET  /v1/data_sources/:data_source_id         # schema (properties)
++ PATCH /v1/data_sources/:data_source_id        # update schema / title
+```
+
+```ts
+// Resolve once, then reuse the data_source_id everywhere downstream.
+const db = await notion.databases.retrieve({ database_id: DATABASE_ID });
+const dataSourceId = db.data_sources[0].id; // verify by name if >1 exists
+```
+
+## Query a data source
+
+Send `filter` + `sorts` in the body. Page size maxes at **100**; results are
+cursor-based. **Always loop** on `has_more` + `next_cursor` or you silently drop
+every row past the first 100. Filter operand shapes per property type live in
+`references/property-shapes.md`.
+
+```ts
+async function queryAll(dataSourceId: string, filter?: object) {
+  const rows: any[] = [];
+  let cursor: string | undefined = undefined;
+  do {
+    const res = await notion.dataSources.query({
+      data_source_id: dataSourceId,
+      filter,
+      page_size: 100,                 // hard max
+      start_cursor: cursor,
+    });
+    rows.push(...res.results);
+    cursor = res.has_more ? res.next_cursor ?? undefined : undefined;
+  } while (cursor);
+  return rows;
+}
+```
+
+## Property write shapes
+
+Most write failures (HTTP 400) are a wrong property envelope. Each type has its
+own JSON shape. The high-frequency ones:
+
+| Type | Write shape (abridged) |
+|---|---|
+| `title` | `{ title: [{ text: { content } }] }` |
+| `rich_text` | `{ rich_text: [{ text: { content } }] }` |
+| `number` | `{ number: 42 }` |
+| `select` | `{ select: { name } }` |
+| `multi_select` | `{ multi_select: [{ name }] }` |
+| `status` | `{ status: { name } }` |
+| `date` | `{ date: { start, end? } }` (ISO 8601) |
+| `checkbox` | `{ checkbox: true }` |
+| `relation` | `{ relation: [{ id }] }` |
+| `people` | `{ people: [{ id }] }` |
+| `url` | `{ url: "https://…" }` |
+
+Full write + read-parse JSON for every type → `references/property-shapes.md`.
+
+## Create / update pages (rows)
+
+A page's parent is the **data source**, not the database:
+
+```ts
+// CREATE a row
+await notion.pages.create({
+  parent: { type: "data_source_id", data_source_id: dataSourceId },
+  properties: {
+    Name: { title: [{ text: { content: "Ship invoice export" } }] },
+    Status: { status: { name: "In progress" } },
+    ExternalId: { rich_text: [{ text: { content: extId } }] },
+  },
+});
+
+// UPDATE a row: PATCH the page by id; send only changed properties
+await notion.pages.update({
+  page_id,
+  properties: { Status: { status: { name: "Done" } } },
+});
+```
+
+To soft-delete: on `2025-09-03` set `{ archived: true }`; on `2026-03-11` that
+field is renamed `{ in_trash: true }`. Match the field to the version you pinned
+(see `references/api-versions.md`).
+
+## Sync patterns
+
+Idempotency is the whole game. **Store the Notion `page_id` keyed by your
+external id** (a column in your DB, or a `rich_text` "ExternalId" property in
+Notion). An upsert is: query-by-external-key → if a row exists, `pages.update`;
+else `pages.create`. Never blind-create on a re-run — that is how you get
+duplicate rows.
+
+- **One-way (app → Notion):** upsert on every sync; the app is source of truth.
+- **Two-way:** track a `last_edited_time` watermark on each side; last-writer
+  wins, or flag conflicts for review. Cursor-checkpoint large pulls.
+
+Dedupe, two-way reconcile, and checkpointing → `references/sync-patterns.md`.
+
+## Rate limits & resilience
+
+The integration is capped at **~3 requests/second average**. Over-limit calls
+return **HTTP 429 with a `Retry-After` header (seconds)** — honor it, do not
+guess a fixed sleep. Cap concurrency, batch reads, back off on 429.
+
+```ts
+async function withRetry<T>(fn: () => Promise<T>, tries = 5): Promise<T> {
+  for (let i = 0; ; i++) {
+    try {
+      return await fn();
+    } catch (e: any) {
+      const after = Number(e?.headers?.["retry-after"]);
+      if (e?.status === 429 && i < tries) {
+        const wait = Number.isFinite(after) ? after * 1000 : 2 ** i * 500;
+        await new Promise((r) => setTimeout(r, wait));
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+```
+
+## Version migration
+
+| From → To | What changed |
+|---|---|
+| `2022-06-28` → `2025-09-03` | DB is a container; query/schema move to `/v1/data_sources`; page parent is `data_source_id`; search filter value `"database"` → `"data_source"` |
+| `2025-09-03` → `2026-03-11` | block `after` param → `position` object (`after_block`/`start`/`end`); `archived` → `in_trash` (pages/dbs/blocks/data sources); block type `transcription` → `meeting_notes` |
+
+Exact field/endpoint diffs → `references/api-versions.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Unpinned `Notion-Version` | Behavior shifts when the default moves | Pin per request/client |
+| `POST /v1/databases/:id/query` on 2025-09-03+ | 404 — that path is gone | Resolve data source → `/v1/data_sources/:id/query` |
+| Forgetting to share the DB with the integration | 404 / empty results, looks like an auth bug | Share in the UI (step 3) |
+| No pagination loop | Silently drops every row past 100 | Loop on `has_more` + `next_cursor` |
+| Ignoring 429 / fixed sleep | Hammers the 3 req/s ceiling, gets banned | Honor `Retry-After`, exponential backoff |
+| Blind `pages.create` on every sync | Duplicate rows on re-run | Upsert: query-by-external-key first |
+| Token in client-side JS or committed | Leaked bearer secret = full workspace access | Env var + secret manager |
+| Assuming one DB = one schema | Breaks on multi-data-source DBs | Resolve and select by data-source name |
+| Using `database_id` as a page parent | Rejected on 2025-09-03+ | `{ type: "data_source_id", data_source_id }` |
+| `archived` on 2026-03-11 | Field renamed | Use `in_trash` for that version |
+
+## verify.sh
+
+`scripts/verify.sh <file-or-dir>` statically lints a connector you (or the agent)
+wrote: it flags a missing pinned `Notion-Version`/`notionVersion`, a deprecated
+`databases/:id/query` query path, a query without a `has_more`/`next_cursor`
+loop, and missing 429/`Retry-After` handling. Read-only; exits 0 on a clean or
+empty target. It does not call Notion.

package/skills/notion-connector/evals/README.md

@@ -0,0 +1,15 @@
+# Evals — notion-connector
+
+`cases.yaml` holds three things: `should_trigger` (prompts that must route into
+this skill — including the non-obvious "`POST /v1/databases/:id/query` returns
+404" post-2025-09-03 symptom and a Spanish phrasing), `should_not_trigger`
+(prompts that belong to a named sibling — `api-connector-builder`, `webhooks`,
+`automation-flows`, `spreadsheet-ops`, `secure-coding` — marking the generic-REST,
+inbound-event, orchestration, bulk-CSV, and secret-handling boundaries), and one
+`capability` scenario with a `must_include` rubric. There is no live runner and
+no Notion calls: route each trigger prompt through your skill-selection harness
+and confirm it lands (or doesn't) as labelled, then have an agent produce code
+for the capability scenario and hand-score it — every `must_include` line should
+be present. To structurally check any connector the skill produces, run
+`../scripts/verify.sh <file-or-dir>`; a clean rubric pass plus a clean verify run
+is the bar.

package/skills/notion-connector/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: notion-connector
+
+should_trigger:
+  - prompt: "We want our internal task tool to push its tasks into a Notion database from a nightly cron job. How do I write to Notion from code?"
+    why: "Core push use case — app/cron writing rows into a Notion database over the API. Exactly the outbound connector this skill owns."
+  - prompt: "Our Notion integration broke after a teammate added a second data source to the database. Reads return nothing now."
+    why: "The flagship 2025-09-03 breakage symptom: a database became a multi-data-source container, so an old integration sees nothing. The skill's database→data-source resolution is the fix."
+  - prompt: "I need to sync our CRM rows into Notion every night and it keeps creating duplicate cards each run. How do I make it idempotent?"
+    why: "Upsert/idempotency — store page_id keyed by external id, query-by-key before create. Squarely the sync-patterns section, non-obvious that the fix is an external-key upsert."
+  - prompt: "guardar registros en una base de datos de Notion desde código sin duplicar filas"
+    why: "Spanish phrasing of the idempotent write-to-Notion-database use case. Must still route here."
+  - prompt: "Why does POST /v1/databases/:id/query suddenly return 404? It worked a few months ago."
+    why: "Non-obvious post-2025-09-03 symptom: the query endpoint moved to /v1/data_sources. An agent must recognize this as a Notion API-version migration, not a generic 404."
+  - prompt: "Build a read-only dashboard feed that mirrors a Notion database into our app, paginating through all rows."
+    why: "Pull/mirror use case requiring the cursor pagination loop (has_more/next_cursor, page_size<=100). Owned by this skill's query section."
+  - prompt: "We need to programmatically write meeting-note pages with headings and bullet blocks into Notion."
+    why: "Reading/writing page block content via the Notion API is in scope ('build/read page content programmatically')."
+
+should_not_trigger:
+  - prompt: "I need to wire up calls to some random third-party REST API that has nothing to do with Notion. Where do I start?"
+    route_to: api-connector-builder
+    why: "Generic call-any-REST-API task with no Notion-specific data model — the generic connector skill, not this one."
+  - prompt: "Notion can send me integration webhook events. How do I receive them and verify the signature in my handler?"
+    route_to: webhooks
+    why: "Inbound event receipt + signature verification is the webhooks skill's domain. This skill is outbound-only."
+  - prompt: "Chain Notion, Slack, and an email send into one automation that fires when a deal closes."
+    route_to: automation-flows
+    why: "Multi-tool orchestration where Notion is one node — that's the automation-flows sequence skill."
+  - prompt: "Bulk-import a CSV, dedupe and transform its columns, then output a clean sheet."
+    route_to: spreadsheet-ops
+    why: "Spreadsheet-shaped bulk transform mechanics with no Notion API involved — spreadsheet-ops owns this."
+  - prompt: "Where should I store the Notion integration token and how do I rotate it safely?"
+    route_to: secure-coding
+    why: "Secret storage/rotation policy is the secure-coding skill; this skill only says 'env var, never client-side' and defers the how."
+
+capability:
+  - scenario: "Build a nightly job that upserts records from our app DB into a Notion database keyed by an external id, paginating safely and never duplicating rows. We only have the database_id."
+    must_include:
+      - "Resolve the data_source_id from the database_id via GET /v1/databases/:id and read data_sources[]"
+      - "Pin a Notion-Version (e.g. 2025-09-03) / pass notionVersion to the client"
+      - "Query-by-external-key (rich_text equals on an ExternalId property) before deciding create vs update"
+      - "Create/update pages with a { type: 'data_source_id', data_source_id } parent, not database_id"
+      - "Cursor pagination loop using has_more + next_cursor with page_size <= 100"
+      - "Honor HTTP 429 Retry-After with backoff and cap concurrency under ~3 req/s"
+      - "Persist the Notion page_id keyed by external id so re-runs stay idempotent"

package/skills/notion-connector/references/api-versions.md

@@ -0,0 +1,63 @@
+# API versions — 2022-06-28 → 2025-09-03 → 2026-03-11 migration map
+
+Pin `Notion-Version` per request. The SDK `@notionhq/client` v5.12.0+ (latest
+5.22.0 as of 2026-05-19) defaults to `2025-09-03` and supports `2026-03-11` when
+you pass `notionVersion`. Behavior is version-gated server-side: the *header you
+send* decides the shapes, not the SDK version alone.
+
+## 2022-06-28 → 2025-09-03 (breaking)
+
+The big one. Databases became **containers of data sources**. A `2022-06-28`
+integration cannot see or query a database once it has more than one data
+source — this is the classic "it worked yesterday, now 404" report.
+
+| Concern | 2022-06-28 | 2025-09-03 |
+|---|---|---|
+| Query rows | `POST /v1/databases/:id/query` | `POST /v1/data_sources/:data_source_id/query` |
+| Read schema | `GET /v1/databases/:id` (props inline) | `GET /v1/data_sources/:data_source_id` |
+| Update schema/title | `PATCH /v1/databases/:id` | `PATCH /v1/data_sources/:data_source_id` |
+| Resolve container | n/a | `GET /v1/databases/:id` → `data_sources[]` ({id,name}) |
+| Page parent | `{ "type": "database_id", "database_id": "…" }` | `{ "type": "data_source_id", "data_source_id": "…" }` |
+| Search object filter | `filter.value = "database"` | `filter.value = "data_source"` (also `"page"`) |
+
+Migration steps:
+
+1. Bump the pinned version to `2025-09-03`.
+2. For every `database_id` you query, first `GET /v1/databases/:id`, read
+   `data_sources[]`, and select the right `id` (by `name` if more than one).
+3. Replace `databases/:id/query` calls with `data_sources/:id/query`.
+4. Change every page-create parent to `data_source_id`.
+5. Update any `POST /v1/search` object filter value to `"data_source"`.
+
+```diff
+- POST /v1/databases/abc123/query
++ GET  /v1/databases/abc123            → data_sources:[{ id:"ds_…", name:"Tasks" }]
++ POST /v1/data_sources/ds_…/query
+```
+
+## 2025-09-03 → 2026-03-11 (breaking)
+
+Smaller, but it changes field names you write.
+
+| Concern | 2025-09-03 | 2026-03-11 |
+|---|---|---|
+| Insert block at position | `after` block param | `position` object: `{ after_block }` / `{ start }` / `{ end }` |
+| Soft delete flag | `archived` (pages/dbs/blocks/data sources) | `in_trash` (same surfaces) |
+| Audio-transcription block | block type `transcription` | block type `meeting_notes` |
+
+```diff
+- { "archived": true }
++ { "in_trash": true }
+
+- await notion.blocks.children.append({ block_id, after, children })
++ await notion.blocks.children.append({ block_id, position: { after_block }, children })
+```
+
+## Picking a version
+
+- Default to **`2025-09-03`** — it is the SDK default and the current major.
+- Opt into **`2026-03-11`** only if you need `meeting_notes` blocks or the new
+  block-`position` insertion semantics, and then use `in_trash` consistently.
+- Whatever you choose, send it as an explicit header on every request and write
+  code against *that* version's field names — never mix `archived` and
+  `in_trash` in one codebase.

package/skills/notion-connector/references/property-shapes.md

@@ -0,0 +1,110 @@
+# Property shapes — write JSON + read-parse for every Notion property type
+
+The Notion API rejects (HTTP 400) any property whose JSON envelope is wrong.
+Each property type is keyed by its **own** type name inside the page
+`properties` map. Below: the write shape (what you send on create/update) and a
+read-parse note (how to pull the value back out of a query result). All keyed
+by the property's display name as it appears in the data-source schema.
+
+## Text & scalar
+
+```ts
+// title — every data source has exactly one title property
+Name: { title: [{ text: { content: "Ship invoice export" } }] }
+// read: page.properties.Name.title.map(t => t.plain_text).join("")
+
+// rich_text
+Notes: { rich_text: [{ text: { content: "first pass" } }] }
+// read: page.properties.Notes.rich_text.map(t => t.plain_text).join("")
+
+// number
+Amount: { number: 1299.5 }            // read: page.properties.Amount.number
+
+// checkbox
+Done: { checkbox: true }              // read: page.properties.Done.checkbox
+
+// url / email / phone_number
+Site: { url: "https://example.com" }
+Contact: { email: "a@b.com" }
+Phone: { phone_number: "+34 600 000 000" }
+// read: page.properties.Site.url   (etc.)
+```
+
+## Choice types
+
+```ts
+// select — single option, created on the fly if the name is new
+Priority: { select: { name: "High" } }
+// read: page.properties.Priority.select?.name ?? null
+
+// multi_select
+Tags: { multi_select: [{ name: "ops" }, { name: "billing" }] }
+// read: page.properties.Tags.multi_select.map(o => o.name)
+
+// status — like select but tied to the schema's status groups;
+// the option name MUST already exist in the schema
+Status: { status: { name: "In progress" } }
+// read: page.properties.Status.status?.name ?? null
+```
+
+## Date & time
+
+```ts
+// date — start required, end optional, ISO 8601; include offset for time
+Due: { date: { start: "2026-06-30" } }
+Window: { date: { start: "2026-06-30T09:00:00+02:00", end: "2026-06-30T17:00:00+02:00" } }
+// read: page.properties.Due.date?.start
+```
+
+## Relations & people
+
+```ts
+// relation — array of related PAGE ids (the related rows)
+Project: { relation: [{ id: "<related_page_id>" }] }
+// read: page.properties.Project.relation.map(r => r.id)
+
+// people — array of Notion user ids the integration can see
+Owner: { people: [{ id: "<user_id>" }] }
+// read: page.properties.Owner.people.map(u => u.id)
+```
+
+## Files
+
+```ts
+// files — external URLs (uploading binary content is a separate flow)
+Attachments: { files: [{ name: "spec.pdf", external: { url: "https://…/spec.pdf" } }] }
+// read: page.properties.Attachments.files.map(f => f.external?.url ?? f.file?.url)
+```
+
+## Read-only / computed (never send on write)
+
+`formula`, `rollup`, `created_time`, `created_by`, `last_edited_time`,
+`last_edited_by`, and `unique_id` are computed by Notion. Including them in a
+create/update body is rejected. Read them:
+
+```ts
+page.properties.Created.created_time;           // ISO string
+page.properties.Total.formula.number;           // depends on formula result type
+page.properties.Ref.unique_id.number;           // auto-incrementing id
+```
+
+## Filter operand shapes (for queries)
+
+Filters mirror the property type. A few common ones:
+
+```ts
+// equals on a select
+{ property: "Status", status: { equals: "In progress" } }
+// contains on rich_text — the upsert-by-external-key workhorse
+{ property: "ExternalId", rich_text: { equals: "ext-42" } }
+// number comparison
+{ property: "Amount", number: { greater_than: 1000 } }
+// date relative
+{ property: "Due", date: { on_or_before: "2026-06-30" } }
+// compound
+{ and: [ { property: "Done", checkbox: { equals: false } },
+         { property: "Due", date: { before: "2026-07-01" } } ] }
+```
+
+Use a `rich_text` "ExternalId" property as your idempotency key and
+`rich_text.equals` to look a row up before deciding create vs update.