OpenSpec Change: enterprise-api-plugin-store

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

Summary

Deliver @suaveplan/api-plugin-store on the genesis branch from scratch at enterprise quality. E-commerce plugin: product catalog (CRUD + variants + images), categories, inventory bridge to @suaveplan/api-plugin-inventory, cart (add/update/remove/clear), checkout (create order + payment intent bridge to @suaveplan/api-plugin-payment), order lifecycle (pending → confirmed → shipped → delivered → returned), and a basic discount/coupon engine. Routes under /store. Per-table SurrealQL. Typed events: store:order:created, store:order:shipped, store:cart:abandoned. Auth-gated write paths; public read paths for product catalog.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`
`@suaveplan/api-plugin-database` (`workspace:^`)	SurrealDB
`@suaveplan/api-plugin-payment` (`workspace:^`)	Payment intent creation
`@suaveplan/api-plugin-inventory` (`workspace:^`)	Stock reservation
`@suaveplan/events` (`workspace:^`)	Event bus
`@suaveplan/error` (`workspace:^`)	`StoreError` hierarchy
`@suaveplan/idempotency` (`workspace:^`)	Checkout guard
`@suaveplan/audit-logging` (`workspace:^`)	Order audit
`@suaveplan/rate-limiter` (`workspace:^`)	Rate limits
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createStorePlugin(config?: StorePluginConfig): PluginDescriptor<StorePluginConfig>

// Services: ProductService, CategoryService, CartService, OrderService, CouponService
// Routes: /store/products, /store/products/:id, /store/categories,
//         /store/cart, /store/checkout, /store/orders, /store/orders/:id

Error codes

type StoreErrorCode =
  | "STORE_PRODUCT_NOT_FOUND"
  | "STORE_OUT_OF_STOCK"
  | "STORE_CART_EMPTY"
  | "STORE_ORDER_NOT_FOUND"
  | "STORE_COUPON_INVALID"
  | "STORE_COUPON_EXPIRED"
  | "STORE_CHECKOUT_FAILED"

File layout

api/commerce/api-plugin-store/
  package.json  tsconfig.json  vitest.config.ts
  surql/ (product, variant, category, cart, cart_item, order, order_item, coupon tables)
  src/
    index.ts  events.ts  types/  errors/  schemas/
    services/product/  services/cart/  services/order/  services/coupon/
    routes/products/  routes/cart/  routes/checkout/  routes/orders/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/api-plugin-payment, @suaveplan/api-plugin-inventory.

3.0 KiB Raw Blame History