@azlib/cms 0.3.0 → 0.5.0

package/README.md

@@ -117,46 +117,56 @@ Create modular, decoupled plugins that extend collections, inject custom fields,
 ```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" },
+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;
       });
-    });
-  },
 
-  // 3. Lifecycle callbacks
-  async onInit(engine) {
-    console.log("[SEO Plugin] Initialized");
-  },
-}));
+      // 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()`:
@@ -173,6 +183,215 @@ 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({ ... });
+```
+
+---
+
+## Built-in HRMS Plugin (`hrmsPlugin`)
+
+`@azlib/cms` includes a full-featured Human Resource Management System (HRMS) plugin for multi-tenant companies, employee directory profiles, attendance tracking, and leave quota management.
+
+### Features
+
+- 🏢 **Multi-Tenant Employers**: Manage distinct companies/organizations with custom work schedules, timezones, and grace periods.
+- 👤 **Employee Directory**: Rich employee profiles, contract/document attachments, emergency contacts, manager hierarchies, and department taxonomies.
+- ⏱️ **Daily Attendance Tracking**: Clock-in and clock-out with automated duration calculation, overtime hours, and late-arrival detection against work schedules.
+- 🏖️ **Leave Quota & Approval Workflow**: Custom leave types (Annual, Sick, Unpaid), balance ledger reports, and manager approval/rejection pipelines.
+- 🌐 **Web Standard REST APIs & Client SDK**: Pre-mounted routes under `/api/hrms/*` and typed `HRMSClient` SDK.
+
+### Usage
+
+```typescript
+import {
+  createCMSEngine,
+  defineConfig,
+  hrmsPlugin,
+  getHRMSService,
+} from "@azlib/cms";
+
+const config = defineConfig({
+  plugins: [
+    hrmsPlugin({
+      workScheduleStart: "09:00",
+      workScheduleEnd: "17:00",
+      standardWorkDayHours: 8,
+      gracePeriodMinutes: 15,
+    }),
+  ],
+});
+
+const cms = createCMSEngine(config);
+await cms.init();
+
+const hrms = getHRMSService(cms);
+
+// 1. Create an Employer
+const employer = await hrms.createEmployer({
+  companyName: "Acme Corp",
+  timezone: "America/New_York",
+});
+
+// 2. Add an Employee
+const employee = await hrms.createEmployee({
+  employerId: employer.id,
+  employeeNumber: "ACME-001",
+  firstName: "Jane",
+  lastName: "Doe",
+  email: "jane.doe@acme.example",
+  hireDate: "2024-01-15",
+});
+
+// 3. Employee Check-In & Check-Out
+await hrms.checkIn({ employeeId: employee.id });
+await hrms.checkOut({ employeeId: employee.id });
+
+// 4. Request Leave & Check Balance
+const leaveReport = await hrms.calculateLeaveBalance(employee.id, 2026);
+console.log(`Remaining days: ${leaveReport.totalRemaining}`);
+```
+
+---
+
 ## License
 
 MIT © Google / azlib