@azlib/cms 0.2.0 → 0.4.0

package/README.md

@@ -12,6 +12,7 @@ A framework-agnostic, modular Content Management System (CMS) runtime inspired b
 - 🗂️ **Hierarchical Taxonomies**: Nested category trees, flat tags, and custom taxonomy binding.
 - 🖼️ **Media & Asset Management**: MIME validation, file sanitization, metadata, and asset queries.
 - 🔒 **RBAC & Capability Matrix**: Built-in Administrator, Editor, Author, Contributor, and Subscriber roles with content ownership checks.
+- 🔌 **Extensible Plugin System**: Package and distribute reusable plugins (`definePlugin`) with schema extensions, custom API routes, lifecycle hooks, and filter pipelines.
 - 🌐 **Universal Web Standard Router**: `Request` -> `Response` HTTP router ready for Next.js App Router, Remix, Vite, Astro, Express, or Cloudflare Workers.
 - 🚀 **Type-Safe Headless Client SDK**: Query content in-process or over HTTP with zero boilerplate (`createCmsClient`).
 
@@ -109,6 +110,198 @@ export async function POST(request: Request) {
 
 ---
 
+## Plugin System
+
+Create modular, decoupled plugins that extend collections, inject custom fields, register custom Web Standard routes, and hook into lifecycle pipelines:
+
+```typescript
+import { definePlugin, fields } from "@azlib/cms";
+
+export const seoPlugin = definePlugin<{ defaultTitleSuffix?: string }>((options = {}) => ({
+  name: "seo-plugin",
+  version: "1.0.0",
+
+  // 1. Inject custom fields into existing collections
+  extendCollections: {
+    posts: [
+      fields.text({ name: "metaTitle", label: "Meta Title" }),
+      fields.text({ name: "metaDescription", label: "Meta Description" }),
+    ],
+  },
+
+  // 2. Programmatic setup for hooks and routes
+  setup({ hooks, registerRoute, engine }) {
+    // Intercept content before saving
+    hooks.addFilter("cms.before_create_input", (input: any) => {
+      if (input.title && options.defaultTitleSuffix && !input.data?.metaTitle) {
+        input.data = {
+          ...input.data,
+          metaTitle: `${input.title} | ${options.defaultTitleSuffix}`,
+        };
+      }
+      return input;
+    });
+
+    // Expose custom Web Standard API route
+    registerRoute("GET", "/api/seo/sitemap", async () => {
+      const posts = await engine.collection("posts").find({ status: "published" });
+      const urls = posts.items.map((p) => `https://example.com/posts/${p.slug}`);
+      return new Response(JSON.stringify({ urls }), {
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+  },
+
+  // 3. Lifecycle callbacks
+  async onInit(engine) {
+    console.log("[SEO Plugin] Initialized");
+  },
+}));
+```
+
+Register plugins declaratively in `defineConfig` or dynamically via `cms.use()`:
+
+```typescript
+// Declarative registration
+export default defineConfig({
+  plugins: [seoPlugin({ defaultTitleSuffix: "Alex's Journal" })],
+});
+
+// Or dynamic registration
+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