Commerce Backend Block Kit

Features

• Product Catalog — List, search, filter, and retrieve products by ID or slug. Supports pagination, category/brand filtering, and full-text-style search across name, description, brand, and category
• Product Variants & Inventory — Per-variant stock tracking with admin-controlled inventory updates
• Product Tags — Structured tagging system (style_tags, season_tags, occasion_tags, fit_tags, color_family) used for filtering and recommendation feeds
• Cart Management — Per-user carts with auto-creation on first read, duplicate variant merging, and server-side repricing (client-submitted prices are always ignored)
• Checkout Sessions — Snapshot-based checkout sessions that re-validate stock and lock totals at session creation
• Mock Payment Processing — Simulated payment confirmation with success and failure modes; designed with a clear extension point for real payment providers (e.g. Stripe)
• Atomic Order Creation — Stock decrement, order + line items, payment record, session completion, and cart clear all execute inside a single SQLite transaction
• Order Management — User-facing order history and detail; admin-facing order listing with status filtering and fulfillment status transitions
• Admin API — Full product lifecycle management (create, update, archive), inventory control, tag replacement, and order/payment administration — all protected by a token header
• Recommendation Feed Endpoint — Tag-driven product feed endpoint for consumption by a separate recommendation block; excludes archived products and out-of-stock variants automatically
• 25 Pure Service Functions — All business logic lives in importable service functions (src/services/*.ts) with no HTTP dependency, enabling in-process consumption by co-located blocks
• 67-Test Integration Suite — HTTP-level tests covering every route group, including server-side reprice assertions, stock decrement verification, cross-user isolation, and session replay rejection
• Idempotent Seed Data — 12 demo clothing products with variants, images, and tags; seed is slug-keyed and safe to re-run

Tech Stack

Setup

Prerequisites

• Node.js 18+
• npm

Installation & Running

npm install

# Optional: compile TypeScript
npm run build

# Seed 12 demo products into commerce.db
npm run seed

# Start development server on :3000
npm run dev

# Run 67 HTTP-level integration tests
npm test

Environment Variables

All variables are optional with sensible defaults.

API Endpoints

All routes are mounted under /api. All responses are JSON. Error shape:

{ "error": { "code": "validation_error", "message": "quantity must be >= 1" } }

Status codes: 400 validation · 401 unauthorized · 404 not found · 409 conflict · 500 server fault

Health

GET /api/health

Public Catalog

GET    /api/products                          # List active products (paginated)
GET    /api/products?limit=5&offset=0&category=tops
GET    /api/products/:idOrSlug                # Get single product by ID or slug
GET    /api/products/search?q=blazer          # Full-text-style search
GET    /api/products/filter?style_tag=minimalist&color_family=white&in_stock=true
GET    /api/recommendations/feed?style_tags=minimalist,classic&season_tags=spring&limit=6

Cart

Requires X-User-Id header on all requests.

GET    /api/cart                              # View cart (auto-created on first read)
POST   /api/cart/items                        # Add item (price_snapshot in body is ignored)
PATCH  /api/cart/items/:cart_item_id          # Update quantity (0 = remove)
DELETE /api/cart/items/:cart_item_id          # Remove item
POST   /api/cart/clear                        # Clear all items

Add item body:

{ "product_id": "<pid>", "variant_id": "<vid>", "quantity": 2 }

Checkout, Payment & Orders

POST   /api/checkout/sessions                 # Open checkout session (requires X-User-Id)
POST   /api/payments/mock-confirm             # Confirm or simulate-fail a mock payment
POST   /api/orders                            # Create order from session (atomic)
GET    /api/orders                            # List user's orders (requires X-User-Id)
GET    /api/orders/:order_id                  # Order detail (requires X-User-Id)

Mock confirm body:

{ "checkout_session_id": "<sid>" }

Simulate failure:

{ "checkout_session_id": "<sid>", "simulate": "fail", "failed_reason": "card_declined" }

Create order body:

{
  "checkout_session_id": "<sid>",
  "shipping_address": {
    "recipient": "Ada Lovelace",
    "line1": "1 Analytical Way",
    "city": "London",
    "postal_code": "WC1",
    "country": "UK"
  }
}

Admin — Products & Inventory

All admin routes require X-Admin-Token: <ADMIN_TOKEN>.

GET    /api/admin/products                    # List all products (any status)
POST   /api/admin/products                    # Create product with variants and tags
PATCH  /api/admin/products/:id                # Update product fields
POST   /api/admin/products/:id/archive        # Soft-delete (archive) a product
POST   /api/admin/products/:id/inventory      # Set absolute stock on a variant
PUT    /api/admin/products/:id/tags           # Replace product tags
POST   /api/admin/seed                        # Re-run seed (idempotent)

Create product body:

{
  "name": "Linen Camp Shirt",
  "price": 78,
  "category": "tops",
  "brand": "Atelier",
  "variants": [{ "size": "M", "color": "sand", "stock_quantity": 12 }],
  "tags": { "style_tags": ["minimalist"], "season_tags": ["summer"], "color_family": "beige" }
}

Admin — Orders & Payments

GET    /api/admin/orders                      # List orders (filterable by order_status, payment_status)
GET    /api/admin/orders/:order_id            # Order detail
PATCH  /api/admin/orders/:order_id/status     # Advance fulfillment status
GET    /api/admin/payments                    # List payments (filterable by status)

Order status values: pending → confirmed → preparing → shipped → delivered · canceled

Payment status values: pending · paid · failed · refunded

Data Model

10 tables with the following relationships:

products ──┬── product_images
           ├── product_variants
           └── product_tags

carts ──── cart_items ──── product_variants

checkout_sessions ── carts

orders ──── order_items ──── product_variants
   └────── payments

Key Invariants

1. Variant ownership — variant must belong to its product; validated at cart add and checkout
2. Stock gated at checkout — authoritative stock check is a single UPDATE … WHERE stock_quantity >= ? inside the order transaction
3. Server-side pricing — price_snapshot values on cart items and order items are always read from the database; client-submitted prices are discarded
4. Atomic orders — stock decrement, order creation, line items, payment record, session completion, and cart clear execute in one transaction

Service Functions

All 25 service functions are pure (no HTTP dependency) and importable directly for in-process use by co-located blocks.

Integration Points

Frontend Block

Consumes catalog, cart, checkout, and order endpoints over HTTP. Must never submit price_snapshot values — the server reprices on every mutation.

Recommendation Block

Calls GET /api/recommendations/feed (or imports getRecommendationProductFeed in-process) to hydrate tag-matched products with current price, stock, images, and variants. The recommendation block remains stateless with respect to commerce data.

Payment Provider Plugin (e.g. Stripe)

The payments table has payment_provider (free-form text, currently 'mock') and provider_payment_id columns ready for a real provider. A Stripe plugin would skip confirmMockPayment and pass its own provider_payment_id directly to createOrderFromCheckout. Webhook handling is the plugin's responsibility.

Project Layout

src/
  app.ts                  # Express app factory
  index.ts                # Bootstrap: migrations, auto-seed, listen
  config.ts               # Environment-driven configuration
  db.ts                   # better-sqlite3 + idempotent migrations
  errors.ts               # Typed error classes (HttpError, NotFound, Conflict, etc.)
  types.ts                # Shared row types and status unions
  validators.ts           # Zero-dependency input validators
  seed.ts                 # 12 demo products
  scripts/run-seed.ts     # npm run seed entrypoint
  tests/run.ts            # npm test — HTTP integration suite (67 tests)
  services/
    catalog.ts            # 11 catalog and admin product functions
    cart.ts               # 5 cart functions
    checkout.ts           # 5 checkout and order functions
    admin.ts              # 4 admin order and payment functions
  routes/
    catalog.ts            # Public catalog endpoints
    cart.ts               # Cart endpoints
    checkout.ts           # Checkout, mock payment, user order endpoints

License

Tetrees License