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

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