@classytic/payroll 2.0.0 → 2.3.0

package/dist/jurisdiction/index.d.ts

@@ -0,0 +1,660 @@
+/**
+ * @classytic/payroll - Multi-Jurisdiction Support
+ *
+ * DESIGN:
+ * - Pluggable jurisdiction rules (tax, overtime, leave, compliance)
+ * - Pure calculation functions
+ * - Smart defaults per country/state/province
+ * - Override at runtime when needed
+ *
+ * Your app passes jurisdiction code, we handle the calculations.
+ */
+type JurisdictionLevel = 'country' | 'state' | 'province' | 'city' | 'custom';
+interface JurisdictionIdentifier {
+    /** ISO country code (e.g., 'US', 'GB', 'BD', 'IN') */
+    country: string;
+    /** State/province code (e.g., 'CA', 'NY', 'ON') */
+    state?: string;
+    /** City/municipality code */
+    city?: string;
+    /** Custom jurisdiction identifier */
+    custom?: string;
+}
+interface TaxBracket {
+    min: number;
+    max: number;
+    rate: number;
+    /** Fixed amount for this bracket (some jurisdictions use fixed + %) */
+    fixedAmount?: number;
+}
+interface TaxConfiguration {
+    /** Income tax brackets (annual income) */
+    incomeTax: TaxBracket[];
+    /** Social security/pension tax rate */
+    socialSecurity?: {
+        employeeRate: number;
+        employerRate: number;
+        ceiling?: number;
+        floor?: number;
+    };
+    /** Medicare/health insurance tax */
+    medicare?: {
+        employeeRate: number;
+        employerRate: number;
+        additionalRate?: number;
+        additionalThreshold?: number;
+    };
+    /** Unemployment insurance */
+    unemployment?: {
+        employerRate: number;
+        ceiling?: number;
+    };
+    /** Other mandatory contributions */
+    otherContributions?: Array<{
+        name: string;
+        employeeRate?: number;
+        employerRate?: number;
+        ceiling?: number;
+    }>;
+    /** Tax-free allowances (annual) */
+    allowances?: {
+        personal: number;
+        dependent?: number;
+        pension?: number;
+    };
+    /** Standard deduction (annual) */
+    standardDeduction?: number;
+}
+interface TaxCalculationInput {
+    annualIncome: number;
+    jurisdiction: JurisdictionIdentifier;
+    dependents?: number;
+    customAllowances?: number;
+    pensionContribution?: number;
+}
+interface TaxCalculationResult {
+    /** Total income tax (annual) */
+    incomeTax: number;
+    /** Social security employee contribution (annual) */
+    socialSecurityEmployee: number;
+    /** Social security employer contribution (annual) */
+    socialSecurityEmployer: number;
+    /** Medicare employee (annual) */
+    medicareEmployee: number;
+    /** Medicare employer (annual) */
+    medicareEmployer: number;
+    /** Unemployment employer (annual) */
+    unemploymentEmployer: number;
+    /** Other contributions */
+    otherContributions: Array<{
+        name: string;
+        employeeAmount: number;
+        employerAmount: number;
+    }>;
+    /** Total employee tax burden (annual) */
+    totalEmployeeTax: number;
+    /** Total employer tax burden (annual) */
+    totalEmployerTax: number;
+    /** Effective tax rate */
+    effectiveRate: number;
+    /** Taxable income after allowances/deductions */
+    taxableIncome: number;
+}
+type OvertimeCalculationBasis = 'daily' | 'weekly' | 'biweekly' | 'monthly';
+interface OvertimeRule {
+    /** Hours threshold before overtime kicks in */
+    threshold: number;
+    /** Overtime multiplier (1.5 = time and a half) */
+    multiplier: number;
+    /** Basis for calculation */
+    basis: OvertimeCalculationBasis;
+    /** Maximum daily hours before double time */
+    doubleTimeThreshold?: number;
+    /** Double time multiplier */
+    doubleTimeMultiplier?: number;
+}
+interface OvertimeConfiguration {
+    /** Standard overtime rules */
+    standard: OvertimeRule;
+    /** Weekend overtime (if different) */
+    weekend?: OvertimeRule;
+    /** Holiday overtime */
+    holiday?: OvertimeRule;
+    /** Night shift differential */
+    nightShift?: {
+        startHour: number;
+        endHour: number;
+        multiplier: number;
+    };
+    /** Consecutive days worked bonus */
+    consecutiveDays?: {
+        threshold: number;
+        multiplier: number;
+    };
+}
+interface LeaveEntitlement {
+    /** Annual leave days per year */
+    annualLeave: {
+        days: number;
+        /** How it accrues */
+        accrual: 'monthly' | 'quarterly' | 'annual' | 'per-hour';
+        /** Accrual rate (days per period) */
+        accrualRate?: number;
+        /** Can it be carried forward */
+        carryForward: boolean;
+        /** Max carry forward days */
+        maxCarryForward?: number;
+    };
+    /** Sick leave */
+    sickLeave: {
+        days: number;
+        accrual: 'monthly' | 'quarterly' | 'annual' | 'unlimited';
+        accrualRate?: number;
+        /** Requires medical certificate after X days */
+        medicalCertificateAfter?: number;
+    };
+    /** Maternity leave */
+    maternityLeave?: {
+        days: number;
+        paidDays: number;
+        /** Percentage of salary paid */
+        paidPercentage: number;
+    };
+    /** Paternity leave */
+    paternityLeave?: {
+        days: number;
+        paidDays: number;
+        paidPercentage: number;
+    };
+    /** Public holidays (annual count) */
+    publicHolidays: number;
+    /** Bereavement leave */
+    bereavementLeave?: {
+        days: number;
+        paidDays: number;
+    };
+    /** Other statutory leaves */
+    otherLeaves?: Array<{
+        name: string;
+        days: number;
+        paidDays: number;
+        paidPercentage: number;
+    }>;
+}
+interface ComplianceRule {
+    /** Rule identifier */
+    id: string;
+    /** Rule name */
+    name: string;
+    /** Rule category */
+    category: 'wage' | 'hours' | 'leave' | 'termination' | 'benefits' | 'safety' | 'other';
+    /** Validation function */
+    validate: (data: EmploymentData) => ComplianceViolation[];
+}
+interface ComplianceViolation {
+    ruleId: string;
+    ruleName: string;
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    message: string;
+    /** Suggested remediation */
+    remediation?: string;
+    /** Monetary penalty (if applicable) */
+    penalty?: number;
+}
+interface EmploymentData {
+    baseSalary: number;
+    currency: string;
+    hoursWorked: number;
+    overtimeHours: number;
+    leaveBalance: {
+        annual: number;
+        sick: number;
+    };
+    hireDate: Date;
+    terminationDate?: Date;
+    [key: string]: any;
+}
+interface WageConfiguration {
+    /** Minimum wage (hourly) */
+    minimumWage: {
+        amount: number;
+        effectiveDate: Date;
+    };
+    /** Living wage (recommended, not mandated) */
+    livingWage?: {
+        amount: number;
+        effectiveDate: Date;
+    };
+    /** Pay frequency requirements */
+    payFrequency: {
+        allowed: Array<'daily' | 'weekly' | 'biweekly' | 'semimonthly' | 'monthly'>;
+        default: 'weekly' | 'biweekly' | 'semimonthly' | 'monthly';
+    };
+    /** Salary payment deadline */
+    paymentDeadline: {
+        /** Days after period end */
+        daysAfterPeriod: number;
+    };
+    /** Probation period rules */
+    probation?: {
+        maxDays: number;
+        /** Can salary be lower during probation */
+        allowReducedSalary: boolean;
+        /** Termination notice during probation */
+        terminationNoticeDays: number;
+    };
+}
+interface WorkingHoursConfiguration {
+    /** Standard work week */
+    standardWeek: {
+        hours: number;
+        days: number;
+    };
+    /** Maximum daily hours */
+    maxDailyHours: number;
+    /** Maximum weekly hours */
+    maxWeeklyHours: number;
+    /** Required breaks */
+    breaks: Array<{
+        afterHours: number;
+        durationMinutes: number;
+        paid: boolean;
+    }>;
+    /** Rest period between shifts */
+    restBetweenShifts: {
+        hours: number;
+    };
+    /** Weekly rest day requirement */
+    weeklyRestDays: {
+        days: number;
+        consecutive: boolean;
+    };
+}
+interface JurisdictionDefinition {
+    /** Jurisdiction identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Level (country, state, etc) */
+    level: JurisdictionLevel;
+    /** Parent jurisdiction (e.g., US for California) */
+    parent?: string;
+    /** Currency code */
+    currency: string;
+    /** Locale code */
+    locale: string;
+    /** Effective date */
+    effectiveFrom: Date;
+    /** End date (if jurisdiction rules changed) */
+    effectiveTo?: Date;
+    tax: TaxConfiguration;
+    overtime: OvertimeConfiguration;
+    leave: LeaveEntitlement;
+    wage: WageConfiguration;
+    workingHours: WorkingHoursConfiguration;
+    complianceRules: ComplianceRule[];
+    metadata?: {
+        /** Government authority */
+        authority?: string;
+        /** Reference laws */
+        laws?: string[];
+        /** Last updated */
+        lastUpdated: Date;
+        /** Maintained by */
+        maintainer?: string;
+    };
+}
+interface PaySlipData {
+    employee: {
+        id: string;
+        name: string;
+        position: string;
+        department?: string;
+        hireDate: Date;
+        taxId?: string;
+        socialSecurityNumber?: string;
+    };
+    employer: {
+        name: string;
+        address: string;
+        taxId?: string;
+        registrationNumber?: string;
+    };
+    period: {
+        start: Date;
+        end: Date;
+        payDate: Date;
+    };
+    earnings: {
+        basic: number;
+        allowances: Array<{
+            name: string;
+            amount: number;
+            taxable: boolean;
+        }>;
+        overtime: number;
+        bonuses: Array<{
+            name: string;
+            amount: number;
+            taxable: boolean;
+        }>;
+        other: Array<{
+            name: string;
+            amount: number;
+            taxable: boolean;
+        }>;
+    };
+    deductions: {
+        incomeTax: number;
+        socialSecurity: number;
+        medicare?: number;
+        providentFund?: number;
+        loans: Array<{
+            name: string;
+            amount: number;
+        }>;
+        advances: number;
+        other: Array<{
+            name: string;
+            amount: number;
+        }>;
+    };
+    totals: {
+        grossEarnings: number;
+        totalDeductions: number;
+        netPay: number;
+    };
+    yearToDate: {
+        grossEarnings: number;
+        incomeTax: number;
+        socialSecurity: number;
+        netPay: number;
+    };
+    bankDetails?: {
+        accountNumber: string;
+        bankName: string;
+        routingNumber?: string;
+    };
+}
+interface PaySlipTemplate {
+    jurisdiction: JurisdictionIdentifier;
+    format: 'pdf' | 'html' | 'json' | 'custom';
+    /** Required fields per jurisdiction */
+    requiredFields: string[];
+    /** Optional fields */
+    optionalFields?: string[];
+    /** Custom template function */
+    customRenderer?: (data: PaySlipData) => any;
+}
+interface StatutoryFilingRequirement {
+    /** Filing type */
+    type: 'monthly' | 'quarterly' | 'annual' | 'event-based';
+    /** Filing name */
+    name: string;
+    /** Due date calculation */
+    dueDate: (period: {
+        start: Date;
+        end: Date;
+    }) => Date;
+    /** Required data */
+    requiredData: string[];
+    /** Generate filing data */
+    generateData: (employees: any[], period: {
+        start: Date;
+        end: Date;
+    }) => any;
+    /** Validation rules */
+    validate?: (data: any) => ComplianceViolation[];
+}
+interface FilingCalendar {
+    jurisdiction: JurisdictionIdentifier;
+    filings: StatutoryFilingRequirement[];
+}
+
+/**
+ * @classytic/payroll - Jurisdiction Registry
+ *
+ * Pluggable jurisdiction system. Register custom jurisdictions at runtime.
+ */
+
+declare class JurisdictionRegistry {
+    private jurisdictions;
+    /**
+     * Register a jurisdiction
+     */
+    register(jurisdiction: JurisdictionDefinition): void;
+    /**
+     * Register multiple jurisdictions
+     */
+    registerMany(jurisdictions: JurisdictionDefinition[]): void;
+    /**
+     * Get jurisdiction by identifier
+     */
+    get(identifier: JurisdictionIdentifier): JurisdictionDefinition | undefined;
+    /**
+     * Get jurisdiction with fallback to parent
+     */
+    getWithFallback(identifier: JurisdictionIdentifier): JurisdictionDefinition | undefined;
+    /**
+     * Check if jurisdiction is registered
+     */
+    has(identifier: JurisdictionIdentifier): boolean;
+    /**
+     * Get all jurisdictions for a country
+     */
+    getByCountry(countryCode: string): JurisdictionDefinition[];
+    /**
+     * Get all registered jurisdictions
+     */
+    getAll(): JurisdictionDefinition[];
+    /**
+     * Remove a jurisdiction
+     */
+    unregister(identifier: JurisdictionIdentifier): boolean;
+    /**
+     * Clear all jurisdictions
+     */
+    clear(): void;
+    /**
+     * Get registry size
+     */
+    size(): number;
+    private makeKey;
+    private makeKeyFromId;
+    private makeKeyFromIdentifier;
+    private validate;
+}
+declare const jurisdictionRegistry: JurisdictionRegistry;
+/**
+ * Register a jurisdiction
+ */
+declare function registerJurisdiction(jurisdiction: JurisdictionDefinition): void;
+/**
+ * Register multiple jurisdictions
+ */
+declare function registerJurisdictions(jurisdictions: JurisdictionDefinition[]): void;
+/**
+ * Get jurisdiction
+ */
+declare function getJurisdiction(identifier: JurisdictionIdentifier): JurisdictionDefinition | undefined;
+/**
+ * Get jurisdiction (throws if not found)
+ */
+declare function requireJurisdiction(identifier: JurisdictionIdentifier): JurisdictionDefinition;
+/**
+ * Check if jurisdiction exists
+ */
+declare function hasJurisdiction(identifier: JurisdictionIdentifier): boolean;
+/**
+ * Get all jurisdictions for a country
+ */
+declare function getJurisdictionsByCountry(countryCode: string): JurisdictionDefinition[];
+
+/**
+ * @classytic/payroll - Jurisdiction-Aware Tax Calculator
+ *
+ * Pure functions for calculating taxes using jurisdiction-specific rules.
+ */
+
+/**
+ * Calculate comprehensive tax for an employee
+ *
+ * @example
+ * ```typescript
+ * const result = calculateJurisdictionTax({
+ *   annualIncome: 100000,
+ *   jurisdiction: { country: 'US', state: 'CA' },
+ *   dependents: 2,
+ * });
+ *
+ * console.log(result.totalEmployeeTax); // Total tax burden
+ * console.log(result.effectiveRate);    // Effective tax rate
+ * ```
+ */
+declare function calculateJurisdictionTax(input: TaxCalculationInput): TaxCalculationResult;
+/**
+ * Calculate monthly tax (convenience wrapper)
+ */
+declare function calculateMonthlyTax(monthlyIncome: number, jurisdiction: JurisdictionIdentifier, options?: {
+    dependents?: number;
+    customAllowances?: number;
+    pensionContribution?: number;
+}): {
+    monthlyIncomeTax: number;
+    monthlySocialSecurity: number;
+    monthlyMedicare: number;
+    monthlyTotal: number;
+    effectiveRate: number;
+};
+/**
+ * Compare tax burden across multiple jurisdictions
+ */
+declare function compareTaxBurden(annualIncome: number, jurisdictions: JurisdictionIdentifier[]): Array<{
+    jurisdiction: JurisdictionIdentifier;
+    jurisdictionName: string;
+    result: TaxCalculationResult;
+}>;
+
+/**
+ * @classytic/payroll - Labor Law Compliance Checker
+ *
+ * Validates employment data against jurisdiction-specific labor laws.
+ */
+
+/**
+ * Check compliance for an employee
+ *
+ * @example
+ * ```typescript
+ * const violations = checkCompliance({
+ *   baseSalary: 2500,
+ *   currency: 'USD',
+ *   hoursWorked: 45,
+ *   jurisdiction: { country: 'US', state: 'CA' },
+ * });
+ *
+ * if (violations.length > 0) {
+ *   console.log('Compliance issues found:', violations);
+ * }
+ * ```
+ */
+declare function checkCompliance(data: EmploymentData, jurisdiction: JurisdictionIdentifier): ComplianceViolation[];
+/**
+ * Check multiple employees for compliance
+ */
+declare function checkBulkCompliance(employees: Array<EmploymentData & {
+    jurisdiction: JurisdictionIdentifier;
+}>, options?: {
+    severityFilter?: ComplianceViolation['severity'][];
+    categoryFilter?: string[];
+}): Array<{
+    employee: EmploymentData;
+    violations: ComplianceViolation[];
+}>;
+/**
+ * Generate compliance report for an organization
+ */
+declare function generateComplianceReport(employees: Array<EmploymentData & {
+    jurisdiction: JurisdictionIdentifier;
+    id: string;
+    name: string;
+}>, options?: {
+    includeCompliant?: boolean;
+    groupByJurisdiction?: boolean;
+}): {
+    summary: {
+        totalEmployees: number;
+        compliantEmployees: number;
+        violationCount: number;
+        criticalViolations: number;
+        highViolations: number;
+        mediumViolations: number;
+        lowViolations: number;
+    };
+    violations: Array<{
+        employeeId: string;
+        employeeName: string;
+        jurisdiction: string;
+        violations: ComplianceViolation[];
+    }>;
+    byJurisdiction?: Map<string, {
+        employeeCount: number;
+        violationCount: number;
+        violations: ComplianceViolation[];
+    }>;
+};
+
+/**
+ * Create a jurisdiction definition with type safety
+ *
+ * @example
+ * ```typescript
+ * const myJurisdiction = createJurisdictionDefinition({
+ *   id: 'US',
+ *   name: 'United States',
+ *   level: 'country',
+ *   currency: 'USD',
+ *   locale: 'en-US',
+ *   effectiveFrom: new Date('2024-01-01'),
+ *   tax: { ... },
+ *   overtime: { ... },
+ *   leave: { ... },
+ *   wage: { ... },
+ *   workingHours: { ... },
+ *   complianceRules: [],
+ * });
+ *
+ * registerJurisdiction(myJurisdiction);
+ * ```
+ */
+declare function createJurisdictionDefinition(definition: JurisdictionDefinition): JurisdictionDefinition;
+/**
+ * Helper to extend an existing jurisdiction (e.g., create a state from a country)
+ *
+ * @example
+ * ```typescript
+ * import { extendJurisdiction } from '@classytic/payroll/jurisdiction';
+ *
+ * // First get your base country jurisdiction (from your data)
+ * const usFederal = getJurisdiction({ country: 'US' });
+ *
+ * // Extend it for a state
+ * const california = extendJurisdiction(usFederal!, {
+ *   id: 'US:CA',
+ *   name: 'California',
+ *   parent: 'US',
+ *   level: 'state',
+ *   wage: {
+ *     minimumWage: { amount: 16, effectiveDate: new Date('2024-01-01') },
+ *   },
+ * });
+ *
+ * registerJurisdiction(california);
+ * ```
+ */
+declare function extendJurisdiction(base: JurisdictionDefinition, overrides: Partial<JurisdictionDefinition> & {
+    id: string;
+    name: string;
+}): JurisdictionDefinition;
+
+export { type ComplianceRule, type ComplianceViolation, type EmploymentData, type FilingCalendar, type JurisdictionDefinition, type JurisdictionIdentifier, type JurisdictionLevel, type LeaveEntitlement, type OvertimeCalculationBasis, type OvertimeConfiguration, type OvertimeRule, type PaySlipData, type PaySlipTemplate, type StatutoryFilingRequirement, type TaxBracket, type TaxCalculationInput, type TaxCalculationResult, type TaxConfiguration, type WageConfiguration, type WorkingHoursConfiguration, calculateJurisdictionTax, calculateMonthlyTax, checkBulkCompliance, checkCompliance, compareTaxBurden, createJurisdictionDefinition, extendJurisdiction, generateComplianceReport, getJurisdiction, getJurisdictionsByCountry, hasJurisdiction, jurisdictionRegistry, registerJurisdiction, registerJurisdictions, requireJurisdiction };