Initial Commit

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

@@ -0,0 +1,111 @@
+# @suaveplan/payment-provider-stripe - Universal Stripe adapter for @suaveplan/payment. Implements PaymentProvider against the Stripe REST API via the slim @suaveplan/payment-providers foundation: Bearer auth on every call, Idempotency-Key forwarding on every mutating call, exhaustive Stripe status/refund-status/refund-reason mapping, payment-method normalisation, every error raised as PaymentProviderError with provider: 'stripe' discriminant. No Node / browser / React deps; every HTTP call flows through the injectable FetchLike from the slim core.
+
+Universal Stripe adapter for `@suaveplan/payment`. Implements
+`PaymentProvider` against the Stripe REST API using the slim
+`@suaveplan/payment-providers` foundation: Bearer auth on every call,
+`Idempotency-Key` forwarding on every mutating call, exhaustive
+Stripe → domain status / refund-status / refund-reason mapping,
+payment-method normalisation, every error raised as
+`PaymentProviderError` with `provider: "stripe"` discriminant.
+
+This package is one of the five sibling adapters that re-landed
+after `2026-05-17-slim-payment-providers` split the bundled
+`@suaveplan/payment-providers` into a foundation-with-sibling-plugins
+shape.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [stripe](./src/stripe/stripe.md) — `StripeProvider` is the Stripe adapter for `@suaveplan/payment`. It implements the `PaymentProvider` contract (six meth…
+  - [stripe](./src/stripe/stripe.md) — `StripeProvider` is the Stripe adapter for `@suaveplan/payment`. It implements the `PaymentProvider` contract (six meth…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/payment-provider-stripe \
+        @suaveplan/payment-providers \
+        @suaveplan/payment
+```
+
+## Quick start
+
+```ts
+import { PaymentEngine } from "@suaveplan/payment";
+import { StripeProvider } from "@suaveplan/payment-provider-stripe";
+
+const provider = new StripeProvider({
+    apiKey: process.env.STRIPE_SECRET_KEY ?? "",
+});
+
+const engine = new PaymentEngine({ provider });
+
+const intent = await engine.createIntent({
+    amount: { amount: 5000n, currency: "USD" },
+    captureMethod: "automatic",
+    idempotencyKey: crypto.randomUUID(),
+});
+```
+
+## Compose with the foundation registry
+
+```ts
+import { ProviderRegistry } from "@suaveplan/payment-providers";
+import { StripeProvider } from "@suaveplan/payment-provider-stripe";
+
+const registry = new ProviderRegistry();
+registry.register(
+    new StripeProvider({ apiKey: process.env.STRIPE_SECRET_KEY ?? "" })
+);
+
+const stripe = registry.get("stripe"); // typed as PaymentProvider
+```
+
+## Features
+
+- **`StripeProvider`** — implements `PaymentProvider` from
+  `@suaveplan/payment` (literal `name: "stripe"`, six lifecycle
+  methods).
+- **Bearer authentication** on every request (read + write).
+- **`Idempotency-Key` forwarding** — when the caller supplies
+  `idempotencyKey` on `CreatePaymentIntentInput` or `RefundInput`,
+  the provider forwards it verbatim to Stripe so retries collapse
+  into a single side effect.
+- **Exhaustive status mappings** — seven Stripe payment-intent
+  statuses, three Stripe refund statuses, four Stripe refund reasons,
+  every unmapped value falls back to `failed` / `other`.
+- **Payment-method normalisation** — `card` carries `brand` + `last4`;
+  any other Stripe `type` maps to `wallet`; absent payment method
+  maps to `undefined`.
+- **Typed errors** — every failure is a `PaymentProviderError` from
+  the slim core with `provider: "stripe"` discriminant.
+- **Universal tier** — zero Node, browser, React, or
+  platform-specific imports. Runs unchanged on Node, Bun, browsers,
+  and Web Workers.
+- **Tree-shakeable** — `sideEffects: false` plus per-feature subpath
+  exports.
+- **100% test coverage** (Istanbul) and **100% docs coverage**.
+
+## Modules
+
+- [`src/stripe/stripe.md`](./src/stripe/stripe.md) — `StripeProvider`
+  class, `StripeConfig`, `StripeIntent` / `StripeRefund` wire-format
+  interfaces.
+
+## Related
+
+- `@suaveplan/payment` — `PaymentEngine`, `WebhookVerifier`,
+  `PaymentProvider` interface, `PaymentIntent` / `Refund` / status
+  enums.
+- `@suaveplan/payment-providers` — slim foundation with
+  `ProviderRegistry`, `httpRequest`, `composeAbortSignal`,
+  `PaymentProviderError`, shared config shapes.
+- `@suaveplan/payment-provider-paypal`,
+  `@suaveplan/payment-provider-square`,
+  `@suaveplan/payment-provider-mollie`,
+  `@suaveplan/payment-provider-adyen` — sibling provider packages.
+
+## License
+
+MIT
+