@classytic/payroll 2.0.0 → 2.3.0

package/dist/services/index.js

@@ -41,10 +41,42 @@ function calculateProbationEnd(hireDate, probationMonths) {
 
 // src/config.ts
 var HRM_CONFIG = {
+  dataRetention: {
+    payrollRecordsTTL: 63072e3,
+    // 2 years in seconds
+    exportWarningDays: 30,
+    archiveBeforeDeletion: true
+  },
   payroll: {
-    defaultCurrency: "BDT"},
+    defaultCurrency: "BDT",
+    allowProRating: true,
+    attendanceIntegration: true,
+    autoDeductions: true,
+    overtimeEnabled: false,
+    overtimeMultiplier: 1.5
+  },
+  salary: {
+    minimumWage: 0,
+    maximumAllowances: 10,
+    maximumDeductions: 10,
+    defaultFrequency: "monthly"
+  },
   employment: {
-    defaultProbationMonths: 3}};
+    defaultProbationMonths: 3,
+    maxProbationMonths: 6,
+    allowReHiring: true,
+    trackEmploymentHistory: true
+  },
+  validation: {
+    requireBankDetails: false,
+    requireUserId: false,
+    // Modern: Allow guest employees by default
+    identityMode: "employeeId",
+    // Modern: Use human-readable IDs as primary
+    identityFallbacks: ["email", "userId"]
+    // Smart fallback chain
+  }
+};
 var ORG_ROLES = {
   OWNER: {
     key: "owner",
@@ -80,15 +112,24 @@ var ORG_ROLES = {
 Object.values(ORG_ROLES).map((role) => role.key);
 
 // src/factories/employee.factory.ts
+function normalizeEmail(email) {
+  if (!email || typeof email !== "string") return void 0;
+  const trimmed = email.trim();
+  return trimmed ? trimmed.toLowerCase() : void 0;
+}
 var EmployeeFactory = class {
   /**
    * Create employee data object
    */
-  static create(params) {
+  static create(params, config = HRM_CONFIG) {
     const { userId, organizationId, employment, compensation, bankDetails } = params;
     const hireDate = employment.hireDate || /* @__PURE__ */ new Date();
+    const normalizedEmail = normalizeEmail(employment.email);
     return {
-      userId,
+      ...userId ? { userId } : {},
+      // Only include userId if present
+      ...normalizedEmail ? { email: normalizedEmail } : {},
+      // Include normalized email for guest employees
       organizationId,
       employeeId: employment.employeeId || `EMP-${Date.now()}-${Math.random().toString(36).substr(2, 6).toUpperCase()}`,
       employmentType: employment.type || "full_time",
@@ -98,9 +139,9 @@ var EmployeeFactory = class {
       hireDate,
       probationEndDate: calculateProbationEnd(
         hireDate,
-        employment.probationMonths ?? HRM_CONFIG.employment.defaultProbationMonths
+        employment.probationMonths ?? config.employment.defaultProbationMonths
       ),
-      compensation: this.createCompensation(compensation),
+      compensation: this.createCompensation(compensation, config),
       workSchedule: employment.workSchedule || this.defaultWorkSchedule(),
       bankDetails: bankDetails || {},
       payrollStats: {
@@ -113,11 +154,11 @@ var EmployeeFactory = class {
   /**
    * Create compensation object
    */
-  static createCompensation(params) {
+  static createCompensation(params, config = HRM_CONFIG) {
     return {
       baseAmount: params.baseAmount,
       frequency: params.frequency || "monthly",
-      currency: params.currency || HRM_CONFIG.payroll.defaultCurrency,
+      currency: params.currency || config.payroll.defaultCurrency,
       allowances: (params.allowances || []).map((a) => ({
         type: a.type || "other",
         name: a.name || a.type || "other",
@@ -325,6 +366,30 @@ var EmployeeQueryBuilder = class extends QueryBuilder {
   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)
    */
@@ -397,8 +462,8 @@ var EmployeeQueryBuilder = class extends QueryBuilder {
   /**
    * Filter by salary range
    */
-  withSalaryRange(min, max) {
-    return this.whereBetween("compensation.netSalary", min, max);
+  withSalaryRange(min2, max2) {
+    return this.whereBetween("compensation.netSalary", min2, max2);
   }
 };
 var PayrollQueryBuilder = class extends QueryBuilder {
@@ -410,6 +475,9 @@ var PayrollQueryBuilder = class extends QueryBuilder {
   }
   /**
    * 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));
@@ -472,6 +540,17 @@ function employee() {
 function payroll() {
   return new PayrollQueryBuilder();
 }
+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_STATUS = {
+  PENDING: "pending"};
 
 // src/utils/validation.ts
 function isActive(employee2) {
@@ -541,21 +620,31 @@ var logger = {
 
 // src/services/employee.service.ts
 var EmployeeService = class {
-  constructor(EmployeeModel) {
+  constructor(EmployeeModel, config) {
     this.EmployeeModel = EmployeeModel;
+    this.config = config || HRM_CONFIG;
   }
+  config;
   /**
-   * Find employee by ID
+   * Find employee by ID with organization validation
+   * 
+   * ⚠️ SECURITY: Always validates employee belongs to specified organization
+   * 
+   * @throws {Error} If employee not found or doesn't belong to organization
    */
-  async findById(employeeId, options = {}) {
-    let query = this.EmployeeModel.findById(toObjectId(employeeId));
+  async findById(employeeId, organizationId, options = {}) {
+    const query = {
+      _id: toObjectId(employeeId),
+      organizationId: toObjectId(organizationId)
+    };
+    let mongooseQuery = this.EmployeeModel.findOne(query);
     if (options.session) {
-      query = query.session(options.session);
+      mongooseQuery = mongooseQuery.session(options.session);
     }
     if (options.populate) {
-      query = query.populate("userId", "name email phone");
+      mongooseQuery = mongooseQuery.populate("userId", "name email phone");
     }
-    return query.exec();
+    return mongooseQuery.exec();
   }
   /**
    * Find employee by user and organization
@@ -568,6 +657,39 @@ var EmployeeService = class {
     }
     return mongooseQuery.exec();
   }
+  /**
+   * Find employee by employeeId (human-readable ID)
+   */
+  async findByEmployeeId(employeeId, organizationId, options = {}) {
+    const query = employee().forEmployeeId(employeeId).forOrganization(organizationId).build();
+    let mongooseQuery = this.EmployeeModel.findOne(query);
+    if (options.session) {
+      mongooseQuery = mongooseQuery.session(options.session);
+    }
+    return mongooseQuery.exec();
+  }
+  /**
+   * Find employee by email (guest employees)
+   */
+  async findByEmail(email, organizationId, options = {}) {
+    const query = employee().forEmail(email).forOrganization(organizationId).build();
+    let mongooseQuery = this.EmployeeModel.findOne(query);
+    if (options.session) {
+      mongooseQuery = mongooseQuery.session(options.session);
+    }
+    return mongooseQuery.exec();
+  }
+  /**
+   * Find all guest employees (no userId)
+   */
+  async findGuestEmployees(organizationId, options = {}) {
+    const query = employee().forOrganization(organizationId).guestEmployees().build();
+    let mongooseQuery = this.EmployeeModel.find(query);
+    if (options.session) {
+      mongooseQuery = mongooseQuery.session(options.session);
+    }
+    return mongooseQuery.exec();
+  }
   /**
    * Find active employees in organization
    */
@@ -617,10 +739,32 @@ var EmployeeService = class {
    * Create new employee
    */
   async create(params, options = {}) {
-    const employeeData = EmployeeFactory.create(params);
-    const [employee2] = await this.EmployeeModel.create([employeeData], {
-      session: options.session
-    });
+    const employeeData = EmployeeFactory.create(params, this.config);
+    let employee2;
+    if (!params.userId) {
+      const dataToInsert = {};
+      for (const [key, value] of Object.entries(employeeData)) {
+        if (key === "userId" || key === "email") continue;
+        dataToInsert[key] = value;
+      }
+      if (employeeData.email && employeeData.email !== "") {
+        dataToInsert.email = employeeData.email;
+      }
+      const now = /* @__PURE__ */ new Date();
+      dataToInsert.createdAt = now;
+      dataToInsert.updatedAt = now;
+      const insertOptions = options.session ? { session: options.session } : {};
+      const result = await this.EmployeeModel.collection.insertOne(
+        dataToInsert,
+        insertOptions
+      );
+      employee2 = await this.EmployeeModel.findById(result.insertedId).session(options.session || null).exec();
+    } else {
+      const [created] = await this.EmployeeModel.create([employeeData], {
+        session: options.session
+      });
+      employee2 = created;
+    }
     logger.info("Employee created", {
       employeeId: employee2.employeeId,
       organizationId: employee2.organizationId.toString()
@@ -628,31 +772,36 @@ var EmployeeService = class {
     return employee2;
   }
   /**
-   * Update employee status
+   * Update employee status with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization before update
    */
-  async updateStatus(employeeId, status, context = {}, options = {}) {
-    const employee2 = await this.findById(employeeId, options);
+  async updateStatus(employeeId, organizationId, status, context = {}, options = {}) {
+    const employee2 = await this.findById(employeeId, organizationId, options);
     if (!employee2) {
-      throw new Error("Employee not found");
+      throw new Error(`Employee not found in organization ${organizationId}`);
     }
     employee2.status = status;
     await employee2.save({ session: options.session });
     logger.info("Employee status updated", {
       employeeId: employee2.employeeId,
+      organizationId: organizationId.toString(),
       newStatus: status
     });
     return employee2;
   }
   /**
-   * Update employee compensation
+   * Update employee compensation with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization before update
    * 
    * NOTE: This merges the compensation fields rather than replacing the entire object.
    * To update allowances/deductions, use addAllowance/removeAllowance methods.
    */
-  async updateCompensation(employeeId, compensation, options = {}) {
-    const currentEmployee = await this.EmployeeModel.findById(toObjectId(employeeId)).session(options.session || null);
+  async updateCompensation(employeeId, organizationId, compensation, options = {}) {
+    const currentEmployee = await this.findById(employeeId, organizationId, options);
     if (!currentEmployee) {
-      throw new Error("Employee not found");
+      throw new Error(`Employee not found in organization ${organizationId}`);
     }
     const updateFields = {
       "compensation.lastModified": /* @__PURE__ */ new Date()
@@ -669,14 +818,22 @@ var EmployeeService = class {
     if (compensation.effectiveFrom !== void 0) {
       updateFields["compensation.effectiveFrom"] = compensation.effectiveFrom;
     }
-    const employee2 = await this.EmployeeModel.findByIdAndUpdate(
-      toObjectId(employeeId),
+    const query = {
+      _id: toObjectId(employeeId),
+      organizationId: toObjectId(organizationId)
+    };
+    const employee2 = await this.EmployeeModel.findOneAndUpdate(
+      query,
       { $set: updateFields },
       { new: true, runValidators: true, session: options.session }
     );
     if (!employee2) {
-      throw new Error("Employee not found");
+      throw new Error(`Employee not found in organization ${organizationId}`);
     }
+    logger.info("Employee compensation updated", {
+      employeeId: employee2.employeeId,
+      organizationId: organizationId.toString()
+    });
     return employee2;
   }
   /**
@@ -742,8 +899,8 @@ var EmployeeService = class {
     return canReceiveSalary(employee2);
   }
 };
-function createEmployeeService(EmployeeModel) {
-  return new EmployeeService(EmployeeModel);
+function createEmployeeService(EmployeeModel, config) {
+  return new EmployeeService(EmployeeModel, config);
 }
 
 // src/utils/calculation.ts
@@ -994,12 +1151,14 @@ var PayrollService = class {
     return payroll2;
   }
   /**
-   * Generate payroll for employee
+   * Generate payroll for employee with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization
    */
   async generateForEmployee(employeeId, organizationId, month, year, options = {}) {
-    const employee2 = await this.employeeService.findById(employeeId, options);
+    const employee2 = await this.employeeService.findById(employeeId, organizationId, options);
     if (!employee2) {
-      throw new Error("Employee not found");
+      throw new Error(`Employee not found in organization ${organizationId}`);
     }
     if (!canReceiveSalary(employee2)) {
       throw new Error("Employee not eligible for payroll");
@@ -1086,12 +1245,22 @@ var PayrollService = class {
     };
   }
   /**
-   * Mark payroll as paid
+   * Mark payroll as paid with organization validation
+   * 
+   * ⚠️ SECURITY: Validates payroll belongs to organization
    */
-  async markAsPaid(payrollId, paymentDetails = {}, options = {}) {
-    const payroll2 = await this.findById(payrollId, options);
+  async markAsPaid(payrollId, organizationId, paymentDetails = {}, options = {}) {
+    const query = {
+      _id: toObjectId(payrollId),
+      organizationId: toObjectId(organizationId)
+    };
+    let payrollFindQuery = this.PayrollModel.findOne(query);
+    if (options.session) {
+      payrollFindQuery = payrollFindQuery.session(options.session);
+    }
+    const payroll2 = await payrollFindQuery;
     if (!payroll2) {
-      throw new Error("Payroll not found");
+      throw new Error(`Payroll not found in organization ${organizationId}`);
     }
     if (payroll2.status === "paid") {
       throw new Error("Payroll already paid");
@@ -1112,12 +1281,22 @@ var PayrollService = class {
     return updated;
   }
   /**
-   * Mark payroll as processed
+   * Mark payroll as processed with organization validation
+   * 
+   * ⚠️ SECURITY: Validates payroll belongs to organization
    */
-  async markAsProcessed(payrollId, options = {}) {
-    const payroll2 = await this.findById(payrollId, options);
+  async markAsProcessed(payrollId, organizationId, options = {}) {
+    const query = {
+      _id: toObjectId(payrollId),
+      organizationId: toObjectId(organizationId)
+    };
+    let payrollFindQuery = this.PayrollModel.findOne(query);
+    if (options.session) {
+      payrollFindQuery = payrollFindQuery.session(options.session);
+    }
+    const payroll2 = await payrollFindQuery;
     if (!payroll2) {
-      throw new Error("Payroll not found");
+      throw new Error(`Payroll not found in organization ${organizationId}`);
     }
     const payrollObj = payroll2.toObject();
     const updatedData = PayrollFactory.markAsProcessed(payrollObj);
@@ -1434,31 +1613,30 @@ var CompensationService = class {
     this.EmployeeModel = EmployeeModel;
   }
   /**
-   * Get employee compensation
+   * Get employee compensation with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization
    */
-  async getEmployeeCompensation(employeeId, options = {}) {
-    let query = this.EmployeeModel.findById(toObjectId(employeeId));
-    if (options.session) {
-      query = query.session(options.session);
-    }
-    const employee2 = await query.exec();
-    if (!employee2) {
-      throw new Error("Employee not found");
-    }
+  async getEmployeeCompensation(employeeId, organizationId, options = {}) {
+    const employee2 = await this.findEmployee(employeeId, organizationId, options);
     return employee2.compensation;
   }
   /**
-   * Calculate compensation breakdown
+   * Calculate compensation breakdown with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization
    */
-  async calculateBreakdown(employeeId, options = {}) {
-    const compensation = await this.getEmployeeCompensation(employeeId, options);
+  async calculateBreakdown(employeeId, organizationId, options = {}) {
+    const compensation = await this.getEmployeeCompensation(employeeId, organizationId, options);
     return CompensationFactory.calculateBreakdown(compensation);
   }
   /**
-   * Update base amount
+   * Update base amount with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization before update
    */
-  async updateBaseAmount(employeeId, newAmount, effectiveFrom = /* @__PURE__ */ new Date(), options = {}) {
-    const employee2 = await this.findEmployee(employeeId, options);
+  async updateBaseAmount(employeeId, organizationId, newAmount, effectiveFrom = /* @__PURE__ */ new Date(), options = {}) {
+    const employee2 = await this.findEmployee(employeeId, organizationId, options);
     const updatedCompensation = CompensationFactory.updateBaseAmount(
       employee2.compensation,
       newAmount,
@@ -1468,15 +1646,18 @@ var CompensationService = class {
     await employee2.save({ session: options.session });
     logger.info("Compensation base amount updated", {
       employeeId: employee2.employeeId,
+      organizationId: organizationId.toString(),
       newAmount
     });
-    return this.calculateBreakdown(employeeId, options);
+    return this.calculateBreakdown(employeeId, organizationId, options);
   }
   /**
-   * Apply salary increment
+   * Apply salary increment with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization before update
    */
-  async applyIncrement(employeeId, params, options = {}) {
-    const employee2 = await this.findEmployee(employeeId, options);
+  async applyIncrement(employeeId, organizationId, params, options = {}) {
+    const employee2 = await this.findEmployee(employeeId, organizationId, options);
     const previousAmount = employee2.compensation.baseAmount;
     const updatedCompensation = CompensationFactory.applyIncrement(
       employee2.compensation,
@@ -1486,17 +1667,20 @@ var CompensationService = class {
     await employee2.save({ session: options.session });
     logger.info("Salary increment applied", {
       employeeId: employee2.employeeId,
+      organizationId: organizationId.toString(),
       previousAmount,
       newAmount: updatedCompensation.baseAmount,
       percentage: params.percentage
     });
-    return this.calculateBreakdown(employeeId, options);
+    return this.calculateBreakdown(employeeId, organizationId, options);
   }
   /**
-   * Add allowance
+   * Add allowance with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization before update
    */
-  async addAllowance(employeeId, allowance, options = {}) {
-    const employee2 = await this.findEmployee(employeeId, options);
+  async addAllowance(employeeId, organizationId, allowance, options = {}) {
+    const employee2 = await this.findEmployee(employeeId, organizationId, options);
     const updatedCompensation = CompensationFactory.addAllowance(
       employee2.compensation,
       allowance
@@ -1505,16 +1689,19 @@ var CompensationService = class {
     await employee2.save({ session: options.session });
     logger.info("Allowance added", {
       employeeId: employee2.employeeId,
+      organizationId: organizationId.toString(),
       type: allowance.type,
       value: allowance.value
     });
-    return this.calculateBreakdown(employeeId, options);
+    return this.calculateBreakdown(employeeId, organizationId, options);
   }
   /**
-   * Remove allowance
+   * Remove allowance with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization before update
    */
-  async removeAllowance(employeeId, allowanceType, options = {}) {
-    const employee2 = await this.findEmployee(employeeId, options);
+  async removeAllowance(employeeId, organizationId, allowanceType, options = {}) {
+    const employee2 = await this.findEmployee(employeeId, organizationId, options);
     const updatedCompensation = CompensationFactory.removeAllowance(
       employee2.compensation,
       allowanceType
@@ -1523,15 +1710,18 @@ var CompensationService = class {
     await employee2.save({ session: options.session });
     logger.info("Allowance removed", {
       employeeId: employee2.employeeId,
+      organizationId: organizationId.toString(),
       type: allowanceType
     });
-    return this.calculateBreakdown(employeeId, options);
+    return this.calculateBreakdown(employeeId, organizationId, options);
   }
   /**
-   * Add deduction
+   * Add deduction with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization before update
    */
-  async addDeduction(employeeId, deduction, options = {}) {
-    const employee2 = await this.findEmployee(employeeId, options);
+  async addDeduction(employeeId, organizationId, deduction, options = {}) {
+    const employee2 = await this.findEmployee(employeeId, organizationId, options);
     const updatedCompensation = CompensationFactory.addDeduction(
       employee2.compensation,
       deduction
@@ -1540,16 +1730,19 @@ var CompensationService = class {
     await employee2.save({ session: options.session });
     logger.info("Deduction added", {
       employeeId: employee2.employeeId,
+      organizationId: organizationId.toString(),
       type: deduction.type,
       value: deduction.value
     });
-    return this.calculateBreakdown(employeeId, options);
+    return this.calculateBreakdown(employeeId, organizationId, options);
   }
   /**
-   * Remove deduction
+   * Remove deduction with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization before update
    */
-  async removeDeduction(employeeId, deductionType, options = {}) {
-    const employee2 = await this.findEmployee(employeeId, options);
+  async removeDeduction(employeeId, organizationId, deductionType, options = {}) {
+    const employee2 = await this.findEmployee(employeeId, organizationId, options);
     const updatedCompensation = CompensationFactory.removeDeduction(
       employee2.compensation,
       deductionType
@@ -1558,29 +1751,35 @@ var CompensationService = class {
     await employee2.save({ session: options.session });
     logger.info("Deduction removed", {
       employeeId: employee2.employeeId,
+      organizationId: organizationId.toString(),
       type: deductionType
     });
-    return this.calculateBreakdown(employeeId, options);
+    return this.calculateBreakdown(employeeId, organizationId, options);
   }
   /**
-   * Set standard compensation
+   * Set standard compensation with organization validation
+   * 
+   * ⚠️ SECURITY: Validates employee belongs to organization before update
    */
-  async setStandardCompensation(employeeId, baseAmount, options = {}) {
-    const employee2 = await this.findEmployee(employeeId, options);
+  async setStandardCompensation(employeeId, organizationId, baseAmount, options = {}) {
+    const employee2 = await this.findEmployee(employeeId, organizationId, options);
     employee2.compensation = CompensationPresets.standard(baseAmount);
     await employee2.save({ session: options.session });
     logger.info("Standard compensation set", {
       employeeId: employee2.employeeId,
+      organizationId: organizationId.toString(),
       baseAmount
     });
-    return this.calculateBreakdown(employeeId, options);
+    return this.calculateBreakdown(employeeId, organizationId, options);
   }
   /**
    * Compare compensation between two employees
+   * 
+   * ⚠️ SECURITY: Validates both employees belong to organization
    */
-  async compareCompensation(employeeId1, employeeId2, options = {}) {
-    const breakdown1 = await this.calculateBreakdown(employeeId1, options);
-    const breakdown2 = await this.calculateBreakdown(employeeId2, options);
+  async compareCompensation(employeeId1, employeeId2, organizationId, options = {}) {
+    const breakdown1 = await this.calculateBreakdown(employeeId1, organizationId, options);
+    const breakdown2 = await this.calculateBreakdown(employeeId2, organizationId, options);
     return {
       employee1: breakdown1,
       employee2: breakdown2,
@@ -1673,16 +1872,22 @@ var CompensationService = class {
     };
   }
   /**
-   * Find employee helper
+   * Find employee helper with organization validation
+   * 
+   * ⚠️ SECURITY: Always validates employee belongs to organization
    */
-  async findEmployee(employeeId, options = {}) {
-    let query = this.EmployeeModel.findById(toObjectId(employeeId));
+  async findEmployee(employeeId, organizationId, options = {}) {
+    const query = {
+      _id: toObjectId(employeeId),
+      organizationId: toObjectId(organizationId)
+    };
+    let mongooseQuery = this.EmployeeModel.findOne(query);
     if (options.session) {
-      query = query.session(options.session);
+      mongooseQuery = mongooseQuery.session(options.session);
     }
-    const employee2 = await query.exec();
+    const employee2 = await mongooseQuery.exec();
     if (!employee2) {
-      throw new Error("Employee not found");
+      throw new Error(`Employee not found in organization ${organizationId}`);
     }
     return employee2;
   }
@@ -1691,6 +1896,277 @@ function createCompensationService(EmployeeModel) {
   return new CompensationService(EmployeeModel);
 }
 
-export { CompensationService, EmployeeService, PayrollService, createCompensationService, createEmployeeService, createPayrollService };
+// src/services/tax-withholding.service.ts
+var TaxWithholdingService = class {
+  constructor(TaxWithholdingModel, TransactionModel, events) {
+    this.TaxWithholdingModel = TaxWithholdingModel;
+    this.TransactionModel = TransactionModel;
+    this.events = events;
+  }
+  /**
+   * Create tax withholding records from payroll breakdown
+   *
+   * Extracts tax deductions from the breakdown and creates separate
+   * TaxWithholding records for each tax type
+   */
+  async createFromBreakdown(params) {
+    const {
+      organizationId,
+      employeeId,
+      userId,
+      payrollRecordId,
+      transactionId,
+      period,
+      breakdown,
+      currency = "BDT",
+      session,
+      context
+    } = params;
+    const taxDeductions = breakdown.deductions?.filter(
+      (d) => d.type === "tax" || this.isTaxDeduction(d.type)
+    ) || [];
+    if (taxDeductions.length === 0) {
+      return [];
+    }
+    const withholdings = [];
+    for (const deduction of taxDeductions) {
+      const taxType = this.mapDeductionTypeToTaxType(deduction.type);
+      const taxRate = breakdown.taxableAmount && breakdown.taxableAmount > 0 ? deduction.amount / breakdown.taxableAmount : 0;
+      const withholdingData = {
+        organizationId,
+        employeeId,
+        userId,
+        payrollRecordId,
+        transactionId,
+        period,
+        amount: deduction.amount,
+        currency,
+        taxType,
+        taxRate,
+        taxableAmount: breakdown.taxableAmount || breakdown.grossSalary,
+        status: TAX_STATUS.PENDING
+      };
+      const [withholding] = await this.TaxWithholdingModel.create([withholdingData], {
+        session
+      });
+      withholdings.push(withholding);
+      if (this.events) {
+        this.events.emitSync("tax:withheld", {
+          withholding: {
+            id: withholding._id,
+            taxType: withholding.taxType,
+            amount: withholding.amount
+          },
+          employee: {
+            id: employeeId,
+            employeeId: ""
+            // Will be filled by caller if needed
+          },
+          payrollRecord: {
+            id: payrollRecordId
+          },
+          period: {
+            month: period.month,
+            year: period.year
+          },
+          organizationId,
+          context
+        });
+      }
+      logger.info("Tax withholding created", {
+        withholdingId: withholding._id.toString(),
+        employeeId: employeeId.toString(),
+        taxType,
+        amount: deduction.amount,
+        period: `${period.month}/${period.year}`
+      });
+    }
+    return withholdings;
+  }
+  /**
+   * Get pending tax withholdings with optional filters
+   */
+  async getPending(params) {
+    const { organizationId, fromPeriod, toPeriod, taxType, employeeId } = params;
+    const options = {};
+    if (fromPeriod) {
+      options.fromMonth = fromPeriod.month;
+      options.fromYear = fromPeriod.year;
+    }
+    if (toPeriod) {
+      options.toMonth = toPeriod.month;
+      options.toYear = toPeriod.year;
+    }
+    if (taxType) {
+      options.taxType = taxType;
+    }
+    let query = this.TaxWithholdingModel.findPending(
+      toObjectId(organizationId),
+      options
+    );
+    if (employeeId) {
+      query = query.where({ employeeId: toObjectId(employeeId) });
+    }
+    return query.exec();
+  }
+  /**
+   * Get tax summary aggregated by type, period, or employee
+   */
+  async getSummary(params) {
+    const { organizationId, fromPeriod, toPeriod, groupBy = "type" } = params;
+    if (groupBy === "type") {
+      const byType = await this.TaxWithholdingModel.getSummaryByType(
+        toObjectId(organizationId),
+        fromPeriod,
+        toPeriod
+      );
+      const totalAmount = byType.reduce((sum2, item) => sum2 + item.totalAmount, 0);
+      const count = byType.reduce((sum2, item) => sum2 + item.count, 0);
+      return {
+        totalAmount,
+        count,
+        byType,
+        period: {
+          fromMonth: fromPeriod.month,
+          fromYear: fromPeriod.year,
+          toMonth: toPeriod.month,
+          toYear: toPeriod.year
+        }
+      };
+    }
+    throw new Error(`groupBy '${groupBy}' not yet implemented`);
+  }
+  /**
+   * Mark tax withholdings as paid
+   *
+   * Updates status, optionally creates government payment transaction,
+   * and emits tax:paid event
+   */
+  async markPaid(params) {
+    const {
+      organizationId,
+      withholdingIds,
+      createTransaction = false,
+      referenceNumber,
+      paidAt = /* @__PURE__ */ new Date(),
+      notes,
+      context
+    } = params;
+    const session = context?.session;
+    const withholdings = await this.TaxWithholdingModel.find({
+      _id: { $in: withholdingIds.map(toObjectId) },
+      organizationId: toObjectId(organizationId)
+    }).session(session || null);
+    if (withholdings.length === 0) {
+      throw new Error("No tax withholdings found with provided IDs");
+    }
+    const totalAmount = withholdings.reduce((sum2, w) => sum2 + w.amount, 0);
+    let governmentTransaction = null;
+    if (createTransaction && this.TransactionModel) {
+      const transactionData = {
+        organizationId: toObjectId(organizationId),
+        type: "tax_payment",
+        flow: "outflow",
+        tags: ["tax", "government", "withholding"],
+        amount: totalAmount,
+        grossAmount: totalAmount,
+        currency: withholdings[0].currency || "BDT",
+        status: "completed",
+        date: paidAt,
+        description: `Tax payment to government - ${referenceNumber || "Multiple withholdings"}`,
+        notes,
+        metadata: {
+          withholdingIds: withholdingIds.map((id) => id.toString()),
+          referenceNumber
+        }
+      };
+      [governmentTransaction] = await this.TransactionModel.create([transactionData], {
+        session
+      });
+    }
+    for (const withholding of withholdings) {
+      withholding.markAsPaid(
+        governmentTransaction?._id,
+        referenceNumber,
+        paidAt
+      );
+      await withholding.save({ session });
+    }
+    if (this.events) {
+      this.events.emitSync("tax:paid", {
+        withholdings: withholdings.map((w) => ({
+          id: w._id,
+          taxType: w.taxType,
+          amount: w.amount
+        })),
+        transaction: governmentTransaction ? {
+          id: governmentTransaction._id,
+          amount: governmentTransaction.amount
+        } : void 0,
+        totalAmount,
+        referenceNumber,
+        paidAt,
+        organizationId: toObjectId(organizationId),
+        context
+      });
+    }
+    logger.info("Tax withholdings marked as paid", {
+      count: withholdings.length,
+      totalAmount,
+      referenceNumber,
+      transactionId: governmentTransaction?._id.toString()
+    });
+    return {
+      withholdings,
+      transaction: governmentTransaction
+    };
+  }
+  /**
+   * Get tax withholdings for a specific payroll record
+   */
+  async getByPayrollRecord(payrollRecordId) {
+    return this.TaxWithholdingModel.getByPayrollRecord(toObjectId(payrollRecordId)).exec();
+  }
+  /**
+   * Get tax withholdings for a specific employee
+   */
+  async getByEmployee(employeeId, options) {
+    return this.TaxWithholdingModel.findByEmployee(toObjectId(employeeId), options).exec();
+  }
+  // ============================================================================
+  // Private Helpers
+  // ============================================================================
+  /**
+   * Check if deduction type is a tax deduction
+   */
+  isTaxDeduction(deductionType) {
+    const taxTypes = ["tax", "income_tax", "social_security", "health_insurance", "pension", "employment_insurance", "local_tax"];
+    return taxTypes.includes(deductionType.toLowerCase());
+  }
+  /**
+   * Map deduction type to TaxType enum
+   */
+  mapDeductionTypeToTaxType(deductionType) {
+    const typeMap = {
+      "tax": TAX_TYPE.INCOME_TAX,
+      "income_tax": TAX_TYPE.INCOME_TAX,
+      "social_security": TAX_TYPE.SOCIAL_SECURITY,
+      "health_insurance": TAX_TYPE.HEALTH_INSURANCE,
+      "pension": TAX_TYPE.PENSION,
+      "employment_insurance": TAX_TYPE.EMPLOYMENT_INSURANCE,
+      "local_tax": TAX_TYPE.LOCAL_TAX
+    };
+    return typeMap[deductionType.toLowerCase()] || TAX_TYPE.OTHER;
+  }
+};
+function createTaxWithholdingService(config) {
+  return new TaxWithholdingService(
+    config.TaxWithholdingModel,
+    config.TransactionModel,
+    config.events
+  );
+}
+
+export { CompensationService, EmployeeService, PayrollService, TaxWithholdingService, createCompensationService, createEmployeeService, createPayrollService, createTaxWithholdingService };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map