@classytic/payroll 2.7.5 → 2.8.0

package/dist/schemas/index.js

@@ -123,76 +123,6 @@ var TAX_STATUS = {
   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 },
@@ -1311,7 +1241,63 @@ function createPayrollRecordFields(options = {}) {
     reversalTransactionId: { type: Schema.Types.ObjectId },
     originalPayrollId: { type: Schema.Types.ObjectId },
     // TTL expiration (per-document)
-    expireAt: { type: Date }
+    expireAt: { type: Date },
+    // Payroll run type (v2.8.0+)
+    payrollRunType: {
+      type: String,
+      enum: ["regular", "off-cycle", "supplemental", "retroactive"],
+      default: "regular"
+    },
+    // Payment frequency at time of processing (v2.9.0+)
+    // Stored for proper idempotency key reconstruction in void/reverse operations
+    paymentFrequency: {
+      type: String,
+      enum: PAYMENT_FREQUENCY_VALUES,
+      default: "monthly"
+    },
+    // Retroactive adjustment details (v2.8.0+)
+    retroactiveAdjustment: {
+      type: new Schema(
+        {
+          originalPeriod: {
+            month: { type: Number, required: true, min: 1, max: 12 },
+            year: { type: Number, required: true }
+          },
+          originalPayrollId: { type: Schema.Types.ObjectId },
+          reason: { type: String, required: true },
+          adjustmentAmount: { type: Number, required: true },
+          approved: { type: Boolean },
+          approvedBy: { type: Schema.Types.ObjectId },
+          approvedAt: { type: Date }
+        },
+        { _id: false }
+      ),
+      required: false
+    },
+    // Employer contributions (v2.8.0+)
+    employerContributions: [
+      {
+        type: {
+          type: String,
+          enum: ["social_security", "pension", "unemployment", "health_insurance", "other"],
+          required: true
+        },
+        amount: { type: Number, required: true },
+        description: { type: String },
+        mandatory: { type: Boolean },
+        referenceNumber: { type: String }
+      }
+    ],
+    // Corrections history (v2.8.0+)
+    corrections: [
+      {
+        previousAmount: { type: Number },
+        newAmount: { type: Number },
+        reason: { type: String },
+        correctedBy: { type: Schema.Types.ObjectId, ref: userRef },
+        correctedAt: { type: Date, default: Date.now }
+      }
+    ]
   };
 }
 var employeeIndexes = [
@@ -1342,17 +1328,51 @@ var employeeIndexes = [
   { fields: { organizationId: 1, "compensation.netSalary": -1 } }
 ];
 var payrollRecordIndexes = [
-  // Composite index for common queries (not unique - app handles duplicates)
+  /**
+   * UNIQUE Compound Index (v2.9.0+) - PRIMARY duplicate protection
+   *
+   * Prevents duplicate payrolls at the database level for the same:
+   * - Organization, Employee, Period (month + year + startDate), Payroll run type
+   *
+   * The period.startDate is critical for non-monthly frequencies (weekly, bi_weekly,
+   * daily, hourly) where multiple payroll runs can occur within the same calendar month.
+   *
+   * Partial filter excludes voided records to allow re-processing.
+   * Duplicate inserts fail with E11000 → converted to DuplicatePayrollError.
+   */
+  {
+    fields: {
+      organizationId: 1,
+      employeeId: 1,
+      "period.month": 1,
+      "period.year": 1,
+      "period.startDate": 1,
+      payrollRunType: 1
+    },
+    options: {
+      unique: true,
+      name: "unique_payroll_per_period_startdate_runtype",
+      // Only enforce for non-voided records (uses $eq which is supported in partial indexes)
+      // When a record is voided, isVoided is set to true, excluding it from unique constraint
+      partialFilterExpression: {
+        isVoided: { $eq: false }
+      }
+    }
+  },
+  // Composite index for common queries
   { 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 } },
+  // Index for payroll run type queries (supplemental, retroactive, etc.)
+  { fields: { organizationId: 1, payrollRunType: 1, "period.year": 1, "period.month": 1 } },
+  // TTL index using expireAt field for per-document retention (jurisdiction-specific)
   {
-    fields: { createdAt: 1 },
+    fields: { expireAt: 1 },
     options: {
-      expireAfterSeconds: HRM_CONFIG.dataRetention.payrollRecordsTTL
-      // TTL applies to ALL records (user handles backups/exports at app level)
+      expireAfterSeconds: 0
+      // Delete immediately when expireAt is reached
     }
   }
 ];