@classytic/payroll 1.0.2 → 2.3.0

package/dist/employee-identity-DXhgOgXE.d.ts

@@ -0,0 +1,473 @@
+import { aF as LeaveType, aG as WorkingDaysOptions, aH as LeaveBalance, aI as LeaveSummaryResult, aJ as LeaveInitConfig, E as EmployeeDocument, O as ObjectIdLike, g as OperationContext } from './types-BN3K_Uhr.js';
+import { Model, Types } from 'mongoose';
+
+/**
+ * @classytic/payroll - Leave Utilities
+ *
+ * Pure, composable leave calculation functions
+ */
+
+/** Default leave allocations by type (days per year) */
+declare const DEFAULT_LEAVE_ALLOCATIONS: Record<LeaveType, number>;
+/** Default carry-over limits by type (days) */
+declare const DEFAULT_CARRY_OVER: Record<LeaveType, number>;
+/**
+ * Calculate working days between two dates
+ * Excludes weekends and optionally holidays
+ *
+ * @example
+ * // March 2024: Get working days for a week
+ * const days = calculateLeaveDays(
+ *   new Date('2024-03-01'),
+ *   new Date('2024-03-08'),
+ *   { holidays: [new Date('2024-03-05')] }
+ * );
+ */
+declare function calculateLeaveDays(startDate: Date, endDate: Date, options?: WorkingDaysOptions): number;
+/**
+ * Check if employee has sufficient leave balance
+ *
+ * @example
+ * if (hasLeaveBalance(employee, 'annual', 5)) {
+ *   // Can request 5 days annual leave
+ * }
+ */
+declare function hasLeaveBalance(employee: {
+    leaveBalances?: LeaveBalance[];
+}, type: LeaveType, days: number, year?: number): boolean;
+/**
+ * Get leave balance for a specific type
+ */
+declare function getLeaveBalance(employee: {
+    leaveBalances?: LeaveBalance[];
+}, type: LeaveType, year?: number): LeaveBalance | undefined;
+/**
+ * Get all leave balances for a year
+ */
+declare function getLeaveBalances(employee: {
+    leaveBalances?: LeaveBalance[];
+}, year?: number): LeaveBalance[];
+/**
+ * Calculate available days for a leave type
+ */
+declare function getAvailableDays(employee: {
+    leaveBalances?: LeaveBalance[];
+}, type: LeaveType, year?: number): number;
+/**
+ * Get comprehensive leave summary for an employee
+ *
+ * @example
+ * const summary = getLeaveSummary(employee, 2024);
+ * console.log(`Available: ${summary.totalAvailable} days`);
+ * console.log(`Annual: ${summary.byType.annual?.available || 0} days`);
+ */
+declare function getLeaveSummary(employee: {
+    leaveBalances?: LeaveBalance[];
+}, year?: number): LeaveSummaryResult;
+/**
+ * Initialize leave balances for a new employee
+ *
+ * @example
+ * // Full allocation for employee hired Jan 1st
+ * const balances = initializeLeaveBalances(new Date('2024-01-01'));
+ *
+ * // Pro-rated for mid-year hire
+ * const balances = initializeLeaveBalances(new Date('2024-07-01'), {
+ *   proRateNewHires: true,
+ * });
+ */
+declare function initializeLeaveBalances(hireDate: Date, config?: LeaveInitConfig, year?: number): LeaveBalance[];
+/**
+ * Calculate prorated allocation for mid-year hire
+ */
+declare function proRateAllocation(fullAllocation: number, hireDate: Date, fiscalYearStartMonth?: number, year?: number): number;
+/**
+ * Calculate unpaid leave deduction for payroll
+ *
+ * @example
+ * const deduction = calculateUnpaidLeaveDeduction(100000, 5, 22);
+ * // Daily rate: 100000 / 22 = 4545
+ * // Deduction: 4545 * 5 = 22727
+ */
+declare function calculateUnpaidLeaveDeduction(baseSalary: number, unpaidDays: number, workingDaysInMonth: number): number;
+/**
+ * Get total unpaid leave days from a list of leave requests
+ */
+declare function getUnpaidLeaveDays(leaveRequests: Array<{
+    type: LeaveType;
+    days: number;
+    status: string;
+}>, status?: string): number;
+/**
+ * Calculate carry-over balances for year-end
+ *
+ * Creates new year balances for ALL leave types from the current year.
+ * Types with carry-over limits get their unused balance carried forward.
+ * Types without carry-over (or 0 limit) start fresh with 0 carriedOver.
+ *
+ * @example
+ * // With default allocations - creates balances for all types
+ * const newBalances = calculateCarryOver(employee.leaveBalances, {
+ *   annual: 5,
+ *   compensatory: 3,
+ * });
+ * // Merge with existing (don't replace entirely)
+ * employee.leaveBalances.push(...newBalances);
+ *
+ * // With custom allocations (org-specific entitlements)
+ * const newBalances = calculateCarryOver(employee.leaveBalances, {
+ *   annual: 5,
+ *   compensatory: 3,
+ * }, {
+ *   annual: 25,  // Custom org policy
+ *   sick: 15,
+ * });
+ */
+declare function calculateCarryOver(balances: LeaveBalance[], maxCarryOver?: Partial<Record<LeaveType, number>>, newYearAllocations?: Partial<Record<LeaveType, number>>): LeaveBalance[];
+/**
+ * Add accrued leave to balances
+ */
+declare function accrueLeaveToBalance(balances: LeaveBalance[], type: LeaveType, amount: number, year?: number): LeaveBalance[];
+declare const _default: {
+    DEFAULT_LEAVE_ALLOCATIONS: Record<LeaveType, number>;
+    DEFAULT_CARRY_OVER: Record<LeaveType, number>;
+    calculateLeaveDays: typeof calculateLeaveDays;
+    hasLeaveBalance: typeof hasLeaveBalance;
+    getLeaveBalance: typeof getLeaveBalance;
+    getLeaveBalances: typeof getLeaveBalances;
+    getAvailableDays: typeof getAvailableDays;
+    getLeaveSummary: typeof getLeaveSummary;
+    initializeLeaveBalances: typeof initializeLeaveBalances;
+    proRateAllocation: typeof proRateAllocation;
+    calculateUnpaidLeaveDeduction: typeof calculateUnpaidLeaveDeduction;
+    getUnpaidLeaveDays: typeof getUnpaidLeaveDays;
+    calculateCarryOver: typeof calculateCarryOver;
+    accrueLeaveToBalance: typeof accrueLeaveToBalance;
+};
+
+/**
+ * @classytic/payroll - Secure Employee Lookup
+ *
+ * Multi-tenant safe employee lookup utilities
+ * Enforces organizationId isolation on all queries
+ */
+
+/**
+ * Employee ID mode for explicit disambiguation
+ *
+ * Controls how the employeeId parameter is interpreted:
+ * - 'auto': Auto-detect via isValidObjectId() (default)
+ * - 'objectId': Force treat as MongoDB _id (ObjectId)
+ * - 'businessId': Force treat as business employeeId string
+ *
+ * @since v2.3.0
+ */
+type EmployeeIdMode = 'auto' | 'objectId' | 'businessId';
+/**
+ * Lookup options for secure employee queries
+ */
+interface SecureEmployeeLookupOptions {
+    /**
+     * Organization ID (required for multi-tenant isolation)
+     * Can be omitted only in single-tenant mode with auto-inject
+     */
+    organizationId?: ObjectIdLike;
+    /**
+     * Employee's Mongoose _id (ObjectId)
+     * Use this when you have the database ID
+     * Takes priority over employeeId if both are provided
+     */
+    _id?: ObjectIdLike;
+    /**
+     * Employee identifier (supports both formats):
+     * - ObjectId: employee._id (MongoDB document ID)
+     * - String: "EMP-001" (business identifier)
+     *
+     * System auto-detects type by default:
+     * - If valid ObjectId → queries by _id field
+     * - If string → queries by employeeId field
+     *
+     * Use employeeIdType to override auto-detection if your business
+     * employeeIds look like ObjectIds (24 hex characters).
+     *
+     * Note: If _id parameter is also provided, _id takes priority
+     */
+    employeeId?: ObjectIdLike | string;
+    /**
+     * Explicit mode hint for employeeId disambiguation
+     *
+     * - 'auto' (default): Auto-detect via isValidObjectId()
+     * - 'objectId': Force treat as MongoDB _id (ObjectId)
+     * - 'businessId': Force treat as business employeeId string
+     *
+     * Use 'businessId' if your employeeIds are 24-hex strings like
+     * "507f1f77bcf86cd799439011" to prevent ObjectId collision.
+     *
+     * @default 'auto'
+     * @since v2.3.0
+     */
+    employeeIdMode?: EmployeeIdMode;
+    /**
+     * User ID reference (optional)
+     */
+    userId?: ObjectIdLike;
+    /**
+     * Email address (optional)
+     */
+    email?: string;
+    /**
+     * Mongoose session for transactions
+     */
+    session?: any;
+    /**
+     * Fields to populate
+     */
+    populate?: string | string[];
+}
+/**
+ * Securely find an employee by various identifiers
+ * ALWAYS enforces organizationId for multi-tenant isolation
+ *
+ * @param model - Employee model
+ * @param options - Lookup options
+ * @returns Employee document or throws EmployeeNotFoundError
+ *
+ * @example
+ * // By ObjectId _id
+ * const emp = await findEmployeeSecure(Employee, {
+ *   _id: employee._id,
+ *   organizationId: org._id
+ * });
+ *
+ * @example
+ * // By string employeeId
+ * const emp = await findEmployeeSecure(Employee, {
+ *   employeeId: "EMP-001",
+ *   organizationId: org._id
+ * });
+ *
+ * @example
+ * // By 24-hex business employeeId (force businessId mode)
+ * const emp = await findEmployeeSecure(Employee, {
+ *   employeeId: "507f1f77bcf86cd799439011",  // Looks like ObjectId!
+ *   employeeIdMode: 'businessId',            // Force treat as business ID
+ *   organizationId: org._id
+ * });
+ *
+ * @example
+ * // By userId
+ * const emp = await findEmployeeSecure(Employee, {
+ *   userId: user._id,
+ *   organizationId: org._id
+ * });
+ */
+declare function findEmployeeSecure<T extends EmployeeDocument>(model: Model<T>, options: SecureEmployeeLookupOptions): Promise<T>;
+/**
+ * Check if an employee exists securely (with org isolation)
+ *
+ * @param model - Employee model
+ * @param options - Lookup options
+ * @returns true if employee exists, false otherwise
+ */
+declare function employeeExistsSecure<T extends EmployeeDocument>(model: Model<T>, options: SecureEmployeeLookupOptions): Promise<boolean>;
+/**
+ * Find multiple employees securely (with org isolation)
+ *
+ * @param model - Employee model
+ * @param options - Query options
+ * @returns Array of employee documents
+ */
+declare function findEmployeesSecure<T extends EmployeeDocument>(model: Model<T>, options: {
+    organizationId: ObjectIdLike;
+    filter?: Record<string, any>;
+    session?: any;
+    limit?: number;
+    skip?: number;
+    sort?: Record<string, 1 | -1>;
+}): Promise<T[]>;
+/**
+ * Validate organizationId is provided (unless single-tenant with auto-inject)
+ *
+ * @param organizationId - Organization ID to validate
+ * @param operation - Operation name for error message
+ * @throws Error if organizationId is missing
+ */
+declare function requireOrganizationId(organizationId: ObjectIdLike | undefined, operation: string): void;
+
+/**
+ * @classytic/payroll - Organization Resolution Utility
+ *
+ * Smart organization ID resolution with priority chain:
+ * 1. Explicit parameter (highest priority)
+ * 2. Context.organizationId (from middleware/auth)
+ * 3. Single-tenant config (if autoInject enabled)
+ * 4. Error (if none found in multi-tenant mode)
+ */
+
+/**
+ * Container-like interface for organization resolution
+ * Only requires the methods we need, allowing any generic Container type
+ */
+interface ContainerLike {
+    isSingleTenant(): boolean;
+    getSingleTenantConfig(): {
+        organizationId?: any;
+        autoInject?: boolean;
+    } | null;
+    getOrganizationId(): string | null;
+}
+/**
+ * Organization resolution parameters
+ */
+interface ResolveOrganizationIdParams {
+    /**
+     * Explicitly provided organizationId (highest priority)
+     */
+    explicit?: ObjectIdLike;
+    /**
+     * Operation context with possible organizationId
+     */
+    context?: OperationContext;
+    /**
+     * Container for single-tenant config access
+     * Accepts any Container with any generic types
+     */
+    container?: ContainerLike;
+    /**
+     * Operation name for error messages
+     */
+    operation?: string;
+}
+/**
+ * Smart organization ID resolution
+ *
+ * Priority Chain:
+ * 1. Explicit param (highest)
+ * 2. Context.organizationId (middleware/auth)
+ * 3. Single-tenant config (if autoInject enabled)
+ * 4. Error (if none found)
+ *
+ * @param params - Resolution parameters
+ * @returns Resolved ObjectId
+ * @throws Error if organizationId cannot be resolved
+ *
+ * @example
+ * // Explicit param wins
+ * const orgId = resolveOrganizationId({
+ *   explicit: org._id,
+ *   context: { organizationId: other._id },
+ *   operation: 'processSalary'
+ * });
+ * // Returns: org._id
+ *
+ * @example
+ * // Context fallback
+ * const orgId = resolveOrganizationId({
+ *   context: { organizationId: org._id },
+ *   operation: 'processSalary'
+ * });
+ * // Returns: org._id from context
+ *
+ * @example
+ * // Single-tenant auto-inject
+ * const orgId = resolveOrganizationId({
+ *   container: singleTenantContainer,
+ *   operation: 'processSalary'
+ * });
+ * // Returns: organizationId from container config
+ */
+declare function resolveOrganizationId(params: ResolveOrganizationIdParams): Types.ObjectId;
+/**
+ * Validate that organizationId is present
+ *
+ * @param organizationId - Organization ID to validate
+ * @param operation - Operation name for error message
+ * @returns ObjectId if valid
+ * @throws Error if organizationId is missing or invalid
+ */
+declare function validateOrganizationId(organizationId: ObjectIdLike | undefined, operation: string): Types.ObjectId;
+/**
+ * Try to resolve organizationId without throwing
+ *
+ * @param params - Resolution parameters
+ * @returns ObjectId if resolved, null otherwise
+ */
+declare function tryResolveOrganizationId(params: ResolveOrganizationIdParams): Types.ObjectId | null;
+
+/**
+ * @classytic/payroll - Employee Identity Helper
+ *
+ * Dual identity system for employee lookups:
+ * - MongoDB ObjectId (_id field)
+ * - Business string identifier (employeeId field like "EMP-001")
+ *
+ * Auto-detects identifier type and builds appropriate queries
+ */
+
+/**
+ * Employee identifier type
+ */
+type EmployeeIdType = 'objectId' | 'string';
+/**
+ * Employee query filter
+ */
+interface EmployeeQueryFilter {
+    _id?: Types.ObjectId;
+    employeeId?: string;
+    organizationId: Types.ObjectId;
+}
+/**
+ * Detect if employeeId is ObjectId or string
+ *
+ * @param employeeId - Employee identifier (ObjectId or string)
+ * @returns 'objectId' if valid ObjectId, 'string' otherwise
+ *
+ * @example
+ * detectEmployeeIdType(employee._id)
+ * // Returns: 'objectId'
+ *
+ * @example
+ * detectEmployeeIdType("EMP-001")
+ * // Returns: 'string'
+ */
+declare function detectEmployeeIdType(employeeId: ObjectIdLike | string): EmployeeIdType;
+/**
+ * Normalize employee identifier to consistent format
+ *
+ * Converts ObjectIdLike to ObjectId, keeps strings as-is
+ *
+ * @param employeeId - Employee identifier
+ * @returns Normalized ObjectId or string
+ */
+declare function normalizeEmployeeId(employeeId: ObjectIdLike | string): Types.ObjectId | string;
+/**
+ * Check if value is a string employee ID (not ObjectId)
+ *
+ * @param value - Value to check
+ * @returns true if string employeeId, false if ObjectId
+ */
+declare function isStringEmployeeId(value: unknown): value is string;
+/**
+ * Check if value is an ObjectId employee identifier
+ *
+ * @param value - Value to check
+ * @returns true if ObjectId, false otherwise
+ */
+declare function isObjectIdEmployeeId(value: unknown): value is ObjectIdLike;
+/**
+ * Format employee identifier for display
+ *
+ * @param employeeId - Employee identifier
+ * @returns Human-readable string
+ *
+ * @example
+ * formatEmployeeId(employee._id)
+ * // Returns: "_id=507f1f77bcf86cd799439011"
+ *
+ * @example
+ * formatEmployeeId("EMP-001")
+ * // Returns: "employeeId=EMP-001"
+ */
+declare function formatEmployeeId(employeeId: ObjectIdLike | string): string;
+
+export { type EmployeeQueryFilter as A, type ContainerLike as C, DEFAULT_LEAVE_ALLOCATIONS as D, type EmployeeIdMode as E, type ResolveOrganizationIdParams as R, type SecureEmployeeLookupOptions as S, _default as _, DEFAULT_CARRY_OVER as a, getLeaveBalances as b, calculateLeaveDays as c, getAvailableDays as d, getLeaveSummary as e, calculateUnpaidLeaveDeduction as f, getLeaveBalance as g, hasLeaveBalance as h, initializeLeaveBalances as i, getUnpaidLeaveDays as j, calculateCarryOver as k, accrueLeaveToBalance as l, findEmployeeSecure as m, employeeExistsSecure as n, findEmployeesSecure as o, proRateAllocation as p, resolveOrganizationId as q, requireOrganizationId as r, detectEmployeeIdType as s, tryResolveOrganizationId as t, normalizeEmployeeId as u, validateOrganizationId as v, isStringEmployeeId as w, isObjectIdEmployeeId as x, formatEmployeeId as y, type EmployeeIdType as z };

package/dist/employee.factory-BlZqhiCk.d.ts

@@ -0,0 +1,189 @@
+import { O as ObjectIdLike, F as EmploymentType, I as Department, J as WorkSchedule, K as PaymentFrequency, N as Allowance, Q as Deduction, V as BankDetails, z as HRMConfig, X as Compensation, Y as TerminationReason } from './types-BN3K_Uhr.js';
+
+/**
+ * @classytic/payroll - Employee Factory
+ *
+ * Clean object creation for employee documents
+ * Builder pattern for fluent API
+ */
+
+interface CreateEmployeeParams {
+    userId?: ObjectIdLike;
+    organizationId: ObjectIdLike;
+    employment: {
+        employeeId?: string;
+        email?: string;
+        type?: EmploymentType;
+        department?: Department | string;
+        position: string;
+        hireDate?: Date;
+        probationMonths?: number;
+        workSchedule?: WorkSchedule;
+    };
+    compensation: {
+        baseAmount: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+        allowances?: Array<Partial<Allowance>>;
+        deductions?: Array<Partial<Deduction>>;
+    };
+    bankDetails?: BankDetails;
+}
+interface EmployeeData {
+    userId?: ObjectIdLike;
+    email?: string;
+    organizationId: ObjectIdLike;
+    employeeId: string;
+    employmentType: EmploymentType;
+    status: 'active';
+    department?: Department;
+    position: string;
+    hireDate: Date;
+    probationEndDate: Date | null;
+    compensation: Compensation;
+    workSchedule: WorkSchedule;
+    bankDetails: BankDetails;
+    payrollStats: {
+        totalPaid: number;
+        paymentsThisYear: number;
+        averageMonthly: number;
+    };
+}
+interface TerminationData {
+    terminatedAt: Date;
+    terminationReason: TerminationReason;
+    terminationNotes?: string;
+    terminatedBy: {
+        userId?: ObjectIdLike;
+        name?: string;
+        role?: string;
+    };
+}
+declare class EmployeeFactory {
+    /**
+     * Create employee data object
+     */
+    static create(params: CreateEmployeeParams, config?: HRMConfig): EmployeeData;
+    /**
+     * Create compensation object
+     */
+    static createCompensation(params: {
+        baseAmount: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+        allowances?: Array<Partial<Allowance>>;
+        deductions?: Array<Partial<Deduction>>;
+    }, config?: HRMConfig): Compensation;
+    /**
+     * Create allowance object
+     */
+    static createAllowance(params: {
+        type: Allowance['type'];
+        amount: number;
+        name?: string;
+        isPercentage?: boolean;
+        taxable?: boolean;
+        recurring?: boolean;
+    }): Allowance;
+    /**
+     * Create deduction object
+     */
+    static createDeduction(params: {
+        type: Deduction['type'];
+        amount: number;
+        name?: string;
+        isPercentage?: boolean;
+        auto?: boolean;
+        recurring?: boolean;
+        description?: string;
+    }): Deduction;
+    /**
+     * Default work schedule
+     */
+    static defaultWorkSchedule(): WorkSchedule;
+    /**
+     * Create termination data
+     */
+    static createTermination(params: {
+        reason: TerminationReason;
+        date?: Date;
+        notes?: string;
+        context?: {
+            userId?: ObjectIdLike;
+            userName?: string;
+            userRole?: string;
+        };
+    }): TerminationData;
+}
+declare class EmployeeBuilder {
+    private data;
+    /**
+     * Set user ID
+     */
+    forUser(userId: ObjectIdLike): this;
+    /**
+     * Set organization ID
+     */
+    inOrganization(organizationId: ObjectIdLike): this;
+    /**
+     * Set employee ID
+     */
+    withEmployeeId(employeeId: string): this;
+    /**
+     * Set department
+     */
+    inDepartment(department: Department): this;
+    /**
+     * Set position
+     */
+    asPosition(position: string): this;
+    /**
+     * Set employment type
+     */
+    withEmploymentType(type: EmploymentType): this;
+    /**
+     * Set hire date
+     */
+    hiredOn(date: Date): this;
+    /**
+     * Set probation period
+     */
+    withProbation(months: number): this;
+    /**
+     * Set work schedule
+     */
+    withSchedule(schedule: WorkSchedule): this;
+    /**
+     * Set base salary
+     */
+    withBaseSalary(amount: number, frequency?: PaymentFrequency, currency?: string): this;
+    /**
+     * Add allowance
+     */
+    addAllowance(type: Allowance['type'], amount: number, options?: {
+        taxable?: boolean;
+        recurring?: boolean;
+    }): this;
+    /**
+     * Add deduction
+     */
+    addDeduction(type: Deduction['type'], amount: number, options?: {
+        auto?: boolean;
+        recurring?: boolean;
+        description?: string;
+    }): this;
+    /**
+     * Set bank details
+     */
+    withBankDetails(bankDetails: BankDetails): this;
+    /**
+     * Build employee data
+     */
+    build(config?: HRMConfig): EmployeeData;
+}
+/**
+ * Create new employee builder
+ */
+declare function createEmployee(): EmployeeBuilder;
+
+export { type CreateEmployeeParams as C, EmployeeFactory as E, type TerminationData as T, EmployeeBuilder as a, type EmployeeData as b, createEmployee as c };

package/dist/idempotency-Cw2CWicb.d.ts

@@ -0,0 +1,52 @@
+import { O as ObjectIdLike } from './types-BN3K_Uhr.js';
+
+/**
+ * Idempotency Manager
+ * Ensures operations are not duplicated when called with the same key
+ */
+
+interface IdempotentResult<T = any> {
+    value: T;
+    cached: boolean;
+    createdAt: Date;
+}
+declare class IdempotencyManager {
+    private cache;
+    constructor(options?: {
+        max?: number;
+        ttl?: number;
+    });
+    /**
+     * Check if key exists and return cached result
+     */
+    get<T>(key: string): IdempotentResult<T> | null;
+    /**
+     * Store result for idempotency key
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * Execute function with idempotency protection
+     */
+    execute<T>(key: string, fn: () => Promise<T>): Promise<IdempotentResult<T>>;
+    /**
+     * Clear a specific key
+     */
+    delete(key: string): void;
+    /**
+     * Clear all keys
+     */
+    clear(): void;
+    /**
+     * Get cache stats
+     */
+    stats(): {
+        size: number;
+        max: number;
+    };
+}
+/**
+ * Generate idempotency key for payroll operations
+ */
+declare function generatePayrollIdempotencyKey(organizationId: ObjectIdLike, employeeId: ObjectIdLike, month: number, year: number): string;
+
+export { IdempotencyManager as I, type IdempotentResult as a, generatePayrollIdempotencyKey as g };