suaveplan/openspec/archive/2026-05-19-add-api-plugin-payment/tasks.md

Tasks — add-api-plugin-payment

1. Scaffold

• 1.1 Create packages/api/api-plugin-payment/ with src/{plugin,middleware,error-codes,otel,routes,services,schemas/{routes},store,types,webhook,idempotency}/ + tests/{setup,integration}/
• 1.2 package.json v0.1.0. Deps: @suaveplan/api-plugin @suaveplan/api-openapi @suaveplan/api-plugin-auth @suaveplan/payment @suaveplan/idempotency @suaveplan/money @suaveplan/error @suaveplan/types @suaveplan/events tslib, hono @hono/zod-openapi (catalog:server), zod (catalog:forms), @opentelemetry/api
• 1.3 14 subpath exports per the proposal
• 1.4 tsconfigs + vite + vitest (100/100/100/100; testTimeout 60000)
• 1.5 tests/setup/polyfills.ts — install in-memory MeterProvider

2. Implementation

• 2.1 src/error-codes/error-codes.{ts,test.ts,md,index.ts} — 15 PAYMENT_PLUGIN.* codes + PaymentPluginError class with statusCode discriminant
• 2.2 src/types/types.{ts,md,index.ts} — PaymentPluginOptions, PaymentPluginConfig
• 2.3 src/otel/instruments.{ts,test.ts,md,index.ts} — 5 counters + 1 histogram
• 2.4 src/store/payment-intent-store.{ts,md,index.ts} — PaymentIntentStore interface + OwnedIntent type
• 2.5 src/store/memory-store.{ts,test.ts,md} — MemoryPaymentIntentStore default impl
• 2.6 src/schemas/money.{ts,test.ts,md,index.ts} — MoneySchema (bigint via z.coerce + currency)
• 2.7 src/schemas/options.{ts,test.ts,md} — PaymentPluginOptionsSchema
• 2.8 src/schemas/routes/<name>.{ts,md} per route (create-intent, list-intents, get-intent, confirm-intent, capture-intent, cancel-intent, refund, webhook) + schemas/routes/routes.test.ts + schemas/routes/index.ts
• 2.9 src/services/payment-service.{ts,test.ts,md,index.ts} — createPaymentService({provider, store, clock}) + PaymentService interface; owner-scoped CRUD + 404 anti-enumeration
• 2.10 src/services/registry-augmentation.{ts,md} — augments ServiceRegistry with paymentService + host slots
• 2.11 src/middleware/idempotency-middleware.{ts,test.ts,md,index.ts} — Idempotency-Key middleware backed by IdempotencyGuard
• 2.12 src/webhook/verify-webhook.{ts,test.ts,md,index.ts} — HMAC verify wrapper around @suaveplan/payment's WebhookVerifier; reads raw body, dispatches via EventBus or directly
• 2.13 src/routes/build-routes.{ts,test.ts,md,index.ts} — buildPaymentRoutes({service, idempotencyMiddleware}) returning PluginRouteEntry[] for the 6 owner-scoped routes
• 2.14 src/plugin/plugin.{ts,test.ts,md,index.ts} — createPaymentPlugin(options) + 6-step onInit
• 2.15 src/index.ts — named re-exports only

3. Tests

• 3.1 Co-located *.test.ts per impl module
• 3.2 src/api-plugin-payment.spec-conformance.test.ts — every PAYMENT_PLUGIN.* code thrown; expectTypeOf on PaymentService, PaymentIntentStore, ServiceRegistry augmentation
• 3.3 tests/integration/full-lifecycle.test.ts — real api + this plugin + auth plugin + FakePaymentProvider implements PaymentProvider; createIntent → confirm → capture → refund → getIntent + cross-user isolation
• 3.4 tests/integration/idempotency.test.ts — same Idempotency-Key returns same intent (no duplicate)
• 3.5 tests/integration/webhook.test.ts — valid HMAC accepted; invalid rejected (signature failure counter increments)
• 3.6 tests/integration/error-paths.test.ts — currency mismatch + amount mismatch + foreign intent 404 anti-enumeration
• 3.7 All tests via @suaveplan/testing/runner; { timeout: 5000 } (60000 for integration)

4. Documentation

• 4.1 Sibling .md per impl (≥200 words)
• 4.2 README.md — quick-start defineApp().use(createAuthPlugin(...)).use(createPaymentPlugin({ provider, webhookSecret })); the 3-way plug-and-play contract; Idempotency-Key recipe; webhook HMAC configuration; provider injection examples

5. Gates

• 5.1 cd /home/paul/web/genesis && bun run check
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-payment --force
• 5.3 bunx turbo test:coverage --filter=@suaveplan/api-plugin-payment → 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/api-plugin-payment → exit 0
• 5.5 bunx turbo build --filter=@suaveplan/api-plugin-payment --force
• 5.6 bun scripts/lint/check-test-runner-imports.ts
• 5.7 Pre-archive 9-row checklist — banned-pattern grep + no export * + no direct vitest/bun:test imports + README + subpath count + bare-version check + missing .md scan

6. Archive

• 6.1 Fold spec → openspec/specs/api-plugin-payment/spec.md
• 6.2 mv change → openspec/archive/2026-05-19-add-api-plugin-payment/
• 6.3 DO NOT refresh MANIFEST or STATUS (orchestrator consolidates)