Initial Commit

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

@@ -0,0 +1,94 @@
+# @suaveplan/payment-provider-adyen - Universal Adyen Checkout API v71 adapter for @suaveplan/payment. Implements the PaymentProvider interface via the slim @suaveplan/payment-providers core (httpRequest + composeAbortSignal + MerchantKeyConfig + PaymentProviderError), forwarding X-API-Key auth on every call and injecting the configured merchantAccount into capture / cancel / refund request bodies. Generates default payment references via an injectable RandomIdFn so the package stays universal and deterministic under test.
+
+Universal **Adyen Checkout API v71 adapter** for `@suaveplan/payment`.
+Implements the `PaymentProvider` interface via the slim
+`@suaveplan/payment-providers` core (`httpRequest`,
+`composeAbortSignal`, `MerchantKeyConfig`, `PaymentProviderError`),
+forwarding `X-API-Key` auth on every call and injecting the configured
+`merchantAccount` into capture / cancel / refund request bodies.
+Generates default payment references via an injectable `RandomIdFn`
+so the package stays universal and deterministic under test.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [adyen](./src/adyen/adyen.md) — Universal adapter that implements the `PaymentProvider` interface from `@suaveplan/payment` against Adyen's Checko…
+  - [adyen](./src/adyen/adyen.md) — Universal adapter that implements the `PaymentProvider` interface from `@suaveplan/payment` against Adyen's Checko…
+  - [mapping](./src/adyen/mapping.md) — Pure mapping helpers that lift Adyen Checkout API v71 response shapes into the canonical `PaymentIntent`, `PaymentMetho…
+- [types](./src/types/adyen.md) — Type alias exported by `@suaveplan/payment-provider-adyen` describing the constructor argument accepted by `AdyenProvid…
+  - [adyen](./src/types/adyen.md) — Type alias exported by `@suaveplan/payment-provider-adyen` describing the constructor argument accepted by `AdyenProvid…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/payment-provider-adyen @suaveplan/payment @suaveplan/payment-providers
+```
+
+## Quick start
+
+```ts
+import { AdyenProvider } from "@suaveplan/payment-provider-adyen";
+import { ProviderRegistry } from "@suaveplan/payment-providers";
+import { PaymentEngine } from "@suaveplan/payment";
+
+const adyen = new AdyenProvider({
+    apiKey: process.env.ADYEN_API_KEY ?? "",
+    merchantAccount: "AcmeMerchantECOM",
+});
+
+const registry = new ProviderRegistry();
+registry.register(adyen);
+
+const engine = new PaymentEngine({ provider: registry.get("adyen") });
+
+const intent = await engine.createIntent({
+    amount: { amount: 5_000n, currency: "USD" },
+    captureMethod: "automatic",
+});
+```
+
+## Features
+
+- **Full `PaymentProvider` surface** — `createIntent` /
+  `confirmIntent` / `captureIntent` / `cancelIntent` / `refund` /
+  `getIntent`.
+- **`X-API-Key` authentication** with `Idempotency-Key` forwarding on
+  `createIntent` and `refund`.
+- **`merchantAccount` context** injected into every modification body
+  (`/captures`, `/cancels`, `/refunds`).
+- **Injectable `RandomIdFn`** for default `reference` generation —
+  with `globalThis.crypto.randomUUID()` fallback at
+  call time.
+- **Adyen status mapping** for all 10 documented v71 result codes
+  plus `failed` fallback.
+- **Typed errors only** — every failure surfaces as
+  `PaymentProviderError` (HTTP / timeout / parse) from the slim core.
+- **Universal tier** — zero `node:` / `bun:` / `fs` / `path` /
+  `stream` / `net` / `http` / `crypto` imports; runs on Node, Bun,
+  browsers, and Web Workers.
+- **Tree-shakeable** — `sideEffects: false` + per-feature subpath
+  exports.
+- **100% test coverage** (Istanbul) + 100% docs coverage.
+
+## Modules
+
+- [`src/adyen/adyen.md`](./src/adyen/adyen.md) — the `AdyenProvider`
+  class.
+- [`src/adyen/mapping.md`](./src/adyen/mapping.md) — pure mappers
+  (`mapStatus`, `mapRefundStatus`, `mapPaymentMethod`, `mapPayment`).
+- [`src/types/adyen.md`](./src/types/adyen.md) — `AdyenConfig` type
+  alias for the slim-core `MerchantKeyConfig`.
+
+## Related
+
+- [`@suaveplan/payment-providers`](../payment-providers/README.md) —
+  slim foundation: `httpRequest`, `composeAbortSignal`,
+  `ProviderRegistry`, `PaymentProviderError`, shared config types.
+- [`@suaveplan/payment`](../payment/README.md) — `PaymentEngine`,
+  `WebhookVerifier`, `PaymentProvider` interface.
+
+## License
+
+MIT
+