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

Add @suaveplan/api-plugin-payment — Hono plugin wrapping @suaveplan/payment + provider siblings

Package: @suaveplan/api-plugin-payment (NEW, server-tier) Status: PROPOSED Type: new-package Position: builds on @suaveplan/api, @suaveplan/api-plugin, @suaveplan/api-openapi, @suaveplan/api-plugin-auth, @suaveplan/payment, optional @suaveplan/idempotency.

• Spec delta: ./specs/api-plugin-payment/spec.md

Why

Genesis ships @suaveplan/payment (universal-tier PaymentProvider interface, PaymentEngine, WebhookVerifier, Refund, full lifecycle) and four concrete provider siblings (@suaveplan/payment-provider-{stripe,adyen,paypal,square,mollie}). What's missing is an HTTP layer that mounts the lifecycle as Zod-typed OpenAPI routes on top of @suaveplan/api, gates them behind requireAuth() from @suaveplan/api-plugin-auth, scopes intents per-user (anti-enumeration), enforces Idempotency-Key on mutation routes, verifies provider-specific webhook HMAC before deserializing payloads, and registers a typed paymentService slot every downstream consumer reads.

This package fills that gap as a definePlugin consumer. It is the canonical payment exemplar of the 3-way plug-and-play contract (Zod schemas at boundary + OpenAPI route registration + service-registry slot) every @suaveplan/api-plugin-* package follows. The plugin is provider-agnostic — the operator constructs the PaymentProvider (Stripe, Adyen, PayPal, Square, Mollie, or a custom impl) and injects it at factory time. No default provider is chosen by the plugin.

What changes

Net-new package at 0.1.0. ADDED:

Plugin factory + descriptor surface

• createPaymentPlugin(options: PaymentPluginOptions): PluginDescriptor<PaymentPluginConfig> — Zod-validated factory returning a PluginDescriptor from @suaveplan/api-plugin. The descriptor implements the canonical 6-step onInit:
  1. Resolve app + openAPIRegistry from ServiceRegistry.
  2. Resolve the caller-supplied PaymentProvider from options.provider (no default — caller injects).
  3. Construct a PaymentService wrapping provider + the PaymentIntentStore (in-memory default) so ownership scoping flows through every route.
  4. Register paymentService in the host ServiceRegistry (typed slot) exposing the full lifecycle.
  5. Register 6 OpenAPI routes via definePluginRoutes (mounted at routePrefix, default /payments) + 1 webhook receiver (POST /payments/webhook) mounted as a separate sub-router because webhook verification reads the raw request body BEFORE Zod parsing.
  6. Log readiness via ctx.logger.info.
• PaymentPluginOptions (validated via PaymentPluginOptionsSchema): { provider: PaymentProvider; routePrefix?: string (default "/payments"); store?: PaymentIntentStore; webhookSecret: string; webhookToleranceMs?: number (default 300_000); webhookAlgorithm?: WebhookAlgorithm (default "SHA-256"); idempotencyStore?: IdempotencyStore; logger?: LoggerLike; clock?: Clock }.

PaymentService (typed ServiceRegistry slot)

• createPaymentService({ provider, store, clock }) returns PaymentService exposing the full lifecycle: createIntent, confirmIntent, captureIntent, cancelIntent, refund, getIntent, listIntents. Every method is owner-scoped — it accepts a Principal.id (and optional tenantId) and rejects access to foreign intents with a 404 (anti-enumeration). The service owns the PaymentIntentStore write-side so provider-side IDs map back to owner ids.

PaymentIntentStore

• PaymentIntentStore interface — record-side persistence mapping a provider-issued PaymentIntent.id back to its ownerId + optional tenantId. MemoryPaymentIntentStore is the in-process default; operators inject any other impl that satisfies the contract (SurrealDB, Postgres, Redis).

Routes (Zod-typed OpenAPI surface)

All mutation routes are requireAuth()-gated and scope to c.get("user").id:

• POST /payments/intents — body: CreatePaymentIntentBody (Money via MoneySchema); response: PaymentIntentResponse. Honours Idempotency-Key header.
• GET /payments/intents — query: ListPaymentIntentsQuery (limit/cursor/status filter); response: PaymentIntentListResponse (only intents owned by the requester).
• GET /payments/intents/{id} — params: PaymentIntentIdParam; response: PaymentIntentResponse. Foreign intent → 404 anti-enumeration.
• POST /payments/intents/{id}/confirm — empty body; response: PaymentIntentResponse.
• POST /payments/intents/{id}/capture — body: CaptureBody (optional partial amount); response: PaymentIntentResponse.
• POST /payments/intents/{id}/cancel — empty body; response: PaymentIntentResponse.
• POST /payments/intents/{id}/refund — body: RefundBody; response: RefundResponse. Honours Idempotency-Key header.

Plus the unauthenticated webhook receiver:

• POST /payments/webhook — verifies the provider-specific HMAC (X-Signature / X-Timestamp) against options.webhookSecret BEFORE deserialising the body, replays through EventBus when api-plugin-events is mounted, otherwise applies updates via the paymentService directly.

Zod schemas (boundary validation) — exposed at ./schemas/*

• ./schemas/money — MoneySchema ({ amount: z.coerce.bigint(), currency: z.string().min(3).max(8) }).
• ./schemas/options — PaymentPluginOptionsSchema.
• ./schemas/routes — request/response per route (CreatePaymentIntentBodySchema, CaptureBodySchema, RefundBodySchema, PaymentIntentIdParamSchema, ListPaymentIntentsQuerySchema, PaymentIntentResponseSchema, RefundResponseSchema, PaymentIntentListResponseSchema, WebhookResponseSchema).

Errors + observability

• PaymentPluginError extends SuaveplanError<PaymentPluginErrorCode> via defineCodes("PAYMENT_PLUGIN", [...]). 12 codes: INVALID_INPUT, NOT_FOUND, FORBIDDEN, PROVIDER_ERROR, WEBHOOK_SIGNATURE_INVALID, WEBHOOK_TIMESTAMP_INVALID, IDEMPOTENCY_CONFLICT, INVALID_STATE, AMOUNT_MISMATCH, CURRENCY_MISMATCH, REFUND_EXCEEDS_CAPTURED, PROVIDER_NOT_CONFIGURED, INTENT_CREATION_FAILED, SERVICE_NOT_AVAILABLE, ROUTE_PREFIX_COLLISION.
• OpenTelemetry: 5 counters and 1 histogram —
  • payments.intents_created_total{outcome,provider}
  • payments.captures_total{outcome,provider}
  • payments.refunds_total{outcome,provider}
  • payments.webhook_received_total{outcome,provider}
  • payments.webhook_signature_failures_total{provider}
  • payments.intent_duration_ms{provider} (histogram)

Subpath exports

., ./plugin/plugin, ./middleware/idempotency-middleware, ./services/payment-service, ./store/memory-store, ./store/payment-intent-store, ./webhook/verify-webhook, ./schemas/money, ./schemas/options, ./schemas/routes, ./routes/build-routes, ./otel/instruments, ./error-codes/error-codes, ./types/types.

Out of scope

• Front-end UI (checkout form, 3-D Secure challenge UI, dispute evidence upload). Backend only.
• Per-tenant provider routing (multi-provider ProviderRouter) — single injected provider for now; multi-provider routing is a follow-up api-plugin-payment-router.
• Saved payment methods / SetupIntents — covered by a follow-up api-plugin-payment-methods.
• Subscription billing — covered by api-plugin-subscription.
• Dispute workflow endpoints — covered by a follow-up api-plugin-payment-disputes.
• Reconciliation export endpoints — covered by api-plugin-export + @suaveplan/payment's PaymentReconciliation directly.

Source mapping

This package is genesis-original with design intent drawn from:

• The genesis @suaveplan/api-plugin PluginContext + ServiceRegistry.
• The genesis @suaveplan/api-openapi definePluginRoutes + RouteBuilder.
• The genesis @suaveplan/api-plugin-auth plug-and-play exemplar (3-step lifecycle + ContextVariableMap augmentation).
• The legacy enterprise/api-plugin-payment.md enterprise plan (canonical source) — section 1 (Purpose), section 3 (Required improvements), section 4 (Feature-rich enhancements 1, 9).
• @suaveplan/payment — PaymentProvider interface, PaymentIntent, Refund, VALID_TRANSITIONS, WebhookVerifier.
• @suaveplan/idempotency — IdempotencyGuard, MemoryIdempotencyStore for the Idempotency-Key middleware.

Requirement	Source
definePlugin consumer shape	@suaveplan/api-plugin
requireAuth() gating, c.get("user") typed Principal	@suaveplan/api-plugin-auth
definePluginRoutes route registration	@suaveplan/api-openapi
PaymentProvider interface, PaymentIntent, Refund	@suaveplan/payment/types/payment
Webhook HMAC verification + timestamp replay protection	@suaveplan/payment/webhook/webhook
Idempotency-Key middleware	@suaveplan/idempotency
Owner-scoped lookups + 404 anti-enumeration	legacy enterprise/api-plugin-payment.md §1 + §3 ("PCI posture") + genesis principle
12 PAYMENT_PLUGIN_* codes	legacy enterprise/api-plugin-payment.md §3 ("Typed errors")
5 counters + 1 histogram	legacy enterprise/api-plugin-payment.md §3 ("Observability")
3-way plug-and-play	genesis architectural principle (verbatim from add-api-plugin-auth)

Impact

Affected dependents

Run bunx turbo ls --filter=...@suaveplan/api-plugin-payment to enumerate. Net-new package; no dependents today.

• No dependents (verified pre-shipment — net-new package; future consumers will be api-plugin-payment-router / api-plugin-payment-methods / api-plugin-payment-disputes).

Catalog additions required

None — hono, @hono/zod-openapi, zod, tslib, @opentelemetry/api, @vitest/coverage-istanbul, vite, vite-plugin-dts, vitest, fast-check are all already pinned in the root catalog.