@classytic/payroll 1.0.2 → 2.3.0

package/dist/shift-compliance/index.d.ts

@@ -0,0 +1,1171 @@
+import { O as ObjectIdLike } from '../types-BN3K_Uhr.js';
+import * as mongoose from 'mongoose';
+import { Schema, SchemaDefinition } from 'mongoose';
+
+/**
+ * @classytic/payroll - Shift Compliance Types
+ *
+ * Clean, modern type definitions for shift-based attendance management.
+ * No legacy baggage - one proper standard.
+ */
+
+/** How penalties are calculated */
+type PenaltyMode = 'flat' | 'per-minute' | 'percentage' | 'tiered';
+/** When overtime kicks in */
+type OvertimeMode = 'daily' | 'weekly' | 'monthly';
+/** When to reset occurrence counters */
+type ResetPeriod = 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly';
+/** Clock-in rounding mode */
+type RoundingMode = 'nearest' | 'up' | 'down';
+/**
+ * Tiered penalty configuration for progressive discipline.
+ *
+ * @example
+ * ```typescript
+ * [
+ *   { from: 1, to: 2, penalty: 0, warning: true },  // 1st-2nd: warning only
+ *   { from: 3, to: 4, penalty: 25 },                 // 3rd-4th: $25
+ *   { from: 5, penalty: 50 }                         // 5th+: $50
+ * ]
+ * ```
+ */
+interface PenaltyTier {
+    /** Occurrence number start (inclusive) */
+    from: number;
+    /** Occurrence number end (inclusive, optional for open-ended) */
+    to?: number;
+    /** Penalty amount for this tier */
+    penalty: number;
+    /** If true, log warning but don't deduct money */
+    warning?: boolean;
+}
+/**
+ * Maximum penalties per period configuration
+ */
+interface MaxPenaltiesPerPeriod {
+    /** Maximum number of penalties allowed */
+    count: number;
+    /** Period type */
+    period: ResetPeriod;
+}
+/**
+ * Weekend premium configuration
+ */
+interface WeekendPremium {
+    /** Saturday premium multiplier (e.g., 1.5 for time-and-a-half) */
+    saturday: number;
+    /** Sunday premium multiplier (e.g., 2.0 for double time) */
+    sunday: number;
+}
+/**
+ * Night shift differential configuration
+ */
+interface NightShiftDifferential {
+    /** Start hour (24h format, e.g., 22 = 10pm) */
+    startHour: number;
+    /** End hour (24h format, e.g., 6 = 6am) */
+    endHour: number;
+    /** Premium multiplier (e.g., 1.2 = 20% extra) */
+    multiplier: number;
+}
+/**
+ * Late arrival policy configuration
+ */
+interface LateArrivalPolicy {
+    /** Enable late arrival tracking */
+    enabled: boolean;
+    /** Grace period in minutes (no penalty if late < this) */
+    gracePeriod: number;
+    /** How to calculate penalty */
+    mode: PenaltyMode;
+    /** Fixed penalty amount per occurrence */
+    flatAmount?: number;
+    /** Penalty per minute late */
+    perMinuteRate?: number;
+    /** Penalty as percentage of daily wage (e.g., 2 = 2%) */
+    percentageRate?: number;
+    /** Progressive penalties based on occurrence count */
+    tiers?: PenaltyTier[];
+    /** Maximum penalties allowed per period */
+    maxPenaltiesPerPeriod?: MaxPenaltiesPerPeriod;
+    /** Maximum total penalty amount per period */
+    maxPenaltyAmount?: {
+        amount: number;
+        period: ResetPeriod;
+    };
+    /** When to reset occurrence counter */
+    resetOccurrenceCount?: ResetPeriod;
+}
+/**
+ * Early departure policy configuration
+ * (Same structure as late arrival)
+ */
+type EarlyDeparturePolicy = LateArrivalPolicy;
+/**
+ * Overtime bonus configuration
+ */
+interface OvertimePolicy {
+    /** Enable overtime bonuses */
+    enabled: boolean;
+    /** When overtime kicks in */
+    mode: OvertimeMode;
+    /** Hours per day before overtime (e.g., 8) */
+    dailyThreshold?: number;
+    /** Overtime multiplier for daily (e.g., 1.5 = time and half) */
+    dailyMultiplier?: number;
+    /** Hours per week before overtime (e.g., 40) */
+    weeklyThreshold?: number;
+    /** Overtime multiplier for weekly */
+    weeklyMultiplier?: number;
+    /** Hours per month before overtime (e.g., 160) */
+    monthlyThreshold?: number;
+    /** Overtime multiplier for monthly */
+    monthlyMultiplier?: number;
+    /** Weekend premium pay (null = disabled) */
+    weekendPremium?: WeekendPremium;
+    /** Night shift premium (null = disabled) */
+    nightShiftDifferential?: NightShiftDifferential;
+}
+/**
+ * Clock-in rounding configuration
+ */
+interface ClockRoundingPolicy {
+    /** Enable clock-in rounding */
+    enabled: boolean;
+    /** Round to nearest X minutes */
+    roundTo: 5 | 10 | 15;
+    /** Rounding mode */
+    mode: RoundingMode;
+}
+/**
+ * Complete attendance policy configuration.
+ *
+ * This is what organizations define and what we use for calculations.
+ * Users can store this in DB, config file, or pass directly.
+ */
+interface AttendancePolicy {
+    /** Unique policy ID (optional, for DB storage) */
+    id?: string;
+    /** Organization this policy belongs to (optional, for multi-tenant) */
+    organizationId?: ObjectIdLike;
+    /** Policy name for display */
+    name: string;
+    /** Policy description */
+    description?: string;
+    /** Who this policy applies to (optional, for targeted policies) */
+    appliesTo?: {
+        departments?: string[];
+        positions?: string[];
+        employeeIds?: ObjectIdLike[];
+        all?: boolean;
+    };
+    /** Late arrival rules */
+    lateArrival: LateArrivalPolicy;
+    /** Early departure rules */
+    earlyDeparture: EarlyDeparturePolicy;
+    /** Overtime bonus rules */
+    overtime: OvertimePolicy;
+    /** Clock-in rounding rules */
+    clockRounding?: ClockRoundingPolicy;
+    /** When this policy becomes effective */
+    effectiveFrom: Date;
+    /** When this policy expires (null = no expiry) */
+    effectiveTo?: Date | null;
+    /** Is this policy active */
+    active: boolean;
+}
+/**
+ * Single late arrival occurrence
+ */
+interface LateOccurrence {
+    /** Date of late arrival */
+    date: Date;
+    /** Scheduled clock-in time */
+    scheduledTime: Date;
+    /** Actual clock-in time */
+    actualTime: Date;
+    /** Minutes late (calculated: actual - scheduled) */
+    minutesLate: number;
+}
+/**
+ * Single early departure occurrence
+ */
+interface EarlyOccurrence {
+    /** Date of early departure */
+    date: Date;
+    /** Scheduled clock-out time */
+    scheduledTime: Date;
+    /** Actual clock-out time */
+    actualTime: Date;
+    /** Minutes early (calculated: scheduled - actual) */
+    minutesEarly: number;
+}
+/**
+ * Single overtime occurrence
+ */
+interface OvertimeOccurrence {
+    /** Date of overtime */
+    date: Date;
+    /** Type of overtime */
+    type: 'daily' | 'weekly' | 'monthly' | 'weekend-saturday' | 'weekend-sunday' | 'night-shift';
+    /** Overtime hours */
+    hours: number;
+    /** Applicable multiplier */
+    multiplier: number;
+}
+/**
+ * Shift compliance data for a period.
+ *
+ * This is what users send us - we do the calculations.
+ */
+interface ShiftComplianceData {
+    /** Number of late arrivals */
+    lateArrivals?: number;
+    /** Total minutes late (sum of all occurrences) */
+    totalLateMinutes?: number;
+    /** Detailed late occurrences (optional, for breakdown) */
+    lateOccurrences?: LateOccurrence[];
+    /** Number of early departures */
+    earlyDepartures?: number;
+    /** Total minutes early */
+    totalEarlyMinutes?: number;
+    /** Detailed early occurrences */
+    earlyOccurrences?: EarlyOccurrence[];
+    /** Total overtime hours */
+    overtimeHours?: number;
+    /** Total overtime days (for daily mode) */
+    overtimeDays?: number;
+    /** Detailed overtime breakdown */
+    overtimeOccurrences?: OvertimeOccurrence[];
+}
+/**
+ * Late penalty calculation result
+ */
+interface LatePenaltyResult {
+    /** Total penalty amount */
+    amount: number;
+    /** Number of occurrences processed */
+    occurrences: number;
+    /** Breakdown per occurrence */
+    breakdown: Array<{
+        date: Date;
+        minutesLate: number;
+        penaltyAmount: number;
+        tier?: number;
+        waived: boolean;
+        reason?: string;
+    }>;
+}
+/**
+ * Early departure penalty result
+ */
+type EarlyDeparturePenaltyResult = LatePenaltyResult;
+/**
+ * Overtime bonus calculation result
+ */
+interface OvertimeBonusResult {
+    /** Total bonus amount */
+    amount: number;
+    /** Total overtime hours */
+    hours: number;
+    /** Breakdown by type */
+    breakdown: Array<{
+        date: Date;
+        type: string;
+        hours: number;
+        rate: number;
+        multiplier: number;
+        amount: number;
+    }>;
+}
+/**
+ * Shift differential calculation result
+ */
+interface ShiftDifferentialResult {
+    /** Total differential amount */
+    amount: number;
+    /** Hours that qualify for differential */
+    hours: number;
+    /** Type of differential */
+    type: 'night' | 'weekend';
+    /** Multiplier applied */
+    multiplier: number;
+}
+/**
+ * Complete shift compliance calculation result.
+ *
+ * This is what we return after processing.
+ */
+interface ShiftComplianceResult {
+    /** Late arrival penalties */
+    latePenalty: LatePenaltyResult;
+    /** Early departure penalties */
+    earlyDeparturePenalty: EarlyDeparturePenaltyResult;
+    /** Overtime bonuses */
+    overtimeBonus: OvertimeBonusResult;
+    /** Shift differential bonuses (if any) */
+    shiftDifferential?: ShiftDifferentialResult;
+    /** Total penalties (to deduct from salary) */
+    totalPenalties: number;
+    /** Total bonuses (to add to salary) */
+    totalBonuses: number;
+    /** Net adjustment (bonuses - penalties) */
+    netAdjustment: number;
+    /** Compliance score (0-100) */
+    complianceScore: number;
+    /** Total occurrence count (late + early) */
+    occurrenceCount: number;
+    /** Is employee at risk (near termination threshold) */
+    isAtRisk: boolean;
+    /** Policy ID that was used */
+    policyId?: string;
+    /** Policy name */
+    policyName: string;
+}
+/**
+ * Input for shift compliance calculation
+ */
+interface CalculateShiftComplianceInput {
+    /** Attendance data for the period */
+    attendance: ShiftComplianceData;
+    /** Policy to apply */
+    policy: AttendancePolicy;
+    /** Daily wage (for percentage-based penalties) */
+    dailyWage: number;
+    /** Hourly rate (for overtime calculations) */
+    hourlyRate: number;
+    /** Current occurrence count (for tiered penalties, optional) */
+    currentOccurrenceCount?: number;
+    /** Employee ID (for logging, optional) */
+    employeeId?: ObjectIdLike;
+    /** Period info (for logging, optional) */
+    period?: {
+        month: number;
+        year: number;
+    };
+}
+/**
+ * Manager override for waiving penalties
+ */
+interface PenaltyOverride {
+    /** Which penalty to override */
+    penaltyId: string;
+    /** Employee affected */
+    employeeId: ObjectIdLike;
+    /** Manager who made the override */
+    overriddenBy: ObjectIdLike;
+    /** When the override was made */
+    overriddenAt: Date;
+    /** Original penalty amount */
+    originalAmount: number;
+    /** New amount (0 = fully waived) */
+    newAmount: number;
+    /** Reason for override */
+    reason: string;
+    /** Does this need approval */
+    approvalRequired?: boolean;
+    /** Who approved (if approval required) */
+    approvedBy?: ObjectIdLike;
+    /** When approved */
+    approvedAt?: Date;
+}
+
+/**
+ * @classytic/payroll - Late Penalty Calculator
+ *
+ * Pure functions for calculating late arrival penalties.
+ * No side effects, no DB calls - just math.
+ */
+
+/**
+ * Calculate penalty using flat rate per occurrence
+ *
+ * @example
+ * ```typescript
+ * // $50 per late occurrence
+ * const result = calculateFlatPenalty(3, 50);
+ * // → { amount: 150, occurrences: 3 }
+ * ```
+ */
+declare function calculateFlatPenalty(occurrenceCount: number, flatAmount: number): {
+    amount: number;
+    occurrences: number;
+};
+/**
+ * Calculate penalty based on minutes late
+ *
+ * @example
+ * ```typescript
+ * // $2 per minute, 45 minutes late
+ * const result = calculatePerMinutePenalty(45, 2);
+ * // → { amount: 90, minutes: 45 }
+ * ```
+ */
+declare function calculatePerMinutePenalty(totalMinutesLate: number, perMinuteRate: number): {
+    amount: number;
+    minutes: number;
+};
+/**
+ * Calculate penalty as percentage of daily wage
+ *
+ * @example
+ * ```typescript
+ * // 2% of $500 daily wage, 3 late occurrences
+ * const result = calculatePercentagePenalty(3, 2, 500);
+ * // → { amount: 30, percentage: 2 }
+ * ```
+ */
+declare function calculatePercentagePenalty(occurrenceCount: number, percentageRate: number, dailyWage: number): {
+    amount: number;
+    percentage: number;
+};
+/**
+ * Calculate total tiered penalties for multiple occurrences
+ *
+ * @example
+ * ```typescript
+ * const tiers = [
+ *   { from: 1, to: 2, penalty: 0, warning: true },
+ *   { from: 3, to: 4, penalty: 25 },
+ *   { from: 5, penalty: 50 },
+ * ];
+ *
+ * // Employee has 5 late occurrences
+ * const result = calculateTieredPenalty(5, 2, tiers);
+ * // → {
+ * //   amount: 125,  // 0 + 0 + 25 + 25 + 50
+ * //   breakdown: [...]
+ * // }
+ * ```
+ */
+declare function calculateTieredPenalty(newOccurrences: number, currentOccurrenceCount: number, tiers: PenaltyTier[]): {
+    amount: number;
+    breakdown: Array<{
+        occurrence: number;
+        penalty: number;
+        tier?: number;
+        warning: boolean;
+    }>;
+};
+/**
+ * Calculate late arrival penalties based on policy
+ *
+ * @example
+ * ```typescript
+ * const policy: LateArrivalPolicy = {
+ *   enabled: true,
+ *   gracePeriod: 5,
+ *   mode: 'flat',
+ *   flatAmount: 50,
+ * };
+ *
+ * const occurrences: LateOccurrence[] = [
+ *   { date: new Date(), scheduledTime, actualTime, minutesLate: 10 },
+ *   { date: new Date(), scheduledTime, actualTime, minutesLate: 3 },  // Within grace
+ * ];
+ *
+ * const result = calculateLatePenalty({
+ *   policy,
+ *   occurrences,
+ *   dailyWage: 500,
+ * });
+ * // → { amount: 50, occurrences: 1, breakdown: [...] }
+ * ```
+ */
+declare function calculateLatePenalty(input: {
+    policy: LateArrivalPolicy;
+    occurrences?: LateOccurrence[];
+    lateCount?: number;
+    totalLateMinutes?: number;
+    dailyWage?: number;
+    currentOccurrenceCount?: number;
+}): LatePenaltyResult;
+
+/**
+ * @classytic/payroll - Overtime Calculator
+ *
+ * Pure functions for calculating overtime bonuses.
+ * No side effects, no DB calls - just math.
+ */
+
+/**
+ * Calculate daily overtime bonus
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 10 hours, threshold is 8, rate is $100/hour
+ * const result = calculateDailyOvertime(10, 8, 1.5, 100);
+ * // → { amount: 100, overtimeHours: 2 }
+ * // Calculation: 2 hours × $100 × 0.5 (extra) = $100
+ * ```
+ */
+declare function calculateDailyOvertime(hoursWorked: number, threshold: number, multiplier: number, hourlyRate: number): {
+    amount: number;
+    overtimeHours: number;
+};
+/**
+ * Calculate weekly overtime bonus
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 45 hours, threshold is 40, rate is $100/hour
+ * const result = calculateWeeklyOvertime(45, 40, 1.5, 100);
+ * // → { amount: 250, overtimeHours: 5 }
+ * ```
+ */
+declare function calculateWeeklyOvertime(hoursWorked: number, threshold: number, multiplier: number, hourlyRate: number): {
+    amount: number;
+    overtimeHours: number;
+};
+/**
+ * Calculate monthly overtime bonus
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 170 hours, threshold is 160
+ * const result = calculateMonthlyOvertime(170, 160, 1.5, 100);
+ * // → { amount: 500, overtimeHours: 10 }
+ * ```
+ */
+declare function calculateMonthlyOvertime(hoursWorked: number, threshold: number, multiplier: number, hourlyRate: number): {
+    amount: number;
+    overtimeHours: number;
+};
+/**
+ * Calculate weekend premium pay
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 8 hours on Saturday
+ * const result = calculateWeekendPremium(8, 1.5, 100, 'saturday');
+ * // → { amount: 400, hours: 8 }
+ * // Regular: 8 × $100 = $800
+ * // Premium: 8 × $100 × 0.5 (extra) = $400
+ * ```
+ */
+declare function calculateWeekendPremium(hours: number, multiplier: number, hourlyRate: number, day: 'saturday' | 'sunday'): {
+    amount: number;
+    hours: number;
+    day: string;
+};
+/**
+ * Calculate night shift differential
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 8 hours during night shift (10pm-6am)
+ * const result = calculateNightShiftDifferential(8, 1.2, 100);
+ * // → { amount: 160, hours: 8 }
+ * // Differential: 8 × $100 × 0.2 (extra) = $160
+ * ```
+ */
+declare function calculateNightShiftDifferential(hours: number, multiplier: number, hourlyRate: number): {
+    amount: number;
+    hours: number;
+};
+/**
+ * Calculate all overtime bonuses based on policy
+ *
+ * @example
+ * ```typescript
+ * const policy: OvertimePolicy = {
+ *   enabled: true,
+ *   mode: 'daily',
+ *   dailyThreshold: 8,
+ *   dailyMultiplier: 1.5,
+ * };
+ *
+ * const occurrences: OvertimeOccurrence[] = [
+ *   { date: new Date(), type: 'daily', hours: 2, multiplier: 1.5 },
+ *   { date: new Date(), type: 'weekend-sunday', hours: 8, multiplier: 2.0 },
+ * ];
+ *
+ * const result = calculateOvertimeBonus({
+ *   policy,
+ *   occurrences,
+ *   hourlyRate: 100,
+ * });
+ * ```
+ */
+declare function calculateOvertimeBonus(input: {
+    policy: OvertimePolicy;
+    occurrences?: OvertimeOccurrence[];
+    overtimeHours?: number;
+    overtimeDays?: number;
+    hourlyRate: number;
+}): OvertimeBonusResult;
+
+/**
+ * @classytic/payroll - Shift Compliance Calculators
+ *
+ * Main calculator that orchestrates all shift compliance calculations.
+ */
+
+/**
+ * Calculate complete shift compliance adjustments.
+ *
+ * This is the main function users call. It takes attendance data + policy
+ * and returns penalties + bonuses.
+ *
+ * @example
+ * ```typescript
+ * const attendance: ShiftComplianceData = {
+ *   lateArrivals: 3,
+ *   totalLateMinutes: 45,
+ *   earlyDepartures: 1,
+ *   totalEarlyMinutes: 20,
+ *   overtimeHours: 8,
+ * };
+ *
+ * const policy: AttendancePolicy = {
+ *   name: 'Manufacturing Policy',
+ *   lateArrival: {
+ *     enabled: true,
+ *     gracePeriod: 0,
+ *     mode: 'flat',
+ *     flatAmount: 50,
+ *   },
+ *   earlyDeparture: {
+ *     enabled: true,
+ *     gracePeriod: 0,
+ *     mode: 'flat',
+ *     flatAmount: 75,
+ *   },
+ *   overtime: {
+ *     enabled: true,
+ *     mode: 'daily',
+ *     dailyThreshold: 8,
+ *     dailyMultiplier: 1.5,
+ *   },
+ *   effectiveFrom: new Date(),
+ *   active: true,
+ * };
+ *
+ * const result = calculateShiftCompliance({
+ *   attendance,
+ *   policy,
+ *   dailyWage: 1500,
+ *   hourlyRate: 200,
+ * });
+ *
+ * // result = {
+ * //   latePenalty: { amount: 150, ... },
+ * //   earlyDeparturePenalty: { amount: 75, ... },
+ * //   overtimeBonus: { amount: 800, ... },
+ * //   totalPenalties: 225,
+ * //   totalBonuses: 800,
+ * //   netAdjustment: 575,  // +800 - 225
+ * //   ...
+ * // }
+ * ```
+ */
+declare function calculateShiftCompliance(input: CalculateShiftComplianceInput): ShiftComplianceResult;
+
+/**
+ * @classytic/payroll - Shift Compliance Configuration
+ *
+ * Default configurations and industry-standard preset policies.
+ */
+
+/**
+ * Default attendance policy (moderate, office-friendly)
+ */
+declare const DEFAULT_ATTENDANCE_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Manufacturing/Factory policy (strict, zero tolerance)
+ */
+declare const MANUFACTURING_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Retail policy (flexible with weekend premiums)
+ */
+declare const RETAIL_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Office/Tech policy (very flexible, progressive discipline)
+ */
+declare const OFFICE_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Healthcare policy (night shift differential, weekend premiums)
+ */
+declare const HEALTHCARE_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Hospitality policy (flexible, weekend/night premiums)
+ */
+declare const HOSPITALITY_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Get a complete policy from a preset
+ *
+ * @example
+ * ```typescript
+ * const policy = createPolicyFromPreset('manufacturing', {
+ *   name: 'Factory Floor Policy',
+ *   organizationId: orgId,
+ * });
+ * ```
+ */
+declare function createPolicyFromPreset(preset: 'default' | 'manufacturing' | 'retail' | 'office' | 'healthcare' | 'hospitality', overrides?: Partial<AttendancePolicy>): AttendancePolicy;
+
+/**
+ * @classytic/payroll - Shift Compliance Fluent Builders
+ *
+ * DX-friendly fluent API for creating attendance policies programmatically.
+ *
+ * @example
+ * ```typescript
+ * const policy = AttendancePolicyBuilder.create()
+ *   .named('Tech Department Policy')
+ *   .description('Flexible policy for tech workers')
+ *   .lateArrival()
+ *     .enable()
+ *     .gracePeriod(15)
+ *     .tieredPenalty()
+ *       .tier(1, 3).warning()
+ *       .tier(4, 5).penalty(20)
+ *       .tier(6).penalty(40)
+ *     .end()
+ *     .maxPenalties(3, 'monthly')
+ *     .resetOccurrences('quarterly')
+ *   .end()
+ *   .overtime()
+ *     .enable()
+ *     .mode('weekly')
+ *     .weeklyThreshold(40, 1.5)
+ *   .end()
+ *   .build();
+ * ```
+ */
+
+/**
+ * Builder for late arrival or early departure policies.
+ * Uses same structure for both since the logic is identical.
+ */
+declare class LatePolicyBuilder<TParent = unknown> {
+    private policy;
+    private parent?;
+    constructor(parent?: TParent);
+    /**
+     * Enable this policy
+     */
+    enable(): this;
+    /**
+     * Disable this policy
+     */
+    disable(): this;
+    /**
+     * Set grace period in minutes (how many minutes late before penalty applies)
+     */
+    gracePeriod(minutes: number): this;
+    /**
+     * Use flat penalty mode (same penalty for each occurrence)
+     *
+     * @param amount - Penalty amount per occurrence
+     */
+    flatPenalty(amount: number): this;
+    /**
+     * Use per-minute penalty mode (penalty based on minutes late)
+     *
+     * @param rate - Penalty per minute late
+     */
+    perMinutePenalty(rate: number): this;
+    /**
+     * Use percentage penalty mode (percentage of daily wage)
+     *
+     * @param percentage - Percentage of daily wage (e.g., 2 for 2%)
+     */
+    percentagePenalty(percentage: number): this;
+    /**
+     * Start building tiered penalty (progressive discipline)
+     *
+     * @example
+     * ```typescript
+     * .tieredPenalty()
+     *   .tier(1, 2).warning()
+     *   .tier(3, 4).penalty(25)
+     *   .tier(5).penalty(50)
+     * .end()
+     * ```
+     */
+    tieredPenalty(): TieredPenaltyBuilder<this>;
+    /**
+     * Set maximum penalties per period (caps total penalties)
+     *
+     * @param count - Max number of penalties
+     * @param period - Period type ('daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly')
+     */
+    maxPenalties(count: number, period: 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly'): this;
+    /**
+     * Set when to reset occurrence counter
+     *
+     * @param period - Reset period ('monthly' | 'quarterly' | 'yearly')
+     */
+    resetOccurrences(period: 'monthly' | 'quarterly' | 'yearly'): this;
+    /**
+     * Add a custom tier (advanced usage)
+     */
+    addTier(tier: PenaltyTier): this;
+    /**
+     * Finish building this policy and return to parent builder
+     */
+    end(): TParent;
+    /**
+     * Build the policy (for standalone usage)
+     */
+    build(): LateArrivalPolicy;
+    /** @internal */
+    _getPolicy(): Partial<LateArrivalPolicy>;
+}
+/**
+ * Builder for tiered penalties (progressive discipline)
+ */
+declare class TieredPenaltyBuilder<TParent> {
+    private tiers;
+    private parent;
+    private currentTier;
+    constructor(parent: TParent);
+    /**
+     * Start a new tier
+     *
+     * @param from - Starting occurrence number (1-indexed)
+     * @param to - Ending occurrence number (optional, omit for open-ended tier)
+     */
+    tier(from: number, to?: number): this;
+    /**
+     * Set this tier as warning only (no financial penalty)
+     */
+    warning(): this;
+    /**
+     * Set penalty amount for this tier
+     */
+    penalty(amount: number): this;
+    /**
+     * Finish building tiers and return to parent
+     */
+    end(): TParent;
+    private saveTier;
+}
+/**
+ * Builder for overtime policies
+ */
+declare class OvertimePolicyBuilder<TParent = unknown> {
+    private policy;
+    private parent?;
+    constructor(parent?: TParent);
+    /**
+     * Enable overtime calculations
+     */
+    enable(): this;
+    /**
+     * Disable overtime calculations
+     */
+    disable(): this;
+    /**
+     * Set overtime calculation mode
+     */
+    mode(mode: 'daily' | 'weekly' | 'monthly'): this;
+    /**
+     * Set daily overtime threshold and multiplier
+     *
+     * @param hours - Hours threshold (e.g., 8)
+     * @param multiplier - Overtime multiplier (e.g., 1.5 for time-and-a-half)
+     */
+    dailyThreshold(hours: number, multiplier: number): this;
+    /**
+     * Set weekly overtime threshold and multiplier
+     *
+     * @param hours - Hours threshold (e.g., 40)
+     * @param multiplier - Overtime multiplier (e.g., 1.5 for time-and-a-half)
+     */
+    weeklyThreshold(hours: number, multiplier: number): this;
+    /**
+     * Set monthly overtime threshold and multiplier
+     *
+     * @param hours - Hours threshold (e.g., 160)
+     * @param multiplier - Overtime multiplier (e.g., 2.0 for double time)
+     */
+    monthlyThreshold(hours: number, multiplier: number): this;
+    /**
+     * Set weekend premium rates
+     *
+     * @param saturday - Saturday multiplier (e.g., 1.5)
+     * @param sunday - Sunday multiplier (e.g., 2.0)
+     */
+    weekendPremium(saturday: number, sunday: number): this;
+    /**
+     * Set night shift differential
+     *
+     * @param startHour - Start hour (24-hour format, e.g., 22 for 10pm)
+     * @param endHour - End hour (24-hour format, e.g., 6 for 6am)
+     * @param multiplier - Night shift multiplier (e.g., 1.3 for 30% premium)
+     */
+    nightShiftDifferential(startHour: number, endHour: number, multiplier: number): this;
+    /**
+     * Finish building this policy and return to parent builder
+     */
+    end(): TParent;
+    /**
+     * Build the policy (for standalone usage)
+     */
+    build(): OvertimePolicy;
+    /** @internal */
+    _getPolicy(): Partial<OvertimePolicy>;
+}
+/**
+ * Builder for clock rounding policies
+ */
+declare class ClockRoundingPolicyBuilder<TParent = unknown> {
+    private policy;
+    private parent?;
+    constructor(parent?: TParent);
+    /**
+     * Enable clock rounding
+     */
+    enable(): this;
+    /**
+     * Disable clock rounding
+     */
+    disable(): this;
+    /**
+     * Set rounding interval in minutes
+     *
+     * @param minutes - Round to nearest N minutes (e.g., 5, 10, 15)
+     */
+    roundTo(minutes: 5 | 10 | 15): this;
+    /**
+     * Set rounding mode
+     *
+     * @param mode - 'up' (favor employee) | 'down' (favor employer) | 'nearest' (neutral)
+     */
+    roundingMode(mode: 'up' | 'down' | 'nearest'): this;
+    /**
+     * Finish building this policy and return to parent builder
+     */
+    end(): TParent;
+    /**
+     * Build the policy (for standalone usage)
+     */
+    build(): ClockRoundingPolicy;
+    /** @internal */
+    _getPolicy(): Partial<ClockRoundingPolicy>;
+}
+/**
+ * Main builder for creating complete attendance policies
+ *
+ * @example
+ * ```typescript
+ * const policy = AttendancePolicyBuilder.create()
+ *   .named('Manufacturing Policy')
+ *   .description('Strict policy for factory floor')
+ *   .organizationId(orgId)
+ *   .lateArrival()
+ *     .enable()
+ *     .gracePeriod(0)
+ *     .flatPenalty(100)
+ *     .maxPenalties(5, 'monthly')
+ *     .resetOccurrences('quarterly')
+ *   .end()
+ *   .earlyDeparture()
+ *     .enable()
+ *     .gracePeriod(0)
+ *     .flatPenalty(150)
+ *   .end()
+ *   .overtime()
+ *     .enable()
+ *     .mode('daily')
+ *     .dailyThreshold(8, 1.5)
+ *     .weeklyThreshold(40, 2.0)
+ *   .end()
+ *   .clockRounding()
+ *     .enable()
+ *     .roundTo(15)
+ *     .roundingMode('down')
+ *   .end()
+ *   .effectiveFrom(new Date('2025-01-01'))
+ *   .build();
+ * ```
+ */
+declare class AttendancePolicyBuilder {
+    private policy;
+    private lateArrivalBuilder?;
+    private earlyDepartureBuilder?;
+    private overtimeBuilder?;
+    private clockRoundingBuilder?;
+    /**
+     * Create a new policy builder
+     */
+    static create(): AttendancePolicyBuilder;
+    /**
+     * Set policy name
+     */
+    named(name: string): this;
+    /**
+     * Set policy description
+     */
+    description(description: string): this;
+    /**
+     * Set organization ID (for multi-tenant systems)
+     */
+    organizationId(id: ObjectIdLike): this;
+    /**
+     * Set policy ID (for updates)
+     */
+    id(id: string): this;
+    /**
+     * Set effective from date
+     */
+    effectiveFrom(date: Date): this;
+    /**
+     * Set effective to date (when policy expires)
+     */
+    effectiveTo(date: Date | null): this;
+    /**
+     * Set policy active status
+     */
+    active(active: boolean): this;
+    /**
+     * Start building late arrival policy
+     */
+    lateArrival(): LatePolicyBuilder<this>;
+    /**
+     * Start building early departure policy
+     */
+    earlyDeparture(): LatePolicyBuilder<this>;
+    /**
+     * Start building overtime policy
+     */
+    overtime(): OvertimePolicyBuilder<this>;
+    /**
+     * Start building clock rounding policy
+     */
+    clockRounding(): ClockRoundingPolicyBuilder<this>;
+    /**
+     * Build the complete attendance policy
+     */
+    build(): AttendancePolicy;
+}
+/**
+ * Create a standalone late arrival policy builder
+ */
+declare function createLatePolicyBuilder(): LatePolicyBuilder<void>;
+/**
+ * Create a standalone overtime policy builder
+ */
+declare function createOvertimePolicyBuilder(): OvertimePolicyBuilder<void>;
+/**
+ * Create a standalone clock rounding policy builder
+ */
+declare function createClockRoundingPolicyBuilder(): ClockRoundingPolicyBuilder<void>;
+
+/**
+ * Schema definition for penalty tiers (progressive discipline)
+ */
+declare const PenaltyTierSchemaDefinition: SchemaDefinition;
+/**
+ * Schema for penalty tiers
+ */
+declare const PenaltyTierSchema: Schema;
+/**
+ * Schema definition for max penalties per period
+ */
+declare const MaxPenaltiesSchemaDefinition: SchemaDefinition;
+/**
+ * Schema for max penalties per period
+ */
+declare const MaxPenaltiesSchema: Schema;
+/**
+ * Schema definition for late arrival policy
+ */
+declare const LateArrivalPolicySchemaDefinition: SchemaDefinition;
+/**
+ * Schema for late arrival policy
+ */
+declare const LateArrivalPolicySchema: Schema;
+/**
+ * Schema definition for early departure policy
+ * (Same structure as late arrival policy)
+ */
+declare const EarlyDeparturePolicySchemaDefinition: {
+    [path: string]: mongoose.SchemaDefinitionProperty<undefined, any, any>;
+};
+/**
+ * Schema for early departure policy
+ */
+declare const EarlyDeparturePolicySchema: Schema;
+/**
+ * Schema definition for weekend premium
+ */
+declare const WeekendPremiumSchemaDefinition: SchemaDefinition;
+/**
+ * Schema for weekend premium
+ */
+declare const WeekendPremiumSchema: Schema;
+/**
+ * Schema definition for night shift differential
+ */
+declare const NightShiftDifferentialSchemaDefinition: SchemaDefinition;
+/**
+ * Schema for night shift differential
+ */
+declare const NightShiftDifferentialSchema: Schema;
+/**
+ * Schema definition for overtime policy
+ */
+declare const OvertimePolicySchemaDefinition: SchemaDefinition;
+/**
+ * Schema for overtime policy
+ */
+declare const OvertimePolicySchema: Schema;
+/**
+ * Schema definition for clock rounding policy
+ */
+declare const ClockRoundingPolicySchemaDefinition: SchemaDefinition;
+/**
+ * Schema for clock rounding policy
+ */
+declare const ClockRoundingPolicySchema: Schema;
+/**
+ * Schema definition for attendance policy
+ *
+ * Users can extend this with their own fields:
+ * ```typescript
+ * const CustomPolicySchema = new Schema({
+ *   ...AttendancePolicySchemaDefinition,
+ *   approvedBy: { type: Schema.Types.ObjectId, ref: 'User' },
+ *   department: String,
+ * });
+ * ```
+ */
+declare const AttendancePolicySchemaDefinition: SchemaDefinition;
+/**
+ * Main Attendance Policy Schema
+ *
+ * @example
+ * ```typescript
+ * import { AttendancePolicySchema } from '@classytic/payroll';
+ * import { model } from 'mongoose';
+ *
+ * const AttendancePolicy = model('AttendancePolicy', AttendancePolicySchema);
+ *
+ * // Create a new policy
+ * const policy = new AttendancePolicy({
+ *   name: 'Tech Department Policy',
+ *   lateArrival: { ... },
+ *   earlyDeparture: { ... },
+ *   overtime: { ... },
+ * });
+ * await policy.save();
+ * ```
+ */
+declare const AttendancePolicySchema: Schema;
+/**
+ * Instance methods interface
+ */
+interface AttendancePolicyDocument {
+    isCurrentlyActive(): boolean;
+}
+/**
+ * Static methods interface
+ */
+interface AttendancePolicyModel {
+    findActiveForOrganization(organizationId: any, date?: Date): Promise<any>;
+}
+
+export { type AttendancePolicy, AttendancePolicyBuilder, type AttendancePolicyDocument, type AttendancePolicyModel, AttendancePolicySchema, AttendancePolicySchemaDefinition, type CalculateShiftComplianceInput, type ClockRoundingPolicy, ClockRoundingPolicyBuilder, ClockRoundingPolicySchema, ClockRoundingPolicySchemaDefinition, DEFAULT_ATTENDANCE_POLICY, type EarlyDeparturePenaltyResult, type EarlyDeparturePolicy, EarlyDeparturePolicySchema, EarlyDeparturePolicySchemaDefinition, type EarlyOccurrence, HEALTHCARE_POLICY, HOSPITALITY_POLICY, type LateArrivalPolicy, LateArrivalPolicySchema, LateArrivalPolicySchemaDefinition, type LateOccurrence, type LatePenaltyResult, LatePolicyBuilder, MANUFACTURING_POLICY, type MaxPenaltiesPerPeriod, MaxPenaltiesSchema, MaxPenaltiesSchemaDefinition, type NightShiftDifferential, NightShiftDifferentialSchema, NightShiftDifferentialSchemaDefinition, OFFICE_POLICY, ObjectIdLike, type OvertimeBonusResult, type OvertimeMode, type OvertimeOccurrence, type OvertimePolicy, OvertimePolicyBuilder, OvertimePolicySchema, OvertimePolicySchemaDefinition, type PenaltyMode, type PenaltyOverride, type PenaltyTier, PenaltyTierSchema, PenaltyTierSchemaDefinition, RETAIL_POLICY, type ResetPeriod, type RoundingMode, type ShiftComplianceData, type ShiftComplianceResult, type ShiftDifferentialResult, TieredPenaltyBuilder, type WeekendPremium, WeekendPremiumSchema, WeekendPremiumSchemaDefinition, calculateDailyOvertime, calculateFlatPenalty, calculateLatePenalty, calculateMonthlyOvertime, calculateNightShiftDifferential, calculateOvertimeBonus, calculatePerMinutePenalty, calculatePercentagePenalty, calculateShiftCompliance, calculateTieredPenalty, calculateWeekendPremium, calculateWeeklyOvertime, createClockRoundingPolicyBuilder, createLatePolicyBuilder, createOvertimePolicyBuilder, createPolicyFromPreset, AttendancePolicySchema as default };