@azlib/cms 0.3.0 → 0.4.0

package/README.md

@@ -173,6 +173,135 @@ cms.use(seoPlugin());
 
 ---
 
+## Built-in E-commerce Plugin
+
+Turn `@azlib/cms` into a complete commerce backend with pre-defined schemas, catalog taxonomies, image uploading, coupon validation, cart calculation, inventory tracking, and orders:
+
+```typescript
+import { createCMSEngine, defineConfig, ecommercePlugin, getEcommerceService } from "@azlib/cms";
+
+// 1. Enable the plugin in your config
+export default defineConfig({
+  plugins: [
+    ecommercePlugin({
+      defaultCurrency: "USD",
+      inventoryManagement: true,
+      defaultShippingCost: 15,
+      defaultTaxRate: 0.08, // 8%
+    }),
+  ],
+});
+```
+
+### 1. Catalog & Product Management
+
+```typescript
+const cms = createCMSEngine();
+cms.use(ecommercePlugin());
+await cms.init();
+
+const commerce = getEcommerceService(cms);
+
+// Create hierarchical catalog category
+const apparel = await commerce.createCategory({ name: "Apparel", slug: "apparel" });
+const shoes = await commerce.createCategory({ name: "Shoes", slug: "shoes", parentId: apparel.id });
+
+// Create product with SKU, pricing, inventory, variants
+const product = await commerce.createProduct({
+  title: "Aero Running Shoes",
+  price: 139.99,
+  compareAtPrice: 169.99,
+  sku: "RUN-AERO-01",
+  stock: 25,
+  status: "published",
+  categoryIds: [shoes.id],
+  variants: [
+    { id: "v-42", title: "Size 42", price: 139.99, stock: 10 },
+    { id: "v-43", title: "Size 43", price: 139.99, stock: 15 },
+  ],
+});
+
+// Upload and attach product images (auto-updates featured image and gallery)
+await commerce.uploadProductImage(product.id, {
+  filename: "aero-shoes.jpg",
+  mimeType: "image/jpeg",
+  sizeBytes: 1048576,
+  url: "https://example.com/uploads/aero-shoes.jpg",
+  isFeatured: true,
+});
+```
+
+### 2. Discounts & Coupon Engine
+
+```typescript
+// Create promotional coupon
+await commerce.createDiscount({
+  title: "Summer 20%",
+  code: "SUMMER20",
+  discountType: "percentage",
+  value: 20,
+  minOrderAmount: 50,
+  maxDiscountAmount: 30,
+});
+
+// Validate discount for a cart
+const validation = await commerce.validateDiscount("SUMMER20", 100);
+// => { valid: true, discountAmount: 20, code: "SUMMER20" }
+```
+
+### 3. Cart Calculation & Orders
+
+```typescript
+// Calculate totals (items, discounts, shipping, and tax)
+const cart = await commerce.calculateCart({
+  items: [{ productId: product.id, quantity: 2 }],
+  discountCode: "SUMMER20",
+});
+
+// Place an order (automatically decrements inventory and increments coupon counter)
+const order = await commerce.createOrder({
+  customerEmail: "customer@example.com",
+  customerName: "Jane Doe",
+  items: [{ productId: product.id, quantity: 2 }],
+  discountCode: "SUMMER20",
+  shippingAddress: {
+    address1: "456 Market St",
+    city: "San Francisco",
+    country: "US",
+    postalCode: "94103",
+  },
+});
+
+console.log(`Order placed: #${order.data.orderNumber} (Total: $${order.data.total})`);
+```
+
+### 4. REST API & Headless Client
+
+Mount the universal `createCMSRouter(cms)` to automatically expose REST endpoints:
+- `GET /api/ecommerce/products` (supports `?category=...&minPrice=...&maxPrice=...&inStock=true&search=...`)
+- `GET /api/ecommerce/products/:idOrSlug`
+- `POST /api/ecommerce/products`
+- `POST /api/ecommerce/products/:id/images`
+- `GET /api/ecommerce/categories` (supports `?tree=true`)
+- `POST /api/ecommerce/discounts/validate`
+- `POST /api/ecommerce/cart/calculate`
+- `POST /api/ecommerce/orders`
+- `PATCH /api/ecommerce/orders/:id/status`
+
+Or query via the Headless Client SDK:
+
+```typescript
+import { createCmsClient, getEcommerceClient } from "@azlib/cms";
+
+const client = createCmsClient({ baseUrl: "https://api.my-shop.com" });
+const shop = getEcommerceClient(client);
+
+const { items: products } = await shop.products.find({ minPrice: 50 });
+const order = await shop.orders.create({ ... });
+```
+
+---
+
 ## License
 
 MIT © Google / azlib