Initial Commit

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

@@ -0,0 +1,179 @@
+# 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 |