chore: add sync-api skill for reconciling the SDK with the Mollie API

A Claude Code skill (.claude/skills/sync-api) that checks — and optionally
fixes — the SDK's types, JSDoc, enums, endpoint coverage and helper wiring
against Mollie's master OpenAPI spec.

It is deliberately script-driven so the model spends its budget on judgment,
not on parsing JSON: a bundled toolchain fetches/caches the master spec, emits
compact per-field digests (descriptions preserved verbatim and self-checked for
loss), reads the SDK's structure via the TypeScript AST, and produces a
deterministic diff. The model then handles only what genuinely needs judgment —
Pick-vs-inline, nullable-vs-optional, breaking changes, description coverage,
and link/embed helper coverage.

Includes the project .claude docs the skill references (CLAUDE.md,
ARCHITECTURE.md), adds the `yaml` devDependency used by the spec extractor, and
ignores the skill's .tmp cache and local worktrees.

Author: janpaepke

.claude/ARCHITECTURE.md

@@ -0,0 +1,58 @@
+# Resource Architecture
+
+Each API resource (payments, refunds, customers, etc.) is composed of up to four parts:
+
+```
+src/
+├── data/<resource>/
+│   ├── data.ts              # Response type + enums
+│   ├── <Resource>.ts        # Sealed public type + transform()
+│   └── <Resource>Helper.ts  # Instance methods (optional)
+│
+└── binders/<resource>/
+    ├── <Resource>Binder.ts  # Endpoint methods (create, get, page, ...)
+    └── parameters.ts        # Request types per operation
+```
+
+## `data.ts` — Response shape
+
+- Defines `*Data` interface extending `Model<'resource-name'>` — the raw API response
+- Contains enums (statuses, embed/include options) and `*Links` interfaces
+- Source of truth for field names and types; `parameters.ts` reuses fields from here via `Pick`
+
+## `<Resource>.ts` — Sealed type + transform
+
+- Defines `type Resource = Seal<ResourceData, ResourceHelper>`
+- `Seal<M, H>` = `Readonly<M> & H` — frozen data properties merged with helper methods
+- `transform()` creates the sealed object and recursively transforms embedded sub-resources
+- This is what SDK consumers interact with
+
+## `<Resource>Helper.ts` — Instance methods
+
+- Extends `Helper<Data, Resource>` base class (provides `refresh()`, toString, inspect)
+- Adds convenience methods for navigating related resources (e.g. `getRefunds()`, `getPayment()`)
+- Not every resource needs a custom helper — simple resources use the base `Helper` directly
+- Wired to the sealed type via `Object.assign(Object.create(new Helper(...)), data)`
+
+## `<Resource>Binder.ts` — Endpoint methods
+
+- Extends `Binder<ResourceData, Resource>`
+- One public method per API operation: `create`, `get`, `page`, `iterate`, `update`, `cancel`/`delete`
+- Delegates to `TransformingNetworkClient`, which auto-applies `transform()` to responses
+
+## `parameters.ts` — Request types
+
+- One type per operation (`CreateParameters`, `GetParameters`, `PageParameters`, etc.)
+- Composed from the Data interface via `Pick` (preserves optionality) and `PickOptional` (forces optional)
+- Request-only fields (not in response) are defined inline here
+- Shared mixins (from `src/types/parameters.ts`): `IdempotencyParameter`, `PaginationParameters`, `SortParameter`, `ThrottlingParameter`, `TestModeParameter`
+- Nested resources include context params (e.g. `paymentId: string`)
+
+## Wiring
+
+New resources must be registered in `createMollieClient.ts`:
+1. Import and register the transformer: `.add('resource-name', transformResource)`
+2. Instantiate and expose the binder: `resourceName: new ResourceBinder(transformingNetworkClient)`
+
+Public types are exported from `src/types.ts` (sealed types, parameter type aliases, enums).
+`*Data` interfaces and helpers are internal — not exported to consumers.

.claude/CLAUDE.md

@@ -0,0 +1,56 @@
+# Mollie API Node.js SDK
+
+Official Node.js client (`@mollie/api-client`) for the Mollie Payment API v2.
+
+Resource layer structure (data, binders, helpers, parameters) is documented in `.claude/ARCHITECTURE.md`.
+
+## Commands
+
+```bash
+yarn build          # Rollup bundle (CJS + ESM) + TypeScript declarations
+yarn test           # Jest tests
+yarn test:watch     # Jest watch mode
+yarn test:cov       # Coverage report
+yarn lint           # ESLint fix + Prettier
+```
+
+## Type System — Request vs Response
+
+IMPORTANT: `data.ts` and `parameters.ts` are **not** two views of the same type. They are separate concerns:
+
+- `data/<resource>/data.ts` → **response** shape (what the API returns). This is the source of truth for field names and types.
+- `binders/<resource>/parameters.ts` → **request** shape (what the consumer sends). Built by `Pick`/`PickOptional` from the Data interface, plus request-only fields that don't appear in responses (e.g. `applePayPaymentToken`, `cardToken`).
+
+`Pick<Data, ...>` preserves optionality from the response type. `PickOptional<Data, ...>` forces fields optional ("exists on response, but optional to send").
+
+Do NOT add request-only fields to `data.ts` — they belong in `parameters.ts`.
+
+## Helpers and underscore-prefixed fields
+
+Consumers should never access underscore-prefixed properties directly (the `_` prefix denotes private/internal, e.g. `_links`, `_embedded`). Helper methods (e.g. `payment.getRefunds()`) abstract these away — they transparently return embedded data if available, or fetch via the API link if not. This is why helpers exist: a single entry point regardless of whether data was embedded or needs fetching.
+
+## Conventions
+
+- Conventional commits for all commit messages.
+- `prefer-rest-params` is intentionally off — the `arguments` object is used deliberately in the renege (promise↔callback) pattern. Don't refactor these to rest params.
+- New transformers must be registered in `createMollieClient.ts` alongside the binder wiring.
+- Enums and public types are exported from `src/createMollieClient.ts` and `src/types.ts`.
+
+## Release Process
+
+Publishing is automated via `.github/workflows/publish.yml` (npm Trusted Publishing / OIDC) — it runs when a GitHub Release is published. There is **no manual `npm publish`** and no npm token.
+
+1. Update `CHANGELOG.md`
+2. `npm version <major|minor|patch>` (bumps `package.json`, commits, creates the `vX.Y.Z` tag)
+3. `git push --follow-tags`
+4. Publish a GitHub Release for the tag → the workflow verifies the tag matches `package.json`, builds, runs unit tests, and publishes with provenance (prereleases like `-rc.N` go to their own dist-tag, not `latest`).
+
+See `CONTRIBUTING.md` for the maintainer-facing version of this.
+
+## Gotchas
+
+- **Mollie API docs are unreliable for optionality/nullability.** Fields marked `required` may work fine without sending them (e.g. `redirectUrl`). Fields typed as `object` (not nullable) may actually be optional (e.g. `billingAddress`). Fields typed as `string | null` are likely optional too (absent from responses despite not being marked optional). Never auto-apply optionality from the docs — flag discrepancies for manual review instead.
+- **Nullable vs optional convention**: `Nullable<T>` (`T | null`) = always present, sometimes null. `T?` = sometimes absent. `?: Nullable<T>` = both. Default to `?` (optional) when uncertain, upgrade to `Nullable<T>` only when confirmed via actual API behavior.
+- **Mollie docs .md trick** — append `.md` to any reference page URL (e.g. `https://docs.mollie.com/reference/create-payment.md`) to get plain-text markdown with fully resolved OpenAPI JSON. No browser automation needed. The GitHub repo `mollie/openapi` (`specs.yaml`) has the full spec but uses `$ref`s.
+- **node-fetch v2** (CommonJS) is the HTTP client, not native fetch.
+- **Node version: README says 14+, `engines` says `>=8` — this mismatch is intentional, do not "fix" it.** The SDK's *code* is expected to run on Node 8+, hence `engines.node: ">=8"`. But the *test environment* won't run on anything older than Node 14, so 14 is the lowest version we can actually verify. The policy: we guarantee it works on 14, and it *probably* works on older versions down to 8 — we just can't prove it. README states 14 (the supported/tested floor); `engines` states 8 (the believed-actual floor). Aligning the two numbers would either drop unverified-but-likely support or claim guarantees we can't back.