sync-api

# Sync Types with Mollie API Compare the SDK's TypeScript types against Mollie's master OpenAPI spec and optionally apply fixes. A bundled toolchain does the **deterministic** work (fetch, resolve, flatten, diff); you apply the **judgment** (Pick-vs-inline, nullability, breaking changes, deprecation, JSDoc). Spend your tokens on judgment, not on parsing JSON. ## Usage `/sync-api <target> [--only structure,docs,wiring]` `<target>` is a **single token** — one of: - **operationId** (e.g. `get-payment`, `create-refund`) — one endpoint - **resource** (e.g. `refunds`, `payments`) — every endpoint of that resource - **all** — every resource (parallel agents, one per resource) `--only` scopes which phases run (default: all three). "just sync the docs" → `--only docs`. If the target doesn't match a known operationId (via `extract-spec.mjs --index`) or resource directory, ask rather than guessing. ## Source of truth The master spec `mollie/openapi:specs.yaml` (operationId **is** the endpoint key, complete, all `$ref`s local). The toolchain fetches and caches it (ETag-validated) under `.tmp/sync-api/`. **Do NOT hand-fetch doc pages to read schemas.** Doc-site slugs are inconsistent with operationIds (e.g. spec `list-chargebacks` = doc `list-payment-chargebacks`; `create-payment-refund.md` 404s — it's `create-refund`) and a wrong slug returns a 200-status 404 page that parses as an empty "in sync" result. Doc pages are only used for `@see` URLs, always HTTP-200-verified before writing (see `references/apply.md`). ## Toolchain (`scripts/`, run via Bash) Run from the **repo root** (paths below are repo-root-relative; the scripts resolve the repo root themselves, so the working directory only matters for locating the script file). | Command | Output | |---|---| | `node .claude/skills/sync-api/scripts/extract-spec.mjs --index` | every operation: `METHOD path -> operationId` | | `node .claude/skills/sync-api/scripts/extract-spec.mjs <operationId> [--side response\|request\|params] [--show\|--json]` | bare: summary + self-check status. `--show`: rendered digest. `--json`: digest rows. Default side: `response` (GET) / `request` (POST/PATCH/PUT). | | `node .claude/skills/sync-api/scripts/extract-spec.mjs <operationId> --meta [--json]` | the **operation's** own `summary` / `description` / `deprecated` — the anchor for the binder-method JSDoc check (Phase 2) | | `node .claude/skills/sync-api/scripts/extract-sdk.mjs <file.ts> [--json]` | SDK structural map: `Pick`/`PickOptional`/inline/heritage, JSDoc, `@see`, **duplicate fields**; for a binder, also `.methods[]` (method name + JSDoc + `@see`) | | `node .claude/skills/sync-api/scripts/diff.mjs <operationId> <file.ts> <TypeName>` | deterministic field delta: missing / extra / type+doc drift. Side is chosen from the SDK type (see below); `readOnly`/`writeOnly` filtered accordingly; bases resolved (incl. cross-file). Field-level only — method JSDoc is Phase 2. | The digest preserves every description **verbatim** — that prose (deprecations, constraints, access restrictions, method-specific relevance) is the core value and the scripts never summarize it. If `extract-spec.mjs` exits **non-zero on a digest**, a description was dropped — treat as a bug, do not proceed on partial data. (A missing *side* — e.g. a `204 No Content` response, or a GET with no query params — is a clean exit 0 with empty output, not an error.) The spec is fetched once and cached; a recent cache is reused without a network call. Offline → it warns once and uses the cache; pass `--refresh` to force a re-fetch. ## Step 1 — Analyze For each operation in scope: 1. **Discover** the SDK side. Glob the resource's files (`src/data/**/<resource>/*.ts`, `src/binders/**/<resource>/*.ts`); run `extract-sdk.mjs <data.ts> --json` and `extract-sdk.mjs <parameters.ts> --json` to see the exported types. 2. **Run `diff.mjs`** for each operation against its SDK mirror(s). An operation has up to **two** mirrors, and `diff.mjs` picks the comparison side automatically from the SDK type you pass: - **Response** ↔ the resource's `Data` interface — `diff <op> <data.ts> <ResourceData>` (every GET/POST/PATCH that returns a body). - **Request body + query params** ↔ the operation's `*Parameters` type — `diff <op> <parameters.ts> <OpParameters>` (`Create*`/`Update*` for body; `Get*`/`Page*`/`Iterate*` for query params; `Cancel*`/`Delete*` for `testmode`-only bodies). Run both where both exist. The diff is the mechanical delta; spend judgment on it, not on re-deriving it. 3. **Apply judgment** over the delta + the verbatim descriptions, across three phases **in order** (each depends on the previous being resolved): ### Phase 1 — Structure Resolve the `diff` "MISSING" / "IN SDK not in spec" / type findings: - **Missing fields** — add with `?` optional by default, always with JSDoc (the spec description, verbatim) and an `@see` link. - **Where a request field lives — `Pick` vs inline (the hardest call):** a field belongs **inline** in `parameters.ts` ONLY if (a) it exists on no `Data` interface anywhere in `src/data/` (request-only / `writeOnly`, e.g. `cardToken`, `dueDate`), OR (b) the spec genuinely differs between request and response for that field (different description, constraints, or type — compare both). Otherwise use `Pick`/`PickOptional` from the owning `Data` interface. `extract-sdk.mjs` flags fields defined via `Pick` **and** inline (`⚠️ DUPLICATES`) — those must be deduplicated to `Pick`/`PickOptional` (verify the `Data` interface's JSDoc is complete first, since it becomes canonical). - **Always `Pick`, never `Omit`** — `Omit` silently leaks newly-added source fields. - **"IN SDK, not in spec" — never auto-remove; judge over-declaration vs spec-incompleteness.** Param-absence is a *proxy*, not proof. When the spec's operation description explains the absence, `diff.mjs` appends it as `— spec note: "…"` — that prose is authoritative (e.g. `testmode` on the terminals pairing endpoints: *"does not support test mode yet"* → a real over-declaration; mind the **"yet"** — the answer may be "keep, support is imminent"). With **no** spec note (e.g. `testmode` on the live-only settlement endpoints), it's a softer call — genuinely unsupported, or just unlisted by Mollie? Flag under "Needs attention" either way. - **`_links` / `_embedded` entries are structure too** — `diff.mjs` flags a missing link/embed property as `[P1] _links.<name>: in spec, not on <Links interface>`. Add the property (e.g. to the `*Links` interface) with JSDoc, exactly like any other field. (The *helper* for it is a separate concern — Phase 3.) - **Response-only (`readOnly`) fields on shared interfaces** stay **required** on the `Data` interface (matching the response); the request strips them via `Pick`. Never weaken a response type because a field isn't sent in requests. - **Enums / types** — add missing enum values; fix genuine type mismatches. **Nullable vs optional (see CLAUDE.md for the project convention):** - On **request** fields, spec `type: [..,'null']` does **NOT** mean `T | null`. Sending `null` to clear a field is a distinct semantic most Mollie fields don't support — default to `T` unless the description explicitly says `null` clears the value. - Never downgrade an existing `Nullable<T>` (confirmed behavior). Don't auto-flip optionality from the spec — the docs are unreliable here. **⚠️ BREAKING CHANGES — warn loudly, never auto-apply.** Removing/renaming a field/type/enum/method; optional→required on a request param; **required→optional on a response field** (breaks consumers doing `obj.field.prop`, even if the spec says optional — the SDK may keep it required based on observed behavior); type changes. Prefix with `⚠️ BREAKING:` under "Needs attention", explain why, and prefer non-breaking alternatives (add alongside, `@deprecated` the old, union types). Response optionality changes require explicit user confirmation. ### Phase 2 — Documentation On the **final** field locations (after Phase 1): - **Deprecation** — check the digest's `deprecated` flag, `xDeprecatedEnum`, AND the description prose ("will be ignored", "no longer supported", "use X instead"). Any deprecation → `@deprecated` JSDoc tag on the SDK field/method. - **JSDoc drift / content loss** — `diff.mjs` flags `no-JSDoc` and `JSDoc may drop N spec sentence(s)` (the SDK JSDoc lost content the spec has). This is **coverage, not verbatim** — the goal is that the spec's information is *reflected* in the code, not copied word-for-word. Apply judgment: - **Intentional drift is fine** — SDK-specific notes, or corrections where the docs are wrong (e.g. docs say a field is required but it isn't). Keep these; a flag here just means "confirm it's deliberate". - **Accidental truncation is not** — a dropped sentence with no reason (constraints, possible values, method-specific relevance) should be restored from the spec description. - **Ignore the shared `Amount`/`URL` boilerplate** ("In v2 endpoints, monetary amounts/URLs are represented as objects…") — it lives on the shared `Amount`/`Url` type, not repeated per field; its absence is not a gap. - **`@see` format** — `diff.mjs` flags `old-@see-format` (`/reference/v2/<api>/...` → `/reference/...`). For bulk, state the count. - **Binder method JSDoc** — `diff.mjs` does NOT cover this (it's method-level, not field-level), so it must be done explicitly. Run `extract-spec.mjs <op> --meta` (the operation's `summary`/`description`/`deprecated`) and `extract-sdk.mjs <binder> --json` (`.methods[]` with JSDoc + `@see`); map each method to its operation via its `@see` slug. Then flag: - **`@deprecated` mismatch** (mechanical) — operation `deprecated: true` but the method JSDoc lacks `@deprecated`, or vice versa. - **Factual drift** (judgment) — product claims, supported-method lists, or legacy-flow references in the method JSDoc that the operation `description` contradicts or no longer mentions (e.g. "supports Cards and Klarna", an Orders-shipment flow). Ignore mere wording differences. ### Phase 3 — Wiring (helper coverage) An **invariant over the current state**: every `_links` / `_embedded` entry the SDK declares should have a corresponding helper — *regardless of whether the entry was just added (Phase 1) or has been there all along*. (Existence + correctness of the entry itself is Phase 1/2; this phase only asks "is there a helper for it?") `diff.mjs` flags `[P3] _links.<name>: no helper (expected get/has<Name>[Url]) — Helper class: <file | NONE — must be created>`. For each, add the helper using the right pattern (list→`HelpfulIterator` + `hasX`; single resource→`getX`; URL-only→`getXUrl`), creating the resource's `*Helper.ts` if none exists. **See `references/wiring.md`** for the patterns and the 4-file `_embedded` procedure. Base `self`/`documentation` are never helper-exposed and aren't flagged. 4. **Report** — issues only, grouped by phase; omit empty phases; counts for bulk items; field path + what differs + `file:line` for individual ones. Never auto-remove SDK fields absent from the spec — flag under "Needs attention". Then a **Summary**: **Doc-synced** (no type change), **Added**, **Needs attention** (omit empty categories). ## Step 2 — Apply 1. **Ask which phases/categories to apply.** If the user selects nothing to change, stop here — there are no edits to make, so the working tree is never touched. 2. **Only if changes will be made, check the working tree is clean** (do this *after* the selection, *before* the first edit). Run `git status --porcelain --untracked-files=no` (the gitignored `.tmp/` cache and untracked files are correctly excluded). If it shows **uncommitted changes to tracked files**, STOP and ask the user — sync edits would interleave with their existing work, muddying the diff. Lead with the safer option (the tree is already dirty, which is the only reason this prompt appears): (a) **isolate in a fresh worktree (recommended/default)** — `git worktree add ../mollie-api-node-sync-<target> -b sync/<target>` (clean checkout of the current commit; their WIP stays put); or (b) apply here anyway (sync edits interleave with the existing changes). Do not proceed until they choose. 3. **Read `references/apply.md`** (Pick/PickOptional mechanics + the mandatory pre-check, `@see` format + verify-before-write, intersection/empty-interface style) and apply edits **in phase order**. **Post-apply gate (MANDATORY):** after edits, run `yarn build:declarations` (typechecks the whole graph via `src/types.ts`, ~2s) and `npx eslint --ext .ts src/<touched dirs>`, then `npx prettier --write <touched files only>` (NOT `yarn lint` — it reformats the whole tree). Fix any diagnostics before reporting done. The gate proves edits are type-valid; it does **not** validate optionality/breaking-change judgment — those stay under "Needs attention". **Post-apply description-coverage review:** re-run `diff.mjs` on each edited `(op, type)` pair and look at the `JSDoc may drop …` flags. This catches the common failure where the apply step **shortened a description while writing JSDoc** — especially on **newly-added fields**, where a coverage gap is almost certainly accidental truncation (you just added it from the spec — restore the dropped content). For pre-existing fields, judge intentional drift vs accidental per the Phase 2 rules. This is a **review, not a hard gate** — fix accidental loss, keep deliberate deviations. ## Parallelization For a resource or `all`, fan out **one agent per resource** (never per endpoint — the request-vs-response `Pick` decision needs both specs in one context; never per check — the phases are dependency-ordered). Each agent runs the full analyze step for its resource and writes verbatim findings to `.tmp/sync-api/report-<resource>.json` (apply reads these, immune to context summarization). Use the contract in **`references/agent-prompt.md`**. `--only` scopes each agent's phases.