Initial Commit

openspec/changes/enterprise-payment-providers/tasks.md

@@ -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/`.