@classytic/payroll 1.0.0 → 2.7.5

package/dist/schemas/index.js

@@ -0,0 +1,1452 @@
+import mongoose, { Schema } from 'mongoose';
+
+// src/schemas/index.ts
+
+// 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);
+var DEPARTMENT = {
+  MANAGEMENT: "management",
+  TRAINING: "training",
+  SALES: "sales",
+  OPERATIONS: "operations",
+  SUPPORT: "support",
+  HR: "hr",
+  MAINTENANCE: "maintenance",
+  MARKETING: "marketing",
+  FINANCE: "finance",
+  IT: "it"
+};
+var DEPARTMENT_VALUES = Object.values(DEPARTMENT);
+var PAYMENT_FREQUENCY = {
+  MONTHLY: "monthly",
+  BI_WEEKLY: "bi_weekly",
+  WEEKLY: "weekly",
+  HOURLY: "hourly",
+  DAILY: "daily"
+};
+var PAYMENT_FREQUENCY_VALUES = Object.values(PAYMENT_FREQUENCY);
+var PAYMENT_METHOD = {
+  BANK: "bank",
+  CASH: "cash",
+  MOBILE: "mobile",
+  BKASH: "bkash",
+  NAGAD: "nagad",
+  ROCKET: "rocket",
+  CHECK: "check"
+};
+var PAYMENT_METHOD_VALUES = Object.values(PAYMENT_METHOD);
+var ALLOWANCE_TYPE = {
+  HOUSING: "housing",
+  TRANSPORT: "transport",
+  MEAL: "meal",
+  MOBILE: "mobile",
+  MEDICAL: "medical",
+  EDUCATION: "education",
+  BONUS: "bonus",
+  OTHER: "other"
+};
+var ALLOWANCE_TYPE_VALUES = Object.values(ALLOWANCE_TYPE);
+var DEDUCTION_TYPE = {
+  TAX: "tax",
+  LOAN: "loan",
+  ADVANCE: "advance",
+  PROVIDENT_FUND: "provident_fund",
+  INSURANCE: "insurance",
+  ABSENCE: "absence",
+  OTHER: "other"
+};
+var DEDUCTION_TYPE_VALUES = Object.values(DEDUCTION_TYPE);
+var PAYROLL_STATUS = {
+  PENDING: "pending",
+  PROCESSING: "processing",
+  PAID: "paid",
+  FAILED: "failed",
+  VOIDED: "voided",
+  REVERSED: "reversed"
+};
+var PAYROLL_STATUS_VALUES = Object.values(PAYROLL_STATUS);
+var TERMINATION_REASON = {
+  RESIGNATION: "resignation",
+  RETIREMENT: "retirement",
+  TERMINATION: "termination",
+  CONTRACT_END: "contract_end",
+  MUTUAL_AGREEMENT: "mutual_agreement",
+  OTHER: "other"
+};
+var TERMINATION_REASON_VALUES = Object.values(TERMINATION_REASON);
+var LEAVE_TYPE = {
+  ANNUAL: "annual",
+  SICK: "sick",
+  UNPAID: "unpaid",
+  MATERNITY: "maternity",
+  PATERNITY: "paternity",
+  BEREAVEMENT: "bereavement",
+  COMPENSATORY: "compensatory",
+  OTHER: "other"
+};
+var LEAVE_TYPE_VALUES = Object.values(LEAVE_TYPE);
+var LEAVE_REQUEST_STATUS = {
+  PENDING: "pending",
+  APPROVED: "approved",
+  REJECTED: "rejected",
+  CANCELLED: "cancelled"
+};
+var LEAVE_REQUEST_STATUS_VALUES = Object.values(LEAVE_REQUEST_STATUS);
+var TAX_TYPE = {
+  INCOME_TAX: "income_tax",
+  SOCIAL_SECURITY: "social_security",
+  HEALTH_INSURANCE: "health_insurance",
+  PENSION: "pension",
+  EMPLOYMENT_INSURANCE: "employment_insurance",
+  LOCAL_TAX: "local_tax",
+  OTHER: "other"
+};
+var TAX_TYPE_VALUES = Object.values(TAX_TYPE);
+var TAX_STATUS = {
+  PENDING: "pending",
+  SUBMITTED: "submitted",
+  PAID: "paid",
+  CANCELLED: "cancelled"
+};
+var TAX_STATUS_VALUES = Object.values(TAX_STATUS);
+
+// src/config.ts
+var HRM_CONFIG = {
+  dataRetention: {
+    /**
+     * Default retention period for payroll records in seconds
+     *
+     * STANDARD APPROACH: expireAt field + configurable TTL index
+     *
+     * ## How It Works:
+     * 1. Set expireAt date on each payroll record
+     * 2. Call PayrollRecord.configureRetention() at app startup
+     * 3. MongoDB deletes documents when expireAt is reached
+     *
+     * ## Usage:
+     *
+     * @example Configure at initialization
+     * ```typescript
+     * await payroll.init({ ... });
+     * await PayrollRecord.configureRetention(0); // 0 = delete when expireAt reached
+     * ```
+     *
+     * @example Set expireAt per record
+     * ```typescript
+     * const expireAt = PayrollRecord.calculateExpireAt(7); // 7 years
+     * await PayrollRecord.updateOne({ _id }, { expireAt });
+     * ```
+     *
+     * ## Jurisdiction Requirements:
+     * - USA: 7 years → 220752000 seconds
+     * - EU/UK: 6 years → 189216000 seconds
+     * - Germany: 10 years → 315360000 seconds
+     * - India: 8 years → 252288000 seconds
+     *
+     * Set to 0 to disable TTL
+     */
+    payrollRecordsTTL: 63072e3}};
+var ORG_ROLES = {
+  OWNER: {
+    key: "owner",
+    label: "Owner",
+    description: "Full organization access (set by Organization model)"
+  },
+  MANAGER: {
+    key: "manager",
+    label: "Manager",
+    description: "Management and administrative features"
+  },
+  TRAINER: {
+    key: "trainer",
+    label: "Trainer",
+    description: "Training and coaching features"
+  },
+  STAFF: {
+    key: "staff",
+    label: "Staff",
+    description: "General staff access to basic features"
+  },
+  INTERN: {
+    key: "intern",
+    label: "Intern",
+    description: "Limited access for interns"
+  },
+  CONSULTANT: {
+    key: "consultant",
+    label: "Consultant",
+    description: "Project-based consultant access"
+  }
+};
+Object.values(ORG_ROLES).map((role) => role.key);
+var 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 }
+);
+
+// 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 logger = {
+  info: (message, meta) => {
+    currentLogger.info(message, meta);
+  },
+  error: (message, meta) => {
+    currentLogger.error(message, meta);
+  },
+  warn: (message, meta) => {
+    currentLogger.warn(message, meta);
+  },
+  debug: (message, meta) => {
+    currentLogger.debug(message, meta);
+  }
+};
+
+// src/models/leave-request.model.ts
+var leaveRequestSchema = new Schema(
+  {
+    organizationId: {
+      type: Schema.Types.ObjectId,
+      required: false,
+      // Optional for single-tenant mode
+      ref: "Organization"
+    },
+    employeeId: {
+      type: Schema.Types.ObjectId,
+      required: true,
+      ref: "Employee"
+    },
+    userId: {
+      type: Schema.Types.ObjectId,
+      required: false,
+      // Optional for guest employees
+      ref: "User"
+    },
+    type: {
+      type: String,
+      enum: LEAVE_TYPE_VALUES,
+      required: true
+    },
+    startDate: {
+      type: Date,
+      required: true,
+      validate: {
+        validator: function(value) {
+          return !this.endDate || value <= this.endDate;
+        },
+        message: "Start date must be before or equal to end date"
+      }
+    },
+    endDate: {
+      type: Date,
+      required: true,
+      validate: {
+        validator: function(value) {
+          return !this.startDate || value >= this.startDate;
+        },
+        message: "End date must be after or equal to start date"
+      }
+    },
+    days: {
+      type: Number,
+      required: true,
+      min: [0.5, "Days must be at least 0.5"]
+    },
+    halfDay: { type: Boolean, default: false },
+    reason: String,
+    status: {
+      type: String,
+      enum: LEAVE_REQUEST_STATUS_VALUES,
+      default: "pending"
+    },
+    reviewedBy: { type: Schema.Types.ObjectId, ref: "User" },
+    reviewedAt: Date,
+    reviewNotes: String,
+    attachments: [String],
+    metadata: { type: Schema.Types.Mixed, default: {} }
+  },
+  { timestamps: true }
+);
+leaveRequestSchema.virtual("isPending").get(function() {
+  return this.status === LEAVE_REQUEST_STATUS.PENDING;
+});
+leaveRequestSchema.virtual("isApproved").get(function() {
+  return this.status === LEAVE_REQUEST_STATUS.APPROVED;
+});
+leaveRequestSchema.virtual("isRejected").get(function() {
+  return this.status === LEAVE_REQUEST_STATUS.REJECTED;
+});
+leaveRequestSchema.virtual("isCancelled").get(function() {
+  return this.status === LEAVE_REQUEST_STATUS.CANCELLED;
+});
+leaveRequestSchema.methods.approve = function(reviewerId, notes) {
+  if (this.status !== LEAVE_REQUEST_STATUS.PENDING) {
+    throw new Error("Can only approve pending requests");
+  }
+  this.status = LEAVE_REQUEST_STATUS.APPROVED;
+  this.reviewedBy = reviewerId;
+  this.reviewedAt = /* @__PURE__ */ new Date();
+  if (notes) this.reviewNotes = notes;
+  logger.info("Leave request approved", {
+    requestId: this._id.toString(),
+    employeeId: this.employeeId.toString(),
+    type: this.type,
+    days: this.days
+  });
+};
+leaveRequestSchema.methods.reject = function(reviewerId, notes) {
+  if (this.status !== LEAVE_REQUEST_STATUS.PENDING) {
+    throw new Error("Can only reject pending requests");
+  }
+  this.status = LEAVE_REQUEST_STATUS.REJECTED;
+  this.reviewedBy = reviewerId;
+  this.reviewedAt = /* @__PURE__ */ new Date();
+  if (notes) this.reviewNotes = notes;
+  logger.info("Leave request rejected", {
+    requestId: this._id.toString(),
+    employeeId: this.employeeId.toString(),
+    type: this.type,
+    days: this.days
+  });
+};
+leaveRequestSchema.methods.cancel = function() {
+  if (this.status !== LEAVE_REQUEST_STATUS.PENDING) {
+    throw new Error("Can only cancel pending requests");
+  }
+  this.status = LEAVE_REQUEST_STATUS.CANCELLED;
+  logger.info("Leave request cancelled", {
+    requestId: this._id.toString(),
+    employeeId: this.employeeId.toString(),
+    type: this.type,
+    days: this.days
+  });
+};
+leaveRequestSchema.statics.findByEmployee = function(employeeId, options = {}) {
+  const query = { employeeId };
+  if (options.status) query.status = options.status;
+  if (options.year) {
+    query.startDate = {
+      $gte: new Date(options.year, 0, 1),
+      $lt: new Date(options.year + 1, 0, 1)
+    };
+  }
+  return this.find(query).sort({ startDate: -1 }).limit(options.limit || 50);
+};
+leaveRequestSchema.statics.findPendingByOrganization = function(organizationId) {
+  const query = {
+    status: LEAVE_REQUEST_STATUS.PENDING
+  };
+  if (organizationId) {
+    query.organizationId = organizationId;
+  }
+  return this.find(query).sort({ createdAt: -1 });
+};
+leaveRequestSchema.statics.findByPeriod = function(organizationId, startDate, endDate, options = {}) {
+  const query = {
+    $or: [
+      { startDate: { $gte: startDate, $lte: endDate } },
+      { endDate: { $gte: startDate, $lte: endDate } },
+      {
+        startDate: { $lte: startDate },
+        endDate: { $gte: endDate }
+      }
+    ]
+  };
+  if (organizationId) {
+    query.organizationId = organizationId;
+  }
+  if (options.status) query.status = options.status;
+  if (options.type) query.type = options.type;
+  return this.find(query).sort({ startDate: 1 });
+};
+leaveRequestSchema.statics.getLeaveStats = function(employeeId, year) {
+  return this.aggregate([
+    {
+      $match: {
+        employeeId,
+        status: LEAVE_REQUEST_STATUS.APPROVED,
+        startDate: {
+          $gte: new Date(year, 0, 1),
+          $lt: new Date(year + 1, 0, 1)
+        }
+      }
+    },
+    {
+      $group: {
+        _id: "$type",
+        totalDays: { $sum: "$days" },
+        count: { $sum: 1 }
+      }
+    }
+  ]).then(
+    (results) => results
+  );
+};
+leaveRequestSchema.statics.getOrganizationSummary = function(organizationId, year) {
+  const matchStage = {
+    startDate: {
+      $gte: new Date(year, 0, 1),
+      $lt: new Date(year + 1, 0, 1)
+    }
+  };
+  if (organizationId) {
+    matchStage.organizationId = organizationId;
+  }
+  return this.aggregate([
+    {
+      $match: matchStage
+    },
+    {
+      $group: {
+        _id: { status: "$status", type: "$type" },
+        totalDays: { $sum: "$days" },
+        count: { $sum: 1 }
+      }
+    }
+  ]);
+};
+leaveRequestSchema.statics.findOverlapping = function(employeeId, startDate, endDate, excludeRequestId) {
+  const query = {
+    employeeId,
+    status: { $in: [LEAVE_REQUEST_STATUS.PENDING, LEAVE_REQUEST_STATUS.APPROVED] },
+    // Overlapping condition: new request overlaps with existing
+    startDate: { $lte: endDate },
+    endDate: { $gte: startDate }
+  };
+  if (excludeRequestId) {
+    query._id = { $ne: excludeRequestId };
+  }
+  return this.find(query).sort({ startDate: 1 });
+};
+leaveRequestSchema.statics.hasOverlap = async function(employeeId, startDate, endDate, excludeRequestId) {
+  const query = {
+    employeeId,
+    status: { $in: [LEAVE_REQUEST_STATUS.PENDING, LEAVE_REQUEST_STATUS.APPROVED] },
+    startDate: { $lte: endDate },
+    endDate: { $gte: startDate }
+  };
+  if (excludeRequestId) {
+    query._id = { $ne: excludeRequestId };
+  }
+  const count = await this.countDocuments(query);
+  return count > 0;
+};
+function getLeaveRequestModel(connection = mongoose.connection) {
+  const modelName = "LeaveRequest";
+  if (connection.models[modelName]) {
+    return connection.models[modelName];
+  }
+  return connection.model(
+    modelName,
+    leaveRequestSchema
+  );
+}
+
+// src/schemas/leave.ts
+var leaveBalanceSchema = new Schema(
+  {
+    type: {
+      type: String,
+      enum: LEAVE_TYPE_VALUES,
+      required: true
+    },
+    allocated: { type: Number, default: 0, min: 0 },
+    used: { type: Number, default: 0, min: 0 },
+    pending: { type: Number, default: 0, min: 0 },
+    carriedOver: { type: Number, default: 0, min: 0 },
+    expiresAt: { type: Date },
+    year: { type: Number, required: true }
+  },
+  { _id: false }
+);
+var leaveBalanceFields = {
+  leaveBalances: [leaveBalanceSchema]
+};
+var leaveRequestIndexes = [
+  { fields: { organizationId: 1, employeeId: 1, startDate: -1 } },
+  { fields: { organizationId: 1, status: 1, createdAt: -1 } },
+  { fields: { employeeId: 1, status: 1 } },
+  { fields: { organizationId: 1, type: 1, status: 1 } }
+];
+var leaveRequestTTLIndex = {
+  fields: { createdAt: 1 },
+  options: {
+    expireAfterSeconds: 63072e3,
+    // 2 years
+    partialFilterExpression: {
+      status: { $in: ["approved", "rejected", "cancelled"] }
+    }
+  }
+};
+function applyLeaveRequestIndexes(schema, options = {}) {
+  if (!options.createIndexes) return;
+  for (const { fields } of leaveRequestIndexes) {
+    schema.index(fields);
+  }
+  if (options.enableTTL) {
+    schema.index(leaveRequestTTLIndex.fields, {
+      ...leaveRequestTTLIndex.options,
+      expireAfterSeconds: options.ttlSeconds ?? leaveRequestTTLIndex.options.expireAfterSeconds
+    });
+  }
+}
+function getLeaveRequestFields() {
+  const paths = leaveRequestSchema.paths;
+  const fields = {};
+  for (const [key, pathObj] of Object.entries(paths)) {
+    if (key === "_id" || key === "__v" || key === "createdAt" || key === "updatedAt") {
+      continue;
+    }
+    fields[key] = pathObj.options || {};
+  }
+  return fields;
+}
+
+// src/core/state-machine.ts
+var StateMachine = class {
+  constructor(config) {
+    this.config = config;
+    this.validTransitions = /* @__PURE__ */ new Map();
+    for (const state of config.states) {
+      this.validTransitions.set(state, /* @__PURE__ */ new Set());
+    }
+    for (const transition of config.transitions) {
+      const fromStates = Array.isArray(transition.from) ? transition.from : [transition.from];
+      for (const from of fromStates) {
+        this.validTransitions.get(from)?.add(transition.to);
+      }
+    }
+    this.terminalStates = new Set(config.terminal || []);
+  }
+  validTransitions;
+  terminalStates;
+  /**
+   * Get the initial state
+   */
+  get initial() {
+    return this.config.initial;
+  }
+  /**
+   * Get all valid states
+   */
+  get states() {
+    return this.config.states;
+  }
+  /**
+   * Check if a state is valid
+   */
+  isValidState(state) {
+    return this.config.states.includes(state);
+  }
+  /**
+   * Check if a state is terminal (no outgoing transitions)
+   */
+  isTerminal(state) {
+    return this.terminalStates.has(state);
+  }
+  /**
+   * Check if transition from one state to another is valid
+   */
+  canTransition(from, to) {
+    return this.validTransitions.get(from)?.has(to) ?? false;
+  }
+  /**
+   * Get all valid next states from current state
+   */
+  getNextStates(from) {
+    return Array.from(this.validTransitions.get(from) || []);
+  }
+  /**
+   * Validate a transition and return result
+   */
+  validateTransition(from, to) {
+    if (!this.isValidState(from)) {
+      return {
+        success: false,
+        from,
+        to,
+        error: `Invalid current state: '${from}'`
+      };
+    }
+    if (!this.isValidState(to)) {
+      return {
+        success: false,
+        from,
+        to,
+        error: `Invalid target state: '${to}'`
+      };
+    }
+    if (this.isTerminal(from)) {
+      return {
+        success: false,
+        from,
+        to,
+        error: `Cannot transition from terminal state '${from}'`
+      };
+    }
+    if (!this.canTransition(from, to)) {
+      const validNext = this.getNextStates(from);
+      return {
+        success: false,
+        from,
+        to,
+        error: `Invalid transition: '${from}' \u2192 '${to}'. Valid transitions from '${from}': [${validNext.join(", ")}]`
+      };
+    }
+    return { success: true, from, to };
+  }
+  /**
+   * Assert a transition is valid, throw if not
+   */
+  assertTransition(from, to) {
+    const result = this.validateTransition(from, to);
+    if (!result.success) {
+      throw new Error(result.error);
+    }
+  }
+};
+function createStateMachine(config) {
+  return new StateMachine(config);
+}
+
+// src/core/payroll-states.ts
+createStateMachine({
+  states: ["pending", "processing", "paid", "failed", "voided", "reversed"],
+  initial: "pending",
+  transitions: [
+    // Normal flow
+    { from: "pending", to: "processing" },
+    { from: "processing", to: "paid" },
+    // Direct payment (skip processing for single salary)
+    { from: "pending", to: "paid" },
+    // Failure handling
+    { from: "processing", to: "failed" },
+    { from: "failed", to: "pending" },
+    // Retry
+    // Void (unpaid only - pending, processing, or failed)
+    { from: ["pending", "processing", "failed"], to: "voided" },
+    // Reversal (paid only)
+    { from: "paid", to: "reversed" },
+    // Restore voided (back to pending for re-processing)
+    { from: "voided", to: "pending" }
+  ],
+  terminal: ["reversed"]
+  // Only reversed is truly terminal
+});
+var TaxStatusMachine = createStateMachine({
+  states: ["pending", "submitted", "paid", "cancelled"],
+  initial: "pending",
+  transitions: [
+    { from: "pending", to: "submitted" },
+    { from: "submitted", to: "paid" },
+    // Direct payment (some jurisdictions)
+    { from: "pending", to: "paid" },
+    // Cancellation (from any non-terminal state)
+    { from: ["pending", "submitted"], to: "cancelled" }
+  ],
+  terminal: ["paid", "cancelled"]
+});
+createStateMachine({
+  states: ["pending", "approved", "rejected", "cancelled"],
+  initial: "pending",
+  transitions: [
+    { from: "pending", to: "approved" },
+    { from: "pending", to: "rejected" },
+    { from: "pending", to: "cancelled" },
+    // Cancel approved leave (before it starts)
+    { from: "approved", to: "cancelled" }
+  ],
+  terminal: ["rejected", "cancelled"]
+});
+createStateMachine({
+  states: ["active", "on_leave", "suspended", "terminated"],
+  initial: "active",
+  transitions: [
+    // Leave management
+    { from: "active", to: "on_leave" },
+    { from: "on_leave", to: "active" },
+    // Suspension
+    { from: ["active", "on_leave"], to: "suspended" },
+    { from: "suspended", to: "active" },
+    // Termination (from any state)
+    { from: ["active", "on_leave", "suspended"], to: "terminated" },
+    // Re-hire (back to active)
+    { from: "terminated", to: "active" }
+  ],
+  terminal: []
+  // No terminal states (re-hire possible)
+});
+
+// src/models/tax-withholding.model.ts
+var taxWithholdingSchema = new Schema(
+  {
+    organizationId: {
+      type: Schema.Types.ObjectId,
+      required: true,
+      ref: "Organization"
+    },
+    employeeId: {
+      type: Schema.Types.ObjectId,
+      required: true,
+      ref: "Employee"
+    },
+    userId: {
+      type: Schema.Types.ObjectId,
+      required: false,
+      ref: "User"
+    },
+    payrollRecordId: {
+      type: Schema.Types.ObjectId,
+      required: true,
+      ref: "PayrollRecord"
+    },
+    transactionId: {
+      type: Schema.Types.ObjectId,
+      required: true,
+      ref: "Transaction"
+    },
+    period: {
+      type: periodSchema,
+      required: true
+    },
+    amount: {
+      type: Number,
+      required: true,
+      min: 0
+    },
+    currency: {
+      type: String,
+      default: "USD"
+    },
+    taxType: {
+      type: String,
+      enum: TAX_TYPE_VALUES,
+      required: true
+    },
+    taxRate: {
+      type: Number,
+      required: true,
+      min: 0,
+      max: 1
+    },
+    taxableAmount: {
+      type: Number,
+      required: true,
+      min: 0
+    },
+    status: {
+      type: String,
+      enum: TAX_STATUS_VALUES,
+      default: "pending"
+    },
+    submittedAt: Date,
+    paidAt: Date,
+    governmentTransactionId: {
+      type: Schema.Types.ObjectId,
+      ref: "Transaction"
+    },
+    referenceNumber: String,
+    // Void metadata (when payroll is voided/reversed)
+    voidedAt: { type: Date },
+    voidedBy: { type: Schema.Types.ObjectId, ref: "User" },
+    voidReason: { type: String },
+    voidMetadata: { type: Schema.Types.Mixed },
+    notes: String,
+    metadata: { type: Schema.Types.Mixed, default: {} }
+  },
+  { timestamps: true }
+);
+taxWithholdingSchema.index({ organizationId: 1, status: 1, "period.year": 1, "period.month": 1 });
+taxWithholdingSchema.index({ employeeId: 1, "period.year": -1, "period.month": -1 });
+taxWithholdingSchema.index({ payrollRecordId: 1 });
+taxWithholdingSchema.index({ transactionId: 1 });
+taxWithholdingSchema.index({ organizationId: 1, taxType: 1, status: 1 });
+taxWithholdingSchema.index({ governmentTransactionId: 1 }, { sparse: true });
+taxWithholdingSchema.virtual("isPending").get(function() {
+  return this.status === TAX_STATUS.PENDING;
+});
+taxWithholdingSchema.virtual("isPaid").get(function() {
+  return this.status === TAX_STATUS.PAID;
+});
+taxWithholdingSchema.virtual("isSubmitted").get(function() {
+  return this.status === TAX_STATUS.SUBMITTED;
+});
+taxWithholdingSchema.methods.markAsSubmitted = function(submittedAt = /* @__PURE__ */ new Date()) {
+  const transition = TaxStatusMachine.validateTransition(this.status, TAX_STATUS.SUBMITTED);
+  if (!transition.success) {
+    throw new Error(transition.error);
+  }
+  this.status = TAX_STATUS.SUBMITTED;
+  this.submittedAt = submittedAt;
+  logger.info("Tax withholding marked as submitted", {
+    withholdingId: this._id.toString(),
+    employeeId: this.employeeId.toString(),
+    taxType: this.taxType,
+    amount: this.amount
+  });
+};
+taxWithholdingSchema.methods.markAsPaid = function(transactionId, referenceNumber, paidAt = /* @__PURE__ */ new Date()) {
+  const transition = TaxStatusMachine.validateTransition(this.status, TAX_STATUS.PAID);
+  if (!transition.success) {
+    throw new Error(transition.error);
+  }
+  this.status = TAX_STATUS.PAID;
+  this.governmentTransactionId = transactionId;
+  this.referenceNumber = referenceNumber;
+  this.paidAt = paidAt;
+  logger.info("Tax withholding marked as paid", {
+    withholdingId: this._id.toString(),
+    employeeId: this.employeeId.toString(),
+    taxType: this.taxType,
+    amount: this.amount,
+    referenceNumber
+  });
+};
+taxWithholdingSchema.statics.findByPeriod = function(organizationId, month, year) {
+  return this.find({
+    organizationId,
+    "period.month": month,
+    "period.year": year
+  });
+};
+taxWithholdingSchema.statics.findByEmployee = function(employeeId, options = {}) {
+  const query = { employeeId };
+  if (options.year) {
+    query["period.year"] = options.year;
+  }
+  if (options.taxType) {
+    query.taxType = options.taxType;
+  }
+  if (options.status) {
+    query.status = options.status;
+  }
+  return this.find(query).sort({ "period.year": -1, "period.month": -1 }).limit(options.limit || 50);
+};
+taxWithholdingSchema.statics.findPending = function(organizationId, options = {}) {
+  const query = {
+    organizationId,
+    status: TAX_STATUS.PENDING
+  };
+  if (options.taxType) {
+    query.taxType = options.taxType;
+  }
+  if (options.fromMonth && options.fromYear) {
+    query.$or = query.$or || [];
+    query.$or.push({
+      $and: [
+        { "period.year": { $gt: options.fromYear } }
+      ]
+    });
+    query.$or.push({
+      $and: [
+        { "period.year": options.fromYear },
+        { "period.month": { $gte: options.fromMonth } }
+      ]
+    });
+  }
+  if (options.toMonth && options.toYear) {
+    const existingOr = query.$or;
+    delete query.$or;
+    query.$and = query.$and || [];
+    if (existingOr) {
+      query.$and.push({ $or: existingOr });
+    }
+    query.$and.push({
+      $or: [
+        { "period.year": { $lt: options.toYear } },
+        {
+          $and: [
+            { "period.year": options.toYear },
+            { "period.month": { $lte: options.toMonth } }
+          ]
+        }
+      ]
+    });
+  }
+  return this.find(query).sort({ "period.year": 1, "period.month": 1 });
+};
+taxWithholdingSchema.statics.getSummaryByType = function(organizationId, fromPeriod, toPeriod) {
+  return this.aggregate([
+    {
+      $match: {
+        organizationId,
+        $or: [
+          { "period.year": { $gt: fromPeriod.year } },
+          {
+            $and: [
+              { "period.year": fromPeriod.year },
+              { "period.month": { $gte: fromPeriod.month } }
+            ]
+          }
+        ],
+        $and: [
+          {
+            $or: [
+              { "period.year": { $lt: toPeriod.year } },
+              {
+                $and: [
+                  { "period.year": toPeriod.year },
+                  { "period.month": { $lte: toPeriod.month } }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      $group: {
+        _id: "$taxType",
+        totalAmount: { $sum: "$amount" },
+        count: { $sum: 1 },
+        withholdingIds: { $push: "$_id" }
+      }
+    },
+    {
+      $project: {
+        _id: 0,
+        taxType: "$_id",
+        totalAmount: 1,
+        count: 1,
+        withholdingIds: 1
+      }
+    }
+  ]).then(
+    (results) => results.map((r) => ({
+      taxType: r.taxType,
+      totalAmount: r.totalAmount,
+      count: r.count,
+      withholdingIds: r.withholdingIds
+    }))
+  );
+};
+taxWithholdingSchema.statics.getByPayrollRecord = function(payrollRecordId) {
+  return this.find({ payrollRecordId });
+};
+taxWithholdingSchema.statics.getTotalByOrganization = function(organizationId, options = {}) {
+  const match = { organizationId };
+  if (options.status) {
+    match.status = options.status;
+  }
+  if (options.year) {
+    match["period.year"] = options.year;
+  }
+  return this.aggregate([
+    { $match: match },
+    {
+      $group: {
+        _id: null,
+        totalAmount: { $sum: "$amount" },
+        count: { $sum: 1 }
+      }
+    }
+  ]).then(
+    (results) => results[0] || { totalAmount: 0, count: 0 }
+  );
+};
+taxWithholdingSchema.statics.addTTLIndex = async function(fieldName, ttlSeconds, options = {}) {
+  const collection = this.collection;
+  const indexName = `${fieldName}_ttl_1`;
+  try {
+    const indexes = await collection.indexes();
+    const hasTTLIndex = indexes.some((idx) => idx.name === indexName);
+    if (hasTTLIndex) {
+      await collection.dropIndex(indexName);
+      logger.info("Dropped existing TTL index", { indexName, fieldName });
+    }
+    const indexOptions = {
+      name: indexName,
+      expireAfterSeconds: ttlSeconds
+    };
+    indexOptions.partialFilterExpression = {
+      [fieldName]: { $exists: true },
+      ...options.partialFilter
+    };
+    await collection.createIndex(
+      { [fieldName]: 1 },
+      indexOptions
+    );
+    logger.info("Added TTL index for auto-cleanup", {
+      fieldName,
+      indexName,
+      expireAfterSeconds: ttlSeconds,
+      retentionDays: Math.round(ttlSeconds / (24 * 60 * 60)),
+      partialFilter: indexOptions.partialFilterExpression
+    });
+  } catch (error) {
+    logger.error("Failed to add TTL index", {
+      fieldName,
+      error: error.message
+    });
+    throw error;
+  }
+};
+taxWithholdingSchema.statics.removeTTLIndex = async function(fieldName) {
+  const collection = this.collection;
+  const indexName = `${fieldName}_ttl_1`;
+  try {
+    const indexes = await collection.indexes();
+    const hasTTLIndex = indexes.some((idx) => idx.name === indexName);
+    if (hasTTLIndex) {
+      await collection.dropIndex(indexName);
+      logger.info("Removed TTL index", { fieldName, indexName });
+    } else {
+      logger.warn("TTL index not found", { fieldName, indexName });
+    }
+  } catch (error) {
+    logger.error("Failed to remove TTL index", {
+      fieldName,
+      error: error.message
+    });
+    throw error;
+  }
+};
+function getTaxWithholdingModel(connection = mongoose.connection) {
+  const modelName = "TaxWithholding";
+  if (connection.models[modelName]) {
+    return connection.models[modelName];
+  }
+  return connection.model(
+    modelName,
+    taxWithholdingSchema
+  );
+}
+
+// src/schemas/tax-withholding.ts
+var taxWithholdingIndexes = [
+  { fields: { organizationId: 1, status: 1, "period.year": 1, "period.month": 1 } },
+  { fields: { employeeId: 1, "period.year": -1, "period.month": -1 } },
+  { fields: { payrollRecordId: 1 } },
+  { fields: { transactionId: 1 } },
+  { fields: { organizationId: 1, taxType: 1, status: 1 } },
+  { fields: { governmentTransactionId: 1 }, options: { sparse: true } }
+];
+function applyTaxWithholdingIndexes(schema) {
+  for (const { fields, options } of taxWithholdingIndexes) {
+    schema.index(fields, options);
+  }
+}
+function getTaxWithholdingFields() {
+  const paths = taxWithholdingSchema.paths;
+  const fields = {};
+  for (const [key, pathObj] of Object.entries(paths)) {
+    if (key === "_id" || key === "__v" || key === "createdAt" || key === "updatedAt") {
+      continue;
+    }
+    fields[key] = pathObj.options || {};
+  }
+  return fields;
+}
+
+// src/schemas/index.ts
+var allowanceSchema = new Schema(
+  {
+    type: {
+      type: String,
+      enum: ALLOWANCE_TYPE_VALUES,
+      required: true
+    },
+    name: { type: String },
+    amount: { type: Number, required: true, min: 0 },
+    isPercentage: { type: Boolean, default: false },
+    value: { type: Number },
+    taxable: { type: Boolean, default: true },
+    recurring: { type: Boolean, default: true },
+    effectiveFrom: { type: Date, default: () => /* @__PURE__ */ new Date() },
+    effectiveTo: { type: Date }
+  },
+  { _id: false }
+);
+var deductionSchema = new Schema(
+  {
+    type: {
+      type: String,
+      enum: DEDUCTION_TYPE_VALUES,
+      required: true
+    },
+    name: { type: String },
+    amount: { type: Number, required: true, min: 0 },
+    isPercentage: { type: Boolean, default: false },
+    value: { type: Number },
+    auto: { type: Boolean, default: false },
+    recurring: { type: Boolean, default: true },
+    effectiveFrom: { type: Date, default: () => /* @__PURE__ */ new Date() },
+    effectiveTo: { type: Date },
+    description: { type: String }
+  },
+  { _id: false }
+);
+var compensationSchema = new Schema(
+  {
+    baseAmount: { type: Number, required: true, min: 0 },
+    frequency: {
+      type: String,
+      enum: PAYMENT_FREQUENCY_VALUES,
+      default: "monthly"
+    },
+    currency: { type: String },
+    // No default - use config or USD fallback in application logic
+    allowances: [allowanceSchema],
+    deductions: [deductionSchema],
+    grossSalary: { type: Number, default: 0 },
+    netSalary: { type: Number, default: 0 },
+    effectiveFrom: { type: Date, default: () => /* @__PURE__ */ new Date() },
+    lastModified: { type: Date, default: () => /* @__PURE__ */ new Date() }
+  },
+  { _id: false }
+);
+var workScheduleSchema = new Schema(
+  {
+    hoursPerWeek: { type: Number, min: 0, max: 168 },
+    hoursPerDay: { type: Number, min: 0, max: 24 },
+    workingDays: [{ type: Number, min: 0, max: 6 }],
+    shiftStart: { type: String },
+    shiftEnd: { type: String }
+  },
+  { _id: false }
+);
+var bankDetailsSchema = new Schema(
+  {
+    accountName: { type: String },
+    accountNumber: { type: String },
+    bankName: { type: String },
+    branchName: { type: String },
+    routingNumber: { type: String }
+  },
+  { _id: false }
+);
+var 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 }
+);
+var 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: () => /* @__PURE__ */ new Date() }
+  },
+  { _id: false }
+);
+function createEmploymentFields(options = {}) {
+  const { organizationRef = "Organization", userRef = "User" } = options;
+  return {
+    userId: {
+      type: Schema.Types.ObjectId,
+      ref: userRef,
+      required: false
+      // Allow guest employees (no user account)
+    },
+    email: {
+      type: String,
+      trim: true,
+      lowercase: true,
+      required: false
+      // For guest employees without user account
+    },
+    organizationId: {
+      type: Schema.Types.ObjectId,
+      ref: organizationRef,
+      // Configurable: 'Branch', 'Company', 'Tenant', etc.
+      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: () => ({}) }
+  };
+}
+var payrollBreakdownSchema = new Schema(
+  {
+    baseAmount: { type: Number, required: true, min: 0 },
+    allowances: [
+      {
+        type: { type: String, required: true },
+        amount: { type: Number, required: true, min: 0 },
+        taxable: { type: Boolean, default: true }
+      }
+    ],
+    deductions: [
+      {
+        type: { type: String, required: true },
+        amount: { type: Number, required: true, min: 0 },
+        description: { type: String }
+      }
+    ],
+    grossSalary: { type: Number, required: true, min: 0 },
+    netSalary: { type: Number, required: true, min: 0 },
+    taxableAmount: { type: Number, default: 0, min: 0 },
+    taxAmount: { type: Number, default: 0, 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 }
+);
+function createPayrollRecordFields(options = {}) {
+  const { organizationRef = "Organization", userRef = "User" } = options;
+  return {
+    organizationId: {
+      type: Schema.Types.ObjectId,
+      ref: organizationRef,
+      // Configurable: 'Branch', 'Company', 'Tenant', etc.
+      required: true
+    },
+    employeeId: {
+      type: Schema.Types.ObjectId,
+      required: true
+    },
+    userId: {
+      type: Schema.Types.ObjectId,
+      ref: userRef,
+      required: false
+      // Optional for guest employees
+    },
+    period: { type: periodSchema, required: true },
+    breakdown: { type: payrollBreakdownSchema, required: true },
+    transactionId: { type: Schema.Types.ObjectId },
+    status: {
+      type: String,
+      enum: PAYROLL_STATUS_VALUES,
+      default: "pending"
+    },
+    paidAt: { type: Date },
+    processedAt: { type: Date },
+    paymentMethod: { type: String, enum: PAYMENT_METHOD_VALUES },
+    metadata: { type: Schema.Types.Mixed },
+    processedBy: { type: Schema.Types.ObjectId, ref: userRef },
+    notes: { type: String },
+    payslipUrl: { type: String },
+    exported: { type: Boolean, default: false },
+    exportedAt: { type: Date },
+    // Void / Reversal fields (v2.4.0+)
+    isVoided: { type: Boolean, default: false },
+    voidedAt: { type: Date },
+    voidedBy: { type: Schema.Types.ObjectId, ref: userRef },
+    voidReason: { type: String },
+    reversedAt: { type: Date },
+    reversedBy: { type: Schema.Types.ObjectId, ref: userRef },
+    reversalReason: { type: String },
+    reversalTransactionId: { type: Schema.Types.ObjectId },
+    originalPayrollId: { type: Schema.Types.ObjectId },
+    // TTL expiration (per-document)
+    expireAt: { type: Date }
+  };
+}
+var employeeIndexes = [
+  { fields: { organizationId: 1, employeeId: 1 }, options: { unique: true } },
+  // Partial unique index: Only includes docs with userId field (excludes guest employees)
+  // Uses partialFilterExpression instead of sparse for compound indexes
+  {
+    fields: { userId: 1, organizationId: 1 },
+    options: {
+      unique: true,
+      partialFilterExpression: { userId: { $exists: true } }
+    }
+  },
+  // Partial unique index: Only includes non-terminated docs with email
+  // This allows email reuse when employees are terminated and rehired
+  {
+    fields: { email: 1, organizationId: 1 },
+    options: {
+      unique: true,
+      partialFilterExpression: {
+        email: { $exists: true },
+        status: { $in: ["active", "on_leave", "suspended"] }
+      }
+    }
+  },
+  { fields: { organizationId: 1, status: 1 } },
+  { fields: { organizationId: 1, department: 1 } },
+  { fields: { organizationId: 1, "compensation.netSalary": -1 } }
+];
+var payrollRecordIndexes = [
+  // Composite index for common queries (not unique - app handles duplicates)
+  { fields: { organizationId: 1, employeeId: 1, "period.month": 1, "period.year": 1 } },
+  { fields: { organizationId: 1, "period.year": 1, "period.month": 1 } },
+  { fields: { employeeId: 1, "period.year": -1, "period.month": -1 } },
+  { fields: { status: 1, createdAt: -1 } },
+  { fields: { organizationId: 1, status: 1, "period.payDate": 1 } },
+  {
+    fields: { createdAt: 1 },
+    options: {
+      expireAfterSeconds: HRM_CONFIG.dataRetention.payrollRecordsTTL
+      // TTL applies to ALL records (user handles backups/exports at app level)
+    }
+  }
+];
+function applyEmployeeIndexes(schema) {
+  for (const { fields, options } of employeeIndexes) {
+    schema.index(fields, options);
+  }
+}
+function applyPayrollRecordIndexes(schema) {
+  for (const { fields, options } of payrollRecordIndexes) {
+    schema.index(fields, options);
+  }
+}
+function createEmployeeSchema(additionalFields = {}, options = {}) {
+  const schema = new Schema(
+    {
+      ...createEmploymentFields(options),
+      ...additionalFields
+    },
+    { timestamps: true }
+  );
+  applyEmployeeIndexes(schema);
+  return schema;
+}
+function createPayrollRecordSchema(additionalFields = {}, options = {}) {
+  const schema = new Schema(
+    {
+      ...createPayrollRecordFields(options),
+      ...additionalFields
+    },
+    { timestamps: true }
+  );
+  applyPayrollRecordIndexes(schema);
+  schema.virtual("totalAmount").get(function() {
+    return this.breakdown?.netSalary || 0;
+  });
+  schema.virtual("isPaid").get(function() {
+    return this.status === "paid";
+  });
+  schema.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}`;
+  });
+  schema.methods.markAsPaid = function(transactionId, paidAt = /* @__PURE__ */ new Date()) {
+    this.status = "paid";
+    this.transactionId = transactionId;
+    this.paidAt = paidAt;
+  };
+  schema.methods.markAsExported = function() {
+    this.exported = true;
+    this.exportedAt = /* @__PURE__ */ new Date();
+  };
+  schema.methods.canBeDeleted = function() {
+    return this.exported && this.status === "paid";
+  };
+  return schema;
+}
+var schemas_default = {
+  // Sub-schemas
+  allowanceSchema,
+  deductionSchema,
+  compensationSchema,
+  workScheduleSchema,
+  bankDetailsSchema,
+  employmentHistorySchema,
+  payrollStatsSchema,
+  payrollBreakdownSchema,
+  periodSchema,
+  // Field creators (configurable references)
+  createEmploymentFields,
+  createPayrollRecordFields,
+  // Indexes
+  employeeIndexes,
+  payrollRecordIndexes,
+  applyEmployeeIndexes,
+  applyPayrollRecordIndexes,
+  // Schema creators
+  createEmployeeSchema,
+  createPayrollRecordSchema
+};
+
+export { allowanceSchema, applyEmployeeIndexes, applyLeaveRequestIndexes, applyPayrollRecordIndexes, applyTaxWithholdingIndexes, bankDetailsSchema, compensationSchema, createEmployeeSchema, createEmploymentFields, createPayrollRecordFields, createPayrollRecordSchema, deductionSchema, schemas_default as default, employeeIndexes, employmentHistorySchema, getLeaveRequestFields, getLeaveRequestModel, getTaxWithholdingFields, getTaxWithholdingModel, leaveBalanceFields, leaveBalanceSchema, leaveRequestIndexes, leaveRequestSchema, leaveRequestTTLIndex, payrollBreakdownSchema, payrollRecordIndexes, payrollStatsSchema, periodSchema, taxWithholdingIndexes, taxWithholdingSchema, workScheduleSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map