suaveplan/openspec/archive/2026-05-17-add-payment-provider-mollie/proposal.md

# Add @suaveplan/payment-provider-mollie — sibling Mollie adapter on the slim core

**Package**: `@suaveplan/payment-provider-mollie`
**Status**: PROPOSED
**Type**: new package (genesis-original, follow-up to the slim refactor)

- **Design**: ./design.md
- **Spec delta**: ./specs/payment-provider-mollie/spec.md

## Why

The slim refactor (`openspec/archive/2026-05-17-slim-payment-providers/`)
removed `MollieProvider` from `@suaveplan/payment-providers` and
committed it to re-land as a sibling package. This change ships that
sibling — `@suaveplan/payment-provider-mollie` — implementing the
`PaymentProvider` contract from `@suaveplan/payment` on top of the slim
core (`httpRequest`, `composeAbortSignal`, `ApiKeyConfig`,
`PaymentProviderError`, `PAYMENT_PROVIDER_CODES`).

Mollie's quirk is **amount marshalling**: every money field on the wire
is a `{ currency, value }` object where `value` is a decimal-formatted
string (`"50.00"`, `"0.01"`, `"12345678.90"`). The genesis money model
is `bigint` minor-units via `@suaveplan/money` (`{ amount: 5000n,
currency: "EUR" }`). The provider owns the round-trip — formatting
minor-units to two-decimal strings for outbound requests, and parsing
incoming strings back to `bigint` minor-units — with full coverage of
the carry / padding / large-value edges that bit hand-rolled
implementations elsewhere.

## What changes

### ADDED

- `MollieProvider` class implementing
  `PaymentProvider` from `@suaveplan/payment`. Constructor accepts
  `ApiKeyConfig` (apiKey + optional baseUrl / timeoutMs / fetch /
  signal / webhookSecret).
- `MOLLIE_DEFAULT_BASE_URL = "https://api.mollie.com/v2"`.
- `MOLLIE_PROVIDER_NAME = "mollie"`.
- `formatMollieAmount(amount: bigint): string` — minor-units →
  `"X.YY"` two-decimal string. Pure, exported, deterministic.
- `parseMollieAmount(value: string): bigint` — `"X.YY"` →
  minor-units `bigint`. Pure, exported, total over the shape Mollie
  emits.
- `mapMollieStatus(status: string): PaymentStatus` and
  `mapMollieRefundStatus(status: string): RefundStatus` — pure,
  exported, total status maps with documented unknown-status fallback.
- Subpath exports `./mollie/mollie` for tree-shaking.

### REMOVED

Nothing — this is a fresh package.

### MODIFIED

- `STATUS.md` — new row for `@suaveplan/payment-provider-mollie`
  flipped to ✅.
- `SUMMARY.md` — new paragraph for the sibling.
- `MANIFEST.md` / `MISSING.yml` — refreshed via the generator scripts.

## Source mapping

The shape of the adapter is anchored to upstream `MollieProvider` at
`/mnt/s/web/suaveplan/packages/universal/payment-providers/src/mollie.ts`
(the pre-slim, pre-sibling implementation) and to the original migration
spec at
`openspec/archive/2026-05-17-add-payment-providers/specs/payment-providers/spec.md`
(Mollie requirement block, L228–L258). The class signature, HTTP verbs,
status mapping, refund-status mapping, payment-method mapping, default
description / redirectUrl, and `Authorization: Bearer ${apiKey}` header
are preserved verbatim.

Departures from upstream:

| Surface | Upstream | Sibling | Reason |
|---|---|---|---|
| `vi.spyOn(globalThis, "fetch")` in tests | yes | replaced with real `FetchLike` closure injected via constructor | rule 8 / slim-core pattern — recording adapter, no global monkey-patching |
| `vi` / `vitest` test-runner import | yes | `@suaveplan/testing/runner` | AGENTS.md §7 |
| `@suaveplan/payment-providers` internal `httpRequest` | yes | unchanged — now imported from the public slim-core export | follow-up to slim refactor |
| Amount-formatting helpers (`formatAmount`, `parseAmount`) | private file-locals | exported (`formatMollieAmount`, `parseMollieAmount`) | reusable, individually unit-testable for edge cases |

## Migration

This is a fresh package — there is no in-tree migration. External
consumers that previously imported `MollieProvider` from
`@suaveplan/payment-providers` (pre-slim) MUST switch the import to
`@suaveplan/payment-provider-mollie`. The class name, constructor
signature, and `PaymentProvider` interface contract are preserved
verbatim; only the package name changes.

```ts
// Before (pre-slim)
import { MollieProvider } from "@suaveplan/payment-providers";

// After
import { MollieProvider } from "@suaveplan/payment-provider-mollie";
```

## Out of scope

- Webhook signature verification — Mollie does not sign its webhooks
  with a shared secret in the standard v2 API surface that this
  adapter implements. The `webhookSecret` field on `ApiKeyConfig` is
  accepted (for shape parity with the other sibling providers) but
  not consumed by this package.
- iDEAL issuer enumeration, Mollie Profiles API, Mollie Customers
  API, Mollie Subscriptions API — out of scope for the
  `PaymentProvider` contract. Future siblings can layer on top.
- OpenTelemetry spans / counters — deferred to align with
  `@suaveplan/payment` and `@suaveplan/payment-providers`, which also
  do not yet ship OTel wiring.

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/payment-provider-mollie` to
enumerate.

- No dependents (verified by the fresh-package status — this package is
  brand-new and nothing on `genesis` imports it yet). Future consumers
  (apps, plugins, payment-engine bootstraps) opt in by adding the
  dependency.

## Parity Checklist

This is a fresh sibling that preserves the upstream `MollieProvider`
behaviour verbatim. Parity is against
`/mnt/s/web/suaveplan/packages/universal/payment-providers/src/mollie.ts`:

| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| `MollieProvider implements PaymentProvider` | yes | ✅ | verbatim, name `"mollie"` |
| `ApiKeyConfig` constructor (`apiKey`, optional `baseUrl`, `timeoutMs`, `webhookSecret`, `fetch`, `signal`) | yes | ✅ | now imports `ApiKeyConfig` from the slim core; the upstream version inlined the same shape |
| `Authorization: Bearer ${apiKey}` header on every call | yes | ✅ | unchanged |
| `createIntent` → `POST /payments` | yes | ✅ | unchanged |
| `confirmIntent` → read-through to `getIntent` | yes | ✅ | unchanged (Mollie auto-captures) |
| `captureIntent` → read-through to `getIntent` | yes | ✅ | unchanged (Mollie auto-captures) |
| `cancelIntent` → `DELETE /payments/{id}` | yes | ✅ | unchanged |
| `refund` → `POST /payments/{id}/refunds` | yes | ✅ | unchanged; refund without explicit amount also covered |
| `getIntent` → `GET /payments/{id}` | yes | ✅ | unchanged |
| Default `description = "Payment"` | yes | ✅ | unchanged |
| Default `redirectUrl = "https://localhost/return"` | yes | ✅ | unchanged |
| Status map (`open` → `created`, `pending`, `authorized`, `paid` → `captured`, `canceled`, `expired` → `canceled`, `failed`, other → `failed`) | yes | ✅ | exported as `mapMollieStatus` for direct unit coverage |
| Refund status map (`refunded` → `succeeded`, `pending`/`queued`/`processing` → `pending`, other → `failed`) | yes | ✅ | exported as `mapMollieRefundStatus` |
| Payment method map (`creditcard` → `card`, other defined method → `wallet`, undefined → no method) | yes | ✅ | unchanged |
| `card` brand + last4 extraction from `details` | yes | ✅ | unchanged |
| Amount marshalling: `bigint` → `"X.YY"` (`formatAmount`) | yes | ✅ | extracted + exported as `formatMollieAmount`; covered with edge cases 1 cent, large values, exact decimals |
| Amount marshalling: `"X.YY"` → `bigint` (`parseAmount`) | yes | ✅ | extracted + exported as `parseMollieAmount`; covered with single-decimal, missing decimal, padded decimal |
| All errors raised as `PaymentProviderError` from the slim core | yes | ✅ | unchanged — `httpRequest` raises typed errors; this package never throws raw `Error` |
| `vi.spyOn` in tests | yes | 🚫 replaced | rule 8 / slim-core pattern: tests inject a recording `FetchLike` |
| Direct `from "vitest"` test imports | yes | 🚫 replaced | AGENTS.md §7: `from "@suaveplan/testing/runner"` |

## Verification approach

- `src/mollie/mollie.test.ts` — exercises every `PaymentProvider`
  method using injected `FetchLike` closures that record requests and
  return controlled `Response`s. Covers:
  - `createIntent` happy path + default description / redirectUrl
  - `confirmIntent` / `captureIntent` read-through
  - `cancelIntent` HTTP DELETE
  - `refund` with explicit amount + without
  - `getIntent` HTTP GET with card brand + last4 extraction
  - Full status-map matrix (all 8 cases incl. unknown → `failed`)
  - Full refund-status-map matrix (all 5 cases)
  - Payment-method map for `creditcard` / `ideal` / undefined
  - Amount marshalling edge cases: 1 cent (`1n` → `"0.01"`), exact
    dollar (`100n` → `"1.00"`), large (`12345678901234n` →
    `"123456789012.34"`), and the inverse round-trips.
  - `Authorization: Bearer …` header surfaced on every recorded call.
  - Network failure surfaces as `PaymentProviderError` (HTTP_ERROR).
- All tests import from `@suaveplan/testing/runner`.
- 100/100/100/100 coverage gate (vitest istanbul) enforced in
  `vitest.config.ts`.