suaveplan/openspec/archive/2026-05-17-add-payment-providers/proposal.md

Add @suaveplan/payment-providers — universal-tier provider plugins (Stripe / PayPal / Square / Mollie / Adyen)

Package: @suaveplan/payment-providers Status: PROPOSED Type: migration (upstream ../suaveplan/packages/universal/payment-providers)

• Spec delta: ./specs/payment-providers/spec.md

Why

STATUS.md line 133 lists @suaveplan/payment-providers as Pending. The upstream package supplies the five reference adapters that implement the @suaveplan/payment PaymentProvider interface — Stripe, PayPal, Square, Mollie, and Adyen. With @suaveplan/payment shipped in the same wave, every commerce-tier downstream (@suaveplan/api-plugin-payment, @suaveplan/booking, @suaveplan/api-plugin-banking) needs at least one of these adapters to deliver an end-to-end payment lifecycle.

The migration preserves the entire upstream public surface verbatim (StripeProvider, PayPalProvider, SquareProvider, MollieProvider, AdyenProvider, httpRequest, ApiKeyConfig, OAuthConfig, MerchantKeyConfig, ProviderResponse, HttpOptions) while upgrading five foundational concerns to the genesis quality bar:

1. Injectable FetchLike — every provider accepts an optional fetch config field defaulting to globalThis.fetch. Tests use a real recording FetchLike rather than vi.spyOn(globalThis, "fetch"), so the no-mocks rule (CLAUDE.md §2) is preserved without losing coverage.
2. Injectable now / randomId — PayPalProvider's token-cache clock and SquareProvider / AdyenProvider's default idempotency-key generator are config fields. This removes module-scope Date.now() and crypto.randomUUID(), aligning with the deterministic universal-tier rule.
3. Injectable base64Encode — PayPal's OAuth Basic header uses btoa by default but accepts an injected encoder so the package runs on every runtime that names Base-64 differently.
4. Typed PaymentProviderError extending SuaveplanError<PaymentProviderErrorCode> replaces the upstream throw new Error(...) raised inside httpRequest. The PAYMENT_PROVIDER_CODES registry is declared via defineCodes("PAYMENT_PROVIDER", [...]) (4 codes: HTTP_ERROR, TIMEOUT, PARSE_ERROR, OAUTH_TOKEN_FAILURE) and every former Error boundary upgrades to a typed factory carrying the HTTP status, response body excerpt, and provider name as discriminants.
5. Folder layout — the upstream flat src/{stripe,paypal,...}.ts becomes src/providers/{stripe,paypal,square,mollie,adyen}/<name>.ts per genesis convention (one feature module per folder, sibling .md, tests, types, barrel). The folder-naming rule §10 is respected by naming children only with the provider name (no -provider suffix). httpRequest moves to src/http/http.ts and its config types to src/types/provider.ts so consumers can tree-shake.

The 8 upstream source files expand to 15 (5 provider impls × {<name>.ts, <name>.md, <name>.test.ts, index.ts} per folder + flat http/, types/, error-codes/ modules). One sibling .md per implementation file lands at genesis quality (≥200 words, basic + advanced examples, full API reference).

What changes

• ADDED: StripeProvider — Stripe REST API adapter, Bearer auth, manual
  • automatic capture, idempotency keys, status + refund-reason mapping.
• ADDED: PayPalProvider — PayPal Orders v2 adapter, OAuth2 client- credentials flow with token cache, injectable now for cache TTL, injectable base64Encode for the Basic auth header.
• ADDED: SquareProvider — Square Payments adapter, Bearer auth, manual + automatic capture, Square-Version header, injectable randomId for default idempotency keys.
• ADDED: MollieProvider — Mollie Payments v2 adapter, Bearer auth, string-based amount marshalling ("50.00"), redirect URL handling.
• ADDED: AdyenProvider — Adyen Checkout v71 adapter, X-API-Key header, merchant-account context, injectable randomId.
• ADDED: httpRequest — universal FetchLike wrapper with timeout via AbortSignal, JSON serialisation, typed errors.
• ADDED: PAYMENT_PROVIDER_CODES registry via defineCodes("PAYMENT_PROVIDER", [...]) — 4 codes (HTTP_ERROR, TIMEOUT, PARSE_ERROR, OAUTH_TOKEN_FAILURE).
• ADDED: PaymentProviderError extends SuaveplanError<PaymentProviderErrorCode> carrying optional provider, httpStatus, bodyExcerpt, and url discriminants; factories httpError, timeoutError, parseError, oauthTokenFailure.
• ADDED: FetchLike type alias re-exported from @suaveplan/payment-providers/http/http.
• ADDED: Subpath exports per public module — 9 entries covering every feature; tree-shakeable.

Out of scope

• @suaveplan/idempotency integration. Providers accept idempotencyKey and forward it to the provider; auto-enforcement via the @suaveplan/idempotency middleware is a follow-up change once that package lands.
• OTel spans / counters. The enterprise audit calls for per-provider observability; the genesis @suaveplan/payment migration also deferred this. Wiring spans here without spans in the engine creates asymmetry. Defer until both packages land OTel together.
• Webhook signature verification. Each provider supports webhook signing (Stripe HMAC, Adyen HMAC, PayPal cert chain, etc.). The upstream package accepts webhookSecret / webhookHmacKey config fields but does NOT implement verification — that lives in @suaveplan/payment's WebhookVerifier. The config fields are preserved as opaque pass-throughs so future verifier integration has the secret material it needs.
• Schema-registry integration. The PaymentProvider interface is validated at the type level; runtime Zod schemas around provider inputs / outputs are a @suaveplan/payment concern.
• Adyen notification HMAC. The webhookHmacKey config field is preserved verbatim from upstream but the matching HMAC verifier ships with @suaveplan/payment's WebhookVerifier, not here.

Source mapping

This change derives from ../suaveplan/enterprise/payment-providers.md.

Requirement	Source lines	Notes
Universal-tier purity (no Node / browser / React)	L37	verbatim
Structured errors extending @suaveplan/error	L42, L61	verbatim
100% test coverage / Istanbul	L50	verbatim
100% docs coverage with sibling .md per symbol	L51	verbatim
File-size budget 250 soft / 300 hard / 500 test	L52	verbatim
No mocks — real services / injectable seams	L53	verbatim
No re-exports of external deps	L54	verbatim
sideEffects: false + tree-shake friendly	L55	verbatim
workspace:^ internal / catalog external deps	L56	verbatim
Biome clean	L58	verbatim
TypeScript strict; no any / ts-ignore	L59	verbatim
Five providers implementing PaymentProvider (Stripe, PayPal, Square, Mollie, Adyen)	L10-L13 (Purpose), upstream src/index.ts L1-L7	verbatim — preserve full public surface
Cancellation via AbortSignal	L44	verbatim
Deterministic clock / RNG	L41	enhancement above upstream — providers gain injectable now / randomId / base64Encode

Requirements with no source line

Requirement	Justification
Injectable FetchLike per provider	Required to satisfy CLAUDE.md rule 2 ("NEVER use mocks") while preserving 100% coverage. Upstream tests vi.spyOn(globalThis, "fetch"); genesis cannot.
Folder-per-provider with sibling .md	Required by CLAUDE.md "Package Structure (library packages)" — five files per feature module. Upstream uses a flat src/<provider>.ts layout.
PAYMENT_PROVIDER_CODES registry (4 codes)	Required by CLAUDE.md rule 8 + enterprise §3 "Structured errors". Upstream httpRequest throws raw Error; genesis upgrades to typed.
Subpath exports per provider	Required by openspec/AGENTS.md §6 — every feature module owns an exports entry for tree-shaking.

Verification approach

Every requirement in the spec delta is verified by tests in the package's src/<feature>/<feature>.test.ts files plus a cross-cutting tier-purity grep test in tests/dep-graph.test.ts. Each provider's test file uses a real FetchLike (recording adapter) — never vi.spyOn / vi.mock — and walks every method (createIntent, confirmIntent, captureIntent, cancelIntent, refund, getIntent) plus the full status-mapping matrix.

• src/http/http.test.ts — covers httpRequest, timeout, error wrapping, typed PaymentProviderError
• src/error-codes/error-codes.test.ts — every code reachable, cause propagation, discriminants
• src/providers/stripe/stripe.test.ts — StripeProvider full surface + status / refund-reason mapping
• src/providers/paypal/paypal.test.ts — PayPalProvider full surface + OAuth token cache + refresh
• src/providers/square/square.test.ts — SquareProvider full surface + randomId injection
• src/providers/mollie/mollie.test.ts — MollieProvider full surface + amount marshalling
• src/providers/adyen/adyen.test.ts — AdyenProvider full surface + merchant-account context
• tests/dep-graph.test.ts — universal-tier purity grep (no node:* / bun:* / fs / path imports)

Migration impact

None — additive only. No genesis consumer imports @suaveplan/payment-providers yet. Future commerce-tier consumers (@suaveplan/api-plugin-payment, @suaveplan/booking) will import these providers by their public class names — every upstream export is preserved.

Impact

Affected dependents

Run bunx turbo ls --filter=...@suaveplan/payment-providers to enumerate. No dependents on the genesis tree yet (only @suaveplan/payment is published; downstream consumers are still pending). The change is additive.

• No dependents (verified by bunx turbo ls --filter=...@suaveplan/payment-providers — empty result).

Parity Checklist

Capability	Upstream	Migrated	Notes
StripeProvider (createIntent, confirmIntent, captureIntent, cancelIntent, refund, getIntent)	yes	yes	full surface preserved
PayPalProvider + OAuth token cache	yes	yes	now injectable now() for TTL + base64Encode for Basic header
SquareProvider	yes	yes	now injectable randomId for default idempotency keys
MollieProvider	yes	yes	full surface preserved
AdyenProvider + merchant-account context	yes	yes	now injectable randomId
httpRequest helper	yes	yes	now raises typed PaymentProviderError instead of raw Error; accepts injectable FetchLike
ApiKeyConfig / OAuthConfig / MerchantKeyConfig / ProviderResponse / HttpOptions types	yes	yes	full surface preserved + added fetch, now, randomId, base64Encode optional fields
vi.spyOn(globalThis, "fetch") in tests	yes	replaced	uses real FetchLike recorder per CLAUDE.md rule 2
Webhook HMAC verifier	scoped out	scoped out	upstream defers to @suaveplan/payment WebhookVerifier; genesis preserves the config fields verbatim
OTel spans / counters	absent	absent	deferred per ## Out of scope to align with @suaveplan/payment
@suaveplan/idempotency middleware	absent	absent	deferred — pass-through preserved