@classytic/payroll 1.0.1 → 2.0.0

package/dist/core/index.d.ts

@@ -0,0 +1,480 @@
+export { C as CompensationChangedEventPayload, k as EmployeeHiredEventPayload, m as EmployeeRehiredEventPayload, l as EmployeeTerminatedEventPayload, E as EventBus, M as MilestoneAchievedEventPayload, N as NotificationPluginOptions, q as PayrollCompletedEventPayload, j as PayrollEventHandler, a as PayrollEventMap, i as PayrollEventType, s as PayrollExportedEventPayload, P as PayrollPluginDefinition, d as PluginContext, z as PluginHooks, y as PluginLogger, b as PluginManager, p as SalaryFailedEventPayload, n as SalaryProcessedEventPayload, S as SalaryUpdatedEventPayload, c as createEventBus, x as createNotificationPlugin, t as definePlugin, g as getEventBus, u as loggingPlugin, v as metricsPlugin, w as notificationPlugin, o as onEmployeeHired, h as onMilestoneAchieved, f as onPayrollCompleted, e as onSalaryProcessed, r as resetEventBus } from '../plugin-D9mOr3_d.js';
+import { Model, ClientSession } from 'mongoose';
+import { n as HRMConfig, S as SingleTenantConfig, o as Logger } from '../types-BSYyX2KJ.js';
+
+/**
+ * @classytic/payroll - Result Type
+ *
+ * Rust-inspired Result type for type-safe error handling
+ * No more try/catch everywhere - explicit error handling
+ */
+/** Success result */
+interface Ok<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/** Error result */
+interface Err<E> {
+    readonly ok: false;
+    readonly error: E;
+}
+/**
+ * Create a success result
+ */
+declare function ok<T>(value: T): Ok<T>;
+/**
+ * Create an error result
+ */
+declare function err<E>(error: E): Err<E>;
+/**
+ * Check if result is success
+ */
+declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
+/**
+ * Check if result is error
+ */
+declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
+/**
+ * Unwrap result value or throw error
+ */
+declare function unwrap<T, E>(result: Result<T, E>): T;
+/**
+ * Unwrap result value or return default
+ */
+declare function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+/**
+ * Unwrap result value or compute default
+ */
+declare function unwrapOrElse<T, E>(result: Result<T, E>, fn: (error: E) => T): T;
+/**
+ * Map success value
+ */
+declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+/**
+ * Map error value
+ */
+declare function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+/**
+ * FlatMap (chain) success value
+ */
+declare function flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+/**
+ * Try/catch wrapper for async functions
+ */
+declare function tryCatch<T, E = Error>(fn: () => Promise<T>, errorTransform?: (error: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Try/catch wrapper for sync functions
+ */
+declare function tryCatchSync<T, E = Error>(fn: () => T, errorTransform?: (error: unknown) => E): Result<T, E>;
+/**
+ * Combine multiple results into one
+ */
+declare function all<T, E>(results: Result<T, E>[]): Result<T[], E>;
+/**
+ * Pattern match on result
+ */
+declare function match<T, E, R>(result: Result<T, E>, handlers: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+}): R;
+/**
+ * Convert Promise<Result> to Result<Promise>
+ */
+declare function fromPromise<T, E = Error>(promise: Promise<T>, errorTransform?: (error: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Create Result from nullable value
+ */
+declare function fromNullable<T, E>(value: T | null | undefined, error: E): Result<T, E>;
+declare class ResultClass<T, E = Error> {
+    private readonly result;
+    private constructor();
+    static ok<T>(value: T): ResultClass<T, never>;
+    static err<E>(error: E): ResultClass<never, E>;
+    static fromAsync<T, E = Error>(fn: () => Promise<T>, errorTransform?: (error: unknown) => E): Promise<ResultClass<T, E>>;
+    isOk(): boolean;
+    isErr(): boolean;
+    unwrap(): T;
+    unwrapOr(defaultValue: T): T;
+    map<U>(fn: (value: T) => U): ResultClass<U, E>;
+    mapErr<F>(fn: (error: E) => F): ResultClass<T, F>;
+    flatMap<U>(fn: (value: T) => Result<U, E>): ResultClass<U, E>;
+    match<R>(handlers: {
+        ok: (value: T) => R;
+        err: (error: E) => R;
+    }): R;
+    toResult(): Result<T, E>;
+}
+/** Result type - either success or error */
+type Result<T, E = Error> = Ok<T> | Err<E>;
+declare const Result: {
+    ok: typeof ok;
+    err: typeof err;
+    isOk: typeof isOk;
+    isErr: typeof isErr;
+    unwrap: typeof unwrap;
+    unwrapOr: typeof unwrapOr;
+    unwrapOrElse: typeof unwrapOrElse;
+    map: typeof map;
+    mapErr: typeof mapErr;
+    flatMap: typeof flatMap;
+    tryCatch: typeof tryCatch;
+    tryCatchSync: typeof tryCatchSync;
+    all: typeof all;
+    match: typeof match;
+    fromPromise: typeof fromPromise;
+    fromNullable: typeof fromNullable;
+};
+
+/**
+ * @classytic/payroll - Dependency Container
+ *
+ * Simple dependency injection container for service management
+ * Enables clean dependency injection and testing
+ */
+
+interface ModelsContainer {
+    EmployeeModel: Model<any>;
+    PayrollRecordModel: Model<any>;
+    TransactionModel: Model<any>;
+    AttendanceModel?: Model<any> | null;
+}
+interface ContainerConfig {
+    models: ModelsContainer;
+    config?: Partial<HRMConfig>;
+    singleTenant?: SingleTenantConfig | null;
+    logger?: Logger;
+}
+declare class Container {
+    private static instance;
+    private _models;
+    private _config;
+    private _singleTenant;
+    private _logger;
+    private _initialized;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): Container;
+    /**
+     * Reset instance (for testing)
+     */
+    static resetInstance(): void;
+    /**
+     * Initialize container with configuration
+     */
+    initialize(config: ContainerConfig): void;
+    /**
+     * Check if container is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Ensure container is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Get models container
+     */
+    getModels(): ModelsContainer;
+    /**
+     * Get Employee model
+     */
+    getEmployeeModel(): Model<any>;
+    /**
+     * Get PayrollRecord model
+     */
+    getPayrollRecordModel(): Model<any>;
+    /**
+     * Get Transaction model
+     */
+    getTransactionModel(): Model<any>;
+    /**
+     * Get Attendance model (optional)
+     */
+    getAttendanceModel(): Model<any> | null;
+    /**
+     * Get configuration
+     */
+    getConfig(): HRMConfig;
+    /**
+     * Get specific config section
+     */
+    getConfigSection<K extends keyof HRMConfig>(section: K): HRMConfig[K];
+    /**
+     * Check if single-tenant mode
+     */
+    isSingleTenant(): boolean;
+    /**
+     * Get single-tenant config
+     */
+    getSingleTenantConfig(): SingleTenantConfig | null;
+    /**
+     * Get organization ID (for single-tenant mode)
+     */
+    getOrganizationId(): string | null;
+    /**
+     * Get logger
+     */
+    getLogger(): Logger;
+    /**
+     * Set logger
+     */
+    setLogger(logger: Logger): void;
+    /**
+     * Has attendance integration
+     */
+    hasAttendanceIntegration(): boolean;
+    /**
+     * Create operation context with defaults
+     */
+    createOperationContext(overrides?: Partial<{
+        userId: string;
+        userName: string;
+        userRole: string;
+        organizationId: string;
+        session: ClientSession;
+    }>): {
+        userId?: string;
+        userName?: string;
+        userRole?: string;
+        organizationId?: string;
+        session?: ClientSession;
+    };
+}
+/**
+ * Get container instance
+ */
+declare function getContainer(): Container;
+/**
+ * Initialize container
+ */
+declare function initializeContainer(config: ContainerConfig): void;
+/**
+ * Check if container is initialized
+ */
+declare function isContainerInitialized(): boolean;
+/**
+ * Get models from container
+ */
+declare function getModels(): ModelsContainer;
+/**
+ * Get config from container
+ */
+declare function getConfig(): HRMConfig;
+/**
+ * Check if single-tenant mode
+ */
+declare function isSingleTenant(): boolean;
+
+/**
+ * @classytic/payroll - Configuration & Calculation Utilities
+ *
+ * DESIGN PRINCIPLES:
+ * 1. Accept data, don't manage it
+ * 2. Pure functions - easy to test, no side effects
+ * 3. Smart defaults that work out of the box
+ * 4. Override at operation time when needed
+ *
+ * The payroll package CALCULATES, it doesn't STORE calendars/holidays.
+ * Your app manages that data and passes it when needed.
+ */
+/** Work schedule configuration */
+interface WorkSchedule {
+    /** Working days (0=Sun, 1=Mon, ..., 6=Sat). Default: Mon-Fri */
+    workDays: number[];
+    /** Hours per work day. Default: 8 */
+    hoursPerDay: number;
+}
+/** Options passed when processing payroll */
+interface PayrollProcessingOptions {
+    /** Holidays in this period (from YOUR app's holiday model) */
+    holidays?: Date[];
+    /** Override work schedule for this operation */
+    workSchedule?: Partial<WorkSchedule>;
+    /** Skip tax calculation */
+    skipTax?: boolean;
+    /** Skip proration (pay full amount regardless of hire/termination date) */
+    skipProration?: boolean;
+    /** Skip attendance deduction */
+    skipAttendance?: boolean;
+}
+/** Working days calculation result */
+interface WorkingDaysResult {
+    /** Total calendar days in period */
+    totalDays: number;
+    /** Working days (excluding weekends and holidays) */
+    workingDays: number;
+    /** Weekend days */
+    weekends: number;
+    /** Holiday count */
+    holidays: number;
+}
+/** Proration calculation result */
+interface ProrationResult {
+    /** Proration ratio (0-1) */
+    ratio: number;
+    /** Reason for proration */
+    reason: 'full' | 'new_hire' | 'termination' | 'both';
+    /** Whether salary should be prorated */
+    isProrated: boolean;
+}
+/** Tax calculation result */
+interface TaxResult {
+    /** Tax amount */
+    amount: number;
+    /** Effective tax rate */
+    effectiveRate: number;
+}
+/** Attendance data (from YOUR attendance system) */
+interface AttendanceInput {
+    /** Expected work days in period */
+    expectedDays: number;
+    /** Actual days worked */
+    actualDays: number;
+}
+/** Complete salary calculation result */
+interface SalaryCalculationResult {
+    /** Original base salary */
+    baseSalary: number;
+    /** Prorated base salary */
+    proratedBase: number;
+    /** Total allowances */
+    totalAllowances: number;
+    /** Total deductions (excluding tax) */
+    totalDeductions: number;
+    /** Attendance deduction */
+    attendanceDeduction: number;
+    /** Gross salary (prorated base + allowances) */
+    grossSalary: number;
+    /** Tax amount */
+    taxAmount: number;
+    /** Net salary (gross - all deductions - tax) */
+    netSalary: number;
+    /** Proration details */
+    proration: ProrationResult;
+    /** Working days details */
+    workingDays: WorkingDaysResult;
+    /** Itemized breakdown */
+    breakdown: {
+        allowances: Array<{
+            type: string;
+            amount: number;
+            taxable: boolean;
+        }>;
+        deductions: Array<{
+            type: string;
+            amount: number;
+        }>;
+    };
+}
+declare const COUNTRY_DEFAULTS: Record<string, {
+    currency: string;
+    workDays: number[];
+    taxBrackets: Array<{
+        min: number;
+        max: number;
+        rate: number;
+    }>;
+}>;
+declare const DEFAULT_WORK_SCHEDULE: WorkSchedule;
+declare const DEFAULT_TAX_BRACKETS: {
+    min: number;
+    max: number;
+    rate: number;
+}[];
+/**
+ * Count working days in a date range
+ *
+ * @example
+ * const result = countWorkingDays(
+ *   new Date('2024-03-01'),
+ *   new Date('2024-03-31'),
+ *   { workDays: [1,2,3,4,5], holidays: companyHolidays }
+ * );
+ */
+declare function countWorkingDays(startDate: Date, endDate: Date, options?: {
+    workDays?: number[];
+    holidays?: Date[];
+}): WorkingDaysResult;
+/**
+ * Calculate proration ratio for partial months
+ *
+ * @example
+ * const proration = calculateProration(
+ *   employee.hireDate,
+ *   employee.terminationDate,
+ *   periodStart,
+ *   periodEnd
+ * );
+ */
+declare function calculateProration(hireDate: Date, terminationDate: Date | null | undefined, periodStart: Date, periodEnd: Date): ProrationResult;
+/**
+ * Calculate tax using brackets (annualized)
+ *
+ * @example
+ * const tax = calculateTax(monthlyIncome, 'USD');
+ */
+declare function calculateTax(monthlyIncome: number, currency: string, customBrackets?: Array<{
+    min: number;
+    max: number;
+    rate: number;
+}>): TaxResult;
+/**
+ * Calculate attendance deduction
+ *
+ * @example
+ * const deduction = calculateAttendanceDeduction(22, 20, dailyRate);
+ */
+declare function calculateAttendanceDeduction(expectedDays: number, actualDays: number, dailyRate: number, maxDeductionPercent?: number): number;
+/**
+ * Calculate complete salary breakdown
+ *
+ * This is the main function for salary calculation.
+ * Pass all data from YOUR app, get back complete breakdown.
+ *
+ * @example
+ * const result = calculateSalaryBreakdown({
+ *   baseSalary: 100000,
+ *   currency: 'USD',
+ *   hireDate: employee.hireDate,
+ *   terminationDate: employee.terminationDate,
+ *   periodStart: new Date('2024-03-01'),
+ *   periodEnd: new Date('2024-03-31'),
+ *   allowances: [{ type: 'housing', amount: 20000, taxable: true }],
+ *   deductions: [{ type: 'provident_fund', amount: 5000 }],
+ *   options: { holidays: companyHolidays },
+ *   attendance: { expectedDays: 22, actualDays: 20 },
+ * });
+ */
+declare function calculateSalaryBreakdown(params: {
+    baseSalary: number;
+    currency: string;
+    hireDate: Date;
+    terminationDate?: Date | null;
+    periodStart: Date;
+    periodEnd: Date;
+    allowances?: Array<{
+        type: string;
+        amount: number;
+        taxable?: boolean;
+    }>;
+    deductions?: Array<{
+        type: string;
+        amount: number;
+    }>;
+    options?: PayrollProcessingOptions;
+    attendance?: AttendanceInput;
+}): SalaryCalculationResult;
+/**
+ * Get pay period dates for a given month
+ *
+ * @example
+ * const period = getPayPeriod(3, 2024); // March 2024
+ */
+declare function getPayPeriod(month: number, year: number, payDay?: number): {
+    startDate: Date;
+    endDate: Date;
+    payDate: Date;
+};
+
+export { type AttendanceInput, COUNTRY_DEFAULTS, Container, type ContainerConfig, DEFAULT_TAX_BRACKETS, DEFAULT_WORK_SCHEDULE, type Err, type ModelsContainer, type Ok, type PayrollProcessingOptions, type ProrationResult, Result, ResultClass, type SalaryCalculationResult, type TaxResult, type WorkSchedule, type WorkingDaysResult, all, calculateAttendanceDeduction, calculateProration, calculateSalaryBreakdown, calculateTax, countWorkingDays, err, flatMap, fromNullable, fromPromise, getConfig, getContainer, getModels, getPayPeriod, initializeContainer, isContainerInitialized, isErr, isOk, isSingleTenant, map, mapErr, match, ok, tryCatch, tryCatchSync, unwrap, unwrapOr, unwrapOrElse };