@classytic/payroll 1.0.0

package/src/hrm.orchestrator.js

@@ -0,0 +1,139 @@
+import * as EmploymentManager from './core/employment.manager.js';
+import * as CompensationManager from './core/compensation.manager.js';
+import * as PayrollManager from './core/payroll.manager.js';
+import logger from './utils/logger.js';
+
+class HRMOrchestrator {
+  constructor() {
+    this._models = null;
+    this._initialized = false;
+  }
+
+  configure({ EmployeeModel, PayrollRecordModel, TransactionModel, AttendanceModel = null }) {
+    if (!EmployeeModel || !PayrollRecordModel || !TransactionModel) {
+      throw new Error('EmployeeModel, PayrollRecordModel, and TransactionModel are required');
+    }
+
+    this._models = { EmployeeModel, PayrollRecordModel, TransactionModel, AttendanceModel };
+    this._initialized = true;
+
+    logger.info('HRM Orchestrator configured', {
+      hasEmployeeModel: !!EmployeeModel,
+      hasPayrollRecordModel: !!PayrollRecordModel,
+      hasTransactionModel: !!TransactionModel,
+      hasAttendanceModel: !!AttendanceModel,
+    });
+  }
+
+  _ensureInitialized() {
+    if (!this._initialized) {
+      throw new Error(
+        'HRM Orchestrator not initialized. ' +
+        'Call initializeHRM({ EmployeeModel, PayrollRecordModel, TransactionModel }) in bootstrap.'
+      );
+    }
+  }
+
+  isInitialized() {
+    return this._initialized;
+  }
+
+  async hire(params) {
+    this._ensureInitialized();
+    return await EmploymentManager.hireEmployee({ ...this._models, ...params });
+  }
+
+  async updateEmployment(params) {
+    this._ensureInitialized();
+    return await EmploymentManager.updateEmployment({ ...this._models, ...params });
+  }
+
+  async terminate(params) {
+    this._ensureInitialized();
+    return await EmploymentManager.terminateEmployee({ ...this._models, ...params });
+  }
+
+  async reHire(params) {
+    this._ensureInitialized();
+    return await EmploymentManager.reHireEmployee({ ...this._models, ...params });
+  }
+
+  async listEmployees(params) {
+    this._ensureInitialized();
+    return await EmploymentManager.getEmployeeList({ ...this._models, ...params });
+  }
+
+  async getEmployee(params) {
+    this._ensureInitialized();
+    return await EmploymentManager.getEmployeeById({ ...this._models, ...params });
+  }
+
+  async updateSalary(params) {
+    this._ensureInitialized();
+    return await CompensationManager.updateSalary({ ...this._models, ...params });
+  }
+
+  async addAllowance(params) {
+    this._ensureInitialized();
+    return await CompensationManager.addAllowance({ ...this._models, ...params });
+  }
+
+  async removeAllowance(params) {
+    this._ensureInitialized();
+    return await CompensationManager.removeAllowance({ ...this._models, ...params });
+  }
+
+  async addDeduction(params) {
+    this._ensureInitialized();
+    return await CompensationManager.addDeduction({ ...this._models, ...params });
+  }
+
+  async removeDeduction(params) {
+    this._ensureInitialized();
+    return await CompensationManager.removeDeduction({ ...this._models, ...params });
+  }
+
+  async updateBankDetails(params) {
+    this._ensureInitialized();
+    return await CompensationManager.updateBankDetails({ ...this._models, ...params });
+  }
+
+  async processSalary(params) {
+    this._ensureInitialized();
+    return await PayrollManager.processSalary({ ...this._models, ...params });
+  }
+
+  async processBulkPayroll(params) {
+    this._ensureInitialized();
+    return await PayrollManager.processBulkPayroll({ ...this._models, ...params });
+  }
+
+  async payrollHistory(params) {
+    this._ensureInitialized();
+    return await PayrollManager.getPayrollHistory({ ...this._models, ...params });
+  }
+
+  async payrollSummary(params) {
+    this._ensureInitialized();
+    return await PayrollManager.getPayrollSummary({ ...this._models, ...params });
+  }
+
+  async exportPayroll(params) {
+    this._ensureInitialized();
+    return await PayrollManager.exportPayrollData({ ...this._models, ...params });
+  }
+
+  getEmployeeModel() {
+    this._ensureInitialized();
+    return this._models.EmployeeModel;
+  }
+
+  getPayrollRecordModel() {
+    this._ensureInitialized();
+    return this._models.PayrollRecordModel;
+  }
+}
+
+export const hrmOrchestrator = new HRMOrchestrator();
+export const hrm = hrmOrchestrator;
+export default hrm;

package/src/index.js

@@ -0,0 +1,172 @@
+export { initializeHRM, isInitialized } from './init.js';
+
+// Logger configuration (for custom logger injection)
+export { setLogger } from './utils/logger.js';
+
+export {
+  EMPLOYMENT_TYPE,
+  EMPLOYMENT_TYPE_VALUES,
+  EMPLOYEE_STATUS,
+  EMPLOYEE_STATUS_VALUES,
+  DEPARTMENT,
+  DEPARTMENT_VALUES,
+  PAYMENT_FREQUENCY,
+  PAYMENT_FREQUENCY_VALUES,
+  PAYMENT_METHOD,
+  PAYMENT_METHOD_VALUES,
+  ALLOWANCE_TYPE,
+  ALLOWANCE_TYPE_VALUES,
+  DEDUCTION_TYPE,
+  DEDUCTION_TYPE_VALUES,
+  PAYROLL_STATUS,
+  PAYROLL_STATUS_VALUES,
+  TERMINATION_REASON,
+  TERMINATION_REASON_VALUES,
+  HRM_TRANSACTION_CATEGORIES,
+  HRM_CATEGORY_VALUES,
+  isHRMManagedCategory,
+} from './enums.js';
+
+export {
+  HRM_CONFIG,
+  SALARY_BANDS,
+  TAX_BRACKETS,
+  ORG_ROLES,
+  ORG_ROLE_KEYS,
+  ROLE_MAPPING,
+  calculateTax,
+  getSalaryBand,
+  determineOrgRole,
+} from './config.js';
+
+export {
+  employmentFields,
+  allowanceSchema,
+  deductionSchema,
+  compensationSchema,
+  workScheduleSchema,
+  bankDetailsSchema,
+  employmentHistorySchema,
+  payrollStatsSchema,
+} from './schemas/employment.schema.js';
+
+export { employeePlugin } from './plugins/employee.plugin.js';
+
+export { default as PayrollRecord } from './models/payroll-record.model.js';
+
+export { hrm, hrmOrchestrator } from './hrm.orchestrator.js';
+
+import { hrm as hrmDefault } from './hrm.orchestrator.js';
+export default hrmDefault;
+
+// ============================================
+// Pure Utilities - Testable, Reusable Functions
+// ============================================
+
+export {
+  addDays,
+  addMonths,
+  diffInDays,
+  diffInMonths,
+  startOfMonth,
+  endOfMonth,
+  startOfYear,
+  endOfYear,
+  isWeekday,
+  isWeekend,
+  getPayPeriod,
+  getCurrentPeriod,
+  calculateProbationEnd,
+  formatDateForDB,
+  parseDBDate,
+} from './utils/date.utils.js';
+
+export {
+  sum,
+  sumBy,
+  sumAllowances,
+  sumDeductions,
+  calculateGross,
+  calculateNet,
+  applyPercentage,
+  calculatePercentage,
+  createAllowanceCalculator,
+  createDeductionCalculator,
+  calculateTotalCompensation,
+  pipe,
+  compose,
+} from './utils/calculation.utils.js';
+
+export {
+  isActive,
+  isOnLeave,
+  isSuspended,
+  isTerminated,
+  isEmployed,
+  canReceiveSalary,
+  hasCompensation,
+  required,
+  minValue,
+  maxValue,
+  isInRange,
+  isPositive,
+  isValidStatus,
+  isValidEmploymentType,
+  compose as composeValidators,
+} from './utils/validation.utils.js';
+
+// ============================================
+// Query Builders - Fluent API for MongoDB
+// ============================================
+
+export {
+  QueryBuilder,
+  EmployeeQueryBuilder,
+  PayrollQueryBuilder,
+  employee,
+  payroll,
+  toObjectId,
+} from './utils/query-builders.js';
+
+// ============================================
+// Factory Methods - Clean Object Creation
+// ============================================
+
+export {
+  EmployeeFactory,
+  EmployeeBuilder,
+  createEmployee,
+} from './factories/employee.factory.js';
+
+export {
+  PayrollFactory,
+  PayrollBuilder,
+  BatchPayrollFactory,
+  createPayroll,
+} from './factories/payroll.factory.js';
+
+export {
+  CompensationFactory,
+  CompensationBuilder,
+  CompensationPresets,
+  createCompensation,
+} from './factories/compensation.factory.js';
+
+// ============================================
+// Service Layer - Clean Abstractions with DI
+// ============================================
+
+export {
+  EmployeeService,
+  createEmployeeService,
+} from './services/employee.service.js';
+
+export {
+  PayrollService,
+  createPayrollService,
+} from './services/payroll.service.js';
+
+export {
+  CompensationService,
+  createCompensationService,
+} from './services/compensation.service.js';

package/src/init.js

@@ -0,0 +1,41 @@
+import { hrm } from './hrm.orchestrator.js';
+import logger, { setLogger } from './utils/logger.js';
+
+let initialized = false;
+
+export function initializeHRM({ EmployeeModel, PayrollRecordModel, TransactionModel, AttendanceModel = null, logger: customLogger }) {
+  // Allow users to inject their own logger
+  if (customLogger) {
+    setLogger(customLogger);
+  }
+
+  if (initialized) {
+    logger.warn('HRM already initialized, skipping');
+    return;
+  }
+
+  if (!EmployeeModel || !PayrollRecordModel || !TransactionModel) {
+    throw new Error(
+      'HRM initialization requires EmployeeModel, PayrollRecordModel, and TransactionModel'
+    );
+  }
+
+  hrm.configure({
+    EmployeeModel,
+    PayrollRecordModel,
+    TransactionModel,
+    AttendanceModel,
+  });
+
+  initialized = true;
+
+  logger.info('HRM library initialized', {
+    hasAttendanceIntegration: !!AttendanceModel,
+  });
+}
+
+export function isInitialized() {
+  return initialized;
+}
+
+export default initializeHRM;

package/src/models/payroll-record.model.js

@@ -0,0 +1,126 @@
+import mongoose from 'mongoose';
+import mongoosePaginate from 'mongoose-paginate-v2';
+import aggregatePaginate from 'mongoose-aggregate-paginate-v2';
+import { PAYROLL_STATUS_VALUES } from '../enums.js';
+import { HRM_CONFIG } from '../config.js';
+
+const { Schema } = mongoose;
+
+const payrollBreakdownSchema = new Schema({
+  baseAmount: { type: Number, required: true, min: 0 },
+
+  allowances: [{
+    type: String,
+    amount: { type: Number, min: 0 },
+    taxable: { type: Boolean, default: true },
+  }],
+
+  deductions: [{
+    type: String,
+    amount: { type: Number, min: 0 },
+    description: String,
+  }],
+
+  grossSalary: { type: Number, required: true, min: 0 },
+  netSalary: { type: Number, required: true, min: 0 },
+
+  workingDays: { type: Number, min: 0 },
+  actualDays: { type: Number, min: 0 },
+  proRatedAmount: { type: Number, default: 0, min: 0 },
+  attendanceDeduction: { type: Number, default: 0, min: 0 },
+  overtimeAmount: { type: Number, default: 0, min: 0 },
+  bonusAmount: { type: Number, default: 0, min: 0 },
+}, { _id: false });
+
+const periodSchema = new Schema({
+  month: { type: Number, required: true, min: 1, max: 12 },
+  year: { type: Number, required: true, min: 2020 },
+  startDate: { type: Date, required: true },
+  endDate: { type: Date, required: true },
+  payDate: { type: Date, required: true },
+}, { _id: false });
+
+const payrollRecordSchema = new Schema({
+  organizationId: { type: Schema.Types.ObjectId, ref: 'Organization', required: true, index: true },
+  employeeId: { type: Schema.Types.ObjectId, required: true, index: true },
+  userId: { type: Schema.Types.ObjectId, ref: 'User', index: true },
+
+  period: { type: periodSchema, required: true },
+
+  breakdown: { type: payrollBreakdownSchema, required: true },
+
+  transactionId: { type: Schema.Types.ObjectId, ref: 'Transaction' },
+
+  status: {
+    type: String,
+    enum: PAYROLL_STATUS_VALUES,
+    default: 'pending',
+    index: true
+  },
+
+  paidAt: { type: Date },
+  paymentMethod: { type: String },
+
+  processedBy: { type: Schema.Types.ObjectId, ref: 'User' },
+  notes: { type: String },
+  payslipUrl: { type: String },
+
+  exported: { type: Boolean, default: false },
+  exportedAt: { type: Date },
+}, {
+  timestamps: true,
+  roleBasedSelect: {
+    user: '-notes -processedBy',
+    admin: '',
+    superadmin: '',
+  }
+});
+
+payrollRecordSchema.index({ organizationId: 1, employeeId: 1, 'period.month': 1, 'period.year': 1 }, { unique: true });
+payrollRecordSchema.index({ organizationId: 1, 'period.year': 1, 'period.month': 1 });
+payrollRecordSchema.index({ employeeId: 1, 'period.year': -1, 'period.month': -1 });
+payrollRecordSchema.index({ status: 1, createdAt: -1 });
+payrollRecordSchema.index({ organizationId: 1, status: 1, 'period.payDate': 1 });
+
+payrollRecordSchema.index(
+  { createdAt: 1 },
+  {
+    expireAfterSeconds: HRM_CONFIG.dataRetention.payrollRecordsTTL,
+    partialFilterExpression: { exported: true }
+  }
+);
+
+payrollRecordSchema.virtual('totalAmount').get(function() {
+  return this.breakdown?.netSalary || 0;
+});
+
+payrollRecordSchema.virtual('isPaid').get(function() {
+  return this.status === 'paid';
+});
+
+payrollRecordSchema.virtual('periodLabel').get(function() {
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  return `${months[this.period.month - 1]} ${this.period.year}`;
+});
+
+payrollRecordSchema.methods.markAsPaid = function(transactionId, paidAt = new Date()) {
+  this.status = 'paid';
+  this.transactionId = transactionId;
+  this.paidAt = paidAt;
+};
+
+payrollRecordSchema.methods.markAsExported = function() {
+  this.exported = true;
+  this.exportedAt = new Date();
+};
+
+payrollRecordSchema.methods.canBeDeleted = function() {
+  return this.exported && this.status === 'paid';
+};
+
+payrollRecordSchema.plugin(mongoosePaginate);
+payrollRecordSchema.plugin(aggregatePaginate);
+
+const PayrollRecord = mongoose.models.PayrollRecord || mongoose.model('PayrollRecord', payrollRecordSchema);
+
+export default PayrollRecord;

package/src/plugins/employee.plugin.js

@@ -0,0 +1,157 @@
+import logger from '../utils/logger.js';
+import { diffInDays } from '../utils/date.utils.js';
+import { sumDeductions } from '../utils/calculation.utils.js';
+import {
+  isActive,
+  isTerminated,
+  canReceiveSalary as canReceiveSalaryUtil,
+} from '../utils/validation.utils.js';
+import { CompensationFactory } from '../factories/compensation.factory.js';
+
+export function employeePlugin(schema, options = {}) {
+
+  schema.virtual('currentSalary').get(function() {
+    return this.compensation?.netSalary || 0;
+  });
+
+  schema.virtual('isActive').get(function() {
+    return isActive(this);
+  });
+
+  schema.virtual('isTerminated').get(function() {
+    return isTerminated(this);
+  });
+
+  schema.virtual('yearsOfService').get(function() {
+    const end = this.terminationDate || new Date();
+    const days = diffInDays(this.hireDate, end);
+    return Math.max(0, Math.floor((days / 365.25) * 10) / 10);
+  });
+
+  schema.virtual('isOnProbation').get(function() {
+    if (!this.probationEndDate) return false;
+    return new Date() < this.probationEndDate;
+  });
+
+  schema.methods.calculateSalary = function() {
+    if (!this.compensation) {
+      return { gross: 0, deductions: 0, net: 0 };
+    }
+
+    const breakdown = CompensationFactory.calculateBreakdown(this.compensation);
+
+    return {
+      gross: breakdown.grossAmount,
+      deductions: sumDeductions(breakdown.deductions),
+      net: breakdown.netAmount
+    };
+  };
+
+  schema.methods.updateSalaryCalculations = function() {
+    const calculated = this.calculateSalary();
+    this.compensation.grossSalary = calculated.gross;
+    this.compensation.netSalary = calculated.net;
+    this.compensation.lastModified = new Date();
+  };
+
+  schema.methods.canReceiveSalary = function() {
+    return (
+      this.status === 'active' &&
+      this.compensation?.baseAmount > 0 &&
+      (!options.requireBankDetails || this.bankDetails?.accountNumber)
+    );
+  };
+
+  schema.methods.addAllowance = function(type, amount, taxable = true) {
+    if (!this.compensation.allowances) {
+      this.compensation.allowances = [];
+    }
+    this.compensation.allowances.push({ type, amount, taxable });
+    this.updateSalaryCalculations();
+  };
+
+  schema.methods.addDeduction = function(type, amount, auto = false, description = '') {
+    if (!this.compensation.deductions) {
+      this.compensation.deductions = [];
+    }
+    this.compensation.deductions.push({ type, amount, auto, description });
+    this.updateSalaryCalculations();
+  };
+
+  schema.methods.removeAllowance = function(type) {
+    if (!this.compensation.allowances) return;
+    this.compensation.allowances = this.compensation.allowances.filter(a => a.type !== type);
+    this.updateSalaryCalculations();
+  };
+
+  schema.methods.removeDeduction = function(type) {
+    if (!this.compensation.deductions) return;
+    this.compensation.deductions = this.compensation.deductions.filter(d => d.type !== type);
+    this.updateSalaryCalculations();
+  };
+
+  schema.methods.terminate = function(reason, terminationDate = new Date()) {
+    if (this.status === 'terminated') {
+      throw new Error('Employee already terminated');
+    }
+
+    if (!this.employmentHistory) {
+      this.employmentHistory = [];
+    }
+
+    this.employmentHistory.push({
+      hireDate: this.hireDate,
+      terminationDate,
+      reason,
+      finalSalary: this.compensation?.netSalary || 0,
+      position: this.position,
+      department: this.department,
+    });
+
+    this.status = 'terminated';
+    this.terminationDate = terminationDate;
+
+    logger.info('Employee terminated', {
+      employeeId: this.employeeId,
+      organizationId: this.organizationId,
+      reason,
+    });
+  };
+
+  schema.methods.reHire = function(hireDate = new Date(), position = null, department = null) {
+    if (this.status !== 'terminated') {
+      throw new Error('Can only re-hire terminated employees');
+    }
+
+    this.status = 'active';
+    this.hireDate = hireDate;
+    this.terminationDate = null;
+
+    if (position) this.position = position;
+    if (department) this.department = department;
+
+    logger.info('Employee re-hired', {
+      employeeId: this.employeeId,
+      organizationId: this.organizationId,
+    });
+  };
+
+  schema.pre('save', function(next) {
+    if (this.isModified('compensation')) {
+      this.updateSalaryCalculations();
+    }
+    next();
+  });
+
+  schema.index({ organizationId: 1, employeeId: 1 }, { unique: true });
+  schema.index({ userId: 1, organizationId: 1 }, { unique: true });
+  schema.index({ organizationId: 1, status: 1 });
+  schema.index({ organizationId: 1, department: 1 });
+  schema.index({ organizationId: 1, 'compensation.netSalary': -1 });
+
+  logger.debug('Employee plugin applied', {
+    requireBankDetails: options.requireBankDetails || false,
+  });
+}
+
+export default employeePlugin;