Initial Commit

packages/money/payment/payment-provider-mollie/README.md

@@ -0,0 +1,72 @@
+# @suaveplan/payment-provider-mollie - Universal Mollie Payments API v2 adapter for @suaveplan/payment. Sibling provider package on the slim @suaveplan/payment-providers core: implements PaymentProvider with Mollie's string-amount marshalling ({ currency, value: "X.YY" }) round-trip via exported formatMollieAmount / parseMollieAmount helpers.
+
+Universal Mollie Payments API v2 adapter for `@suaveplan/payment`.
+Sibling provider package on the slim `@suaveplan/payment-providers`
+core: implements `PaymentProvider` with Mollie's string-amount
+marshalling (`{ currency, value: "X.YY" }`) round-trip via the
+exported `formatMollieAmount` / `parseMollieAmount` helpers.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [mollie](./src/mollie/mollie.md) — `MollieProvider` is the sibling adapter that implements the `PaymentProvider` contract from `@suaveplan/payment…
+  - [mollie](./src/mollie/mollie.md) — `MollieProvider` is the sibling adapter that implements the `PaymentProvider` contract from `@suaveplan/payment…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/payment-provider-mollie @suaveplan/payment-providers @suaveplan/payment
+```
+
+## Quick start
+
+```ts
+import { ProviderRegistry } from "@suaveplan/payment-providers";
+import { MollieProvider } from "@suaveplan/payment-provider-mollie";
+
+const registry = new ProviderRegistry();
+registry.register(
+    new MollieProvider({ apiKey: process.env.MOLLIE_API_KEY ?? "" })
+);
+
+const mollie = registry.get("mollie");
+const intent = await mollie.createIntent({
+    amount: { amount: 5000n, currency: "EUR" },
+    description: "Order #42",
+    returnUrl: "https://shop.example/return",
+});
+console.log(intent.id, intent.status);
+```
+
+## Features
+
+- `MollieProvider` — full `PaymentProvider` lifecycle
+  (`createIntent`, `confirmIntent`, `captureIntent`, `cancelIntent`,
+  `refund`, `getIntent`) on top of the slim `httpRequest` helper.
+- Pure, exported amount helpers — `formatMollieAmount(amount: bigint)`
+  and `parseMollieAmount(value: string)` — that round-trip losslessly
+  via `bigint` and cover the 1-cent, exact-major, large-value, and
+  over-precision edges.
+- Total exported status maps — `mapMollieStatus` and
+  `mapMollieRefundStatus` — each individually unit-testable without
+  invoking the network path.
+- `Authorization: Bearer <apiKey>` header auto-applied on every call.
+- Universal — no Node-specific or browser-specific globals; runs
+  on Node 18+, Bun, browsers, and Web Workers.
+- All failures surface as `PaymentProviderError` from
+  `@suaveplan/payment-providers` carrying a `PAYMENT_PROVIDER_*` code.
+
+## Modules
+
+- [`src/mollie/mollie.md`](./src/mollie/mollie.md) —
+  `MollieProvider` class, helpers, and status maps.
+
+## Sibling packages
+
+Part of the `@suaveplan/payment-provider-*` family. See
+[`@suaveplan/payment-providers`](../payment-providers/README.md) for the
+shared foundation (`ProviderRegistry`, `httpRequest`,
+`composeAbortSignal`, `PaymentProviderError`, the `PAYMENT_PROVIDER_*`
+code registry, and the shared config shapes).
+