OpenSpec Change: enterprise-api-plugin-payment

Change ID: enterprise-api-plugin-payment
Package: @suaveplan/api-plugin-payment
Category: api/commerce
Target path: api/commerce/api-plugin-payment
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/api-plugin-payment.md

Summary

Deliver @suaveplan/api-plugin-payment on the genesis branch from scratch at enterprise quality. HTTP surface over @suaveplan/payment: mounts /payments (intent lifecycle + refunds + list) and /webhooks/payment (HMAC-verified ingestion). Wraps a caller-supplied PaymentProvider in a PaymentEngine. Per-table SurrealQL migrations. Typed event bus — no as any casts. Full onTenantCreate/onTenantDelete lifecycle. Idempotency on mutations, rate limiting, and audit logging on all write paths. PCI-DSS SAQ-A posture documented.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Response helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`
`@suaveplan/api-plugin-database` (`workspace:^`)	SurrealDB
`@suaveplan/payment` (`workspace:^`)	`PaymentEngine`, `PaymentProvider`
`@suaveplan/events` (`workspace:^`)	Typed event bus
`@suaveplan/error` (`workspace:^`)	Typed errors
`@suaveplan/idempotency` (`workspace:^`)	Mutation guard
`@suaveplan/audit-logging` (`workspace:^`)	Write-path audit
`@suaveplan/rate-limiter` (`workspace:^`)	Rate limiting
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createPaymentPlugin(provider: PaymentProvider, config?: PaymentPluginConfig): PluginDescriptor<PaymentPluginConfig>
class PaymentService { createIntent, confirm, capture, cancel, refund, list }

// Schemas
CreatePaymentIntentSchema, MoneySchema, PaymentIntentIdParamSchema
PaymentIntentResponseSchema, PaymentListQuerySchema, RefundRequestSchema, RefundResponseSchema

// Types
PaymentPluginConfig, PaymentDomainEventMap, SerializedIntent, SerializedRefund

Error codes

type PaymentErrorCode =
  | "PAYMENT_INTENT_NOT_FOUND"
  | "PAYMENT_ALREADY_CAPTURED"
  | "PAYMENT_REFUND_EXCEEDS"
  | "PAYMENT_WEBHOOK_SIGNATURE"
  | "PAYMENT_WEBHOOK_STALE"
  | "PAYMENT_PROVIDER_ERROR"

Genesis additions vs main-branch

PaymentBusEventMap declared via src/events.ts module augmentation — replaces all (ctx.eventBus as any)?.emit?.() calls.
Per-table SurrealQL — intent.surql, refund.surql, webhook_event.surql.
Real onTenantCreate/onTenantDelete — SurrealDB namespacing + provider configuration.
onClose detaches all engine listeners registered in onInit.
onInit reads ctx.getPluginConfig for webhookSecret / webhookToleranceMs overrides.
Idempotency on POST /payments and POST /payments/:id/refund.
Rate limiting on create-intent and refund.
Audit logging on every state-changing operation and accepted webhook.

File layout

api/commerce/api-plugin-payment/
  package.json  tsconfig.json  vitest.config.ts
  surql/intent.surql  surql/refund.surql  surql/webhook_event.surql
  src/
    index.ts  events.ts
    types/  errors/
    services/payment/
    schemas/
    routes/payment/  routes/webhook/  routes/problem-json.ts
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/payment, @suaveplan/events, @suaveplan/idempotency, @suaveplan/audit-logging, @suaveplan/rate-limiter, @suaveplan/error.

3.7 KiB Raw Permalink Blame History