@classytic/payroll 2.7.5 → 2.8.0

package/README.md

@@ -1,10 +1,6 @@
 # @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)
+HRM & Payroll for MongoDB. Multi-tenant, event-driven, type-safe.
 
 ## Install
 
@@ -21,130 +17,190 @@ const payroll = createPayrollInstance()
   .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
   .build();
 
-// Hire employee
+// Hire
 await payroll.hire({
   organizationId,
-  employment: { email: 'dev@example.com', position: 'Engineer' },
-  compensation: { baseSalary: 80000, currency: 'USD' },
+  employment: { email: 'dev@example.com', position: 'Engineer', hireDate: new Date() },
+  compensation: { baseAmount: 80000, currency: 'USD', frequency: 'monthly' },
 });
 
 // Process salary
 await payroll.processSalary({
   organizationId,
   employeeId,
-  period: { month: 1, year: 2024 },
+  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
+## Package Exports
 
 | Entry Point | Description |
 |-------------|-------------|
-| `@classytic/payroll` | Main API (Payroll class, types, errors) |
-| `@classytic/payroll/schemas` | Mongoose schemas for extending |
+| `@classytic/payroll` | Main API: Payroll class, types, schemas, errors |
+| `@classytic/payroll/calculators` | Pure calculation functions (no DB required) |
 | `@classytic/payroll/utils` | Date, money, validation utilities |
-| `@classytic/payroll/calculators` | Pure calculation functions (no DB) |
+| `@classytic/payroll/schemas` | Mongoose schema factories |
+
+---
 
-## Employee Management
+## Employee Operations
 
 ```typescript
 // Hire
-await payroll.hire({ organizationId, employment, compensation });
+await payroll.hire({
+  organizationId,
+  employment: { email, employeeId, position, department, hireDate },
+  compensation: { baseAmount, currency, frequency },
+});
 
 // Get employee
-const employee = await payroll.getEmployee({ employeeId, organizationId });
+const emp = 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
+// Update employment
+await payroll.updateEmployment({
+  employeeId,
   organizationId,
-  mode: 'employeeId',   // 'userId' | 'employeeId' | 'email' | 'any'
+  updates: { position: 'Senior Engineer', department: 'engineering' },
 });
 
-// Update
-await payroll.updateEmployment({ employeeId, updates: { position: 'Lead' } });
-
 // Terminate
-await payroll.terminate({ employeeId, terminationDate, reason: 'resignation' });
+await payroll.terminate({
+  employeeId,
+  organizationId,
+  terminationDate: new Date(),
+  reason: 'resignation',
+});
 
 // Re-hire
-await payroll.reHire({ employeeId, hireDate: new Date() });
+await payroll.reHire({ employeeId, organizationId, hireDate: new Date() });
 ```
 
-## Listing Employees
-
-Employee listing/queries are done at app level using your models directly:
+## Compensation
 
 ```typescript
-// Use your EmployeeModel with mongokit or mongoose directly
-const employees = await EmployeeModel.find({
+// Update salary
+await payroll.updateSalary({
+  employeeId,
   organizationId,
-  'employment.status': 'active'
+  compensation: { baseAmount: 90000 },
+  effectiveFrom: new Date(),
 });
 
-// Or with mongokit repository
-const repo = createRepository(EmployeeModel);
-const result = await repo.getAll({
-  filters: { organizationId, 'employment.status': 'active' },
-  page: 1,
-  limit: 100,
+// Add allowance
+await payroll.addAllowance({
+  employeeId,
+  organizationId,
+  allowance: {
+    type: 'housing',    // 'housing' | 'transport' | 'meal' | 'mobile' | 'medical' | 'bonus' | 'other'
+    amount: 2000,
+    taxable: true,
+  },
+});
+
+// Add deduction
+await payroll.addDeduction({
+  employeeId,
+  organizationId,
+  deduction: {
+    type: 'provident_fund',  // 'tax' | 'loan' | 'advance' | 'provident_fund' | 'insurance'
+    amount: 500,
+    auto: true,
+  },
+});
+
+// Update bank details
+await payroll.updateBankDetails({
+  employeeId,
+  organizationId,
+  bankDetails: { accountNumber, bankName, routingNumber },
 });
 ```
 
-## Compensation
+### Payment Frequencies
 
-```typescript
-// Update salary
-await payroll.updateSalary({ employeeId, compensation: { baseSalary: 90000 } });
+Supports multiple payment frequencies with automatic tax annualization:
 
-// Add allowance
-await payroll.addAllowance({ employeeId, allowance: { type: 'housing', amount: 2000 } });
+| Frequency | baseAmount | Periods/Year | Example ($104k/year) |
+|-----------|------------|--------------|----------------------|
+| `monthly` | Monthly salary | 12 | $8,666.67/month |
+| `bi_weekly` | Bi-weekly wage | 26 | $4,000/bi-week |
+| `weekly` | Weekly wage | 52 | $2,000/week |
+| `daily` | Daily rate | 365 | $285/day |
+| `hourly` | Hourly rate | 2080 | $50/hour |
 
-// Add deduction
-await payroll.addDeduction({ employeeId, deduction: { type: 'loan', amount: 500 } });
-```
+Tax is calculated consistently: same annual income = same annual tax, regardless of frequency.
 
-## Bulk Processing
+## Payroll Processing
 
 ```typescript
-await payroll.processBulkPayroll({
+// Single employee
+const result = await payroll.processSalary({
   organizationId,
-  period: { month: 1, year: 2024 },
-  onProgress: ({ current, total }) => console.log(`${current}/${total}`),
+  employeeId,
+  month: 1,
+  year: 2024,
+  paymentDate: new Date(),
+  paymentMethod: 'bank',
+  payrollRunType: 'regular',  // 'regular' | 'supplemental' | 'retroactive' | 'off-cycle'
+});
+// Returns: { employee, payrollRecord, transaction }
+
+// Bulk processing
+const bulk = await payroll.processBulkPayroll({
+  organizationId,         // Optional in single-tenant mode or with context.organizationId
+  month: 1,
+  year: 2024,
+  employeeIds: [],        // Optional: specific employees (default: all active + on_leave)
+  batchSize: 50,
+  concurrency: 5,
+  onProgress: (p) => console.log(`${p.percentage}%`),
 });
+// Returns: { successCount, failCount, totalAmount, successful[], failed[] }
 ```
 
-## Leave Management
+### Duplicate Protection
+
+The package provides database-level duplicate protection via a unique compound index:
 
 ```typescript
-// Request leave
-await payroll.requestLeave({
-  employeeId,
+// Unique index on: (organizationId, employeeId, period.month, period.year, payrollRunType)
+// With partial filter: { isVoided: { $eq: false } }
+
+// This allows:
+// - One active record per employee per period per run type
+// - Multiple run types in same period (regular + supplemental)
+// - Re-processing after voiding (requires restorePayroll() first)
+// - Re-processing after reversing
+```
+
+**Important**: Voided records require `restorePayroll()` before re-processing. Voided is a terminal state that preserves audit trail.
+
+## Two-Phase Export
+
+Safe export that only marks records after downstream confirms receipt:
+
+```typescript
+// Phase 1: Prepare (records NOT marked)
+const { records, exportId } = await payroll.prepareExport({
   organizationId,
-  leaveType: 'annual',
-  startDate: new Date('2024-01-15'),
-  endDate: new Date('2024-01-17'),
+  startDate: new Date('2024-01-01'),
+  endDate: new Date('2024-01-31'),
 });
 
-// Approve
-await payroll.approveLeave({ leaveRequestId, approverId });
+// Send to external system...
+
+// Phase 2a: Confirm success (marks records)
+await payroll.confirmExport({ organizationId, exportId });
+
+// Phase 2b: Cancel if failed (records stay unmarked)
+await payroll.cancelExport({ organizationId, exportId, reason: 'API error' });
 ```
 
 ## Void / Reverse / Restore
 
-Payroll corrections with full state tracking:
-
 ```typescript
-// Void unpaid payroll
+// Void unpaid payroll (pending, processing, failed)
 await payroll.voidPayroll({
   organizationId,
   payrollRecordId,
@@ -158,7 +214,7 @@ await payroll.reversePayroll({
   reason: 'Duplicate payment',
 });
 
-// Restore voided payroll
+// Restore voided payroll (blocked if replacement exists)
 await payroll.restorePayroll({
   organizationId,
   payrollRecordId,
@@ -166,7 +222,7 @@ await payroll.restorePayroll({
 });
 ```
 
-**State Flow:**
+**Status Flow:**
 ```
 PENDING → PROCESSING → PAID → REVERSED
    ↓          ↓
@@ -175,350 +231,304 @@ PENDING → PROCESSING → PAID → REVERSED
        PENDING (restore)
 ```
 
-## Events
+## Leave Management
 
 ```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}`);
+// Request leave
+await payroll.requestLeave({
+  employeeId,
+  organizationId,
+  leaveType: 'annual',  // 'annual' | 'sick' | 'unpaid' | 'maternity' | 'paternity'
+  startDate: new Date('2024-03-01'),
+  endDate: new Date('2024-03-05'),
+  reason: 'Vacation',
 });
-```
 
-## Webhooks
+// Approve
+await payroll.approveLeave({ leaveRequestId, organizationId, approverId: managerId });
 
-```typescript
-await payroll.registerWebhook({
+// Reject
+await payroll.rejectLeave({
+  leaveRequestId,
   organizationId,
-  url: 'https://api.example.com/webhooks',
-  events: ['payroll:processed'],
-  secret: 'your-secret',
+  rejectedBy: managerId,
+  rejectionReason: 'Insufficient leave balance',
 });
+
+// Get balance
+const balance = await payroll.getLeaveBalance({ employeeId, organizationId });
+// { annual: { total: 20, used: 5, remaining: 15 }, sick: {...}, ... }
 ```
 
-## Tenant Modes
+---
 
-### Single-Tenant (Recommended for most apps)
+## Pure Calculators (No DB Required)
 
-For apps serving one organization:
+Import from `@classytic/payroll/calculators` for client-side or serverless:
 
 ```typescript
-const payroll = createPayrollInstance()
-  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
-  .forSingleTenant({ organizationId: YOUR_ORG_ID, autoInject: true })
-  .build();
+import {
+  calculateSalaryBreakdown,
+  calculateProRating,
+  calculateAttendanceDeduction,
+} from '@classytic/payroll/calculators';
+```
 
-// No organizationId needed - auto-injected
-await payroll.hire({
-  employment: { email: 'dev@example.com', position: 'Engineer' },
-  compensation: { baseSalary: 80000, currency: 'USD' },
-});
+### Salary Breakdown
 
-await payroll.processSalary({
-  employeeId,
-  period: { month: 1, year: 2024 },
+```typescript
+const breakdown = calculateSalaryBreakdown({
+  employee: {
+    hireDate: new Date('2024-01-01'),
+    terminationDate: null,
+    compensation: {
+      baseAmount: 100000,
+      frequency: 'monthly',
+      currency: 'USD',
+      allowances: [
+        { type: 'housing', amount: 20000, taxable: true },
+        { type: 'transport', amount: 5000, taxable: true },
+      ],
+      deductions: [
+        { type: 'provident_fund', amount: 5000, auto: true },
+      ],
+    },
+  },
+  period: {
+    month: 3,
+    year: 2024,
+    startDate: new Date('2024-03-01'),
+    endDate: new Date('2024-03-31'),
+  },
+  attendance: {
+    expectedDays: 22,
+    actualDays: 20,
+  },
+  config: {
+    allowProRating: true,
+    autoDeductions: true,
+    defaultCurrency: 'USD',
+    attendanceIntegration: true,
+  },
+  taxBrackets: [
+    { min: 0, max: 600000, rate: 0 },
+    { min: 600000, max: 1200000, rate: 0.1 },
+    { min: 1200000, max: Infinity, rate: 0.2 },
+  ],
 });
 
-await payroll.getEmployee({ employeeId });
-await payroll.updateEmployment({ employeeId, updates: { position: 'Lead' } });
-await payroll.terminate({ employeeId, terminationDate, reason: 'resignation' });
+// Returns PayrollBreakdown
+{
+  baseAmount: number,
+  allowances: Array<{ type, amount, taxable }>,
+  deductions: Array<{ type, amount, description }>,
+  grossSalary: number,
+  netSalary: number,
+  taxableAmount: number,
+  taxAmount: number,
+  workingDays: number,
+  actualDays: number,
+  proRatedAmount: number,
+  attendanceDeduction: number,
+}
 ```
 
-### Multi-Tenant
-
-For SaaS apps serving multiple organizations:
+### Pro-Rating
 
 ```typescript
-const payroll = createPayrollInstance()
-  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
-  .build();
+import { calculateProRating } from '@classytic/payroll/calculators';
+
+const result = calculateProRating({
+  hireDate: new Date('2024-03-15'),
+  terminationDate: null,
+  periodStart: new Date('2024-03-01'),
+  periodEnd: new Date('2024-03-31'),
+  workingDays: [1, 2, 3, 4, 5],
+  holidays: [],
+});
 
-// organizationId required on all operations
-await payroll.hire({ organizationId, employment, compensation });
-await payroll.processSalary({ organizationId, employeeId, period });
-await payroll.getEmployee({ organizationId, employeeId });
+// Returns ProRatingResult
+{
+  isProRated: true,
+  ratio: 0.545,
+  periodWorkingDays: 22,
+  effectiveWorkingDays: 12,
+  reason: 'new_hire',
+}
 ```
 
-## Pure Calculators
+---
 
-No database required - works in browser/serverless:
+## Events
 
 ```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,
-});
+payroll.on('employee:hired', (payload) => { /* { employee, organizationId } */ });
+payroll.on('employee:terminated', (payload) => { /* { employee, reason } */ });
+payroll.on('salary:processed', (payload) => { /* { payrollRecord, transaction } */ });
+payroll.on('payroll:completed', (payload) => { /* { summary, period } */ });
+payroll.on('payroll:exported', (payload) => { /* { exportId, recordCount } */ });
 ```
 
-## Shift Compliance
-
-Late penalties, overtime bonuses, night differentials:
+## Webhooks
 
 ```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' }],
-  },
+// Register webhook
+payroll.registerWebhook({
+  url: 'https://api.example.com/webhooks',
+  events: ['salary:processed', 'employee:hired'],
+  secret: 'your-secret',
 });
 
-console.log(result.penalties);  // Late penalties
-console.log(result.bonuses);    // Overtime bonuses
-console.log(result.netAdjustment);
+// Verify signature in handler
+const signature = req.headers['x-payroll-signature'];
+const timestamp = req.headers['x-payroll-timestamp'];
+const signedPayload = `${timestamp}.${JSON.stringify(req.body)}`;
+const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
 ```
 
+---
+
 ## Configuration
 
+### Multi-Tenant (Default)
+
 ```typescript
 const payroll = createPayrollInstance()
   .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
   .withConfig({
-    currency: 'USD',
     payroll: {
+      defaultCurrency: 'USD',
       attendanceIntegration: true,
-      autoCreateTransaction: true,
-    },
-    leave: {
-      enabled: true,
-      defaultBalances: { annual: 20, sick: 10 },
+      allowProRating: true,
+      autoDeductions: true,
     },
   })
   .build();
-```
 
-## Timeline Audit
+// organizationId required on all operations
+await payroll.hire({ organizationId, employment, compensation });
+```
 
-Integrate with `@classytic/mongoose-timeline-audit` for WHO/WHAT/WHEN tracking:
+### Single-Tenant
 
 ```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();
-});
+const payroll = createPayrollInstance()
+  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+  .forSingleTenant({ organizationId: YOUR_ORG_ID, autoInject: true })
+  .build();
+
+// organizationId auto-injected
+await payroll.hire({ employment, compensation });
 ```
 
-## TypeScript
+---
+
+## Key Types
 
 ```typescript
 import type {
+  // Documents
   EmployeeDocument,
   PayrollRecordDocument,
   LeaveRequestDocument,
+
+  // Core types
   Compensation,
+  Allowance,
+  Deduction,
   PayrollBreakdown,
+  TaxBracket,
+  BankDetails,
+
+  // Params
+  HireEmployeeParams,
+  ProcessSalaryParams,
+  ProcessBulkPayrollParams,
+  ExportPayrollParams,
+
+  // Results
+  ProcessSalaryResult,
+  BulkPayrollResult,
+
+  // Enums
+  EmployeeStatus,      // 'active' | 'on_leave' | 'suspended' | 'terminated'
+  PayrollStatus,       // 'pending' | 'processing' | 'paid' | 'failed' | 'voided' | 'reversed'
+  PayrollRunType,      // 'regular' | 'supplemental' | 'retroactive' | 'off-cycle'
+  LeaveType,           // 'annual' | 'sick' | 'unpaid' | 'maternity' | 'paternity'
+  AllowanceType,       // 'housing' | 'transport' | 'meal' | 'mobile' | 'medical' | 'bonus' | 'other'
+  DeductionType,       // 'tax' | 'loan' | 'advance' | 'provident_fund' | 'insurance'
+  PaymentFrequency,    // 'monthly' | 'bi_weekly' | 'weekly' | 'daily' | 'hourly'
+  PaymentMethod,       // 'bank' | 'cash' | 'check'
 } from '@classytic/payroll';
 ```
 
-## Schemas & Indexes
+---
 
-The package exports schema creators and recommended indexes:
+## Schemas
 
 ```typescript
 import {
   createEmployeeSchema,
   createPayrollRecordSchema,
-  applyEmployeeIndexes,
-  applyPayrollRecordIndexes,
+  employeeIndexes,
+  payrollRecordIndexes,
 } 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
+// Create with custom fields
+const employeeSchema = createEmployeeSchema({
+  skills: [String],
+  certifications: [{ name: String, date: Date }],
 });
-```
-
-### 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,
-  }),
-]);
+// Apply indexes
+employeeIndexes.forEach(idx => employeeSchema.index(idx.fields, idx.options));
 ```
 
-### Custom Mongokit Plugins
+---
 
-Create your own plugins for cross-cutting concerns:
+## Utilities
 
 ```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);
+import {
+  // Date
+  addDays, addMonths, diffInDays, startOfMonth, endOfMonth,
+  getPayPeriod, getWorkingDaysInMonth,
 
-// 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 });
+  // Money (banker's rounding)
+  roundMoney, percentageOf, prorateAmount,
 
-  // Automatic commit on success, rollback on error
-  return { payroll, transaction };
-});
+  // Query builders
+  toObjectId, isValidObjectId,
+} from '@classytic/payroll/utils';
 ```
 
-### Type-Safe Utilities
+---
 
-Use the new type guards for cleaner code:
+## Error Handling
 
 ```typescript
 import {
-  getEmployeeEmail,
-  getEmployeeName,
-  isGuestEmployee,
-  isDuplicateKeyError,
-  parseDuplicateKeyError,
+  PayrollError,
+  DuplicatePayrollError,
+  EmployeeNotFoundError,
+  NotEligibleError,
+  ValidationError,
 } 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({ ... });
+  await payroll.processSalary({ organizationId, employeeId, month, year });
 } catch (error) {
-  if (isDuplicateKeyError(error)) {
-    const field = parseDuplicateKeyError(error);
-    console.error(`Duplicate ${field}`);
+  if (error instanceof DuplicatePayrollError) {
+    // Already processed for this period + run type
+  } else if (error instanceof EmployeeNotFoundError) {
+    // Employee doesn't exist
+  } else if (error instanceof NotEligibleError) {
+    // Employee not eligible (terminated, etc.)
   }
 }
 ```
 
-## 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