@azlib/cms 0.4.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()`:
@@ -178,7 +188,12 @@ cms.use(seoPlugin());
 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";
+import {
+  createCMSEngine,
+  defineConfig,
+  ecommercePlugin,
+  getEcommerceService,
+} from "@azlib/cms";
 
 // 1. Enable the plugin in your config
 export default defineConfig({
@@ -203,8 +218,15 @@ 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 });
+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({
@@ -272,12 +294,15 @@ const order = await commerce.createOrder({
   },
 });
 
-console.log(`Order placed: #${order.data.orderNumber} (Total: $${order.data.total})`);
+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`
@@ -302,6 +327,71 @@ 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