@classytic/payroll 2.7.5 → 2.8.0

package/dist/core/index.js

@@ -0,0 +1,1962 @@
+import { LRUCache } from 'lru-cache';
+import crypto from 'crypto';
+import { Types } from 'mongoose';
+
+// src/core/result.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+function isOk(result) {
+  return result.ok === true;
+}
+function isErr(result) {
+  return result.ok === false;
+}
+function unwrap(result) {
+  if (isOk(result)) {
+    return result.value;
+  }
+  throw result.error;
+}
+function unwrapOr(result, defaultValue) {
+  if (isOk(result)) {
+    return result.value;
+  }
+  return defaultValue;
+}
+function unwrapOrElse(result, fn) {
+  if (isOk(result)) {
+    return result.value;
+  }
+  return fn(result.error);
+}
+function map(result, fn) {
+  if (isOk(result)) {
+    return ok(fn(result.value));
+  }
+  return result;
+}
+function mapErr(result, fn) {
+  if (isErr(result)) {
+    return err(fn(result.error));
+  }
+  return result;
+}
+function flatMap(result, fn) {
+  if (isOk(result)) {
+    return fn(result.value);
+  }
+  return result;
+}
+async function tryCatch(fn, errorTransform) {
+  try {
+    const value = await fn();
+    return ok(value);
+  } catch (error) {
+    if (errorTransform) {
+      return err(errorTransform(error));
+    }
+    return err(error);
+  }
+}
+function tryCatchSync(fn, errorTransform) {
+  try {
+    const value = fn();
+    return ok(value);
+  } catch (error) {
+    if (errorTransform) {
+      return err(errorTransform(error));
+    }
+    return err(error);
+  }
+}
+function all(results) {
+  const values = [];
+  for (const result of results) {
+    if (isErr(result)) {
+      return result;
+    }
+    values.push(result.value);
+  }
+  return ok(values);
+}
+function match(result, handlers) {
+  if (isOk(result)) {
+    return handlers.ok(result.value);
+  }
+  return handlers.err(result.error);
+}
+async function fromPromise(promise, errorTransform) {
+  return tryCatch(() => promise, errorTransform);
+}
+function fromNullable(value, error) {
+  if (value === null || value === void 0) {
+    return err(error);
+  }
+  return ok(value);
+}
+var ResultClass = class _ResultClass {
+  constructor(result) {
+    this.result = result;
+  }
+  static ok(value) {
+    return new _ResultClass(ok(value));
+  }
+  static err(error) {
+    return new _ResultClass(err(error));
+  }
+  static async fromAsync(fn, errorTransform) {
+    const result = await tryCatch(fn, errorTransform);
+    return new _ResultClass(result);
+  }
+  isOk() {
+    return isOk(this.result);
+  }
+  isErr() {
+    return isErr(this.result);
+  }
+  unwrap() {
+    return unwrap(this.result);
+  }
+  unwrapOr(defaultValue) {
+    return unwrapOr(this.result, defaultValue);
+  }
+  map(fn) {
+    return new _ResultClass(map(this.result, fn));
+  }
+  mapErr(fn) {
+    return new _ResultClass(mapErr(this.result, fn));
+  }
+  flatMap(fn) {
+    return new _ResultClass(flatMap(this.result, fn));
+  }
+  match(handlers) {
+    return match(this.result, handlers);
+  }
+  toResult() {
+    return this.result;
+  }
+};
+var Result = {
+  ok,
+  err,
+  isOk,
+  isErr,
+  unwrap,
+  unwrapOr,
+  unwrapOrElse,
+  map,
+  mapErr,
+  flatMap,
+  tryCatch,
+  tryCatchSync,
+  all,
+  match,
+  fromPromise,
+  fromNullable
+};
+
+// 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();
+function getLogger() {
+  return {
+    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/core/events.ts
+var EventBus = class {
+  handlers = /* @__PURE__ */ new Map();
+  /**
+   * Register an event handler
+   */
+  on(event, handler) {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.handlers.get(event).add(handler);
+    return () => this.off(event, handler);
+  }
+  /**
+   * Register a one-time event handler
+   */
+  once(event, handler) {
+    const wrappedHandler = async (payload) => {
+      this.off(event, wrappedHandler);
+      await handler(payload);
+    };
+    return this.on(event, wrappedHandler);
+  }
+  /**
+   * Remove an event handler
+   */
+  off(event, handler) {
+    const eventHandlers = this.handlers.get(event);
+    if (eventHandlers) {
+      eventHandlers.delete(handler);
+    }
+  }
+  /**
+   * Emit an event
+   */
+  async emit(event, payload) {
+    const eventHandlers = this.handlers.get(event);
+    if (!eventHandlers || eventHandlers.size === 0) {
+      return;
+    }
+    const handlers = Array.from(eventHandlers);
+    await Promise.all(
+      handlers.map(async (handler) => {
+        try {
+          await handler(payload);
+        } catch (error) {
+          getLogger().error(`Event handler error for ${event}`, {
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      })
+    );
+  }
+  /**
+   * Emit event synchronously (fire-and-forget)
+   */
+  emitSync(event, payload) {
+    void this.emit(event, payload);
+  }
+  /**
+   * Remove all handlers for an event
+   */
+  removeAllListeners(event) {
+    if (event) {
+      this.handlers.delete(event);
+    } else {
+      this.handlers.clear();
+    }
+  }
+  /**
+   * Get listener count for an event
+   */
+  listenerCount(event) {
+    return this.handlers.get(event)?.size ?? 0;
+  }
+  /**
+   * Get all registered events
+   */
+  eventNames() {
+    return Array.from(this.handlers.keys());
+  }
+};
+var defaultEventBus = null;
+function getEventBus() {
+  if (!defaultEventBus) {
+    defaultEventBus = new EventBus();
+  }
+  return defaultEventBus;
+}
+function createEventBus() {
+  return new EventBus();
+}
+function resetEventBus() {
+  if (defaultEventBus) {
+    defaultEventBus.removeAllListeners();
+  }
+  defaultEventBus = null;
+}
+function onEmployeeHired(handler) {
+  return getEventBus().on("employee:hired", handler);
+}
+function onSalaryProcessed(handler) {
+  return getEventBus().on("salary:processed", handler);
+}
+function onPayrollCompleted(handler) {
+  return getEventBus().on("payroll:completed", handler);
+}
+function onMilestoneAchieved(handler) {
+  return getEventBus().on("milestone:achieved", handler);
+}
+var IdempotencyManager = class _IdempotencyManager {
+  cache;
+  static hasLoggedWarning = false;
+  constructor(options = {}) {
+    this.cache = new LRUCache({
+      max: options.max || 1e4,
+      // Store 10k keys
+      ttl: options.ttl || 1e3 * 60 * 60 * 24
+      // 24 hours default
+    });
+    if (!options.suppressWarning && !_IdempotencyManager.hasLoggedWarning && process.env.NODE_ENV === "production") {
+      _IdempotencyManager.hasLoggedWarning = true;
+      getLogger().warn(
+        "IdempotencyManager: Using in-memory cache. For horizontal scaling, implement database-backed idempotency. See @classytic/payroll documentation for implementation guidance.",
+        { cacheMax: options.max || 1e4, cacheTTL: options.ttl || 864e5 }
+      );
+    }
+  }
+  /**
+   * Check if key exists and return cached result
+   */
+  get(key) {
+    const cached = this.cache.get(key);
+    if (!cached) return null;
+    return {
+      value: cached.value,
+      cached: true,
+      createdAt: cached.createdAt
+    };
+  }
+  /**
+   * Store result for idempotency key
+   */
+  set(key, value) {
+    this.cache.set(key, {
+      value,
+      createdAt: /* @__PURE__ */ new Date()
+    });
+  }
+  /**
+   * Execute function with idempotency protection
+   */
+  async execute(key, fn) {
+    const cached = this.get(key);
+    if (cached) {
+      return cached;
+    }
+    const value = await fn();
+    this.set(key, value);
+    return {
+      value,
+      cached: false,
+      createdAt: /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * Clear a specific key
+   */
+  delete(key) {
+    this.cache.delete(key);
+  }
+  /**
+   * Clear all keys
+   */
+  clear() {
+    this.cache.clear();
+  }
+  /**
+   * Get cache stats
+   */
+  stats() {
+    return {
+      size: this.cache.size,
+      max: this.cache.max
+    };
+  }
+};
+function generatePayrollIdempotencyKey(organizationId, employeeId, month, year, payrollRunType = "regular", periodStartDate) {
+  if (periodStartDate) {
+    const startDateStr = periodStartDate.toISOString().split("T")[0];
+    return `payroll:${organizationId}:${employeeId}:${year}-${month}:${startDateStr}:${payrollRunType}`;
+  }
+  return `payroll:${organizationId}:${employeeId}:${year}-${month}:${payrollRunType}`;
+}
+var WebhookManager = class {
+  webhooks = [];
+  deliveryLog = [];
+  maxLogSize;
+  storePayloads;
+  constructor(options) {
+    this.maxLogSize = options?.maxLogSize ?? 1e3;
+    this.storePayloads = options?.storePayloads ?? false;
+  }
+  /**
+   * Register a webhook
+   */
+  register(config) {
+    this.webhooks.push({
+      retries: 3,
+      timeout: 3e4,
+      ...config
+    });
+  }
+  /**
+   * Remove a webhook
+   */
+  unregister(url) {
+    this.webhooks = this.webhooks.filter((w) => w.url !== url);
+  }
+  /**
+   * Send webhook for event
+   */
+  async send(event, payload) {
+    const matchingWebhooks = this.webhooks.filter((w) => w.events.includes(event));
+    const deliveries = matchingWebhooks.map(
+      (webhook) => this.deliver(webhook, event, payload)
+    );
+    await Promise.allSettled(deliveries);
+  }
+  /**
+   * Deliver webhook with retries
+   */
+  async deliver(webhook, event, payload) {
+    const deliveryId = `${Date.now()}-${Math.random().toString(36)}`;
+    const delivery = {
+      id: deliveryId,
+      event,
+      url: webhook.url,
+      payload: this.storePayloads ? payload : void 0,
+      attempt: 0,
+      status: "pending"
+    };
+    this.deliveryLog.push(delivery);
+    this.pruneLog();
+    const maxRetries = webhook.retries || 3;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      delivery.attempt = attempt;
+      try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), webhook.timeout || 3e4);
+        const timestamp = Math.floor(Date.now() / 1e3);
+        const deliveredAt = (/* @__PURE__ */ new Date()).toISOString();
+        const requestBody = {
+          event,
+          payload,
+          deliveredAt
+        };
+        const headers = {
+          "Content-Type": "application/json",
+          "X-Payroll-Event": event,
+          "X-Payroll-Delivery": deliveryId,
+          "X-Payroll-Timestamp": timestamp.toString(),
+          ...webhook.headers
+        };
+        if (webhook.secret) {
+          headers["X-Payroll-Signature"] = this.generateSignature(requestBody, webhook.secret, timestamp);
+        }
+        const response = await fetch(webhook.url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(requestBody),
+          signal: controller.signal
+        });
+        clearTimeout(timeout);
+        delivery.response = {
+          status: response.status,
+          body: await response.text()
+        };
+        delivery.sentAt = /* @__PURE__ */ new Date();
+        if (response.ok) {
+          delivery.status = "sent";
+          return delivery;
+        }
+        const shouldRetry = response.status >= 500 || response.status === 429 || response.status === 408;
+        if (shouldRetry && attempt < maxRetries) {
+          const backoff = Math.pow(2, attempt) * 1e3;
+          const jitter = Math.random() * 1e3;
+          await this.sleep(backoff + jitter);
+          continue;
+        }
+        delivery.status = "failed";
+        delivery.error = `HTTP ${response.status}`;
+        return delivery;
+      } catch (error) {
+        delivery.error = error.message;
+        if (attempt < maxRetries) {
+          await this.sleep(Math.pow(2, attempt) * 1e3);
+          continue;
+        }
+        delivery.status = "failed";
+        return delivery;
+      }
+    }
+    return delivery;
+  }
+  /**
+   * Generate HMAC-SHA256 signature for webhook (Stripe-style)
+   *
+   * Format: t=<timestamp>,v1=<hmac_signature>
+   *
+   * The signed payload is: timestamp.JSON(requestBody)
+   * where requestBody = { event, payload, deliveredAt }
+   *
+   * Consumers should verify:
+   * 1. Timestamp is within tolerance (e.g., 5 minutes)
+   * 2. HMAC signature matches
+   *
+   * @example Verify signature (consumer side)
+   * ```typescript
+   * import crypto from 'crypto';
+   *
+   * const signature = req.headers['x-payroll-signature'];
+   * const timestamp = req.headers['x-payroll-timestamp'];
+   * const requestBody = req.body; // { event, payload, deliveredAt }
+   *
+   * // Check timestamp (replay protection)
+   * const now = Math.floor(Date.now() / 1000);
+   * if (Math.abs(now - parseInt(timestamp)) > 300) {
+   *   throw new Error('Signature expired');
+   * }
+   *
+   * // Verify signature
+   * const signedPayload = `${timestamp}.${JSON.stringify(requestBody)}`;
+   * const expectedSignature = crypto
+   *   .createHmac('sha256', secret)
+   *   .update(signedPayload)
+   *   .digest('hex');
+   *
+   * const parts = signature.split(',');
+   * const providedSignature = parts.find(p => p.startsWith('v1='))?.split('=')[1];
+   *
+   * if (providedSignature !== expectedSignature) {
+   *   throw new Error('Invalid signature');
+   * }
+   * ```
+   */
+  generateSignature(requestBody, secret, timestamp) {
+    const data = JSON.stringify(requestBody);
+    const signedPayload = `${timestamp}.${data}`;
+    const hmac = crypto.createHmac("sha256", secret);
+    hmac.update(signedPayload);
+    const signature = hmac.digest("hex");
+    return `t=${timestamp},v1=${signature}`;
+  }
+  /**
+   * Prune delivery log to stay within maxLogSize.
+   * Removes oldest entries first.
+   */
+  pruneLog() {
+    if (this.deliveryLog.length > this.maxLogSize) {
+      this.deliveryLog = this.deliveryLog.slice(-this.maxLogSize);
+    }
+  }
+  /**
+   * Sleep for ms
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Get delivery log
+   */
+  getDeliveries(options) {
+    let results = this.deliveryLog;
+    if (options?.event) {
+      results = results.filter((d) => d.event === options.event);
+    }
+    if (options?.status) {
+      results = results.filter((d) => d.status === options.status);
+    }
+    if (options?.limit) {
+      results = results.slice(-options.limit);
+    }
+    return results;
+  }
+  /**
+   * Clear delivery log
+   */
+  clearLog() {
+    this.deliveryLog = [];
+  }
+  /**
+   * Get all registered webhooks
+   */
+  getWebhooks() {
+    return [...this.webhooks];
+  }
+};
+
+// src/core/plugin.ts
+var PluginManager = class {
+  constructor(context) {
+    this.context = context;
+  }
+  plugins = /* @__PURE__ */ new Map();
+  hooks = /* @__PURE__ */ new Map();
+  /**
+   * Register a plugin
+   */
+  async register(plugin) {
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin "${plugin.name}" is already registered`);
+    }
+    if (plugin.hooks) {
+      for (const [hookName, handler] of Object.entries(plugin.hooks)) {
+        if (handler) {
+          this.addHook(hookName, handler);
+        }
+      }
+    }
+    if (plugin.init) {
+      await plugin.init(this.context);
+    }
+    this.plugins.set(plugin.name, plugin);
+    this.context.logger.debug(`Plugin "${plugin.name}" registered`);
+  }
+  /**
+   * Unregister a plugin
+   */
+  async unregister(name) {
+    const plugin = this.plugins.get(name);
+    if (!plugin) {
+      return;
+    }
+    if (plugin.destroy) {
+      await plugin.destroy();
+    }
+    this.plugins.delete(name);
+    this.context.logger.debug(`Plugin "${name}" unregistered`);
+  }
+  /**
+   * Add a hook handler
+   */
+  addHook(hookName, handler) {
+    if (!this.hooks.has(hookName)) {
+      this.hooks.set(hookName, []);
+    }
+    this.hooks.get(hookName).push(handler);
+  }
+  /**
+   * Execute hooks for a given event
+   */
+  async executeHooks(hookName, ...args) {
+    const handlers = this.hooks.get(hookName);
+    if (!handlers || handlers.length === 0) {
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        await handler(...args);
+      } catch (error) {
+        this.context.logger.error(`Hook "${hookName}" error:`, { error });
+        const errorHandlers = this.hooks.get("onError");
+        if (errorHandlers) {
+          for (const errorHandler of errorHandlers) {
+            try {
+              await errorHandler(error, hookName);
+            } catch (handlerError) {
+              getLogger().debug("Error handler threw an error", {
+                hook: hookName,
+                handlerError: handlerError instanceof Error ? handlerError.message : String(handlerError)
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Get registered plugin names
+   */
+  getPluginNames() {
+    return Array.from(this.plugins.keys());
+  }
+  /**
+   * Check if plugin is registered
+   */
+  hasPlugin(name) {
+    return this.plugins.has(name);
+  }
+};
+function definePlugin(definition) {
+  return definition;
+}
+var loggingPlugin = definePlugin({
+  name: "logging",
+  version: "1.0.0",
+  init: (context) => {
+    context.addHook("employee:hired", (payload) => {
+      context.logger.info("Employee hired", {
+        employeeId: payload.employee.employeeId,
+        position: payload.employee.position
+      });
+    });
+    context.addHook("salary:processed", (payload) => {
+      context.logger.info("Salary processed", {
+        employeeId: payload.employee.employeeId,
+        amount: payload.payroll.netAmount,
+        period: payload.payroll.period
+      });
+    });
+    context.addHook("employee:terminated", (payload) => {
+      context.logger.info("Employee terminated", {
+        employeeId: payload.employee.employeeId,
+        reason: payload.reason
+      });
+    });
+  },
+  hooks: {
+    onError: (error, context) => {
+      getLogger().error(`[Payroll Error] ${context}:`, { error: error.message });
+    }
+  }
+});
+var metricsPlugin = definePlugin({
+  name: "metrics",
+  version: "1.0.0",
+  init: (context) => {
+    const metrics = {
+      employeesHired: 0,
+      employeesTerminated: 0,
+      salariesProcessed: 0,
+      totalPaid: 0,
+      errors: 0
+    };
+    context.addHook("employee:hired", () => {
+      metrics.employeesHired++;
+    });
+    context.addHook("employee:terminated", () => {
+      metrics.employeesTerminated++;
+    });
+    context.addHook("salary:processed", (payload) => {
+      metrics.salariesProcessed++;
+      metrics.totalPaid += payload.payroll.netAmount;
+    });
+    context.payroll.metrics = metrics;
+  },
+  hooks: {
+    onError: (error, context) => {
+    }
+  }
+});
+function createNotificationPlugin(options) {
+  return definePlugin({
+    name: "notification",
+    version: "1.0.0",
+    init: (context) => {
+      if (options.onHired) {
+        context.addHook("employee:hired", async (payload) => {
+          await options.onHired({
+            id: payload.employee.id,
+            name: payload.employee.position
+          });
+        });
+      }
+      if (options.onTerminated) {
+        context.addHook("employee:terminated", async (payload) => {
+          await options.onTerminated({
+            id: payload.employee.id,
+            name: payload.employee.name
+          });
+        });
+      }
+      if (options.onSalaryProcessed) {
+        context.addHook("salary:processed", async (payload) => {
+          await options.onSalaryProcessed({
+            employee: {
+              id: payload.employee.id,
+              name: payload.employee.name
+            },
+            amount: payload.payroll.netAmount
+          });
+        });
+      }
+      if (options.onMilestone) {
+        context.addHook("milestone:achieved", async (payload) => {
+          await options.onMilestone({
+            employee: {
+              id: payload.employee.id,
+              name: payload.employee.name
+            },
+            milestone: payload.milestone.message
+          });
+        });
+      }
+    }
+  });
+}
+var notificationPlugin = createNotificationPlugin({});
+function toObjectId(id) {
+  if (id instanceof Types.ObjectId) return id;
+  return new Types.ObjectId(id);
+}
+
+// src/core/repository-plugins.ts
+function multiTenantPlugin(organizationId) {
+  return {
+    name: "multi-tenant",
+    apply(repo) {
+      if (!organizationId) return;
+      const orgId = toObjectId(organizationId);
+      repo.on("before:create", async (context) => {
+        if (context.data) {
+          if (Array.isArray(context.data)) {
+            context.data = context.data.map((item) => ({
+              ...item,
+              organizationId: orgId
+              // CRITICAL: Force override - never allow caller to set different orgId
+            }));
+          } else {
+            context.data = {
+              ...context.data,
+              organizationId: orgId
+              // CRITICAL: Force override - never allow caller to set different orgId
+            };
+          }
+        }
+      });
+      repo.on("before:getAll", async (context) => {
+        context.filters = {
+          ...context.filters || {},
+          organizationId: orgId
+        };
+      });
+      repo.on("before:getById", async (context) => {
+        context.filters = {
+          ...context.filters || {},
+          organizationId: orgId
+        };
+      });
+      repo.on("before:getByQuery", async (context) => {
+        if (!context.query) {
+          context.query = {};
+        }
+        context.query.organizationId = orgId;
+      });
+      repo.on("before:update", async (context) => {
+        context.filters = {
+          ...context.filters || {},
+          organizationId: orgId
+        };
+      });
+      repo.on("before:delete", async (context) => {
+        context.filters = {
+          ...context.filters || {},
+          organizationId: orgId
+        };
+      });
+    }
+  };
+}
+
+// src/utils/money.ts
+function roundMoney(value, decimals = 2) {
+  const multiplier = Math.pow(10, decimals);
+  const scaled = value * multiplier;
+  const fraction = scaled - Math.floor(scaled);
+  if (Math.abs(fraction - 0.5) < 1e-10) {
+    const floor = Math.floor(scaled);
+    const rounded = floor % 2 === 0 ? floor : floor + 1;
+    return rounded / multiplier;
+  }
+  return Math.round(scaled) / multiplier;
+}
+function percentageOf(amount, percentage, decimals = 2) {
+  return roundMoney(amount * percentage / 100, decimals);
+}
+function prorateAmount(amount, ratio, decimals = 2) {
+  return roundMoney(amount * ratio, decimals);
+}
+
+// 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,
+    // 2 years - adjust per jurisdiction
+    exportWarningDays: 30,
+    archiveBeforeDeletion: true
+  },
+  payroll: {
+    defaultCurrency: "USD",
+    allowProRating: true,
+    attendanceIntegration: true,
+    autoDeductions: true,
+    overtimeEnabled: false,
+    overtimeMultiplier: 1.5
+  },
+  salary: {
+    minimumWage: 0,
+    maximumAllowances: 10,
+    maximumDeductions: 10,
+    defaultFrequency: "monthly"
+  },
+  employment: {
+    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",
+    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);
+function getPayPeriodsPerYear(frequency) {
+  const periodsMap = {
+    monthly: 12,
+    bi_weekly: 26,
+    weekly: 52,
+    daily: 365,
+    hourly: 2080
+    // Assuming 40 hours/week * 52 weeks
+  };
+  return periodsMap[frequency];
+}
+function mergeConfig(customConfig) {
+  if (!customConfig) return HRM_CONFIG;
+  return {
+    dataRetention: { ...HRM_CONFIG.dataRetention, ...customConfig.dataRetention },
+    payroll: { ...HRM_CONFIG.payroll, ...customConfig.payroll },
+    salary: { ...HRM_CONFIG.salary, ...customConfig.salary },
+    employment: { ...HRM_CONFIG.employment, ...customConfig.employment },
+    validation: {
+      ...HRM_CONFIG.validation,
+      ...customConfig.validation,
+      // Ensure fallbacks is always EmployeeIdentityMode[]
+      identityFallbacks: customConfig.validation?.identityFallbacks ?? HRM_CONFIG.validation.identityFallbacks
+    }
+  };
+}
+
+// src/core/container.ts
+var Container = class {
+  _models = null;
+  _config = HRM_CONFIG;
+  _singleTenant = null;
+  _logger;
+  _initialized = false;
+  constructor() {
+    this._logger = getLogger();
+  }
+  /**
+   * Initialize container with configuration
+   */
+  initialize(config) {
+    if (this._initialized) {
+      this._logger.warn("Container already initialized, re-initializing");
+    }
+    this._models = config.models;
+    this._config = mergeConfig(config.config);
+    this._singleTenant = config.singleTenant ?? null;
+    if (config.logger) {
+      this._logger = config.logger;
+    }
+    this._initialized = true;
+    this._logger.info("Container initialized", {
+      hasEmployeeModel: !!this._models.EmployeeModel,
+      hasPayrollRecordModel: !!this._models.PayrollRecordModel,
+      hasTransactionModel: !!this._models.TransactionModel,
+      hasAttendanceModel: !!this._models.AttendanceModel,
+      hasLeaveRequestModel: !!this._models.LeaveRequestModel,
+      hasTaxWithholdingModel: !!this._models.TaxWithholdingModel,
+      isSingleTenant: !!this._singleTenant
+    });
+  }
+  /**
+   * Check if container is initialized
+   */
+  isInitialized() {
+    return this._initialized;
+  }
+  /**
+   * Reset container (useful for testing)
+   */
+  reset() {
+    this._models = null;
+    this._config = HRM_CONFIG;
+    this._singleTenant = null;
+    this._initialized = false;
+    this._logger.info("Container reset");
+  }
+  /**
+   * Ensure container is initialized
+   */
+  ensureInitialized() {
+    if (!this._initialized || !this._models) {
+      throw new Error(
+        "Payroll not initialized. Call Payroll.initialize() first."
+      );
+    }
+  }
+  /**
+   * Get models container (strongly typed)
+   */
+  getModels() {
+    this.ensureInitialized();
+    return this._models;
+  }
+  /**
+   * Get Employee model (strongly typed)
+   */
+  getEmployeeModel() {
+    this.ensureInitialized();
+    return this._models.EmployeeModel;
+  }
+  /**
+   * Get PayrollRecord model (strongly typed)
+   */
+  getPayrollRecordModel() {
+    this.ensureInitialized();
+    return this._models.PayrollRecordModel;
+  }
+  /**
+   * Get Transaction model (strongly typed)
+   */
+  getTransactionModel() {
+    this.ensureInitialized();
+    return this._models.TransactionModel;
+  }
+  /**
+   * Get Attendance model (optional, strongly typed)
+   */
+  getAttendanceModel() {
+    this.ensureInitialized();
+    return this._models.AttendanceModel ?? null;
+  }
+  /**
+   * Get LeaveRequest model (optional, strongly typed)
+   */
+  getLeaveRequestModel() {
+    this.ensureInitialized();
+    return this._models.LeaveRequestModel ?? null;
+  }
+  /**
+   * Get TaxWithholding model (optional, strongly typed)
+   */
+  getTaxWithholdingModel() {
+    this.ensureInitialized();
+    return this._models.TaxWithholdingModel ?? null;
+  }
+  /**
+   * Get configuration
+   */
+  getConfig() {
+    return this._config;
+  }
+  /**
+   * Get specific config section
+   */
+  getConfigSection(section) {
+    return this._config[section];
+  }
+  /**
+   * Check if single-tenant mode
+   */
+  isSingleTenant() {
+    return !!this._singleTenant;
+  }
+  /**
+   * Get single-tenant config
+   */
+  getSingleTenantConfig() {
+    return this._singleTenant;
+  }
+  /**
+   * Get organization ID (for single-tenant mode)
+   */
+  getOrganizationId() {
+    if (!this._singleTenant || !this._singleTenant.organizationId) return null;
+    return typeof this._singleTenant.organizationId === "string" ? this._singleTenant.organizationId : this._singleTenant.organizationId.toString();
+  }
+  /**
+   * Get logger
+   */
+  getLogger() {
+    return this._logger;
+  }
+  /**
+   * Set logger
+   */
+  setLogger(logger) {
+    this._logger = logger;
+  }
+  /**
+   * Has attendance integration
+   */
+  hasAttendanceIntegration() {
+    return !!this._models?.AttendanceModel && this._config.payroll.attendanceIntegration;
+  }
+  /**
+   * Create operation context with defaults
+   *
+   * In single-tenant mode with autoInject enabled (default), automatically
+   * injects the configured organizationId into the context.
+   *
+   * @throws Error if autoInject is enabled but no organizationId is configured
+   */
+  createOperationContext(overrides) {
+    const context = {};
+    const isSingleTenant2 = !!this._singleTenant;
+    const autoInjectEnabled = isSingleTenant2 && this._singleTenant?.autoInject !== false;
+    if (autoInjectEnabled && !overrides?.organizationId) {
+      const orgId = this.getOrganizationId();
+      if (orgId) {
+        context.organizationId = orgId;
+      } else {
+        throw new Error(
+          "Single-tenant mode with autoInject enabled requires organizationId in configuration. Configure it via forSingleTenant({ organizationId: YOUR_ORG_ID }) or provide it explicitly."
+        );
+      }
+    }
+    return { ...context, ...overrides };
+  }
+};
+var defaultContainer = null;
+function getContainer() {
+  if (!defaultContainer) {
+    defaultContainer = new Container();
+  }
+  return defaultContainer;
+}
+function initializeContainer(config) {
+  getContainer().initialize(config);
+}
+function isContainerInitialized() {
+  return defaultContainer?.isInitialized() ?? false;
+}
+function getModels() {
+  return getContainer().getModels();
+}
+function getConfig() {
+  return getContainer().getConfig();
+}
+function isSingleTenant() {
+  return getContainer().isSingleTenant();
+}
+
+// src/utils/date.ts
+function toUTCDateString(date) {
+  const d = new Date(date);
+  d.setHours(0, 0, 0, 0);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+function isEffectiveForPeriod(item, periodStart, periodEnd) {
+  const effectiveFrom = item.effectiveFrom ? new Date(item.effectiveFrom) : /* @__PURE__ */ new Date(0);
+  const effectiveTo = item.effectiveTo ? new Date(item.effectiveTo) : /* @__PURE__ */ new Date("2099-12-31");
+  return effectiveFrom <= periodEnd && effectiveTo >= periodStart;
+}
+
+// src/core/config.ts
+var DEFAULT_WORK_SCHEDULE = {
+  workingDays: [1, 2, 3, 4, 5],
+  // Monday to Friday
+  hoursPerDay: 8
+};
+function countWorkingDays(startDate, endDate, options = {}) {
+  const workDays = options.workingDays || DEFAULT_WORK_SCHEDULE.workingDays;
+  const holidaySet = new Set(
+    (options.holidays || []).map((d) => toUTCDateString(d))
+  );
+  let totalDays = 0;
+  let workingDays = 0;
+  let holidays = 0;
+  let weekends = 0;
+  const current = new Date(startDate);
+  current.setHours(0, 0, 0, 0);
+  const end = new Date(endDate);
+  end.setHours(0, 0, 0, 0);
+  while (current <= end) {
+    totalDays++;
+    const isHoliday = holidaySet.has(toUTCDateString(current));
+    const isWorkDay = workDays.includes(current.getDay());
+    if (isHoliday) {
+      holidays++;
+    } else if (isWorkDay) {
+      workingDays++;
+    } else {
+      weekends++;
+    }
+    current.setDate(current.getDate() + 1);
+  }
+  return { totalDays, workingDays, weekends, holidays };
+}
+function calculateProration(hireDate, terminationDate, periodStart, periodEnd) {
+  const hire = new Date(hireDate);
+  hire.setHours(0, 0, 0, 0);
+  const term = terminationDate ? new Date(terminationDate) : null;
+  if (term) term.setHours(0, 0, 0, 0);
+  const start = new Date(periodStart);
+  start.setHours(0, 0, 0, 0);
+  const end = new Date(periodEnd);
+  end.setHours(0, 0, 0, 0);
+  if (hire > end || term && term < start) {
+    return { ratio: 0, reason: "not_active", isProrated: true };
+  }
+  const effectiveStart = hire > start ? hire : start;
+  const effectiveEnd = term && term < end ? term : end;
+  const totalDays = Math.ceil((end.getTime() - start.getTime()) / 864e5) + 1;
+  const actualDays = Math.ceil((effectiveEnd.getTime() - effectiveStart.getTime()) / 864e5) + 1;
+  const ratio = Math.min(1, Math.max(0, actualDays / totalDays));
+  const isNewHire = hire > start;
+  const isTermination = term !== null && term < end;
+  let reason = "full";
+  if (isNewHire && isTermination) {
+    reason = "both";
+  } else if (isNewHire) {
+    reason = "new_hire";
+  } else if (isTermination) {
+    reason = "termination";
+  }
+  return { ratio, reason, isProrated: ratio < 1 };
+}
+function getPayPeriod(month, year, payDay = 28) {
+  const startDate = new Date(year, month - 1, 1);
+  const endDate = new Date(year, month, 0);
+  const payDate = new Date(year, month - 1, Math.min(payDay, endDate.getDate()));
+  return { startDate, endDate, payDate };
+}
+
+// src/calculators/attendance.calculator.ts
+function calculateAttendanceDeduction(input) {
+  const { expectedWorkingDays, actualWorkingDays, dailyRate } = input;
+  const expected = Math.max(0, expectedWorkingDays);
+  const actual = Math.max(0, actualWorkingDays);
+  const rate = Math.max(0, dailyRate);
+  const absentDays = Math.max(0, expected - actual);
+  const deductionAmount = roundMoney(absentDays * rate, 2);
+  return {
+    absentDays,
+    deductionAmount,
+    dailyRate: rate,
+    hasDeduction: deductionAmount > 0
+  };
+}
+function calculateDailyRate(monthlySalary, workingDays) {
+  if (workingDays <= 0) return 0;
+  return roundMoney(monthlySalary / workingDays, 2);
+}
+
+// src/utils/calculation.ts
+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 calculateGross(baseAmount, allowances) {
+  return baseAmount + sumAllowances(allowances);
+}
+function calculateNet(gross, deductions) {
+  return Math.max(0, gross - sumDeductions(deductions));
+}
+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 roundMoney(tax);
+}
+
+// src/calculators/prorating.calculator.ts
+function calculateProRating(input) {
+  const { hireDate, terminationDate, periodStart, periodEnd, workingDays, holidays = [] } = input;
+  const hire = new Date(hireDate);
+  const termination = terminationDate ? new Date(terminationDate) : null;
+  const effectiveStart = hire > periodStart ? hire : periodStart;
+  const effectiveEnd = termination && termination < periodEnd ? termination : periodEnd;
+  if (effectiveStart > periodEnd || termination && termination < periodStart) {
+    const periodWorkingDays2 = countWorkingDays(periodStart, periodEnd, { workingDays, holidays }).workingDays;
+    return {
+      isProRated: true,
+      ratio: 0,
+      periodWorkingDays: periodWorkingDays2,
+      effectiveWorkingDays: 0,
+      effectiveStart: periodStart,
+      effectiveEnd: periodStart
+      // Effectively zero days
+    };
+  }
+  const periodWorkingDays = countWorkingDays(periodStart, periodEnd, { workingDays, holidays }).workingDays;
+  const effectiveWorkingDays = countWorkingDays(effectiveStart, effectiveEnd, { workingDays, holidays }).workingDays;
+  const ratio = periodWorkingDays > 0 ? Math.min(1, Math.max(0, effectiveWorkingDays / periodWorkingDays)) : 0;
+  const isProRated = ratio < 1;
+  return {
+    isProRated,
+    ratio,
+    periodWorkingDays,
+    effectiveWorkingDays,
+    effectiveStart,
+    effectiveEnd
+  };
+}
+
+// src/calculators/salary.calculator.ts
+function calculateSalaryBreakdown(input) {
+  const { employee, period, attendance, options = {}, config, taxBrackets, taxOptions, jurisdictionTaxConfig } = input;
+  const comp = employee.compensation;
+  const originalBaseAmount = comp.baseAmount;
+  const proRating = calculateProRatingForSalary(
+    employee.hireDate,
+    employee.terminationDate || null,
+    period.startDate,
+    period.endDate,
+    options,
+    employee.workSchedule
+  );
+  let baseAmount = originalBaseAmount;
+  if (proRating.isProRated && config.allowProRating && !options.skipProration) {
+    baseAmount = prorateAmount(baseAmount, proRating.ratio);
+  }
+  const effectiveAllowances = (comp.allowances || []).filter((a) => isEffectiveForPeriod(a, period.startDate, period.endDate));
+  const effectiveDeductions = (comp.deductions || []).filter((d) => isEffectiveForPeriod(d, period.startDate, period.endDate)).filter((d) => d.auto || d.recurring);
+  const allowances = processAllowances(effectiveAllowances, originalBaseAmount, proRating, config, options.skipProration);
+  const deductions = processDeductions(effectiveDeductions, originalBaseAmount, proRating, config, options.skipProration);
+  if (!options.skipAttendance && config.attendanceIntegration && attendance) {
+    const attendanceDeductionResult = calculateAttendanceDeductionFromData(
+      attendance,
+      baseAmount,
+      proRating.effectiveWorkingDays
+    );
+    if (attendanceDeductionResult.hasDeduction) {
+      deductions.push({
+        type: "absence",
+        amount: attendanceDeductionResult.deductionAmount,
+        description: `Unpaid leave deduction (${attendanceDeductionResult.absentDays} days)`
+      });
+    }
+  }
+  const grossSalary = calculateGross(baseAmount, allowances);
+  const taxableAllowances = allowances.filter((a) => a.taxable);
+  let taxableAmount = baseAmount + sumAllowances(taxableAllowances);
+  const preTaxDeductionAmount = calculatePreTaxDeductions(
+    effectiveDeductions,
+    deductions,
+    taxOptions,
+    jurisdictionTaxConfig
+  );
+  taxableAmount = Math.max(0, taxableAmount - preTaxDeductionAmount);
+  const frequency = employee.compensation?.frequency || "monthly";
+  let taxAmount = 0;
+  if (!options.skipTax && taxBrackets.length > 0 && config.autoDeductions) {
+    taxAmount = calculateEnhancedTax(
+      taxableAmount,
+      taxBrackets,
+      taxOptions,
+      jurisdictionTaxConfig,
+      frequency
+    );
+  }
+  if (taxAmount > 0) {
+    deductions.push({
+      type: "tax",
+      amount: taxAmount,
+      description: "Income tax"
+    });
+  }
+  const netSalary = calculateNet(grossSalary, deductions);
+  return {
+    baseAmount,
+    allowances,
+    deductions,
+    grossSalary,
+    netSalary,
+    taxableAmount,
+    taxAmount,
+    workingDays: proRating.periodWorkingDays,
+    actualDays: proRating.effectiveWorkingDays,
+    proRatedAmount: proRating.isProRated && !options.skipProration ? baseAmount : 0,
+    attendanceDeduction: attendance ? deductions.find((d) => d.type === "absence")?.amount || 0 : 0
+  };
+}
+function calculateProRatingForSalary(hireDate, terminationDate, periodStart, periodEnd, options, employeeWorkSchedule) {
+  const workingDays = options?.workSchedule?.workingDays || employeeWorkSchedule?.workingDays || [1, 2, 3, 4, 5];
+  const holidays = options?.holidays || [];
+  return calculateProRating({
+    hireDate,
+    terminationDate,
+    periodStart,
+    periodEnd,
+    workingDays,
+    holidays
+  });
+}
+function processAllowances(allowances, originalBaseAmount, proRating, config, skipProration) {
+  return allowances.map((a) => {
+    let amount = a.isPercentage && a.value !== void 0 ? percentageOf(originalBaseAmount, a.value) : a.amount;
+    const originalAmount = amount;
+    if (proRating.isProRated && config.allowProRating && !skipProration) {
+      amount = prorateAmount(amount, proRating.ratio);
+    }
+    return {
+      type: a.type,
+      amount,
+      taxable: a.taxable ?? true,
+      originalAmount,
+      isPercentage: a.isPercentage,
+      value: a.value
+    };
+  });
+}
+function processDeductions(deductions, originalBaseAmount, proRating, config, skipProration) {
+  return deductions.map((d) => {
+    let amount = d.isPercentage && d.value !== void 0 ? percentageOf(originalBaseAmount, d.value) : d.amount;
+    const originalAmount = amount;
+    if (proRating.isProRated && config.allowProRating && !skipProration) {
+      amount = prorateAmount(amount, proRating.ratio);
+    }
+    return {
+      type: d.type,
+      amount,
+      description: d.description,
+      originalAmount,
+      isPercentage: d.isPercentage,
+      value: d.value
+    };
+  });
+}
+function calculateAttendanceDeductionFromData(attendance, baseAmount, effectiveWorkingDays) {
+  const expectedDays = attendance.expectedDays ?? effectiveWorkingDays;
+  const actualDays = attendance.actualDays;
+  if (actualDays === void 0) {
+    return { hasDeduction: false, deductionAmount: 0, absentDays: 0 };
+  }
+  const dailyRate = calculateDailyRate(baseAmount, expectedDays);
+  const result = calculateAttendanceDeduction({
+    expectedWorkingDays: expectedDays,
+    actualWorkingDays: actualDays,
+    dailyRate
+  });
+  return {
+    hasDeduction: result.hasDeduction,
+    deductionAmount: result.deductionAmount,
+    absentDays: result.absentDays
+  };
+}
+function calculatePreTaxDeductions(effectiveDeductions, processedDeductions, taxOptions, jurisdictionTaxConfig) {
+  let totalPreTax = 0;
+  for (let i = 0; i < effectiveDeductions.length; i++) {
+    const original = effectiveDeductions[i];
+    const processed = processedDeductions[i];
+    if (original.reducesTaxableIncome) {
+      totalPreTax += processed?.amount || 0;
+    }
+  }
+  if (jurisdictionTaxConfig?.preTaxDeductionTypes?.length) {
+    const preTaxTypes = new Set(jurisdictionTaxConfig.preTaxDeductionTypes);
+    for (let i = 0; i < effectiveDeductions.length; i++) {
+      const original = effectiveDeductions[i];
+      const processed = processedDeductions[i];
+      if (original.reducesTaxableIncome) continue;
+      if (preTaxTypes.has(original.type)) {
+        totalPreTax += processed?.amount || 0;
+      }
+    }
+  }
+  if (taxOptions?.preTaxDeductions?.length) {
+    for (const deduction of taxOptions.preTaxDeductions) {
+      totalPreTax += deduction.amount;
+    }
+  }
+  return roundMoney(totalPreTax);
+}
+function calculateEnhancedTax(periodTaxable, taxBrackets, taxOptions, jurisdictionTaxConfig, frequency = "monthly") {
+  const periodsPerYear = getPayPeriodsPerYear(frequency);
+  let annualTaxable = periodTaxable * periodsPerYear;
+  const threshold = getApplicableThreshold(taxOptions, jurisdictionTaxConfig);
+  if (threshold > 0) {
+    annualTaxable = Math.max(0, annualTaxable - threshold);
+  }
+  let annualTax = applyTaxBrackets(annualTaxable, taxBrackets);
+  if (taxOptions?.taxCredits?.length && annualTax > 0) {
+    annualTax = applyTaxCredits(annualTax, taxOptions.taxCredits);
+  }
+  return roundMoney(annualTax / periodsPerYear);
+}
+function getApplicableThreshold(taxOptions, jurisdictionTaxConfig) {
+  if (taxOptions?.standardDeductionOverride !== void 0) {
+    return taxOptions.standardDeductionOverride;
+  }
+  if (taxOptions?.taxpayerCategory) {
+    const category = taxOptions.taxpayerCategory;
+    if (taxOptions.thresholdOverrides?.[category] !== void 0) {
+      return taxOptions.thresholdOverrides[category];
+    }
+    if (jurisdictionTaxConfig?.thresholdsByCategory?.[category] !== void 0) {
+      return jurisdictionTaxConfig.thresholdsByCategory[category];
+    }
+  }
+  if (taxOptions?.applyStandardDeduction && jurisdictionTaxConfig?.standardDeduction) {
+    return jurisdictionTaxConfig.standardDeduction;
+  }
+  return 0;
+}
+function applyTaxCredits(annualTax, taxCredits) {
+  let remainingTax = annualTax;
+  for (const credit of taxCredits) {
+    if (remainingTax <= 0) break;
+    let creditAmount = credit.amount;
+    if (credit.maxPercent !== void 0 && credit.maxPercent > 0) {
+      const maxCredit = annualTax * credit.maxPercent;
+      creditAmount = Math.min(creditAmount, maxCredit);
+    }
+    creditAmount = Math.min(creditAmount, remainingTax);
+    remainingTax -= creditAmount;
+  }
+  return Math.max(0, remainingTax);
+}
+
+// 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
+var PayrollStatusMachine = 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"]
+});
+var LeaveRequestStatusMachine = 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"]
+});
+var EmployeeStatusMachine = 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/core/timeline-audit.ts
+var PAYROLL_EVENTS = {
+  /**
+   * Employee lifecycle events
+   */
+  EMPLOYEE: {
+    /** Employee was hired */
+    HIRED: "employee.hired",
+    /** Employee was terminated */
+    TERMINATED: "employee.terminated",
+    /** Employee was re-hired after termination */
+    REHIRED: "employee.rehired",
+    /** Employee status changed (active, on_leave, suspended) */
+    STATUS_CHANGED: "employee.status_changed",
+    /** Employee department/position changed */
+    ROLE_CHANGED: "employee.role_changed",
+    /** Employee probation ended */
+    PROBATION_ENDED: "employee.probation_ended",
+    /** Recommended event limits for employee timeline */
+    limits: {
+      "employee.status_changed": 50,
+      "employee.role_changed": 20
+    }
+  },
+  /**
+   * Compensation events
+   */
+  COMPENSATION: {
+    /** Base salary was updated */
+    SALARY_UPDATED: "compensation.salary_updated",
+    /** Allowance was added */
+    ALLOWANCE_ADDED: "compensation.allowance_added",
+    /** Allowance was removed */
+    ALLOWANCE_REMOVED: "compensation.allowance_removed",
+    /** Deduction was added */
+    DEDUCTION_ADDED: "compensation.deduction_added",
+    /** Deduction was removed */
+    DEDUCTION_REMOVED: "compensation.deduction_removed",
+    /** Bank details were updated */
+    BANK_UPDATED: "compensation.bank_updated",
+    /** Recommended event limits */
+    limits: {
+      "compensation.salary_updated": 24,
+      // 2 years of monthly updates
+      "compensation.allowance_added": 20,
+      "compensation.allowance_removed": 20,
+      "compensation.deduction_added": 20,
+      "compensation.deduction_removed": 20,
+      "compensation.bank_updated": 10
+    }
+  },
+  /**
+   * Payroll processing events
+   */
+  PAYROLL: {
+    /** Salary was processed */
+    PROCESSED: "payroll.processed",
+    /** Payroll was voided (before payment) */
+    VOIDED: "payroll.voided",
+    /** Payroll was reversed (after payment) */
+    REVERSED: "payroll.reversed",
+    /** Payroll was restored from voided state */
+    RESTORED: "payroll.restored",
+    /** Payroll export was generated */
+    EXPORTED: "payroll.exported",
+    /** Recommended event limits */
+    limits: {
+      "payroll.processed": 36,
+      // 3 years of monthly payroll
+      "payroll.voided": 10,
+      "payroll.reversed": 10,
+      "payroll.restored": 5,
+      "payroll.exported": 20
+    }
+  },
+  /**
+   * Tax withholding events
+   */
+  TAX: {
+    /** Tax was withheld */
+    WITHHELD: "tax.withheld",
+    /** Tax was submitted to authorities */
+    SUBMITTED: "tax.submitted",
+    /** Tax payment was made */
+    PAID: "tax.paid",
+    /** Tax withholding was cancelled */
+    CANCELLED: "tax.cancelled",
+    /** Recommended event limits */
+    limits: {
+      "tax.withheld": 36,
+      "tax.submitted": 12,
+      "tax.paid": 12,
+      "tax.cancelled": 10
+    }
+  },
+  /**
+   * Leave management events
+   */
+  LEAVE: {
+    /** Leave was requested */
+    REQUESTED: "leave.requested",
+    /** Leave was approved */
+    APPROVED: "leave.approved",
+    /** Leave was rejected */
+    REJECTED: "leave.rejected",
+    /** Leave was cancelled */
+    CANCELLED: "leave.cancelled",
+    /** Leave balance was accrued */
+    ACCRUED: "leave.accrued",
+    /** Annual leave was reset */
+    RESET: "leave.reset",
+    /** Recommended event limits */
+    limits: {
+      "leave.requested": 50,
+      "leave.approved": 50,
+      "leave.rejected": 20,
+      "leave.cancelled": 20,
+      "leave.accrued": 12,
+      "leave.reset": 5
+    }
+  }
+};
+var EMPLOYEE_TIMELINE_CONFIG = {
+  ownerField: "organizationId",
+  fieldName: "timeline",
+  hideByDefault: true,
+  // Don't include timeline in normal queries
+  eventLimits: {
+    ...PAYROLL_EVENTS.EMPLOYEE.limits,
+    ...PAYROLL_EVENTS.COMPENSATION.limits
+  }
+};
+var PAYROLL_RECORD_TIMELINE_CONFIG = {
+  ownerField: "organizationId",
+  fieldName: "timeline",
+  hideByDefault: true,
+  eventLimits: PAYROLL_EVENTS.PAYROLL.limits
+};
+var LEAVE_REQUEST_TIMELINE_CONFIG = {
+  ownerField: "organizationId",
+  fieldName: "timeline",
+  hideByDefault: true,
+  eventLimits: PAYROLL_EVENTS.LEAVE.limits
+};
+function buildTimelineMetadata(context) {
+  if (!context) return {};
+  const result = {};
+  if (context.userId) {
+    result.performedByUserId = String(context.userId);
+  }
+  if (context.userName) {
+    result.performedByName = context.userName;
+  }
+  if (context.userRole) {
+    result.performedByRole = context.userRole;
+  }
+  if (context.organizationId) {
+    result.organizationId = String(context.organizationId);
+  }
+  return result;
+}
+function buildRequestContext(request) {
+  if (!request) return void 0;
+  const getHeader = (name) => {
+    if (request.get) return request.get(name);
+    if (request.headers) {
+      const value = request.headers[name.toLowerCase()];
+      return Array.isArray(value) ? value[0] : value;
+    }
+    return void 0;
+  };
+  return {
+    ip: request.ip || getHeader("x-forwarded-for"),
+    userAgent: getHeader("user-agent"),
+    origin: getHeader("origin")
+  };
+}
+
+export { Container, DEFAULT_WORK_SCHEDULE, EMPLOYEE_TIMELINE_CONFIG, EmployeeStatusMachine, EventBus, IdempotencyManager, LEAVE_REQUEST_TIMELINE_CONFIG, LeaveRequestStatusMachine, PAYROLL_EVENTS, PAYROLL_RECORD_TIMELINE_CONFIG, PayrollStatusMachine, PluginManager, Result, ResultClass, StateMachine, TaxStatusMachine, WebhookManager, all, buildRequestContext, buildTimelineMetadata, calculateAttendanceDeduction, calculateProration, calculateSalaryBreakdown, countWorkingDays, createEventBus, createNotificationPlugin, createStateMachine, definePlugin, err, flatMap, fromNullable, fromPromise, generatePayrollIdempotencyKey, getConfig, getContainer, getEventBus, getModels, getPayPeriod, initializeContainer, isContainerInitialized, isErr, isOk, isSingleTenant, loggingPlugin, map, mapErr, match, metricsPlugin, multiTenantPlugin, notificationPlugin, ok, onEmployeeHired, onMilestoneAchieved, onPayrollCompleted, onSalaryProcessed, resetEventBus, tryCatch, tryCatchSync, unwrap, unwrapOr, unwrapOrElse };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map