@classytic/payroll 1.0.2 → 2.3.0

package/dist/utils/index.js

@@ -0,0 +1,1515 @@
+import { Types } from 'mongoose';
+
+// src/utils/logger.ts
+var createConsoleLogger = () => ({
+  info: (message, meta) => {
+    if (meta) {
+      console.log(`[Payroll] INFO: ${message}`, meta);
+    } else {
+      console.log(`[Payroll] INFO: ${message}`);
+    }
+  },
+  error: (message, meta) => {
+    if (meta) {
+      console.error(`[Payroll] ERROR: ${message}`, meta);
+    } else {
+      console.error(`[Payroll] ERROR: ${message}`);
+    }
+  },
+  warn: (message, meta) => {
+    if (meta) {
+      console.warn(`[Payroll] WARN: ${message}`, meta);
+    } else {
+      console.warn(`[Payroll] WARN: ${message}`);
+    }
+  },
+  debug: (message, meta) => {
+    if (process.env.NODE_ENV !== "production") {
+      if (meta) {
+        console.log(`[Payroll] DEBUG: ${message}`, meta);
+      } else {
+        console.log(`[Payroll] DEBUG: ${message}`);
+      }
+    }
+  }
+});
+var currentLogger = createConsoleLogger();
+var loggingEnabled = true;
+function getLogger() {
+  return currentLogger;
+}
+function setLogger(logger2) {
+  currentLogger = logger2;
+}
+function resetLogger() {
+  currentLogger = createConsoleLogger();
+}
+function createChildLogger(prefix) {
+  const parent = currentLogger;
+  return {
+    info: (message, meta) => parent.info(`[${prefix}] ${message}`, meta),
+    error: (message, meta) => parent.error(`[${prefix}] ${message}`, meta),
+    warn: (message, meta) => parent.warn(`[${prefix}] ${message}`, meta),
+    debug: (message, meta) => parent.debug(`[${prefix}] ${message}`, meta)
+  };
+}
+function createSilentLogger() {
+  return {
+    info: () => {
+    },
+    error: () => {
+    },
+    warn: () => {
+    },
+    debug: () => {
+    }
+  };
+}
+function enableLogging() {
+  loggingEnabled = true;
+}
+function disableLogging() {
+  loggingEnabled = false;
+}
+function isLoggingEnabled() {
+  return loggingEnabled;
+}
+var logger = {
+  info: (message, meta) => {
+    if (loggingEnabled) currentLogger.info(message, meta);
+  },
+  error: (message, meta) => {
+    if (loggingEnabled) currentLogger.error(message, meta);
+  },
+  warn: (message, meta) => {
+    if (loggingEnabled) currentLogger.warn(message, meta);
+  },
+  debug: (message, meta) => {
+    if (loggingEnabled) currentLogger.debug(message, meta);
+  }
+};
+
+// src/utils/date.ts
+function addDays(date, days) {
+  const result = new Date(date);
+  result.setDate(result.getDate() + days);
+  return result;
+}
+function addMonths(date, months) {
+  const result = new Date(date);
+  result.setMonth(result.getMonth() + months);
+  return result;
+}
+function addYears(date, years) {
+  const result = new Date(date);
+  result.setFullYear(result.getFullYear() + years);
+  return result;
+}
+function subDays(date, days) {
+  return addDays(date, -days);
+}
+function subMonths(date, months) {
+  return addMonths(date, -months);
+}
+function startOfMonth(date) {
+  const result = new Date(date);
+  result.setDate(1);
+  result.setHours(0, 0, 0, 0);
+  return result;
+}
+function endOfMonth(date) {
+  const result = new Date(date);
+  result.setMonth(result.getMonth() + 1, 0);
+  result.setHours(23, 59, 59, 999);
+  return result;
+}
+function startOfYear(date) {
+  const result = new Date(date);
+  result.setMonth(0, 1);
+  result.setHours(0, 0, 0, 0);
+  return result;
+}
+function endOfYear(date) {
+  const result = new Date(date);
+  result.setMonth(11, 31);
+  result.setHours(23, 59, 59, 999);
+  return result;
+}
+function startOfDay(date) {
+  const result = new Date(date);
+  result.setHours(0, 0, 0, 0);
+  return result;
+}
+function endOfDay(date) {
+  const result = new Date(date);
+  result.setHours(23, 59, 59, 999);
+  return result;
+}
+function diffInDays(start, end) {
+  return Math.ceil(
+    (new Date(end).getTime() - new Date(start).getTime()) / (1e3 * 60 * 60 * 24)
+  );
+}
+function diffInMonths(start, end) {
+  const startDate = new Date(start);
+  const endDate = new Date(end);
+  return (endDate.getFullYear() - startDate.getFullYear()) * 12 + (endDate.getMonth() - startDate.getMonth());
+}
+function diffInYears(start, end) {
+  return Math.floor(diffInMonths(start, end) / 12);
+}
+var daysBetween = diffInDays;
+var monthsBetween = diffInMonths;
+function isWeekday(date) {
+  const day = new Date(date).getDay();
+  return day >= 1 && day <= 5;
+}
+function isWeekend(date) {
+  const day = new Date(date).getDay();
+  return day === 0 || day === 6;
+}
+function getDayOfWeek(date) {
+  return new Date(date).getDay();
+}
+function getDayName(date) {
+  const days = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday"
+  ];
+  return days[getDayOfWeek(date)];
+}
+function getPayPeriod(month, year) {
+  const startDate = new Date(year, month - 1, 1);
+  return {
+    month,
+    year,
+    startDate: startOfMonth(startDate),
+    endDate: endOfMonth(startDate)
+  };
+}
+function getCurrentPeriod(date = /* @__PURE__ */ new Date()) {
+  const d = new Date(date);
+  return {
+    year: d.getFullYear(),
+    month: d.getMonth() + 1
+  };
+}
+function getWorkingDaysInMonth(year, month) {
+  const start = new Date(year, month - 1, 1);
+  const end = endOfMonth(start);
+  let count = 0;
+  const current = new Date(start);
+  while (current <= end) {
+    if (isWeekday(current)) {
+      count++;
+    }
+    current.setDate(current.getDate() + 1);
+  }
+  return count;
+}
+function getDaysInMonth(year, month) {
+  return new Date(year, month, 0).getDate();
+}
+function calculateProbationEnd(hireDate, probationMonths) {
+  if (!probationMonths || probationMonths <= 0) return null;
+  return addMonths(hireDate, probationMonths);
+}
+function isOnProbation(probationEndDate, now = /* @__PURE__ */ new Date()) {
+  if (!probationEndDate) return false;
+  return now < new Date(probationEndDate);
+}
+function calculateYearsOfService(hireDate, terminationDate) {
+  const end = terminationDate || /* @__PURE__ */ new Date();
+  const days = diffInDays(hireDate, end);
+  return Math.max(0, Math.floor(days / 365.25 * 10) / 10);
+}
+function isDateInRange(date, start, end) {
+  const checkDate = new Date(date);
+  return checkDate >= new Date(start) && checkDate <= new Date(end);
+}
+function getPayPeriodDateRange(month, year) {
+  const period = getPayPeriod(month, year);
+  return { start: period.startDate, end: period.endDate };
+}
+function formatDateForDB(date) {
+  if (!date) return "";
+  return new Date(date).toISOString();
+}
+function parseDBDate(dateString) {
+  if (!dateString) return null;
+  return new Date(dateString);
+}
+function formatPeriod({ month, year }) {
+  return `${String(month).padStart(2, "0")}/${year}`;
+}
+function parsePeriod(periodString) {
+  const [month, year] = periodString.split("/").map(Number);
+  return { month, year };
+}
+function getMonthName(month) {
+  const months = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December"
+  ];
+  return months[month - 1] || "";
+}
+function getShortMonthName(month) {
+  const months = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec"
+  ];
+  return months[month - 1] || "";
+}
+var date_default = {
+  addDays,
+  addMonths,
+  addYears,
+  subDays,
+  subMonths,
+  startOfMonth,
+  endOfMonth,
+  startOfYear,
+  endOfYear,
+  startOfDay,
+  endOfDay,
+  diffInDays,
+  diffInMonths,
+  diffInYears,
+  daysBetween,
+  monthsBetween,
+  isWeekday,
+  isWeekend,
+  getDayOfWeek,
+  getDayName,
+  getPayPeriod,
+  getCurrentPeriod,
+  getWorkingDaysInMonth,
+  getDaysInMonth,
+  calculateProbationEnd,
+  isOnProbation,
+  calculateYearsOfService,
+  isDateInRange,
+  getPayPeriodDateRange,
+  formatDateForDB,
+  parseDBDate,
+  formatPeriod,
+  parsePeriod,
+  getMonthName,
+  getShortMonthName
+};
+
+// src/utils/calculation.ts
+function sum(numbers) {
+  return numbers.reduce((total, n) => total + n, 0);
+}
+function sumBy(items, getter) {
+  return items.reduce((total, item) => total + getter(item), 0);
+}
+function sumAllowances(allowances) {
+  return sumBy(allowances, (a) => a.amount);
+}
+function sumDeductions(deductions) {
+  return sumBy(deductions, (d) => d.amount);
+}
+function applyPercentage(amount, percentage) {
+  return Math.round(amount * (percentage / 100));
+}
+function calculatePercentage(part, total) {
+  return total > 0 ? Math.round(part / total * 100) : 0;
+}
+function roundTo(value, decimals = 2) {
+  const factor = Math.pow(10, decimals);
+  return Math.round(value * factor) / factor;
+}
+function calculateGross(baseAmount, allowances) {
+  return baseAmount + sumAllowances(allowances);
+}
+function calculateNet(gross, deductions) {
+  return Math.max(0, gross - sumDeductions(deductions));
+}
+function calculateTotalCompensation(baseAmount, allowances, deductions) {
+  const gross = calculateGross(baseAmount, allowances);
+  const totalDeductions = sumDeductions(deductions);
+  const net = calculateNet(gross, deductions);
+  return { gross, net, deductions: totalDeductions };
+}
+function calculateAllowanceAmount(allowance, baseAmount) {
+  if (allowance.isPercentage && allowance.value !== void 0) {
+    return applyPercentage(baseAmount, allowance.value);
+  }
+  return allowance.amount;
+}
+function calculateDeductionAmount(deduction, baseAmount) {
+  if (deduction.isPercentage && deduction.value !== void 0) {
+    return applyPercentage(baseAmount, deduction.value);
+  }
+  return deduction.amount;
+}
+function calculateAllowances(allowances, baseAmount) {
+  return allowances.map((allowance) => ({
+    ...allowance,
+    calculatedAmount: calculateAllowanceAmount(allowance, baseAmount)
+  }));
+}
+function calculateDeductions(deductions, baseAmount) {
+  return deductions.map((deduction) => ({
+    ...deduction,
+    calculatedAmount: calculateDeductionAmount(deduction, baseAmount)
+  }));
+}
+function calculateCompensationBreakdown(compensation) {
+  const { baseAmount, allowances = [], deductions = [] } = compensation;
+  const calculatedAllowances = calculateAllowances(allowances, baseAmount);
+  const calculatedDeductions = calculateDeductions(deductions, baseAmount);
+  const grossAmount = baseAmount + sumBy(calculatedAllowances, (a) => a.calculatedAmount);
+  const netAmount = grossAmount - sumBy(calculatedDeductions, (d) => d.calculatedAmount);
+  return {
+    baseAmount,
+    allowances: calculatedAllowances,
+    deductions: calculatedDeductions,
+    grossAmount,
+    netAmount: Math.max(0, netAmount)
+  };
+}
+function calculateProRating(hireDate, periodStart, periodEnd) {
+  const totalDays = diffInDays(periodStart, periodEnd) + 1;
+  if (hireDate <= periodStart) {
+    return {
+      isProRated: false,
+      totalDays,
+      actualDays: totalDays,
+      ratio: 1
+    };
+  }
+  if (hireDate > periodStart && hireDate <= periodEnd) {
+    const actualDays = diffInDays(hireDate, periodEnd) + 1;
+    const ratio = actualDays / totalDays;
+    return {
+      isProRated: true,
+      totalDays,
+      actualDays,
+      ratio
+    };
+  }
+  return {
+    isProRated: false,
+    totalDays,
+    actualDays: 0,
+    ratio: 0
+  };
+}
+function applyProRating(amount, proRating) {
+  return Math.round(amount * proRating.ratio);
+}
+function calculateProRatedSalary(baseAmount, hireDate, period) {
+  const proRating = calculateProRating(hireDate, period.startDate, period.endDate);
+  const amount = applyProRating(baseAmount, proRating);
+  return { amount, proRating };
+}
+function applyTaxBrackets(amount, brackets) {
+  let tax = 0;
+  for (const bracket of brackets) {
+    if (amount > bracket.min) {
+      const taxableAmount = Math.min(amount, bracket.max) - bracket.min;
+      tax += taxableAmount * bracket.rate;
+    }
+  }
+  return Math.round(tax);
+}
+function calculateTax(amount, brackets) {
+  const tax = applyTaxBrackets(amount, brackets);
+  return {
+    gross: amount,
+    tax,
+    net: amount - tax
+  };
+}
+function pipe(...fns) {
+  return (value) => fns.reduce((acc, fn) => fn(acc), value);
+}
+function compose(...fns) {
+  return (value) => fns.reduceRight((acc, fn) => fn(acc), value);
+}
+function createAllowanceCalculator(allowances) {
+  return (baseSalary) => calculateAllowances(allowances, baseSalary);
+}
+function createDeductionCalculator(deductions) {
+  return (baseSalary) => calculateDeductions(deductions, baseSalary);
+}
+function calculateOvertime(hourlyRate, overtimeHours, multiplier = 1.5) {
+  return Math.round(hourlyRate * overtimeHours * multiplier);
+}
+function calculateHourlyRate(monthlySalary, hoursPerMonth = 176) {
+  return Math.round(monthlySalary / hoursPerMonth);
+}
+function calculateDailyRate(monthlySalary, daysPerMonth = 22) {
+  return Math.round(monthlySalary / daysPerMonth);
+}
+var calculation_default = {
+  sum,
+  sumBy,
+  sumAllowances,
+  sumDeductions,
+  applyPercentage,
+  calculatePercentage,
+  roundTo,
+  calculateGross,
+  calculateNet,
+  calculateTotalCompensation,
+  calculateAllowanceAmount,
+  calculateDeductionAmount,
+  calculateAllowances,
+  calculateDeductions,
+  calculateCompensationBreakdown,
+  calculateProRating,
+  applyProRating,
+  calculateProRatedSalary,
+  applyTaxBrackets,
+  calculateTax,
+  pipe,
+  compose,
+  createAllowanceCalculator,
+  createDeductionCalculator,
+  calculateOvertime,
+  calculateHourlyRate,
+  calculateDailyRate
+};
+
+// src/enums.ts
+var EMPLOYMENT_TYPE = {
+  FULL_TIME: "full_time",
+  PART_TIME: "part_time",
+  CONTRACT: "contract",
+  INTERN: "intern",
+  CONSULTANT: "consultant"
+};
+var EMPLOYMENT_TYPE_VALUES = Object.values(EMPLOYMENT_TYPE);
+var EMPLOYEE_STATUS = {
+  ACTIVE: "active",
+  ON_LEAVE: "on_leave",
+  SUSPENDED: "suspended",
+  TERMINATED: "terminated"
+};
+var EMPLOYEE_STATUS_VALUES = Object.values(EMPLOYEE_STATUS);
+
+// src/utils/validation.ts
+function isActive(employee2) {
+  return employee2?.status === "active";
+}
+function isOnLeave(employee2) {
+  return employee2?.status === "on_leave";
+}
+function isSuspended(employee2) {
+  return employee2?.status === "suspended";
+}
+function isTerminated(employee2) {
+  return employee2?.status === "terminated";
+}
+function isEmployed(employee2) {
+  return isActive(employee2) || isOnLeave(employee2) || isSuspended(employee2);
+}
+function canReceiveSalary(employee2) {
+  return (isActive(employee2) || isOnLeave(employee2)) && (employee2.compensation?.baseAmount ?? 0) > 0;
+}
+function canUpdateEmployment(employee2) {
+  return !isTerminated(employee2);
+}
+function hasCompensation(employee2) {
+  return (employee2.compensation?.baseAmount ?? 0) > 0;
+}
+function isValidCompensation(compensation) {
+  return !!(compensation?.baseAmount && compensation.baseAmount > 0 && compensation.frequency && compensation.currency);
+}
+function isValidBankDetails(bankDetails) {
+  return !!(bankDetails?.accountNumber && bankDetails.bankName && bankDetails.accountName);
+}
+function isInProbation(employee2, now = /* @__PURE__ */ new Date()) {
+  if (!employee2?.probationEndDate) return false;
+  return new Date(employee2.probationEndDate) > now;
+}
+function hasCompletedProbation(employee2, now = /* @__PURE__ */ new Date()) {
+  if (!employee2?.probationEndDate) return true;
+  return new Date(employee2.probationEndDate) <= now;
+}
+function isEligibleForBonus(employee2, requiredMonths = 6) {
+  if (!isActive(employee2) || !employee2.hireDate) return false;
+  const monthsEmployed = diffInMonths(employee2.hireDate, /* @__PURE__ */ new Date());
+  return monthsEmployed >= requiredMonths;
+}
+function isEligibleForPayroll(employee2) {
+  const reasons = [];
+  if (!isActive(employee2) && !isOnLeave(employee2)) {
+    reasons.push("Employee is not in active or on-leave status");
+  }
+  if (!hasCompensation(employee2)) {
+    reasons.push("Employee has no valid compensation");
+  }
+  return {
+    eligible: reasons.length === 0,
+    reasons
+  };
+}
+function required(fieldName) {
+  return (value) => value !== void 0 && value !== null && value !== "" ? true : `${fieldName} is required`;
+}
+function min(minValue2, fieldName) {
+  return (value) => value >= minValue2 ? true : `${fieldName} must be at least ${minValue2}`;
+}
+function max(maxValue2, fieldName) {
+  return (value) => value <= maxValue2 ? true : `${fieldName} must not exceed ${maxValue2}`;
+}
+function inRange(minValue2, maxValue2, fieldName) {
+  return (value) => value >= minValue2 && value <= maxValue2 ? true : `${fieldName} must be between ${minValue2} and ${maxValue2}`;
+}
+function isPositive(fieldName) {
+  return (value) => value > 0 ? true : `${fieldName} must be positive`;
+}
+function oneOf(allowedValues, fieldName) {
+  return (value) => allowedValues.includes(value) ? true : `${fieldName} must be one of: ${allowedValues.join(", ")}`;
+}
+function isValidStatus(value) {
+  return EMPLOYEE_STATUS_VALUES.includes(value);
+}
+function isValidEmploymentType(value) {
+  return EMPLOYMENT_TYPE_VALUES.includes(value);
+}
+function composeValidators(...validators) {
+  return (value, data) => {
+    for (const validator of validators) {
+      const result = validator(value, data);
+      if (result !== true) return result;
+    }
+    return true;
+  };
+}
+function createValidator(validationFns) {
+  return (data) => {
+    const errors = [];
+    for (const [field, validator] of Object.entries(validationFns)) {
+      const result = validator(data[field], data);
+      if (result !== true) {
+        errors.push(result);
+      }
+    }
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  };
+}
+function hasRequiredFields(obj, fields) {
+  const missing = fields.filter(
+    (field) => obj[field] === void 0 || obj[field] === null
+  );
+  return {
+    valid: missing.length === 0,
+    missing
+  };
+}
+var minValue = min;
+var maxValue = max;
+var isInRange = inRange;
+var validation_default = {
+  // Status validators
+  isActive,
+  isOnLeave,
+  isSuspended,
+  isTerminated,
+  isEmployed,
+  canReceiveSalary,
+  canUpdateEmployment,
+  // Compensation validators
+  hasCompensation,
+  isValidCompensation,
+  isValidBankDetails,
+  // Probation validators
+  isInProbation,
+  hasCompletedProbation,
+  // Eligibility validators
+  isEligibleForBonus,
+  isEligibleForPayroll,
+  // Field validators
+  required,
+  min,
+  max,
+  inRange,
+  isPositive,
+  oneOf,
+  // Enum validators
+  isValidStatus,
+  isValidEmploymentType,
+  // Composite validators
+  composeValidators,
+  createValidator,
+  hasRequiredFields
+};
+function toObjectId(id) {
+  if (id instanceof Types.ObjectId) return id;
+  return new Types.ObjectId(id);
+}
+function safeToObjectId(id) {
+  if (id instanceof Types.ObjectId) return id;
+  if (typeof id === "string" && Types.ObjectId.isValid(id)) {
+    return new Types.ObjectId(id);
+  }
+  return null;
+}
+function isValidObjectId(value) {
+  if (value instanceof Types.ObjectId) return true;
+  if (typeof value === "string") return Types.ObjectId.isValid(value);
+  return false;
+}
+var QueryBuilder = class {
+  query;
+  constructor(initialQuery = {}) {
+    this.query = { ...initialQuery };
+  }
+  /**
+   * Add where condition
+   */
+  where(field, value) {
+    this.query[field] = value;
+    return this;
+  }
+  /**
+   * Add $in condition
+   */
+  whereIn(field, values) {
+    this.query[field] = { $in: values };
+    return this;
+  }
+  /**
+   * Add $nin condition
+   */
+  whereNotIn(field, values) {
+    this.query[field] = { $nin: values };
+    return this;
+  }
+  /**
+   * Add $gte condition
+   */
+  whereGte(field, value) {
+    const existing = this.query[field] || {};
+    this.query[field] = { ...existing, $gte: value };
+    return this;
+  }
+  /**
+   * Add $lte condition
+   */
+  whereLte(field, value) {
+    const existing = this.query[field] || {};
+    this.query[field] = { ...existing, $lte: value };
+    return this;
+  }
+  /**
+   * Add $gt condition
+   */
+  whereGt(field, value) {
+    const existing = this.query[field] || {};
+    this.query[field] = { ...existing, $gt: value };
+    return this;
+  }
+  /**
+   * Add $lt condition
+   */
+  whereLt(field, value) {
+    const existing = this.query[field] || {};
+    this.query[field] = { ...existing, $lt: value };
+    return this;
+  }
+  /**
+   * Add between condition
+   */
+  whereBetween(field, start, end) {
+    this.query[field] = { $gte: start, $lte: end };
+    return this;
+  }
+  /**
+   * Add $exists condition
+   */
+  whereExists(field) {
+    this.query[field] = { $exists: true };
+    return this;
+  }
+  /**
+   * Add $exists: false condition
+   */
+  whereNotExists(field) {
+    this.query[field] = { $exists: false };
+    return this;
+  }
+  /**
+   * Add $ne condition
+   */
+  whereNot(field, value) {
+    this.query[field] = { $ne: value };
+    return this;
+  }
+  /**
+   * Add regex condition
+   */
+  whereRegex(field, pattern, flags = "i") {
+    this.query[field] = { $regex: pattern, $options: flags };
+    return this;
+  }
+  /**
+   * Merge another query
+   */
+  merge(otherQuery) {
+    this.query = { ...this.query, ...otherQuery };
+    return this;
+  }
+  /**
+   * Build and return the query
+   */
+  build() {
+    return { ...this.query };
+  }
+};
+var EmployeeQueryBuilder = class extends QueryBuilder {
+  /**
+   * Filter by organization
+   */
+  forOrganization(organizationId) {
+    return this.where("organizationId", toObjectId(organizationId));
+  }
+  /**
+   * Filter by user
+   */
+  forUser(userId) {
+    return this.where("userId", toObjectId(userId));
+  }
+  /**
+   * Filter by employeeId (human-readable ID)
+   */
+  forEmployeeId(employeeId) {
+    return this.where("employeeId", employeeId);
+  }
+  /**
+   * Filter by email (for guest employees)
+   */
+  forEmail(email) {
+    return this.where("email", email.toLowerCase().trim());
+  }
+  /**
+   * Filter guest employees (no userId)
+   */
+  guestEmployees() {
+    return this.where("userId", null);
+  }
+  /**
+   * Filter user-linked employees (has userId)
+   */
+  userLinkedEmployees() {
+    return this.where("userId", { $ne: null });
+  }
+  /**
+   * Filter by status(es)
+   */
+  withStatus(...statuses) {
+    if (statuses.length === 1) {
+      return this.where("status", statuses[0]);
+    }
+    return this.whereIn("status", statuses);
+  }
+  /**
+   * Filter active employees
+   */
+  active() {
+    return this.withStatus("active");
+  }
+  /**
+   * Filter employed employees (not terminated)
+   */
+  employed() {
+    return this.whereIn("status", ["active", "on_leave", "suspended"]);
+  }
+  /**
+   * Filter terminated employees
+   */
+  terminated() {
+    return this.withStatus("terminated");
+  }
+  /**
+   * Filter by department
+   */
+  inDepartment(department) {
+    return this.where("department", department);
+  }
+  /**
+   * Filter by position
+   */
+  inPosition(position) {
+    return this.where("position", position);
+  }
+  /**
+   * Filter by employment type
+   */
+  withEmploymentType(type) {
+    return this.where("employmentType", type);
+  }
+  /**
+   * Filter by hire date (after)
+   */
+  hiredAfter(date) {
+    return this.whereGte("hireDate", date);
+  }
+  /**
+   * Filter by hire date (before)
+   */
+  hiredBefore(date) {
+    return this.whereLte("hireDate", date);
+  }
+  /**
+   * Filter by minimum salary
+   */
+  withMinSalary(amount) {
+    return this.whereGte("compensation.netSalary", amount);
+  }
+  /**
+   * Filter by maximum salary
+   */
+  withMaxSalary(amount) {
+    return this.whereLte("compensation.netSalary", amount);
+  }
+  /**
+   * Filter by salary range
+   */
+  withSalaryRange(min2, max2) {
+    return this.whereBetween("compensation.netSalary", min2, max2);
+  }
+};
+var PayrollQueryBuilder = class extends QueryBuilder {
+  /**
+   * Filter by organization
+   */
+  forOrganization(organizationId) {
+    return this.where("organizationId", toObjectId(organizationId));
+  }
+  /**
+   * Filter by employee
+   *
+   * Note: PayrollRecord.employeeId is always ObjectId _id
+   * If passing a string business ID, resolve to _id first
+   */
+  forEmployee(employeeId) {
+    return this.where("employeeId", toObjectId(employeeId));
+  }
+  /**
+   * Filter by period
+   */
+  forPeriod(month, year) {
+    if (month !== void 0) {
+      this.where("period.month", month);
+    }
+    if (year !== void 0) {
+      this.where("period.year", year);
+    }
+    return this;
+  }
+  /**
+   * Filter by status(es)
+   */
+  withStatus(...statuses) {
+    if (statuses.length === 1) {
+      return this.where("status", statuses[0]);
+    }
+    return this.whereIn("status", statuses);
+  }
+  /**
+   * Filter paid records
+   */
+  paid() {
+    return this.withStatus("paid");
+  }
+  /**
+   * Filter pending records
+   */
+  pending() {
+    return this.whereIn("status", ["pending", "processing"]);
+  }
+  /**
+   * Filter by date range
+   */
+  inDateRange(start, end) {
+    return this.whereBetween("period.payDate", start, end);
+  }
+  /**
+   * Filter exported records
+   */
+  exported() {
+    return this.where("exported", true);
+  }
+  /**
+   * Filter not exported records
+   */
+  notExported() {
+    return this.where("exported", false);
+  }
+};
+function employee() {
+  return new EmployeeQueryBuilder();
+}
+function payroll() {
+  return new PayrollQueryBuilder();
+}
+function createQueryBuilder(initialQuery) {
+  return new QueryBuilder(initialQuery);
+}
+function buildEmployeeQuery(options) {
+  const builder = employee().forOrganization(options.organizationId);
+  if (options.userId) {
+    builder.forUser(options.userId);
+  }
+  if (options.statuses) {
+    builder.withStatus(...options.statuses);
+  }
+  if (options.department) {
+    builder.inDepartment(options.department);
+  }
+  if (options.employmentType) {
+    builder.withEmploymentType(options.employmentType);
+  }
+  return builder.build();
+}
+function buildPayrollQuery(options) {
+  const builder = payroll();
+  if (options.organizationId) {
+    builder.forOrganization(options.organizationId);
+  }
+  if (options.employeeId) {
+    builder.forEmployee(options.employeeId);
+  }
+  if (options.month || options.year) {
+    builder.forPeriod(options.month, options.year);
+  }
+  if (options.statuses) {
+    builder.withStatus(...options.statuses);
+  }
+  return builder.build();
+}
+function buildAggregationPipeline(...stages) {
+  return stages.filter((stage) => !!stage);
+}
+function matchStage(query) {
+  return { $match: query };
+}
+function groupStage(groupBy, aggregations) {
+  return {
+    $group: {
+      _id: groupBy,
+      ...aggregations
+    }
+  };
+}
+function sortStage(sortBy) {
+  return { $sort: sortBy };
+}
+function limitStage(limit) {
+  return { $limit: limit };
+}
+function skipStage(skip) {
+  return { $skip: skip };
+}
+function projectStage(fields) {
+  return { $project: fields };
+}
+function lookupStage(options) {
+  return { $lookup: options };
+}
+function unwindStage(path, options = {}) {
+  return { $unwind: { path, ...options } };
+}
+var query_builders_default = {
+  toObjectId,
+  safeToObjectId,
+  isValidObjectId,
+  QueryBuilder,
+  EmployeeQueryBuilder,
+  PayrollQueryBuilder,
+  employee,
+  payroll,
+  createQueryBuilder,
+  buildEmployeeQuery,
+  buildPayrollQuery,
+  buildAggregationPipeline,
+  matchStage,
+  groupStage,
+  sortStage,
+  limitStage,
+  skipStage,
+  projectStage,
+  lookupStage,
+  unwindStage
+};
+
+// src/utils/leave.ts
+var DEFAULT_LEAVE_ALLOCATIONS = {
+  annual: 20,
+  sick: 10,
+  unpaid: 0,
+  // Unlimited
+  maternity: 90,
+  paternity: 10,
+  bereavement: 5,
+  compensatory: 0,
+  other: 0
+};
+var DEFAULT_CARRY_OVER = {
+  annual: 5,
+  sick: 0,
+  unpaid: 0,
+  maternity: 0,
+  paternity: 0,
+  bereavement: 0,
+  compensatory: 5,
+  other: 0
+};
+function calculateLeaveDays(startDate, endDate, options = {}) {
+  const {
+    workingDays = [1, 2, 3, 4, 5],
+    // Mon-Fri by default
+    holidays = [],
+    includeEndDate = true
+  } = options;
+  const holidaySet = new Set(holidays.map((d) => new Date(d).toDateString()));
+  let count = 0;
+  const current = new Date(startDate);
+  current.setHours(0, 0, 0, 0);
+  const end = new Date(endDate);
+  end.setHours(0, 0, 0, 0);
+  if (!includeEndDate) {
+    end.setDate(end.getDate() - 1);
+  }
+  while (current <= end) {
+    const isWorkDay = workingDays.includes(current.getDay());
+    const isHoliday = holidaySet.has(current.toDateString());
+    if (isWorkDay && !isHoliday) {
+      count++;
+    }
+    current.setDate(current.getDate() + 1);
+  }
+  return count;
+}
+function hasLeaveBalance(employee2, type, days, year = (/* @__PURE__ */ new Date()).getFullYear()) {
+  if (type === "unpaid") return true;
+  const balance = getLeaveBalance(employee2, type, year);
+  if (!balance) return false;
+  const available = balance.allocated + balance.carriedOver - balance.used - balance.pending;
+  return available >= days;
+}
+function getLeaveBalance(employee2, type, year = (/* @__PURE__ */ new Date()).getFullYear()) {
+  return employee2.leaveBalances?.find((b) => b.type === type && b.year === year);
+}
+function getLeaveBalances(employee2, year = (/* @__PURE__ */ new Date()).getFullYear()) {
+  return (employee2.leaveBalances || []).filter((b) => b.year === year);
+}
+function getAvailableDays(employee2, type, year = (/* @__PURE__ */ new Date()).getFullYear()) {
+  if (type === "unpaid") return Infinity;
+  const balance = getLeaveBalance(employee2, type, year);
+  if (!balance) return 0;
+  return Math.max(
+    0,
+    balance.allocated + balance.carriedOver - balance.used - balance.pending
+  );
+}
+function getLeaveSummary(employee2, year = (/* @__PURE__ */ new Date()).getFullYear()) {
+  const balances = getLeaveBalances(employee2, year);
+  const byType = {};
+  let totalAllocated = 0;
+  let totalUsed = 0;
+  let totalPending = 0;
+  for (const balance of balances) {
+    const available = Math.max(
+      0,
+      balance.allocated + balance.carriedOver - balance.used - balance.pending
+    );
+    byType[balance.type] = {
+      allocated: balance.allocated + balance.carriedOver,
+      used: balance.used,
+      pending: balance.pending,
+      available
+    };
+    totalAllocated += balance.allocated + balance.carriedOver;
+    totalUsed += balance.used;
+    totalPending += balance.pending;
+  }
+  return {
+    year,
+    balances,
+    totalAllocated,
+    totalUsed,
+    totalPending,
+    totalAvailable: Math.max(0, totalAllocated - totalUsed - totalPending),
+    byType
+  };
+}
+function initializeLeaveBalances(hireDate, config = {}, year = (/* @__PURE__ */ new Date()).getFullYear()) {
+  const {
+    defaultAllocations = DEFAULT_LEAVE_ALLOCATIONS,
+    proRateNewHires = true,
+    fiscalYearStartMonth = 1
+  } = config;
+  const fiscalYearStart = new Date(year, fiscalYearStartMonth - 1, 1);
+  const fiscalYearEnd = new Date(year + 1, fiscalYearStartMonth - 1, 0);
+  let prorationRatio = 1;
+  if (proRateNewHires && hireDate > fiscalYearStart) {
+    const totalDays = diffInDays2(fiscalYearStart, fiscalYearEnd);
+    const remainingDays = diffInDays2(hireDate, fiscalYearEnd);
+    prorationRatio = Math.max(0, Math.min(1, remainingDays / totalDays));
+  }
+  const balances = [];
+  for (const [type, allocation] of Object.entries(defaultAllocations)) {
+    if (allocation > 0) {
+      balances.push({
+        type,
+        allocated: Math.round(allocation * prorationRatio),
+        used: 0,
+        pending: 0,
+        carriedOver: 0,
+        year
+      });
+    }
+  }
+  return balances;
+}
+function proRateAllocation(fullAllocation, hireDate, fiscalYearStartMonth = 1, year = (/* @__PURE__ */ new Date()).getFullYear()) {
+  const fiscalYearStart = new Date(year, fiscalYearStartMonth - 1, 1);
+  if (hireDate <= fiscalYearStart) {
+    return fullAllocation;
+  }
+  const fiscalYearEnd = new Date(year + 1, fiscalYearStartMonth - 1, 0);
+  const totalDays = diffInDays2(fiscalYearStart, fiscalYearEnd);
+  const remainingDays = Math.max(0, diffInDays2(hireDate, fiscalYearEnd));
+  return Math.round(fullAllocation * remainingDays / totalDays);
+}
+function calculateUnpaidLeaveDeduction(baseSalary, unpaidDays, workingDaysInMonth) {
+  if (unpaidDays <= 0 || workingDaysInMonth <= 0) return 0;
+  const dailyRate = baseSalary / workingDaysInMonth;
+  return Math.round(dailyRate * unpaidDays);
+}
+function getUnpaidLeaveDays(leaveRequests, status = "approved") {
+  return leaveRequests.filter((r) => r.type === "unpaid" && r.status === status).reduce((sum2, r) => sum2 + r.days, 0);
+}
+function calculateCarryOver(balances, maxCarryOver = DEFAULT_CARRY_OVER, newYearAllocations = DEFAULT_LEAVE_ALLOCATIONS) {
+  if (!balances.length) return [];
+  const currentYear = balances[0].year;
+  const newYear = currentYear + 1;
+  return balances.map((balance) => {
+    const available = balance.allocated + balance.carriedOver - balance.used - balance.pending;
+    const maxForType = maxCarryOver[balance.type] ?? 0;
+    const carryOver = maxForType > 0 ? Math.min(Math.max(0, available), maxForType) : 0;
+    return {
+      type: balance.type,
+      allocated: newYearAllocations[balance.type] ?? DEFAULT_LEAVE_ALLOCATIONS[balance.type] ?? 0,
+      used: 0,
+      pending: 0,
+      carriedOver: carryOver,
+      year: newYear
+    };
+  });
+}
+function accrueLeaveToBalance(balances, type, amount, year = (/* @__PURE__ */ new Date()).getFullYear()) {
+  const existingIdx = balances.findIndex((b) => b.type === type && b.year === year);
+  if (existingIdx >= 0) {
+    balances[existingIdx].allocated += amount;
+  } else {
+    balances.push({
+      type,
+      allocated: amount,
+      used: 0,
+      pending: 0,
+      carriedOver: 0,
+      year
+    });
+  }
+  return balances;
+}
+function diffInDays2(start, end) {
+  const startDate = new Date(start);
+  const endDate = new Date(end);
+  startDate.setHours(0, 0, 0, 0);
+  endDate.setHours(0, 0, 0, 0);
+  return Math.ceil((endDate.getTime() - startDate.getTime()) / (1e3 * 60 * 60 * 24));
+}
+var leave_default = {
+  DEFAULT_LEAVE_ALLOCATIONS,
+  DEFAULT_CARRY_OVER,
+  calculateLeaveDays,
+  hasLeaveBalance,
+  getLeaveBalance,
+  getLeaveBalances,
+  getAvailableDays,
+  getLeaveSummary,
+  initializeLeaveBalances,
+  proRateAllocation,
+  calculateUnpaidLeaveDeduction,
+  getUnpaidLeaveDays,
+  calculateCarryOver,
+  accrueLeaveToBalance
+};
+
+// src/errors/index.ts
+var PayrollError = class extends Error {
+  code;
+  status;
+  context;
+  timestamp;
+  /**
+   * Create a PayrollError.
+   *
+   * Supports BOTH constructor styles for backwards compatibility:
+   * - new PayrollError(message, code?, status?, context?)
+   * - new PayrollError(code, status, message, context?)
+   */
+  constructor(messageOrCode, codeOrStatus = "PAYROLL_ERROR", statusOrMessage = 500, context = {}) {
+    const isLegacySignature = typeof messageOrCode === "string" && typeof codeOrStatus === "string";
+    const message = isLegacySignature ? messageOrCode : statusOrMessage;
+    super(message);
+    this.name = this.constructor.name;
+    this.code = isLegacySignature ? codeOrStatus : messageOrCode;
+    this.status = isLegacySignature ? statusOrMessage : codeOrStatus;
+    this.context = context ?? {};
+    this.timestamp = /* @__PURE__ */ new Date();
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+  /**
+   * Convert error to JSON for API responses (ClockIn-compatible shape)
+   */
+  toJSON() {
+    return {
+      error: {
+        type: this.name,
+        code: this.code,
+        message: this.message,
+        status: this.status,
+        context: this.context,
+        timestamp: this.timestamp.toISOString()
+      }
+    };
+  }
+  /**
+   * Check if error is operational (expected) vs programmer error
+   */
+  isOperational() {
+    return true;
+  }
+};
+var EmployeeNotFoundError = class extends PayrollError {
+  constructor(employeeId, context) {
+    super(
+      employeeId ? `Employee not found: ${employeeId}` : "Employee not found",
+      "EMPLOYEE_NOT_FOUND",
+      404,
+      context ?? {}
+    );
+  }
+};
+
+// src/utils/employee-lookup.ts
+async function findEmployeeSecure(model, options) {
+  const {
+    organizationId,
+    _id,
+    employeeId,
+    employeeIdMode = "auto",
+    userId,
+    email,
+    session,
+    populate
+  } = options;
+  const query = {};
+  if (organizationId) {
+    query.organizationId = toObjectId(organizationId);
+  }
+  if (_id) {
+    query._id = toObjectId(_id);
+  } else if (employeeId !== void 0) {
+    const shouldTreatAsObjectId = employeeIdMode === "objectId" || employeeIdMode === "auto" && isValidObjectId(employeeId);
+    const shouldTreatAsBusinessId = employeeIdMode === "businessId" || employeeIdMode === "auto" && !isValidObjectId(employeeId);
+    if (shouldTreatAsObjectId) {
+      query._id = toObjectId(employeeId);
+    } else if (shouldTreatAsBusinessId) {
+      query.employeeId = employeeId;
+    }
+  } else if (userId) {
+    query.userId = toObjectId(userId);
+  } else if (email) {
+    query.email = email;
+  } else {
+    throw new Error(
+      "findEmployeeSecure requires at least one identifier: _id, employeeId, userId, or email"
+    );
+  }
+  let mongooseQuery = model.findOne(query);
+  if (session) {
+    mongooseQuery = mongooseQuery.session(session);
+  }
+  if (populate) {
+    const fields = Array.isArray(populate) ? populate : [populate];
+    for (const field of fields) {
+      mongooseQuery = mongooseQuery.populate(field);
+    }
+  }
+  const employee2 = await mongooseQuery;
+  if (!employee2) {
+    const identifier = _id ? `_id=${_id}` : employeeId ? `employeeId=${employeeId}` : userId ? `userId=${userId}` : `email=${email}`;
+    throw new EmployeeNotFoundError(
+      `Employee not found: ${identifier}${organizationId ? ` in organization ${organizationId}` : ""}`
+    );
+  }
+  return employee2;
+}
+async function employeeExistsSecure(model, options) {
+  try {
+    await findEmployeeSecure(model, options);
+    return true;
+  } catch (error) {
+    if (error instanceof EmployeeNotFoundError) {
+      return false;
+    }
+    throw error;
+  }
+}
+async function findEmployeesSecure(model, options) {
+  const { organizationId, filter = {}, session, limit, skip, sort } = options;
+  const query = {
+    organizationId: toObjectId(organizationId),
+    ...filter
+  };
+  let mongooseQuery = model.find(query);
+  if (session) {
+    mongooseQuery = mongooseQuery.session(session);
+  }
+  if (limit) {
+    mongooseQuery = mongooseQuery.limit(limit);
+  }
+  if (skip) {
+    mongooseQuery = mongooseQuery.skip(skip);
+  }
+  if (sort) {
+    mongooseQuery = mongooseQuery.sort(sort);
+  }
+  return mongooseQuery;
+}
+function requireOrganizationId(organizationId, operation) {
+  if (!organizationId) {
+    throw new Error(
+      `${operation} requires organizationId. In multi-tenant mode, you must explicitly provide organizationId. In single-tenant mode, ensure autoInject is enabled in configuration.`
+    );
+  }
+}
+
+// src/utils/org-resolution.ts
+function resolveOrganizationId(params) {
+  const { explicit, context, container, operation } = params;
+  if (explicit) {
+    return toObjectId(explicit);
+  }
+  if (context?.organizationId) {
+    return toObjectId(context.organizationId);
+  }
+  if (container?.isSingleTenant()) {
+    const singleTenantConfig = container.getSingleTenantConfig();
+    if (singleTenantConfig?.autoInject) {
+      const orgId = container.getOrganizationId();
+      if (orgId) {
+        return toObjectId(orgId);
+      }
+    }
+  }
+  const operationName = operation || "Operation";
+  throw new Error(
+    `${operationName} requires organizationId. Options:
+1. Provide it explicitly in parameters
+2. Pass it via context (from middleware/auth)
+3. Enable single-tenant mode with autoInject: true
+
+Example (multi-tenant):
+  await payroll.${operation || "method"}({ organizationId: org._id, ... });
+
+Example (single-tenant):
+  const payroll = createPayrollInstance()
+    .withModels({ ... })
+    .forSingleTenant({ organizationId: myOrg._id, autoInject: true })
+    .build();`
+  );
+}
+function validateOrganizationId(organizationId, operation) {
+  if (!organizationId) {
+    throw new Error(
+      `${operation} requires organizationId. Provide it explicitly, via context, or enable single-tenant mode with autoInject.`
+    );
+  }
+  try {
+    return toObjectId(organizationId);
+  } catch (error) {
+    throw new Error(
+      `${operation} received invalid organizationId: ${organizationId}. Must be a valid ObjectId, ObjectId string, or ObjectId-like object.`
+    );
+  }
+}
+function tryResolveOrganizationId(params) {
+  try {
+    return resolveOrganizationId(params);
+  } catch {
+    return null;
+  }
+}
+
+// src/utils/employee-identity.ts
+function detectEmployeeIdType(employeeId) {
+  if (isValidObjectId(employeeId)) {
+    return "objectId";
+  }
+  return "string";
+}
+function normalizeEmployeeId(employeeId) {
+  const idType = detectEmployeeIdType(employeeId);
+  if (idType === "objectId") {
+    return toObjectId(employeeId);
+  }
+  return employeeId;
+}
+function isStringEmployeeId(value) {
+  return typeof value === "string" && !isValidObjectId(value);
+}
+function isObjectIdEmployeeId(value) {
+  return isValidObjectId(value);
+}
+function formatEmployeeId(employeeId) {
+  const idType = detectEmployeeIdType(employeeId);
+  if (idType === "objectId") {
+    return `_id=${toObjectId(employeeId).toString()}`;
+  }
+  return `employeeId=${employeeId}`;
+}
+
+export { DEFAULT_CARRY_OVER, DEFAULT_LEAVE_ALLOCATIONS, EmployeeQueryBuilder, PayrollQueryBuilder, QueryBuilder, accrueLeaveToBalance, addDays, addMonths, addYears, applyPercentage, applyProRating, applyTaxBrackets, buildAggregationPipeline, buildEmployeeQuery, buildPayrollQuery, calculateAllowanceAmount, calculateAllowances, calculateCarryOver, calculateCompensationBreakdown, calculateDailyRate, calculateDeductionAmount, calculateDeductions, calculateGross, calculateHourlyRate, calculateLeaveDays, calculateNet, calculateOvertime, calculatePercentage, calculateProRatedSalary, calculateProRating, calculateProbationEnd, calculateTax, calculateTotalCompensation, calculateUnpaidLeaveDeduction, calculateYearsOfService, calculation_default as calculationUtils, canReceiveSalary, canUpdateEmployment, compose, composeValidators, createAllowanceCalculator, createChildLogger, createDeductionCalculator, createQueryBuilder, createSilentLogger, createValidator, date_default as dateUtils, daysBetween, detectEmployeeIdType, diffInDays, diffInMonths, diffInYears, disableLogging, employee, employeeExistsSecure, enableLogging, endOfDay, endOfMonth, endOfYear, findEmployeeSecure, findEmployeesSecure, formatDateForDB, formatEmployeeId, formatPeriod, getAvailableDays, getCurrentPeriod, getDayName, getDayOfWeek, getDaysInMonth, getLeaveBalance, getLeaveBalances, getLeaveSummary, getLogger, getMonthName, getPayPeriod, getPayPeriodDateRange, getShortMonthName, getUnpaidLeaveDays, getWorkingDaysInMonth, groupStage, hasCompensation, hasCompletedProbation, hasLeaveBalance, hasRequiredFields, inRange, initializeLeaveBalances, isActive, isDateInRange, isEligibleForBonus, isEligibleForPayroll, isEmployed, isInProbation, isInRange, isLoggingEnabled, isObjectIdEmployeeId, isOnLeave, isOnProbation, isPositive, isStringEmployeeId, isSuspended, isTerminated, isValidBankDetails, isValidCompensation, isValidEmploymentType, isValidObjectId, isValidStatus, isWeekday, isWeekend, leave_default as leaveUtils, limitStage, logger, lookupStage, matchStage, max, maxValue, min, minValue, monthsBetween, normalizeEmployeeId, oneOf, parseDBDate, parsePeriod, payroll, pipe, proRateAllocation, projectStage, query_builders_default as queryBuilders, requireOrganizationId, required, resetLogger, resolveOrganizationId, roundTo, safeToObjectId, setLogger, skipStage, sortStage, startOfDay, startOfMonth, startOfYear, subDays, subMonths, sum, sumAllowances, sumBy, sumDeductions, toObjectId, tryResolveOrganizationId, unwindStage, validateOrganizationId, validation_default as validationUtils };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map