🛒 3Z Insta Cart - Node.js / Express / TypeScript E-Commerce REST API

A production-grade, idiomatic Node.js (Express + TypeScript) REST API for 3Z Insta Cart, an instant grocery & e-commerce shopping platform matching the full functionality, error schemas, and business rules of the Spring Boot and Python/Flask editions.

---

🚀 Key Features

• Product Catalog & Inventory:
  • Full CRUD operations with category filtering, keyword search, stock tracking, and pricing.
  • Pre-seeded with 12 instant grocery items across categories (PRODUCE, DAIRY_EGGS, BAKERY, BEVERAGES, SNACKS, PANTRY, MEAT_SEAFOOD).
• 3Z Insta Cart Shopping Engine:
  • Add items to cart with automatic duplicate item quantity consolidation.
  • Real-time stock validation and error handling.
  • Dynamic financial computation: subtotal, 7% sales tax, and tiered delivery fee ($3.99, free on orders over $35.00).
• Atomic Checkout & Order Management:
  • Validates stock availability and deducts inventory atomically at checkout via SQLite transactions.
  • Unique order tracking generation (3Z-YYYYMMDDHHMMSS-XXXX).
  • Order status tracking (PENDING -> CONFIRMED -> PREPARING -> OUT_FOR_DELIVERY -> DELIVERED).
• Interactive Documentation & Observability:
  • OpenAPI / Swagger UI at http://localhost:8080/swagger-ui.html.
  • OpenAPI JSON Spec at http://localhost:8080/v3/api-docs.
  • Health checks at http://localhost:8080/actuator/health and http://localhost:8080/health.

---

🛠️ Tech Stack & Requirements

• Runtime: Node.js 22+
• Language: TypeScript 5.7+ (with tsx runtime execution)
• Web Framework: Express 4.21
• Database: SQLite with better-sqlite3 (WAL mode enabled)
• Validation: Zod 3.24
• Documentation: Swagger UI (swagger-ui-express)
• Testing: Vitest 3.0 & Supertest 7.0

---

📦 How to Setup and Run

1. Install Dependencies

cd /Users/peterperez/Documents/webprojects/nodejsprojects/3z-insta-cart
npm install

2. Run Automated Tests

npm test

3. Start Development Server

npm run dev

4. Start Production Server

npm start

Or on a custom port:

PORT=8080 npm start

---

📖 API Documentation & Endpoints

📍 Interactive Swagger UI

Open your browser at: 👉 http://localhost:8080/swagger-ui.html 👉 OpenAPI JSON Spec: http://localhost:8080/v3/api-docs

---

🛒 1. Shopping Cart API (/api/v1/carts)

Method	Endpoint	Description
GET	/api/v1/carts/:cartId	Get cart details with calculated totals & items
GET	/api/v1/carts/customer/:customerId	Get or create cart for customer
POST	/api/v1/carts/:cartId/items	Add product to cart (body: {"productId": 1, "quantity": 2})
PUT	/api/v1/carts/:cartId/items/:itemId	Update item quantity in cart
DELETE	/api/v1/carts/:cartId/items/:itemId	Remove specific item
DELETE	/api/v1/carts/:cartId/clear	Clear all items from cart

---

📦 2. Orders & Checkout API (/api/v1)

Method	Endpoint	Description
POST	/api/v1/checkout	Checkout cart, deduct stock, create order
GET	/api/v1/orders/:id	Get order details by ID
GET	/api/v1/orders/number/:orderNumber	Lookup order by 3Z tracking number
GET	/api/v1/orders/customer/:customerId	View order history for a customer
PATCH	/api/v1/orders/:id/status	Update order delivery status

---

🍎 3. Products API (/api/v1/products)

Method	Endpoint	Description
GET	/api/v1/products	List active products (supports ?category= and ?search=)
GET	/api/v1/products/:id	Get product details
POST	/api/v1/products	Create a new product
PUT	/api/v1/products/:id	Update product information/stock
DELETE	/api/v1/products/:id	Soft delete product

---

👤 4. Customers API (/api/v1/customers)

Method	Endpoint	Description
GET	/api/v1/customers	List registered customers
GET	/api/v1/customers/:id	Get customer profile
POST	/api/v1/customers	Register a new customer

---

🧪 Quick Test Walkthrough (cURL)

# 1. Fetch available products
curl http://localhost:8080/api/v1/products

# 2. Add Organic Avocados and Whole Milk to Cart 1
curl -X POST http://localhost:8080/api/v1/carts/1/items \
  -H "Content-Type: application/json" \
  -d '{"productId": 1, "quantity": 2}'

curl -X POST http://localhost:8080/api/v1/carts/1/items \
  -H "Content-Type: application/json" \
  -d '{"productId": 4, "quantity": 1}'

# 3. View Cart Summary & Totals
curl http://localhost:8080/api/v1/carts/1

# 4. Instant Checkout
curl -X POST http://localhost:8080/api/v1/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "cartId": 1,
    "deliveryAddress": "742 Evergreen Terrace",
    "deliveryCity": "Springfield",
    "deliveryZipCode": "97477",
    "deliveryInstructions": "Leave on front porch"
  }'

# 5. Track Order Status
curl http://localhost:8080/api/v1/orders/1

3Z-Insta-Cart-nodejs