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 $refs 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).

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.