@classytic/payroll 1.0.0 → 2.7.5

package/README.md

@@ -1,574 +1,525 @@
-# 🎯 HRM Library - Human Resource Management
-
-Modern, flexible, production-ready HRM system following Stripe/Passport.js architecture patterns.
-
-## 🌟 Key Features
-
-### Multi-Tenant Support
-- Same user can be employee in multiple organizations
-- Complete data isolation per tenant
-- Re-hiring support with full employment history
-
-### Smart Payroll
-- **Pro-rated calculations** (mid-month hires)
-- **Attendance integration** (unpaid leave auto-deduction)
-- **Automatic deductions** (loans, advances, tax)
-- **Bulk payroll processing**
-- **Transaction integration** (seamless with existing system)
-
-### Data Retention
-- **Auto-deletion**: PayrollRecords expire after 2 years (MongoDB TTL)
-- **Export before deletion**: Required export for compliance
-- **Configurable retention**: Adjust via `HRM_CONFIG`
-
-### Flexible Architecture
-- **Reusable schemas**: Merge with your custom fields
-- **Plugin system**: Adds methods, virtuals, indexes
-- **Clean DSL**: `hrm.hire()`, `hrm.processSalary()`, `hrm.terminate()`
-- **Dependency injection**: Models injected at bootstrap
-
-## 📁 Structure
-
-```
-lib/hrm/
-├── index.js                    # Public exports
-├── init.js                     # Bootstrap initialization
-├── hrm.orchestrator.js         # Clean API (Stripe-like)
-├── enums.js                    # Single source of truth
-├── config.js                   # Configurable settings
-│
-├── models/
-│   └── payroll-record.model.js # Universal payroll ledger
-│
-├── schemas/
-│   └── employment.schema.js    # Reusable mongoose schemas
-│
-├── plugins/
-│   └── employee.plugin.js      # Mongoose plugin (methods/virtuals)
-│
-├── core/                       # Domain business logic
-│   ├── employment.manager.js   # Hire/terminate operations
-│   ├── compensation.manager.js # Salary/allowance operations
-│   └── payroll.manager.js      # Payroll processing
-│
-├── factories/                  # Clean object creation
-│   ├── employee.factory.js     # Employee creation with defaults
-│   ├── payroll.factory.js      # Payroll generation
-│   └── compensation.factory.js # Compensation breakdown
-│
-├── services/                   # High-level operations
-│   ├── employee.service.js     # Employee CRUD + queries
-│   ├── payroll.service.js      # Batch payroll processing
-│   └── compensation.service.js # Compensation calculations
-│
-└── utils/                      # Pure, reusable functions
-    ├── date.utils.js           # Date calculations
-    ├── calculation.utils.js    # Salary calculations
-    ├── validation.utils.js     # Validators
-    └── query-builders.js       # Fluent query API
-```
-
-## 🚀 Quick Start
-
-### 1. Create Your Employee Model
-
-```javascript
-// modules/employee/employee.model.js
-import mongoose from 'mongoose';
-import { employmentFields, employeePlugin } from '#lib/hrm/index.js';
-
-const employeeSchema = new mongoose.Schema({
-  // Core HRM fields (required)
-  ...employmentFields,
-
-  // Your custom fields
-  certifications: [{ name: String, issuedDate: Date }],
-  specializations: [String],
-  emergencyContact: { name: String, phone: String },
-  // ... any other fields you need
-});
-
-// Apply HRM plugin (adds methods, virtuals, indexes)
-employeeSchema.plugin(employeePlugin);
-
-export default mongoose.model('Employee', employeeSchema);
-```
-
-### 2. Bootstrap Integration
-
-```javascript
-// bootstrap/hrm.js
-import { initializeHRM } from '#lib/hrm/index.js';
-import Employee from '../modules/employee/employee.model.js';
-import PayrollRecord from '#lib/hrm/models/payroll-record.model.js';
-import Transaction from '../modules/transaction/transaction.model.js';
-import Attendance from '#lib/attendance/models/attendance.model.js';
-
-export async function loadHRM() {
-  initializeHRM({
-    EmployeeModel: Employee,
-    PayrollRecordModel: PayrollRecord,
-    TransactionModel: Transaction,
-    AttendanceModel: Attendance, // Optional
-  });
-}
-```
-
-### 3. Use the HRM API
-
-```javascript
-import { hrm } from '#lib/hrm/index.js';
-
-// Hire employee
-const employee = await hrm.hire({
-  organizationId,
-  userId,
-  employment: {
-    employeeId: 'EMP-001',
-    type: 'full_time',
-    department: 'training',
-    position: 'Senior Trainer',
-    hireDate: new Date(),
-  },
-  compensation: {
-    baseAmount: 50000,
-    frequency: 'monthly',
-    allowances: [
-      { type: 'housing', amount: 10000 },
-      { type: 'transport', amount: 5000 }
-    ]
-  },
-  bankDetails: {
-    accountName: 'John Doe',
-    accountNumber: '1234567890',
-    bankName: 'Example Bank'
-  },
-  context: { userId: hrManagerId }
-});
-
-// Process salary (creates Transaction automatically)
-const result = await hrm.processSalary({
-  employeeId: employee._id,
-  month: 11,
-  year: 2025,
-  paymentDate: new Date(),
-  paymentMethod: 'bank',
-  context: { userId: hrManagerId }
-});
-
-// Bulk payroll (all active employees)
-const results = await hrm.processBulkPayroll({
-  organizationId,
-  month: 11,
-  year: 2025,
-  context: { userId: hrManagerId }
-});
-```
-
-
-## 🎨 Complete API Reference
-
-### Employment Lifecycle
-
-```javascript
-// Hire
-await hrm.hire({ organizationId, userId, employment, compensation, bankDetails, context });
-
-// Update employment details
-await hrm.updateEmployment({ employeeId, updates: { department: 'management' }, context });
-
-// Terminate
-await hrm.terminate({ employeeId, terminationDate, reason: 'resignation', notes, context });
-
-// Re-hire (same employee, new stint)
-await hrm.reHire({ employeeId, hireDate, position, compensation, context });
-
-// List employees
-await hrm.listEmployees({
-  organizationId,
-  filters: { status: 'active', department: 'training', minSalary: 40000 },
-  pagination: { page: 1, limit: 20 }
-});
-
-// Get single employee
-await hrm.getEmployee({ employeeId, populateUser: true });
-```
-
-### Compensation Management
-
-```javascript
-// Update salary
-await hrm.updateSalary({
-  employeeId,
-  compensation: { baseAmount: 60000 },
-  effectiveFrom: new Date(),
-  context
-});
-
-// Add allowance
-await hrm.addAllowance({
-  employeeId,
-  type: 'meal',
-  amount: 3000,
-  taxable: true,
-  recurring: true,
-  context
-});
-
-// Remove allowance
-await hrm.removeAllowance({ employeeId, type: 'meal', context });
-
-// Add deduction
-await hrm.addDeduction({
-  employeeId,
-  type: 'loan',
-  amount: 5000,
-  auto: true, // Auto-deduct from salary
-  description: 'Personal loan repayment',
-  context
-});
-
-// Remove deduction
-await hrm.removeDeduction({ employeeId, type: 'loan', context });
-
-// Update bank details
-await hrm.updateBankDetails({
-  employeeId,
-  bankDetails: { accountNumber: '9876543210', bankName: 'New Bank' },
-  context
-});
-```
-
-### Payroll Processing
-
-```javascript
-// Process single salary
-await hrm.processSalary({
-  employeeId,
-  month: 11,
-  year: 2025,
-  paymentDate: new Date(),
-  paymentMethod: 'bank',
-  context
-});
-
-// Bulk payroll
-await hrm.processBulkPayroll({
-  organizationId,
-  month: 11,
-  year: 2025,
-  employeeIds: [], // Empty = all active employees
-  paymentDate: new Date(),
-  paymentMethod: 'bank',
-  context
-});
-
-// Payroll history
-await hrm.payrollHistory({
-  employeeId,
-  organizationId,
-  month: 11,
-  year: 2025,
-  status: 'paid',
-  pagination: { page: 1, limit: 20 }
-});
-
-// Payroll summary
-await hrm.payrollSummary({
-  organizationId,
-  month: 11,
-  year: 2025
-});
-
-// Export payroll data (before auto-deletion)
-const records = await hrm.exportPayroll({
-  organizationId,
-  startDate: new Date('2023-01-01'),
-  endDate: new Date('2023-12-31'),
-  format: 'json'
-});
-```
-
-## 📊 Data Models
-
-### Employee (Your Model + HRM Fields)
-
-```javascript
-{
-  // Identity & tenant
-  userId: ObjectId,              // Links to User
-  organizationId: ObjectId,      // Multi-tenant isolation
-  employeeId: "EMP-001",         // Custom ID (unique per org)
-
-  // Employment
-  employmentType: "full_time",   // full_time, part_time, contract, intern
-  status: "active",              // active, on_leave, suspended, terminated
-  department: "training",
-  position: "Senior Trainer",
-
-  // Dates
-  hireDate: Date,
-  terminationDate: Date,
-  probationEndDate: Date,
-
-  // Employment history (re-hiring support)
-  employmentHistory: [{
-    hireDate: Date,
-    terminationDate: Date,
-    reason: String,
-    finalSalary: Number
-  }],
-
-  // Compensation
-  compensation: {
-    baseAmount: 50000,
-    frequency: "monthly",
-    currency: "BDT",
-
-    allowances: [
-      { type: "housing", amount: 10000, taxable: true },
-      { type: "transport", amount: 5000, taxable: false }
-    ],
-
-    deductions: [
-      { type: "loan", amount: 2000, auto: true }
-    ],
-
-    grossSalary: 65000,    // Auto-calculated
-    netSalary: 63000,      // Auto-calculated
-  },
-
-  // Bank details
-  bankDetails: {
-    accountName: String,
-    accountNumber: String,
-    bankName: String
-  },
-
-  // Payroll stats (pre-calculated)
-  payrollStats: {
-    totalPaid: 500000,
-    lastPaymentDate: Date,
-    nextPaymentDate: Date,
-    paymentsThisYear: 10,
-    averageMonthly: 50000
-  },
-
-  // YOUR CUSTOM FIELDS
-  certifications: [...],
-  specializations: [...],
-  emergencyContact: {...}
-}
-```
-
-### PayrollRecord (Universal Ledger)
-
-```javascript
-{
-  organizationId: ObjectId,
-  employeeId: ObjectId,
-  userId: ObjectId,
-
-  period: {
-    month: 11,
-    year: 2025,
-    startDate: Date,
-    endDate: Date,
-    payDate: Date
-  },
-
-  breakdown: {
-    baseAmount: 50000,
-    allowances: [...],
-    deductions: [...],
-    grossSalary: 65000,
-    netSalary: 63000,
-
-    // Smart calculations
-    workingDays: 30,
-    actualDays: 25,           // If joined mid-month
-    proRatedAmount: 41667,    // Pro-rated salary
-    attendanceDeduction: 0,   // From attendance integration
-    overtimeAmount: 0,
-    bonusAmount: 0
-  },
-
-  transactionId: ObjectId,    // Links to Transaction
-  status: "paid",
-  paidAt: Date,
-
-  // Export tracking
-  exported: false,            // Must export before TTL deletion
-  exportedAt: Date
-}
-```
-
-## ⚙️ Configuration
-
-```javascript
-// lib/hrm/config.js
-export const HRM_CONFIG = {
-  dataRetention: {
-    payrollRecordsTTL: 63072000,      // 2 years in seconds
-    exportWarningDays: 30,            // Warn before deletion
-    archiveBeforeDeletion: true,
-  },
-
-  payroll: {
-    defaultCurrency: 'BDT',
-    allowProRating: true,             // Mid-month hire calculations
-    attendanceIntegration: true,      // Unpaid leave deductions
-    autoDeductions: true,             // Auto-deduct loans/advances
-  },
-
-  employment: {
-    defaultProbationMonths: 3,
-    allowReHiring: true,              // Re-hire terminated employees
-    trackEmploymentHistory: true,
-  },
-
-  validation: {
-    requireBankDetails: false,
-    allowMultiTenantEmployees: true,  // Same user in multiple orgs
-  },
-};
-```
-
-## 🔑 Key Concepts
-
-### Multi-Tenant Architecture
-
-Same user can work at multiple gyms:
-```javascript
-// User "john@example.com" (userId: 123)
-// Works at Gym A
-{ userId: 123, organizationId: "gymA", employeeId: "EMP-001", status: "active" }
-
-// Also works at Gym B
-{ userId: 123, organizationId: "gymB", employeeId: "STAFF-05", status: "active" }
-```
-
-Indexes ensure uniqueness:
-- `{ userId: 1, organizationId: 1 }` unique
-- `{ organizationId: 1, employeeId: 1 }` unique
-
-### Re-Hiring Flow
-
-```javascript
-// Employee leaves
-await hrm.terminate({
-  employeeId,
-  reason: 'resignation',
-  terminationDate: new Date()
-});
-// status: 'terminated', data preserved
-
-// Employee comes back
-await hrm.reHire({
-  employeeId,
-  hireDate: new Date(),
-  position: 'Manager', // Optional: new position
-  compensation: { baseAmount: 60000 } // Optional: new salary
-});
-// status: 'active', previous stint added to employmentHistory[]
-```
-
-### Smart Payroll Calculations
-
-**Pro-Rating (Mid-Month Hire)**:
-```javascript
-// Employee hired on Nov 15
-// Working days: 15 out of 30
-// Base salary: 60,000
-// Pro-rated: 60,000 × (15/30) = 30,000
-```
-
-**Attendance Integration**:
-```javascript
-// Monthly salary: 60,000
-// Working days: 30
-// Attended days: 25
-// Absent days: 5
-// Daily rate: 60,000 / 30 = 2,000
-// Deduction: 5 × 2,000 = 10,000
-// Final: 60,000 - 10,000 = 50,000
-```
-
-**Auto Deductions**:
-```javascript
-compensation: {
-  baseAmount: 60000,
-  allowances: [{ type: 'housing', amount: 10000 }],
-  deductions: [
-    { type: 'loan', amount: 5000, auto: true },  // Auto-deduct
-    { type: 'tax', amount: 3000, auto: true }
-  ],
-  grossSalary: 70000,
-  netSalary: 62000  // 70000 - 5000 - 3000
-}
-```
-
-### Transaction Integration
-
-Every salary payment creates a Transaction:
-```javascript
-{
-  organizationId,
-  type: 'expense',
-  category: 'salary',
-  amount: 63000,
-  method: 'bank',
-  status: 'completed',
-  referenceId: employeeId,
-  referenceModel: 'Employee',
-  metadata: {
-    employeeId: 'EMP-001',
-    payrollRecordId: ObjectId(...),
-    period: { month: 11, year: 2025 },
-    breakdown: { ... }
-  }
-}
-```
-
-### Data Retention & Export
-
-PayrollRecords auto-delete after 2 years:
-```javascript
-// TTL index on PayrollRecord
-payrollRecordSchema.index(
-  { createdAt: 1 },
-  {
-    expireAfterSeconds: 63072000,  // 2 years
-    partialFilterExpression: { exported: true }  // Only if exported
-  }
-);
-
-// Export before deletion
-const records = await hrm.exportPayroll({
-  organizationId,
-  startDate: new Date('2023-01-01'),
-  endDate: new Date('2023-12-31')
-});
-// Marks records as exported, making them eligible for deletion
-```
-
-## 🎯 Design Philosophy
-
-- **Stripe/Passport.js inspired**: Clean DSL, dependency injection, reusable components
-- **Lightweight**: Not a complex ERP, gym-focused features only
-- **Multi-tenant**: Same user can work at multiple organizations
-- **Smart defaults**: Pro-rating, attendance integration, automatic calculations
-- **Production-ready**: Transaction integration, data retention, comprehensive error handling
-
-## ✅ Next Steps
-
-1. Test bootstrap initialization
-2. Create Fastify routes in `modules/employee/`
-3. Add API handlers
-4. Migrate existing staff from organization module
-5. Deploy and monitor
-
----
-
-**Built with ❤️ following world-class architecture patterns**
-**Ready for multi-tenant gym management**
+# @classytic/payroll
+
+Enterprise HRM & Payroll for MongoDB. Clean architecture, multi-tenant, type-safe.
+
+[![npm](https://img.shields.io/npm/v/@classytic/payroll)](https://www.npmjs.com/package/@classytic/payroll)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)
+[![MIT](https://img.shields.io/badge/License-MIT-yellow)](https://opensource.org/licenses/MIT)
+
+## Install
+
+```bash
+npm install @classytic/payroll mongoose @classytic/mongokit
+```
+
+## Quick Start
+
+```typescript
+import { createPayrollInstance } from '@classytic/payroll';
+
+const payroll = createPayrollInstance()
+  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+  .build();
+
+// Hire employee
+await payroll.hire({
+  organizationId,
+  employment: { email: 'dev@example.com', position: 'Engineer' },
+  compensation: { baseSalary: 80000, currency: 'USD' },
+});
+
+// Process salary
+await payroll.processSalary({
+  organizationId,
+  employeeId,
+  period: { month: 1, year: 2024 },
+});
+```
+
+## Features
+
+- **Employee Lifecycle**: Hire, update, terminate, re-hire
+- **Compensation**: Salary, allowances, deductions
+- **Bulk Processing**: Handle 10k+ employees with streaming
+- **Multi-tenant**: Automatic organization isolation
+- **Events & Webhooks**: React to payroll events
+- **Type-safe**: Full TypeScript support
+
+## Exports
+
+| Entry Point | Description |
+|-------------|-------------|
+| `@classytic/payroll` | Main API (Payroll class, types, errors) |
+| `@classytic/payroll/schemas` | Mongoose schemas for extending |
+| `@classytic/payroll/utils` | Date, money, validation utilities |
+| `@classytic/payroll/calculators` | Pure calculation functions (no DB) |
+
+## Employee Management
+
+```typescript
+// Hire
+await payroll.hire({ organizationId, employment, compensation });
+
+// Get employee
+const employee = await payroll.getEmployee({ employeeId, organizationId });
+
+// Get by flexible identity (userId, employeeId, or email)
+const emp = await payroll.getEmployeeByIdentity({
+  identity: 'EMP-001',  // or userId or email
+  organizationId,
+  mode: 'employeeId',   // 'userId' | 'employeeId' | 'email' | 'any'
+});
+
+// Update
+await payroll.updateEmployment({ employeeId, updates: { position: 'Lead' } });
+
+// Terminate
+await payroll.terminate({ employeeId, terminationDate, reason: 'resignation' });
+
+// Re-hire
+await payroll.reHire({ employeeId, hireDate: new Date() });
+```
+
+## Listing Employees
+
+Employee listing/queries are done at app level using your models directly:
+
+```typescript
+// Use your EmployeeModel with mongokit or mongoose directly
+const employees = await EmployeeModel.find({
+  organizationId,
+  'employment.status': 'active'
+});
+
+// Or with mongokit repository
+const repo = createRepository(EmployeeModel);
+const result = await repo.getAll({
+  filters: { organizationId, 'employment.status': 'active' },
+  page: 1,
+  limit: 100,
+});
+```
+
+## Compensation
+
+```typescript
+// Update salary
+await payroll.updateSalary({ employeeId, compensation: { baseSalary: 90000 } });
+
+// Add allowance
+await payroll.addAllowance({ employeeId, allowance: { type: 'housing', amount: 2000 } });
+
+// Add deduction
+await payroll.addDeduction({ employeeId, deduction: { type: 'loan', amount: 500 } });
+```
+
+## Bulk Processing
+
+```typescript
+await payroll.processBulkPayroll({
+  organizationId,
+  period: { month: 1, year: 2024 },
+  onProgress: ({ current, total }) => console.log(`${current}/${total}`),
+});
+```
+
+## Leave Management
+
+```typescript
+// Request leave
+await payroll.requestLeave({
+  employeeId,
+  organizationId,
+  leaveType: 'annual',
+  startDate: new Date('2024-01-15'),
+  endDate: new Date('2024-01-17'),
+});
+
+// Approve
+await payroll.approveLeave({ leaveRequestId, approverId });
+```
+
+## Void / Reverse / Restore
+
+Payroll corrections with full state tracking:
+
+```typescript
+// Void unpaid payroll
+await payroll.voidPayroll({
+  organizationId,
+  payrollRecordId,
+  reason: 'Test payroll',
+});
+
+// Reverse paid payroll (creates reversal transaction)
+await payroll.reversePayroll({
+  organizationId,
+  payrollRecordId,
+  reason: 'Duplicate payment',
+});
+
+// Restore voided payroll
+await payroll.restorePayroll({
+  organizationId,
+  payrollRecordId,
+  reason: 'Voided in error',
+});
+```
+
+**State Flow:**
+```
+PENDING → PROCESSING → PAID → REVERSED
+   ↓          ↓
+   └──→ VOIDED ←── FAILED
+         ↓
+       PENDING (restore)
+```
+
+## Events
+
+```typescript
+payroll.on('employee:hired', (payload) => {
+  console.log(`New hire: ${payload.employee.email}`);
+});
+
+payroll.on('payroll:processed', (payload) => {
+  console.log(`Salary processed: ${payload.payrollRecord.id}`);
+});
+```
+
+## Webhooks
+
+```typescript
+await payroll.registerWebhook({
+  organizationId,
+  url: 'https://api.example.com/webhooks',
+  events: ['payroll:processed'],
+  secret: 'your-secret',
+});
+```
+
+## Tenant Modes
+
+### Single-Tenant (Recommended for most apps)
+
+For apps serving one organization:
+
+```typescript
+const payroll = createPayrollInstance()
+  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+  .forSingleTenant({ organizationId: YOUR_ORG_ID, autoInject: true })
+  .build();
+
+// No organizationId needed - auto-injected
+await payroll.hire({
+  employment: { email: 'dev@example.com', position: 'Engineer' },
+  compensation: { baseSalary: 80000, currency: 'USD' },
+});
+
+await payroll.processSalary({
+  employeeId,
+  period: { month: 1, year: 2024 },
+});
+
+await payroll.getEmployee({ employeeId });
+await payroll.updateEmployment({ employeeId, updates: { position: 'Lead' } });
+await payroll.terminate({ employeeId, terminationDate, reason: 'resignation' });
+```
+
+### Multi-Tenant
+
+For SaaS apps serving multiple organizations:
+
+```typescript
+const payroll = createPayrollInstance()
+  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+  .build();
+
+// organizationId required on all operations
+await payroll.hire({ organizationId, employment, compensation });
+await payroll.processSalary({ organizationId, employeeId, period });
+await payroll.getEmployee({ organizationId, employeeId });
+```
+
+## Pure Calculators
+
+No database required - works in browser/serverless:
+
+```typescript
+import {
+  calculateSalaryBreakdown,
+  calculateProRating,
+  calculateAttendanceDeduction
+} from '@classytic/payroll/calculators';
+
+// Calculate salary breakdown
+const breakdown = calculateSalaryBreakdown({
+  baseSalary: 5000,
+  allowances: [{ type: 'housing', amount: 500 }],
+  deductions: [{ type: 'tax', percentage: 10 }],
+});
+
+// Pro-rate for mid-month joins
+const proRated = calculateProRating({
+  amount: 5000,
+  startDate: new Date('2024-01-15'),
+  endDate: new Date('2024-01-31'),
+  totalDays: 31,
+});
+```
+
+## Shift Compliance
+
+Late penalties, overtime bonuses, night differentials:
+
+```typescript
+import {
+  calculateShiftCompliance,
+  DEFAULT_ATTENDANCE_POLICY
+} from '@classytic/payroll';
+
+const result = calculateShiftCompliance({
+  policy: DEFAULT_ATTENDANCE_POLICY,
+  baseSalary: 5000,
+  shiftData: {
+    lateArrivals: [{ minutes: 15 }],
+    overtime: [{ hours: 2, type: 'weekday' }],
+  },
+});
+
+console.log(result.penalties);  // Late penalties
+console.log(result.bonuses);    // Overtime bonuses
+console.log(result.netAdjustment);
+```
+
+## Configuration
+
+```typescript
+const payroll = createPayrollInstance()
+  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+  .withConfig({
+    currency: 'USD',
+    payroll: {
+      attendanceIntegration: true,
+      autoCreateTransaction: true,
+    },
+    leave: {
+      enabled: true,
+      defaultBalances: { annual: 20, sick: 10 },
+    },
+  })
+  .build();
+```
+
+## Timeline Audit
+
+Integrate with `@classytic/mongoose-timeline-audit` for WHO/WHAT/WHEN tracking:
+
+```typescript
+import timelineAuditPlugin from '@classytic/mongoose-timeline-audit';
+import { EMPLOYEE_TIMELINE_CONFIG, PAYROLL_EVENTS } from '@classytic/payroll';
+
+employeeSchema.plugin(timelineAuditPlugin, EMPLOYEE_TIMELINE_CONFIG);
+
+payroll.on('employee:hired', async ({ data }) => {
+  const employee = await Employee.findById(data.employee.id);
+  employee.addTimelineEvent(
+    PAYROLL_EVENTS.EMPLOYEE.HIRED,
+    `Hired as ${data.employee.position}`,
+    request
+  );
+  await employee.save();
+});
+```
+
+## TypeScript
+
+```typescript
+import type {
+  EmployeeDocument,
+  PayrollRecordDocument,
+  LeaveRequestDocument,
+  Compensation,
+  PayrollBreakdown,
+} from '@classytic/payroll';
+```
+
+## Schemas & Indexes
+
+The package exports schema creators and recommended indexes:
+
+```typescript
+import {
+  createEmployeeSchema,
+  createPayrollRecordSchema,
+  applyEmployeeIndexes,
+  applyPayrollRecordIndexes,
+} from '@classytic/payroll/schemas';
+
+// Create schemas
+const employeeSchema = createEmployeeSchema();
+const payrollRecordSchema = createPayrollRecordSchema();
+
+// Apply recommended indexes (optional)
+applyEmployeeIndexes(employeeSchema);
+applyPayrollRecordIndexes(payrollRecordSchema);
+```
+
+**Note on duplicate prevention**: The package handles duplicate payroll detection at the application level (idempotency cache + existing record checks). No unique index is enforced by default, giving you control over your indexing strategy.
+
+If you need DB-level uniqueness:
+
+```typescript
+// Add your own unique index if needed
+payrollRecordSchema.index(
+  { organizationId: 1, employeeId: 1, 'period.month': 1, 'period.year': 1 },
+  { unique: true }
+);
+```
+
+## Mongokit Integration
+
+The payroll package is built on [@classytic/mongokit](https://github.com/classytic/mongokit) for powerful repository patterns and plugins.
+
+### Audit Trail Plugin
+
+Automatically track who created/updated records with the built-in audit plugin:
+
+```typescript
+import { Repository } from '@classytic/mongokit';
+import { payrollAuditPlugin } from '@classytic/payroll';
+import { EmployeeModel } from './models';
+
+// Create repository with audit plugin
+const employeeRepo = new Repository(EmployeeModel, [
+  payrollAuditPlugin({
+    userId: currentUser._id,
+    userName: currentUser.name,
+    organizationId: orgId,
+  }),
+]);
+
+// All creates/updates now auto-capture audit fields
+await employeeRepo.create({
+  employment: { email: 'dev@example.com' },
+  compensation: { baseSalary: 80000 },
+  // createdBy, createdAt automatically added
+});
+
+await employeeRepo.update(employeeId, {
+  $set: { 'employment.position': 'Senior' },
+  // updatedBy, updatedAt automatically added
+});
+```
+
+### Available Audit Plugins
+
+```typescript
+import {
+  payrollAuditPlugin,    // Tracks creates & updates
+  readAuditPlugin,       // Tracks read access (compliance)
+  fullAuditPlugin,       // Combines both + comprehensive events
+} from '@classytic/payroll';
+
+// Full audit with compliance tracking
+const repo = new Repository(PayrollRecordModel, [
+  fullAuditPlugin({
+    userId: currentUser._id,
+    organizationId: orgId,
+  }),
+]);
+```
+
+### Custom Mongokit Plugins
+
+Create your own plugins for cross-cutting concerns:
+
+```typescript
+import type { Repository } from '@classytic/mongokit';
+
+// Example: Auto-encrypt sensitive fields
+function encryptionPlugin(secretKey: string) {
+  return (repo: Repository) => {
+    repo.on('before:create', async (ctx) => {
+      if (ctx.data.ssn) {
+        ctx.data.ssn = encrypt(ctx.data.ssn, secretKey);
+      }
+    });
+
+    repo.on('after:getById', async (ctx) => {
+      if (ctx.result?.ssn) {
+        ctx.result.ssn = decrypt(ctx.result.ssn, secretKey);
+      }
+    });
+  };
+}
+
+// Apply to repository
+const repo = new Repository(EmployeeModel, [
+  encryptionPlugin(process.env.SECRET_KEY),
+  payrollAuditPlugin({ userId, organizationId }),
+]);
+```
+
+### Transaction Management
+
+Mongokit provides clean transaction handling:
+
+```typescript
+import { Repository } from '@classytic/mongokit';
+
+const payrollRepo = new Repository(PayrollRecordModel);
+
+// Automatic transaction management
+const result = await payrollRepo.withTransaction(async (session) => {
+  // All operations use the same session
+  const payroll = await payrollRepo.create(payrollData, { session });
+  const transaction = await transactionRepo.create(txData, { session });
+
+  // Automatic commit on success, rollback on error
+  return { payroll, transaction };
+});
+```
+
+### Type-Safe Utilities
+
+Use the new type guards for cleaner code:
+
+```typescript
+import {
+  getEmployeeEmail,
+  getEmployeeName,
+  isGuestEmployee,
+  isDuplicateKeyError,
+  parseDuplicateKeyError,
+} from '@classytic/payroll';
+
+// Type-safe employee identity access
+const email = getEmployeeEmail(employee); // Works for guest & user-linked
+const name = getEmployeeName(employee);   // Fallback to employeeId
+
+if (isGuestEmployee(employee)) {
+  console.log('Guest employee:', employee.employeeId);
+}
+
+// Type-safe error handling
+try {
+  await payroll.hire({ ... });
+} catch (error) {
+  if (isDuplicateKeyError(error)) {
+    const field = parseDuplicateKeyError(error);
+    console.error(`Duplicate ${field}`);
+  }
+}
+```
+
+## Security
+
+- **Multi-tenant isolation**: All queries scoped by `organizationId`
+- **Repository plugin**: Auto-injects tenant filter on all operations
+- **Secure lookups**: `findEmployeeSecure()` enforces org boundaries
+- **State machines**: Prevent invalid status transitions
+
+## License
+
+MIT