Add @suaveplan/payment-provider-stripe sibling adapter

Package: @suaveplan/payment-provider-stripe Status: PROPOSED Type: new-package

Why

The 2026-05-17-slim-payment-providers change extracted the five concrete provider adapters (Stripe, PayPal, Square, Mollie, Adyen) out of @suaveplan/payment-providers and into sibling packages so consumers pay only for the providers they install. This change lands the Stripe sibling.

@suaveplan/payment-provider-stripe re-lands the StripeProvider class (previously @suaveplan/payment-providers.StripeProvider prior to the slim-down) verbatim against the slim foundation. It implements PaymentProvider from @suaveplan/payment, uses httpRequest from the slim foundation for every HTTP call, forwards Bearer auth and the caller-supplied Idempotency-Key header on every mutating request, maps Stripe payment-intent / refund status codes to the domain PaymentStatus / RefundStatus enums, and raises only PaymentProviderError.

What changes

ADDED: @suaveplan/payment-provider-stripe package at packages/universal/payment-provider-stripe/ (0.1.0, universal tier, sideEffects: false).
ADDED: class StripeProvider implements PaymentProvider with literal name: "stripe". Constructor accepts a StripeConfig extending ApiKeyConfig (Stripe secret key + optional webhookSecret, plus the shared ProviderCommonOptions).
ADDED: All six PaymentProvider methods — createIntent, confirmIntent, captureIntent, cancelIntent, refund, getIntent — each routed through httpRequest against the Stripe REST API.
ADDED: Stripe-domain → PaymentIntent / Refund mappers (mapIntent, mapRefund, mapStatus, mapRefundStatus, mapRefundReason) that translate every Stripe lifecycle state into the @suaveplan/payment enums.
ADDED: StripeConfig type re-export so consumers can pin the construction shape without reaching into the slim core for ApiKeyConfig.
ADDED: Subpath exports for ./stripe/stripe so consumers can tree-shake the provider class directly.

Out of scope

Webhook signature verification — @suaveplan/payment already ships the WebhookVerifier; this package only carries the webhookSecret field on StripeConfig for downstream wiring.
OpenTelemetry spans / counters on the provider — defers to a monorepo-wide observability pass tracking @suaveplan/payment-level instrumentation.
Stripe Connect, Customer / Setup-intent / Subscription APIs — the PaymentProvider contract only covers payment-intent + refund lifecycle; non-contract Stripe surfaces are deferred to dedicated follow-up packages.
Currency conversion — Stripe's minor-unit (cents) amount is mapped to MoneyLike.amount: bigint 1:1 with currency uppercased; no zero-decimal currency adjustment is performed in this change (parity with the pre-slim shape).

Source mapping

This change derives from ../suaveplan/enterprise/payment-providers.md and the verbatim upstream Stripe implementation that was bundled into the just-slimmed @suaveplan/payment-providers package.

Requirement	Source lines	Notes
Universal-tier purity (no Node / browser / React deps)	`enterprise/payment-providers.md` L37	verbatim cross-cutting rule
Zero `Math.random` / `Date.now` at module scope; injectable seams	`enterprise/payment-providers.md` L40	satisfied via shared `ProviderCommonOptions` (fetch/timeoutMs/signal)
Structured errors extending `@suaveplan/error`	`enterprise/payment-providers.md` L42, L61	uses `PaymentProviderError` from the slim core; raises no raw `Error`
`AbortSignal` everywhere async, per-call timeout	`enterprise/payment-providers.md` L43	inherits `httpRequest` composition of caller `signal` + internal timeout
Idempotency-key wiring on mutating calls	`enterprise/payment-providers.md` L44	`createIntent` / `refund` forward `Idempotency-Key` when caller supplies it
Tree-shakeable, `sideEffects: false`	`enterprise/payment-providers.md` L55	verbatim
`workspace:^` internal deps + Bun catalog externals	`enterprise/payment-providers.md` L56	verbatim
100% Istanbul coverage + 100% docs coverage	`enterprise/payment-providers.md` L50-L51	genesis-wide policy as well
File-size budget (250 soft / 300 hard / 500 test)	`enterprise/payment-providers.md` L52	verbatim
StripeProvider full lifecycle (`createIntent` / `confirmIntent` / `captureIntent` / `cancelIntent` / `refund` / `getIntent`)	`/mnt/s/web/suaveplan/packages/universal/payment-providers/src/stripe.ts` L130-L209	verbatim port against slim foundation; previously folded as a removed requirement by `2026-05-17-slim-payment-providers` (`specs/payment-providers/spec.md` "Requirement: StripeProvider full lifecycle")
Stripe status → `PaymentStatus` mapping table	`/mnt/s/web/suaveplan/packages/universal/payment-providers/src/stripe.ts` L45-L56	verbatim 7-row mapping including `unknown → failed` fallback
Stripe refund status → `RefundStatus` mapping	`/mnt/s/web/suaveplan/packages/universal/payment-providers/src/stripe.ts` L58-L62	verbatim 3-branch mapping (`succeeded` / `pending` / `failed`)
Stripe refund reason → `RefundReason` mapping	`/mnt/s/web/suaveplan/packages/universal/payment-providers/src/stripe.ts` L104-L111	verbatim 4-branch mapping (`duplicate` / `fraudulent` / `requested_by_customer` / `other`)
Bearer auth header on every request	`/mnt/s/web/suaveplan/packages/universal/payment-providers/src/stripe.ts` L211-L217	verbatim `Authorization: Bearer <apiKey>` header
`StripeProvider.name === "stripe"`	`/mnt/s/web/suaveplan/packages/universal/payment-providers/src/stripe.ts` L119	verbatim literal name

Requirements with no source line

Requirement	Justification
`provider: "stripe"` discriminant on every raised `PaymentProviderError`	Slim-foundation `httpRequest` accepts a `provider` field on `HttpOptions`; wiring it on every call lets consumers discriminate Stripe failures from sibling-package failures without parsing messages. Not required by the upstream file but mandatory for the slim-core contract.
Injectable `fetch` / `signal` / `timeoutMs` forwarded to `httpRequest` on every call	The upstream file held its own `timeoutMs` but never forwarded the caller's external `signal` or `fetch`. Required by the slim foundation (every sibling MUST flow through `ProviderCommonOptions`); upgraded from the upstream surface in this migration.

Verification approach

Every requirement in specs/payment-provider-stripe/spec.md carries a **Verified by:** line citing concrete it(...) titles in:

src/stripe/stripe.test.ts — every PaymentProvider method, the Bearer / Idempotency-Key header forwarding, every status / refund- status / refund-reason branch, provider discriminant on raised errors, injected FetchLike + signal forwarding.
tests/dep-graph.test.ts — pins universal-tier purity (no node: / bun: / fs / path / etc imports under src/).

Tests use a real recording FetchLike closure — no vi.mock, no vi.stubGlobal. The Stripe REST API surface is exercised purely through the injected fetch.

Migration impact

None — additive only. This package is brand new under packages/universal/payment-provider-stripe/ and is not yet consumed by any other package in the monorepo. Consumers that previously imported StripeProvider from @suaveplan/payment-providers (none exist on genesis; that surface was removed by 2026-05-17-slim-payment-providers before any consumer landed) will import from the new package per the slim-core migration table.

Impact

Affected dependents

Run bunx turbo ls --filter=...@suaveplan/payment-provider-stripe to enumerate. The package is brand new with no current dependents.

Dependent	Action
(none)	[x] no action needed — new package, no consumers yet

Future dependents will be: @suaveplan/api-plugin-payment (when it lands as a Stripe-configurable host) and any application-layer package that wires the PaymentEngine to Stripe.

8.0 KiB Raw Blame History