112 lines
4.4 KiB
Markdown
112 lines
4.4 KiB
Markdown
# @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
|
|
|