@classytic/payroll 1.0.2 → 2.3.0

package/src/init.js

@@ -1,62 +0,0 @@
-import { hrm } from './hrm.orchestrator.js';
-import logger, { setLogger } from './utils/logger.js';
-
-let initialized = false;
-
-/**
- * Initialize HRM/Payroll framework
- *
- * @param {Object} options - Initialization options
- * @param {Model} options.EmployeeModel - Employee model (required)
- * @param {Model} options.PayrollRecordModel - Payroll record model (required)
- * @param {Model} options.TransactionModel - Transaction model (required)
- * @param {Model} options.AttendanceModel - Optional attendance model for integration
- * @param {Object} options.logger - Optional custom logger
- *
- * @example Multi-Tenant (default)
- * initializeHRM({
- *   EmployeeModel,
- *   PayrollRecordModel,
- *   TransactionModel
- * });
- *
- * @example Single-Tenant
- * // For single-tenant apps, add organizationId with default value in your Employee schema:
- * // organizationId: { type: ObjectId, required: true, default: () => FIXED_ORG_ID }
- */
-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

@@ -1,126 +0,0 @@
-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

@@ -1,164 +0,0 @@
-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,
-    });
-  };
-
-  /**
-   * Pre-save hook to automatically update salary calculations
-   * when compensation is modified.
-   *
-   * Mongoose v9 compatible - uses async function without next callback
-   * - Use throw instead of next(err) for errors
-   * - Use return instead of return next()
-   */
-  schema.pre('save', async function() {
-    if (this.isModified('compensation')) {
-      this.updateSalaryCalculations();
-    }
-  });
-
-  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;

package/src/schemas/employment.schema.js

@@ -1,126 +0,0 @@
-import mongoose from 'mongoose';
-import {
-  EMPLOYMENT_TYPE_VALUES,
-  EMPLOYEE_STATUS_VALUES,
-  DEPARTMENT_VALUES,
-  PAYMENT_FREQUENCY_VALUES,
-  ALLOWANCE_TYPE_VALUES,
-  DEDUCTION_TYPE_VALUES,
-  TERMINATION_REASON_VALUES,
-} from '../enums.js';
-
-const { Schema } = mongoose;
-
-const allowanceSchema = new Schema({
-  type: { type: String, enum: ALLOWANCE_TYPE_VALUES, required: true },
-  amount: { type: Number, required: true, min: 0 },
-  taxable: { type: Boolean, default: true },
-  recurring: { type: Boolean, default: true },
-  effectiveFrom: { type: Date, default: () => new Date() },
-  effectiveTo: { type: Date },
-}, { _id: false });
-
-const deductionSchema = new Schema({
-  type: { type: String, enum: DEDUCTION_TYPE_VALUES, required: true },
-  amount: { type: Number, required: true, min: 0 },
-  auto: { type: Boolean, default: false },
-  recurring: { type: Boolean, default: true },
-  effectiveFrom: { type: Date, default: () => new Date() },
-  effectiveTo: { type: Date },
-  description: { type: String },
-}, { _id: false });
-
-const compensationSchema = new Schema({
-  baseAmount: { type: Number, required: true, min: 0 },
-  frequency: { type: String, enum: PAYMENT_FREQUENCY_VALUES, default: 'monthly' },
-  currency: { type: String, default: 'BDT' },
-
-  allowances: [allowanceSchema],
-  deductions: [deductionSchema],
-
-  grossSalary: { type: Number, default: 0 },
-  netSalary: { type: Number, default: 0 },
-
-  effectiveFrom: { type: Date, default: () => new Date() },
-  lastModified: { type: Date, default: () => new Date() },
-}, { _id: false });
-
-const workScheduleSchema = new Schema({
-  hoursPerWeek: { type: Number, min: 0, max: 168 },
-  hoursPerDay: { type: Number, min: 0, max: 24 },  // 🆕 Standard hours per day (e.g., 8 for full-time, 4 for part-time)
-  workingDays: [{ type: Number, min: 0, max: 6 }],  // Array of days (0=Sunday, 6=Saturday)
-  shiftStart: { type: String },  // e.g., "09:00"
-  shiftEnd: { type: String },    // e.g., "17:00"
-}, { _id: false });
-
-const bankDetailsSchema = new Schema({
-  accountName: { type: String },
-  accountNumber: { type: String },
-  bankName: { type: String },
-  branchName: { type: String },
-  routingNumber: { type: String },
-}, { _id: false });
-
-const employmentHistorySchema = new Schema({
-  hireDate: { type: Date, required: true },
-  terminationDate: { type: Date, required: true },
-  reason: { type: String, enum: TERMINATION_REASON_VALUES },
-  finalSalary: { type: Number },
-  position: { type: String },
-  department: { type: String },
-  notes: { type: String },
-}, { timestamps: true });
-
-const payrollStatsSchema = new Schema({
-  totalPaid: { type: Number, default: 0, min: 0 },
-  lastPaymentDate: { type: Date },
-  nextPaymentDate: { type: Date },
-  paymentsThisYear: { type: Number, default: 0, min: 0 },
-  averageMonthly: { type: Number, default: 0, min: 0 },
-  updatedAt: { type: Date, default: () => new Date() },
-}, { _id: false });
-
-export const employmentFields = {
-  userId: { type: Schema.Types.ObjectId, ref: 'User', required: true },
-  organizationId: { type: Schema.Types.ObjectId, ref: 'Organization', required: true },
-
-  employeeId: { type: String, required: true },
-
-  employmentType: {
-    type: String,
-    enum: EMPLOYMENT_TYPE_VALUES,
-    default: 'full_time'
-  },
-
-  status: {
-    type: String,
-    enum: EMPLOYEE_STATUS_VALUES,
-    default: 'active'
-  },
-
-  department: { type: String, enum: DEPARTMENT_VALUES },
-  position: { type: String, required: true },
-
-  hireDate: { type: Date, required: true },
-  terminationDate: { type: Date },
-  probationEndDate: { type: Date },
-
-  employmentHistory: [employmentHistorySchema],
-
-  compensation: { type: compensationSchema, required: true },
-  workSchedule: workScheduleSchema,
-  bankDetails: bankDetailsSchema,
-  payrollStats: { type: payrollStatsSchema, default: () => ({}) },
-};
-
-export {
-  allowanceSchema,
-  deductionSchema,
-  compensationSchema,
-  workScheduleSchema,
-  bankDetailsSchema,
-  employmentHistorySchema,
-  payrollStatsSchema,
-};
-
-export default employmentFields;

package/src/services/compensation.service.js

@@ -1,231 +0,0 @@
-/**
- * Compensation Service - Beautiful Compensation Management
- * Clean abstraction for salary adjustments and calculations
- */
-
-import {
-  CompensationFactory,
-  CompensationPresets,
-} from '../factories/compensation.factory.js';
-
-export class CompensationService {
-  constructor(EmployeeModel) {
-    this.EmployeeModel = EmployeeModel;
-  }
-
-  async getEmployeeCompensation(employeeId) {
-    const employee = await this.EmployeeModel.findById(employeeId);
-    if (!employee) throw new Error('Employee not found');
-
-    return employee.compensation;
-  }
-
-  async calculateBreakdown(employeeId) {
-    const compensation = await this.getEmployeeCompensation(employeeId);
-    return CompensationFactory.calculateBreakdown(compensation);
-  }
-
-  async updateBaseAmount(employeeId, newAmount, effectiveFrom) {
-    const employee = await this.EmployeeModel.findById(employeeId);
-    if (!employee) throw new Error('Employee not found');
-
-    const updatedCompensation = CompensationFactory.updateBaseAmount(
-      employee.compensation,
-      newAmount,
-      effectiveFrom
-    );
-
-    employee.compensation = updatedCompensation;
-    await employee.save();
-
-    return this.calculateBreakdown(employeeId);
-  }
-
-  async applyIncrement(employeeId, { percentage, amount, effectiveFrom }) {
-    const employee = await this.EmployeeModel.findById(employeeId);
-    if (!employee) throw new Error('Employee not found');
-
-    const updatedCompensation = CompensationFactory.applyIncrement(
-      employee.compensation,
-      { percentage, amount, effectiveFrom }
-    );
-
-    employee.compensation = updatedCompensation;
-    employee.incrementHistory = employee.incrementHistory || [];
-    employee.incrementHistory.push({
-      previousAmount: employee.compensation.baseAmount,
-      newAmount: updatedCompensation.baseAmount,
-      percentage,
-      amount,
-      effectiveFrom: effectiveFrom || new Date(),
-      appliedAt: new Date(),
-    });
-
-    await employee.save();
-
-    return this.calculateBreakdown(employeeId);
-  }
-
-  async addAllowance(employeeId, allowance) {
-    const employee = await this.EmployeeModel.findById(employeeId);
-    if (!employee) throw new Error('Employee not found');
-
-    const updatedCompensation = CompensationFactory.addAllowance(
-      employee.compensation,
-      allowance
-    );
-
-    employee.compensation = updatedCompensation;
-    await employee.save();
-
-    return this.calculateBreakdown(employeeId);
-  }
-
-  async removeAllowance(employeeId, allowanceType) {
-    const employee = await this.EmployeeModel.findById(employeeId);
-    if (!employee) throw new Error('Employee not found');
-
-    const updatedCompensation = CompensationFactory.removeAllowance(
-      employee.compensation,
-      allowanceType
-    );
-
-    employee.compensation = updatedCompensation;
-    await employee.save();
-
-    return this.calculateBreakdown(employeeId);
-  }
-
-  async addDeduction(employeeId, deduction) {
-    const employee = await this.EmployeeModel.findById(employeeId);
-    if (!employee) throw new Error('Employee not found');
-
-    const updatedCompensation = CompensationFactory.addDeduction(
-      employee.compensation,
-      deduction
-    );
-
-    employee.compensation = updatedCompensation;
-    await employee.save();
-
-    return this.calculateBreakdown(employeeId);
-  }
-
-  async removeDeduction(employeeId, deductionType) {
-    const employee = await this.EmployeeModel.findById(employeeId);
-    if (!employee) throw new Error('Employee not found');
-
-    const updatedCompensation = CompensationFactory.removeDeduction(
-      employee.compensation,
-      deductionType
-    );
-
-    employee.compensation = updatedCompensation;
-    await employee.save();
-
-    return this.calculateBreakdown(employeeId);
-  }
-
-  async setStandardCompensation(employeeId, baseAmount) {
-    const employee = await this.EmployeeModel.findById(employeeId);
-    if (!employee) throw new Error('Employee not found');
-
-    employee.compensation = CompensationPresets.standard(baseAmount);
-    await employee.save();
-
-    return this.calculateBreakdown(employeeId);
-  }
-
-  async compareCompensation(employeeId1, employeeId2) {
-    const breakdown1 = await this.calculateBreakdown(employeeId1);
-    const breakdown2 = await this.calculateBreakdown(employeeId2);
-
-    return {
-      employee1: breakdown1,
-      employee2: breakdown2,
-      difference: {
-        base: breakdown2.baseAmount - breakdown1.baseAmount,
-        gross: breakdown2.grossAmount - breakdown1.grossAmount,
-        net: breakdown2.netAmount - breakdown1.netAmount,
-      },
-      ratio: {
-        base: breakdown2.baseAmount / breakdown1.baseAmount,
-        gross: breakdown2.grossAmount / breakdown1.grossAmount,
-        net: breakdown2.netAmount / breakdown1.netAmount,
-      },
-    };
-  }
-
-  async getDepartmentCompensationStats(organizationId, department) {
-    const employees = await this.EmployeeModel.find({
-      organizationId,
-      department,
-      status: { $in: ['active', 'on_leave'] },
-    });
-
-    const breakdowns = employees.map((emp) =>
-      CompensationFactory.calculateBreakdown(emp.compensation)
-    );
-
-    const totals = breakdowns.reduce(
-      (acc, breakdown) => ({
-        totalBase: acc.totalBase + breakdown.baseAmount,
-        totalGross: acc.totalGross + breakdown.grossAmount,
-        totalNet: acc.totalNet + breakdown.netAmount,
-      }),
-      { totalBase: 0, totalGross: 0, totalNet: 0 }
-    );
-
-    return {
-      department,
-      employeeCount: employees.length,
-      ...totals,
-      averageBase: totals.totalBase / employees.length,
-      averageGross: totals.totalGross / employees.length,
-      averageNet: totals.totalNet / employees.length,
-    };
-  }
-
-  async getOrganizationCompensationStats(organizationId) {
-    const employees = await this.EmployeeModel.find({
-      organizationId,
-      status: { $in: ['active', 'on_leave'] },
-    });
-
-    const breakdowns = employees.map((emp) =>
-      CompensationFactory.calculateBreakdown(emp.compensation)
-    );
-
-    const totals = breakdowns.reduce(
-      (acc, breakdown) => ({
-        totalBase: acc.totalBase + breakdown.baseAmount,
-        totalGross: acc.totalGross + breakdown.grossAmount,
-        totalNet: acc.totalNet + breakdown.netAmount,
-      }),
-      { totalBase: 0, totalGross: 0, totalNet: 0 }
-    );
-
-    const byDepartment = {};
-    employees.forEach((emp) => {
-      const dept = emp.department || 'unassigned';
-      if (!byDepartment[dept]) {
-        byDepartment[dept] = { count: 0, totalNet: 0 };
-      }
-      const breakdown = CompensationFactory.calculateBreakdown(emp.compensation);
-      byDepartment[dept].count++;
-      byDepartment[dept].totalNet += breakdown.netAmount;
-    });
-
-    return {
-      employeeCount: employees.length,
-      ...totals,
-      averageBase: totals.totalBase / employees.length,
-      averageGross: totals.totalGross / employees.length,
-      averageNet: totals.totalNet / employees.length,
-      byDepartment,
-    };
-  }
-}
-
-export const createCompensationService = (EmployeeModel) =>
-  new CompensationService(EmployeeModel);