Initial Commit
This commit is contained in:
176
openspec/changes/enterprise-payment-providers/proposal.md
Normal file
176
openspec/changes/enterprise-payment-providers/proposal.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# OpenSpec Change: enterprise-payment-providers
|
||||
|
||||
- **Change ID**: enterprise-payment-providers
|
||||
- **Package**: `@suaveplan/payment-providers`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/commerce/payment-providers`
|
||||
- **Status**: IN PROGRESS
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/payment-providers.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/payment-providers` on the genesis branch from scratch at enterprise quality. The package provides concrete `PaymentAdapter` implementations for Stripe, PayPal, Square, Mollie, and Adyen. Each adapter wraps the provider's REST API using injectable fetch (no provider SDK dependency), implements the full `PaymentAdapter` interface from `@suaveplan/payment`, handles provider-specific webhook signature verification, and normalises provider error codes to the canonical `PAYMENT.*` code registry. The main-branch version sat at 100% coverage. Genesis adds structured errors, Zod schemas, OTel instrumentation, retry with circuit breaker, and integration-test harnesses.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `PaymentProviderError`; extends `PAYMENT.*` code set |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
|
||||
| `@suaveplan/payment` (`workspace:^`) | `PaymentAdapter` interface; `PaymentIntent`, `PaymentWebhookEvent` types |
|
||||
| `@suaveplan/retry` (`workspace:^`) | Retry + circuit breaker for provider API calls |
|
||||
| `@suaveplan/crypto` (`workspace:^`) | HMAC webhook signature verification |
|
||||
| `zod` (`catalog:forms`) | Provider response schema validation |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
### Provider factories
|
||||
|
||||
```ts
|
||||
function createStripeAdapter(options: StripeAdapterOptions): PaymentAdapter
|
||||
function createPayPalAdapter(options: PayPalAdapterOptions): PaymentAdapter
|
||||
function createSquareAdapter(options: SquareAdapterOptions): PaymentAdapter
|
||||
function createMollieAdapter(options: MollieAdapterOptions): PaymentAdapter
|
||||
function createAdyenAdapter(options: AdyenAdapterOptions): PaymentAdapter
|
||||
```
|
||||
|
||||
All option types share a common base:
|
||||
|
||||
```ts
|
||||
interface BaseAdapterOptions {
|
||||
apiKey: string
|
||||
webhookSecret?: string
|
||||
environment?: 'sandbox' | 'production' // default 'production'
|
||||
retryOptions?: RetryOptions
|
||||
fetch?: typeof globalThis.fetch
|
||||
clock?: Clock
|
||||
logger?: LoggerLike
|
||||
}
|
||||
|
||||
interface StripeAdapterOptions extends BaseAdapterOptions {
|
||||
apiVersion?: string // default 'latest'
|
||||
}
|
||||
|
||||
interface PayPalAdapterOptions extends BaseAdapterOptions {
|
||||
clientId: string
|
||||
clientSecret: string
|
||||
}
|
||||
|
||||
interface AdyenAdapterOptions extends BaseAdapterOptions {
|
||||
merchantAccount: string
|
||||
liveUrlPrefix?: string
|
||||
}
|
||||
```
|
||||
|
||||
### Provider-normalised types
|
||||
|
||||
Each provider's raw response is normalised to `PaymentIntent` via a per-provider mapper; these mappers are exported for testing:
|
||||
|
||||
```ts
|
||||
function normalizeStripePaymentIntent(raw: unknown): PaymentIntent
|
||||
function normalizePayPalOrder(raw: unknown): PaymentIntent
|
||||
function normalizeSquarePayment(raw: unknown): PaymentIntent
|
||||
function normalizeMolliePayment(raw: unknown): PaymentIntent
|
||||
function normalizeAdyenPayment(raw: unknown): PaymentIntent
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
Provider errors are wrapped in `PaymentError` with existing `PAYMENT_PROVIDER_ERROR` code plus an added detail field:
|
||||
|
||||
```ts
|
||||
interface PaymentProviderErrorDetail {
|
||||
provider: string
|
||||
providerCode?: string
|
||||
providerMessage?: string
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Genesis additions
|
||||
|
||||
1. **Zod schemas** for all provider-specific option types and raw response shapes.
|
||||
2. **Sandbox/production switching** — `environment: 'sandbox'` routes to provider test endpoints automatically.
|
||||
3. **Idempotency key passthrough** — all create/capture/refund calls forward the caller-supplied idempotency key as the provider-specific header (`Idempotency-Key` for Stripe, etc.).
|
||||
4. **Circuit breaker** — wraps all provider API calls via `@suaveplan/retry`; opens after 5 consecutive provider errors.
|
||||
5. **OTel instrumentation** — span `payment_provider.api_call` with attributes `payment_provider.name`, `payment_provider.method`; counter `payment_provider.api_total`; histogram `payment_provider.api_duration_ms`.
|
||||
6. **Provider error normalisation** — 4xx/5xx provider responses are mapped to the closest `PAYMENT.*` error code with provider details preserved in the error context.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/commerce/payment-providers/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
providers/
|
||||
stripe/
|
||||
stripe.ts
|
||||
stripe.md
|
||||
stripe.types.ts
|
||||
stripe.test.ts
|
||||
index.ts
|
||||
paypal/
|
||||
paypal.ts
|
||||
paypal.md
|
||||
paypal.types.ts
|
||||
paypal.test.ts
|
||||
index.ts
|
||||
square/
|
||||
square.ts
|
||||
square.md
|
||||
square.types.ts
|
||||
square.test.ts
|
||||
index.ts
|
||||
mollie/
|
||||
mollie.ts
|
||||
mollie.md
|
||||
mollie.types.ts
|
||||
mollie.test.ts
|
||||
index.ts
|
||||
adyen/
|
||||
adyen.ts
|
||||
adyen.md
|
||||
adyen.types.ts
|
||||
adyen.test.ts
|
||||
index.ts
|
||||
__benchmarks__/
|
||||
payment-providers.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream consumers**: `@suaveplan/booking`, any server-side checkout flow.
|
||||
|
||||
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/payment`, `@suaveplan/retry`, `@suaveplan/crypto`.
|
||||
72
openspec/changes/enterprise-payment-providers/tasks.md
Normal file
72
openspec/changes/enterprise-payment-providers/tasks.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Tasks: enterprise-payment-providers
|
||||
|
||||
**Change ID**: enterprise-payment-providers
|
||||
**Package**: `@suaveplan/payment-providers`
|
||||
**Target path**: `universal/commerce/payment-providers`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/payment`, `@suaveplan/retry`, `@suaveplan/crypto`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create `universal/commerce/payment-providers/` with `src/`, `tests/`, `src/__benchmarks__/` and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, correct `exports` map, `dependencies`, and `devDependencies`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [ ] `src/types/common.ts` — `BaseAdapterOptions`, `StripeAdapterOptions`, `PayPalAdapterOptions`, `SquareAdapterOptions`, `MollieAdapterOptions`, `AdyenAdapterOptions`, `PaymentProviderErrorDetail`.
|
||||
- [ ] `src/types/common.md` (≥200 words, both examples, API reference).
|
||||
- [ ] `src/error-codes.ts` — no new error codes beyond `@suaveplan/payment`; re-export `PaymentError` and add `PaymentProviderErrorDetail` context injection helpers. Register docs call.
|
||||
- [ ] `src/types/schemas.ts` + `schemas.md` — Zod schemas for all option types and raw response shapes.
|
||||
|
||||
---
|
||||
|
||||
## 3. Provider adapters (one sub-task per provider)
|
||||
|
||||
For each of `stripe`, `paypal`, `square`, `mollie`, `adyen`:
|
||||
|
||||
- [ ] Implement `create{Provider}Adapter(options: {Provider}AdapterOptions): PaymentAdapter`.
|
||||
- `create`: POST to provider create endpoint; include caller idempotency key as provider-specific header.
|
||||
- `authorise`: POST to provider confirm/capture endpoint.
|
||||
- `capture`: POST to provider capture endpoint.
|
||||
- `refund`: POST to provider refund endpoint.
|
||||
- `cancel`: POST to provider cancel/void endpoint.
|
||||
- `verifyWebhook`: provider-specific HMAC or RSA verification via `@suaveplan/crypto`.
|
||||
- `normalizeWebhook(body)`: parse provider events to `PaymentWebhookEvent[]`.
|
||||
- Wrap all API calls with `@suaveplan/retry` (3 retries, exponential backoff); circuit breaker opens after 5 failures.
|
||||
- Environment switching: sandbox URLs when `options.environment === 'sandbox'`.
|
||||
- [ ] Export `normalize{Provider}{Entity}` mapper functions (e.g. `normalizeStripePaymentIntent`).
|
||||
- [ ] Write unit tests per provider: `create` success, `create` 4xx maps to `PAYMENT_PROVIDER_ERROR`, `verifyWebhook` valid/invalid, `normalizeWebhook` sample payload.
|
||||
|
||||
---
|
||||
|
||||
## 4. OTel instrumentation
|
||||
|
||||
- [ ] Span `payment_provider.api_call` with attributes `payment_provider.name`, `payment_provider.method`; counter `payment_provider.api_total`; histogram `payment_provider.api_duration_ms`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Benchmarks (`src/__benchmarks__/payment-providers.bench.ts`)
|
||||
|
||||
- [ ] `normalizeStripePaymentIntent` 100 000 times.
|
||||
|
||||
---
|
||||
|
||||
## 6. Docs + verify
|
||||
|
||||
- [ ] One `.md` per implementation file (≥200 words, both examples, API reference). Root `README.md`.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/payment-providers` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/payment-providers` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/payment-providers`.
|
||||
- [ ] Archive: `openspec/archive/2026-04-24-enterprise-payment-providers/`.
|
||||
Reference in New Issue
Block a user