suaveplan/openspec/archive/2026-05-17-add-payment-provider-paypal/tasks.md

Tasks — add-payment-provider-paypal

Every checkbox MUST reflect work actually done in this change. No retroactive ticking.

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/payment-providers.md end-to-end
• 1.2 Read the slim-core spec and code (packages/universal/payment-providers/src/) plus the slim archive (openspec/archive/2026-05-17-slim-payment-providers/)
• 1.3 Read openspec/AGENTS.md Sections 13 and 14 (and §7 test-runner rule)
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Fill ## Source mapping table — every requirement cites a line range OR appears in the "no source line" table with justification
• 1.6 Draft specs/payment-provider-paypal/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement carries a **Verified by:** line naming concrete it(...) titles

2. Implementation

• 2.1 Scaffold packages/universal/payment-provider-paypal/ (package.json, tsconfig.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md, tests/setup/polyfills.ts, tests/dep-graph.test.ts)
• 2.2 Implement src/paypal/paypal.types.ts — PayPalConfig (extends OAuthConfig + sandbox?: boolean), PayPalOrder, PayPalRefund, PayPalTokenResponse wire shapes
• 2.3 Implement src/paypal/paypal.ts — PayPalProvider class with constructor, token cache, all 6 PaymentProvider methods, status mapping helpers, amount marshalling, idempotency-header wiring
• 2.4 Wire src/paypal/index.ts (named exports) and src/index.ts package barrel (named exports)
• 2.5 Add subpath exports in package.json (., ./paypal/paypal, ./package.json)

3. Tests

• 3.1 src/paypal/paypal.test.ts — every scenario in the spec delta exercised via a FetchLike recorder closure (no globalThis.fetch patching); FakeClock for token-expiry assertions; all it(...) carry { timeout: 5000 }
• 3.2 tests/dep-graph.test.ts — pins dependency invariants (only payment, payment-providers, error, tslib; no Node/browser/React imports)
• 3.3 Every test file imports runner primitives from @suaveplan/testing/runner (§7 / CLAUDE.md rule 11)
• 3.4 Coverage at 100/100/100/100

4. Documentation

• 4.1 src/paypal/paypal.md — Purpose / Features / Basic + Advanced Usage / API Reference / Implementation Notes (≥200 words)
• 4.2 README.md — install / quick-start / Modules links / migration
• 4.3 No CLAUDE.md entry required (per CLAUDE.md doc-policy note — sibling-plugin packages are documented through MANIFEST.md / STATUS.md / SUMMARY.md and the per-package .md files)

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome 0/0/0 across the monorepo
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/payment-provider-paypal — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/payment-provider-paypal — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/payment-provider-paypal — exit 0, no error findings
• 5.5 bunx turbo build --filter=@suaveplan/payment-provider-paypal — green

6. Pre-archive 7-row checklist (AGENTS.md §13)

• 6.1 Generics threaded (PayPalProvider.name is the literal "paypal"; httpRequest<T> generics threaded through every call site)
• 6.2 Zod schemas wired at every declared boundary — N/A (this adapter consumes the slim core's typed httpRequest and the @suaveplan/payment interface; no public Zod boundary beyond the structural OAuthConfig extension)
• 6.3 Every error code reachable: OAUTH_TOKEN_FAILURE raised by token-fetch failure path; HTTP_ERROR / TIMEOUT / PARSE_ERROR reachable transitively via httpRequest; tested in both directions
• 6.4 Strict-mode behaviors — sandbox flag both on and off; token cache hit AND refresh; refund with AND without amount/idempotency; createIntent with AND without idempotency
• 6.5 OTel instruments — N/A; deferred per the slim core's matching deferral until @suaveplan/payment lands an observability surface
• 6.6 Lifecycle dedup — token cache reuse asserted (single token call across two intents); refresh-after-expiry asserted
• 6.7 No retroactive tick — every box above corresponds to work done in this change

7. Archive

• 7.1 Fold spec delta into openspec/specs/payment-provider-paypal/spec.md
• 7.2 Move openspec/changes/add-payment-provider-paypal/ → openspec/archive/2026-05-17-add-payment-provider-paypal/
• 7.3 Refresh MANIFEST.md, MISSING.yml, STATUS.md, SUMMARY.md