@classytic/payroll 2.7.5 → 2.8.0

package/dist/{employee-identity-Cq2wo9-2.d.ts → error-helpers-Bm6lMny2.d.ts}

@@ -1,5 +1,110 @@
-import { L as LeaveType, a as LeaveBalance, W as WorkingDaysOptions, b as LeaveSummaryResult, c as LeaveInitConfig, O as ObjectIdLike, E as EmployeeDocument, d as OperationContext } from './types-BVDjiVGS.js';
-import { Model, Types } from 'mongoose';
+import { aj as HttpError, ak as ErrorCode, a7 as LeaveType, al as LeaveBalance, am as WorkingDaysOptions, an as LeaveSummaryResult, ao as LeaveInitConfig, a2 as ObjectIdLike, E as EmployeeDocument, ap as OperationContext } from './types-bZdAJueH.js';
+import { ClientSession, Model, Types } from 'mongoose';
+
+/**
+ * @classytic/payroll - Error Handling
+ *
+ * Custom error classes with error codes and HTTP status
+ */
+
+declare class PayrollError extends Error implements HttpError {
+    readonly code: ErrorCode;
+    readonly status: number;
+    readonly context: Record<string, unknown>;
+    readonly timestamp: Date;
+    /**
+     * Create a PayrollError.
+     *
+     * Supports BOTH constructor styles for backwards compatibility:
+     * - new PayrollError(message, code?, status?, context?)
+     * - new PayrollError(code, status, message, context?)
+     */
+    constructor(messageOrCode: string | ErrorCode, codeOrStatus?: ErrorCode | number, statusOrMessage?: number | string, context?: Record<string, unknown>);
+    /**
+     * Convert error to JSON for API responses (ClockIn-compatible shape)
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Check if error is operational (expected) vs programmer error
+     */
+    isOperational(): boolean;
+}
+/**
+ * Not initialized error
+ */
+declare class NotInitializedError extends PayrollError {
+    constructor(message?: string);
+}
+/**
+ * Employee not found error
+ */
+declare class EmployeeNotFoundError extends PayrollError {
+    constructor(employeeId?: string, context?: Record<string, unknown>);
+}
+/**
+ * Invalid employee error
+ */
+declare class InvalidEmployeeError extends PayrollError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Duplicate payroll error
+ */
+declare class DuplicatePayrollError extends PayrollError {
+    constructor(employeeId: string, month: number, year: number, payrollRunType?: string, context?: Record<string, unknown>);
+}
+/**
+ * Validation error
+ */
+declare class ValidationError extends PayrollError {
+    readonly errors: string[];
+    constructor(errors: string | string[], context?: Record<string, unknown>);
+}
+/**
+ * Employee terminated error
+ */
+declare class EmployeeTerminatedError extends PayrollError {
+    constructor(employeeId?: string, context?: Record<string, unknown>);
+}
+/**
+ * Already processed error
+ */
+declare class AlreadyProcessedError extends PayrollError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Not eligible error
+ */
+declare class NotEligibleError extends PayrollError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Security error (unauthorized access, cross-organization access, etc.)
+ */
+declare class SecurityError extends PayrollError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Create error from code
+ */
+declare function createError(code: ErrorCode, message: string, context?: Record<string, unknown>): PayrollError;
+/**
+ * Check if error is PayrollError
+ */
+declare function isPayrollError(error: unknown): error is PayrollError;
+/**
+ * Extract error info for logging
+ */
+declare function extractErrorInfo(error: unknown): {
+    code: string;
+    status: number;
+    message: string;
+    context?: Record<string, unknown>;
+};
+/**
+ * Convert unknown error to PayrollError
+ */
+declare function toPayrollError(error: unknown): PayrollError;
 
 /**
  * @classytic/payroll - Leave Utilities
@@ -232,7 +337,7 @@ interface SecureEmployeeLookupOptions {
     /**
      * Mongoose session for transactions
      */
-    session?: any;
+    session?: ClientSession;
     /**
      * Fields to populate
      */
@@ -296,8 +401,8 @@ declare function employeeExistsSecure<T extends EmployeeDocument>(model: Model<T
  */
 declare function findEmployeesSecure<T extends EmployeeDocument>(model: Model<T>, options: {
     organizationId: ObjectIdLike;
-    filter?: Record<string, any>;
-    session?: any;
+    filter?: Record<string, unknown>;
+    session?: ClientSession;
     limit?: number;
     skip?: number;
     sort?: Record<string, 1 | -1>;
@@ -328,7 +433,7 @@ declare function requireOrganizationId(organizationId: ObjectIdLike | undefined,
 interface ContainerLike {
     isSingleTenant(): boolean;
     getSingleTenantConfig(): {
-        organizationId?: any;
+        organizationId?: ObjectIdLike;
         autoInject?: boolean;
     } | null;
     getOrganizationId(): string | null;
@@ -487,4 +592,149 @@ declare function isObjectIdEmployeeId(value: unknown): value is ObjectIdLike;
  */
 declare function formatEmployeeId(employeeId: ObjectIdLike | string): string;
 
-export { validateOrganizationId as A, type ContainerLike as C, DEFAULT_CARRY_OVER as D, type EmployeeIdMode as E, type ResolveOrganizationIdParams as R, type SecureEmployeeLookupOptions as S, _default as _, DEFAULT_LEAVE_ALLOCATIONS as a, type EmployeeIdType as b, type EmployeeQueryFilter as c, accrueLeaveToBalance as d, calculateCarryOver as e, calculateLeaveDays as f, calculateUnpaidLeaveDeduction as g, detectEmployeeIdType as h, employeeExistsSecure as i, findEmployeeSecure as j, findEmployeesSecure as k, formatEmployeeId as l, getAvailableDays as m, getLeaveBalance as n, getLeaveBalances as o, getLeaveSummary as p, getUnpaidLeaveDays as q, hasLeaveBalance as r, initializeLeaveBalances as s, isObjectIdEmployeeId as t, isStringEmployeeId as u, normalizeEmployeeId as v, proRateAllocation as w, requireOrganizationId as x, resolveOrganizationId as y, tryResolveOrganizationId as z };
+/**
+ * @classytic/payroll - Error Helpers
+ *
+ * Higher-level error handling utilities that combine type guards
+ * and error classes for common payroll error scenarios.
+ *
+ * Uses:
+ * - `../errors/index.js` for PayrollError classes
+ * - `./type-guards.js` for MongoDB error type checking
+ *
+ * @module @classytic/payroll/utils/error-helpers
+ */
+
+interface TransactionErrorResult {
+    /** Whether the error is transaction-related */
+    isTransactionError: boolean;
+    /** Whether transactions are unsupported (standalone MongoDB) */
+    isUnsupported: boolean;
+    /** Whether the operation can be safely retried */
+    retryable: boolean;
+    /** Wrapped PayrollError with context */
+    error: PayrollError;
+    /** Original error for logging */
+    originalError: unknown;
+}
+/**
+ * Handle transaction-specific errors with categorization and retry guidance.
+ *
+ * Categorizes transaction errors into:
+ * - **Unsupported**: Standalone MongoDB without replica set (non-retryable, graceful fallback)
+ * - **Transient**: Network issues, coordinator changes (retryable)
+ * - **Connection**: Server unreachable, shutdown (retryable after delay)
+ * - **Other**: Unknown transaction errors (non-retryable)
+ *
+ * @param error - Unknown error from a transaction operation
+ * @param operationName - Name of the operation for context (e.g., 'processSalary')
+ * @returns Structured error result with retry guidance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await processWithTransaction(session);
+ * } catch (error) {
+ *   const result = handleTransactionError(error, 'processSalary');
+ *   if (result.isUnsupported) {
+ *     // Fall back to non-transactional processing
+ *     await processWithoutTransaction();
+ *   } else if (result.retryable) {
+ *     // Retry the operation
+ *     await retry(() => processWithTransaction(session));
+ *   } else {
+ *     throw result.error;
+ *   }
+ * }
+ * ```
+ */
+declare function handleTransactionError(error: unknown, operationName: string): TransactionErrorResult;
+interface DuplicateKeyErrorResult {
+    /** Whether the error is a duplicate key error */
+    isDuplicate: boolean;
+    /** The field name that caused the duplicate */
+    field: string;
+    /** Wrapped DuplicatePayrollError or PayrollError */
+    error: PayrollError;
+}
+/**
+ * Handle MongoDB duplicate key errors with field extraction.
+ *
+ * Converts raw MongoDB E11000 errors into structured DuplicatePayrollError
+ * or PayrollError with the duplicate field identified.
+ *
+ * @param error - Unknown error from a create/update operation
+ * @param context - Additional context for the error
+ * @returns Structured duplicate key error result
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await PayrollRecord.create(data);
+ * } catch (error) {
+ *   const result = handleDuplicateKeyError(error, {
+ *     employeeId: 'EMP-001',
+ *     month: 1,
+ *     year: 2024,
+ *   });
+ *   if (result.isDuplicate) {
+ *     throw result.error; // DuplicatePayrollError with field info
+ *   }
+ *   throw error; // Re-throw non-duplicate errors
+ * }
+ * ```
+ */
+declare function handleDuplicateKeyError(error: unknown, context?: {
+    employeeId?: string;
+    month?: number;
+    year?: number;
+}): DuplicateKeyErrorResult;
+interface PayrollErrorResult {
+    /** Error code for programmatic handling */
+    code: string;
+    /** HTTP status code */
+    status: number;
+    /** Human-readable error message */
+    message: string;
+    /** Additional context */
+    context: Record<string, unknown>;
+    /** Whether the error is operational (expected) vs programmer error */
+    operational: boolean;
+    /** Whether the operation can be retried */
+    retryable: boolean;
+}
+/**
+ * Handle any payroll operation error and produce a structured result.
+ *
+ * Combines error classification from type-guards with PayrollError
+ * extraction to produce a unified error result suitable for API responses,
+ * logging, or retry decisions.
+ *
+ * @param error - Unknown error from any payroll operation
+ * @param operationName - Name of the operation for context
+ * @returns Structured error result
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await payroll.processSalary(params);
+ * } catch (error) {
+ *   const result = handlePayrollError(error, 'processSalary');
+ *   logger.error(result.message, { code: result.code, context: result.context });
+ *   res.status(result.status).json({ error: result });
+ * }
+ * ```
+ */
+declare function handlePayrollError(error: unknown, operationName: string): PayrollErrorResult;
+/**
+ * Format error for user-facing display.
+ *
+ * Strips internal details and produces a clean message suitable
+ * for API responses or UI display.
+ *
+ * @param error - Unknown error
+ * @returns User-safe error message
+ */
+declare function formatUserError(error: unknown): string;
+
+export { toPayrollError as $, normalizeEmployeeId as A, proRateAllocation as B, type ContainerLike as C, DEFAULT_CARRY_OVER as D, type EmployeeIdMode as E, requireOrganizationId as F, resolveOrganizationId as G, tryResolveOrganizationId as H, validateOrganizationId as I, AlreadyProcessedError as J, DuplicatePayrollError as K, EmployeeNotFoundError as L, EmployeeTerminatedError as M, InvalidEmployeeError as N, NotEligibleError as O, type PayrollErrorResult as P, NotInitializedError as Q, type ResolveOrganizationIdParams as R, type SecureEmployeeLookupOptions as S, type TransactionErrorResult as T, PayrollError as U, SecurityError as V, ValidationError as W, createError as X, extractErrorInfo as Y, isPayrollError as Z, _default as _, DEFAULT_LEAVE_ALLOCATIONS as a, type DuplicateKeyErrorResult as b, type EmployeeIdType as c, type EmployeeQueryFilter as d, accrueLeaveToBalance as e, calculateCarryOver as f, calculateLeaveDays as g, calculateUnpaidLeaveDeduction as h, detectEmployeeIdType as i, employeeExistsSecure as j, findEmployeeSecure as k, findEmployeesSecure as l, formatEmployeeId as m, formatUserError as n, getAvailableDays as o, getLeaveBalance as p, getLeaveBalances as q, getLeaveSummary as r, getUnpaidLeaveDays as s, handleDuplicateKeyError as t, handlePayrollError as u, handleTransactionError as v, hasLeaveBalance as w, initializeLeaveBalances as x, isObjectIdEmployeeId as y, isStringEmployeeId as z };