suaveplan/openspec/changes/enterprise-api-plugin-store/tasks.md

Tasks: enterprise-api-plugin-store

Change ID: enterprise-api-plugin-store Package: @suaveplan/api-plugin-store Target path: api/commerce/api-plugin-store Prerequisite packages on Verdaccio: @suaveplan/api, @suaveplan/api-shared, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/api-plugin-payment, @suaveplan/api-plugin-inventory, @suaveplan/events, @suaveplan/idempotency, @suaveplan/audit-logging, @suaveplan/rate-limiter, @suaveplan/error

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create api/commerce/api-plugin-store/; package.json v0.0.0; standard tooling.

---

2. Types, errors, events, schemas

• Types: Product, ProductVariant, Category, Cart, CartItem, Order, OrderItem, Coupon, StorePluginConfig (Zod).
• Errors: 7-code union + metadata + registration. Test + doc.
• Events: StoreEventMap (store:order:created, store:order:shipped, store:order:delivered, store:cart:abandoned).
• Zod schemas for all request/response shapes.

---

3. SurrealQL

• Per-table files: product.surql, variant.surql, category.surql, cart.surql, cart_item.surql, order.surql, order_item.surql, coupon.surql. All with tenantId indexes.

---

4. Services (each .test.ts + .md)

• ProductService: createProduct, updateProduct, deleteProduct, getProduct, listProducts (paginated, filterable by category/price/stock).
• CategoryService: CRUD + tree operations (parent/child).
• CartService: addItem, updateItem, removeItem, clearCart, getCart. Reserve inventory via api-plugin-inventory on add.
• OrderService: createOrder (from cart + payment intent + inventory commit), getOrder, listOrders, updateStatus. Emit store:order:* events; audit-log state changes.
• CouponService: createCoupon, validateCoupon, applyCoupon, expireCoupon.

---

5. Routes

• Products: public GET /store/products, GET /store/products/:id; auth-gated POST/PATCH/DELETE.
• Categories: public read; auth-gated write.
• Cart: GET/POST/PATCH/DELETE /store/cart — requireAuth.
• Checkout: POST /store/checkout — requireAuth + idempotency + rate-limit + audit.
• Orders: GET /store/orders, GET /store/orders/:id, PATCH /store/orders/:id/status — requireAuth + audit.
• Route .test.ts + .md.

---

6. Plugin factory + integration tests + publish

• createStorePlugin: definePlugin, dependencies: ["database", "auth"], migrationsPath: "./surql".
• Integration: add-to-cart → checkout → order created → status updated (real SurrealDB).
• bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-store — green; 100% coverage.
• bun scripts/publish.ts --package @suaveplan/api-plugin-store.
• Archive → openspec/archive/2026-04-24-enterprise-api-plugin-store/.