#!/usr/bin/env node
import { CommandLineOptions } from './CommandLineOptions';
import { FinalSchedule } from './FinalSchedule';
import { Logger } from './logger/Logger';
import { OnCallUser } from './OnCallUser';
/**
 * Summary result from processing schedules.
 *
 * @remarks
 * This interface provides aggregate metrics from a calOohPay execution,
 * useful for testing, monitoring, and integration scenarios.
 *
 * @since 2.1.0
 */
export interface CalOohPayResult {
    /** Number of schedules successfully processed */
    schedulesProcessed: number;
    /** Total number of unique users across all schedules */
    totalUsers: number;
    /** Total compensation amount in GBP across all schedules */
    totalCompensation: number;
}
/**
 * Extracts and consolidates on-call users from a PagerDuty final schedule.
 *
 * This function processes all schedule entries from a PagerDuty final schedule and creates
 * a dictionary of OnCallUser objects, consolidating multiple time periods for the same user
 * into a single OnCallUser with multiple OnCallPeriods.
 *
 * @param finalSchedule - The final schedule object from PagerDuty containing rendered schedule entries
 * @param timeZone - The IANA timezone identifier to use for OOH calculations across all entries
 * @returns A Record mapping user IDs to OnCallUser objects with their consolidated on-call periods
 *
 * @remarks
 * Key behaviours:
 * - Multiple schedule entries for the same user are consolidated into one OnCallUser
 * - Each unique user ID becomes a key in the returned Record
 * - If a user appears multiple times, their OnCallPeriods are accumulated
 * - Empty schedule (no entries) returns an empty Record
 * - All periods use the same timezone for consistency
 *
 * Algorithm:
 * 1. Initialize empty dictionary of users
 * 2. For each schedule entry:
 *    - Convert entry to OnCallUser with single period
 *    - If user already exists, add the new period to their existing periods
 *    - If user is new, add them to the dictionary
 * 3. Return consolidated dictionary
 *
 * @example
 * ```typescript
 * const finalSchedule = {
 *   rendered_schedule_entries: [
 *     { start: new Date('2024-01-01T18:00:00Z'), end: new Date('2024-01-02T09:00:00Z'),
 *       user: { id: 'USER1', summary: 'John Doe' } },
 *     { start: new Date('2024-01-02T18:00:00Z'), end: new Date('2024-01-03T09:00:00Z'),
 *       user: { id: 'USER1', summary: 'John Doe' } },
 *     { start: new Date('2024-01-03T18:00:00Z'), end: new Date('2024-01-04T09:00:00Z'),
 *       user: { id: 'USER2', summary: 'Jane Smith' } }
 *   ]
 * };
 * const users = extractOnCallUsersFromFinalSchedule(finalSchedule, 'Europe/London');
 * // Returns: { 'USER1': OnCallUser with 2 periods, 'USER2': OnCallUser with 1 period }
 * ```
 *
 * @see {@link FinalSchedule}
 * @see {@link OnCallUser}
 * @see {@link OnCallPeriod}
 */
export declare function extractOnCallUsersFromFinalSchedule(finalSchedule: FinalSchedule, timeZone: string): Record<string, OnCallUser>;
/**
 * Main function to calculate out-of-hours (OOH) on-call payments for PagerDuty schedules.
 *
 * This asynchronous function orchestrates the entire on-call payment calculation workflow:
 * - Authenticates with PagerDuty API
 * - Fetches schedule data for one or more schedules sequentially
 * - Calculates OOH compensation for each user
 * - Outputs results to console and optionally to CSV file
 *
 * @param cliOptions - Command line options containing schedule IDs, date range, timezone, and output settings
 * @returns A Promise that resolves when all schedules have been processed
 *
 * @throws {Error} If API authentication fails, schedule fetch fails, or CSV write fails
 *
 * @remarks
 * ### Sequential Processing (Race Condition Fix)
 * This function uses `async/await` to process schedules **sequentially** rather than concurrently.
 * This design choice prevents:
 * - Race conditions when writing to the same CSV file
 * - Unpredictable output order
 * - Interleaved console output from multiple schedules
 *
 * ### Authentication
 * API token is retrieved from:
 * 1. CLI option (`--key` or `-k`) if provided
 * 2. Environment variable `API_TOKEN` otherwise
 *
 * ### Timezone Handling
 * The effective timezone for OOH calculations is determined by priority:
 * 1. CLI option (`--timeZoneId` or `-t`) if provided (overrides schedule timezone)
 * 2. Schedule's timezone from PagerDuty API
 * 3. 'UTC' as fallback
 *
 * ### CSV Output
 * If `outputFile` is specified:
 * - Existing file is deleted before processing first schedule
 * - First schedule writes create new file (append=false)
 * - Subsequent schedules append to existing file (append=true)
 * - All schedules write to the same file sequentially
 *
 * ### Error Handling
 * - Each schedule is processed in a try-catch block
 * - Errors include specific schedule ID for debugging
 * - First error stops processing and propagates to top-level handler
 * - Top-level handler logs error and exits with code 1
 *
 * @example
 * ```typescript
 * // Process single schedule with default settings
 * await calOohPay({
 *   rotaIds: 'PXXXXXX',
 *   since: '2024-01-01T00:00:00Z',
 *   until: '2024-01-31T23:59:59Z',
 *   timeZoneId: undefined,
 *   key: undefined,
 *   outputFile: undefined
 * });
 *
 * // Process multiple schedules with CSV output
 * await calOohPay({
 *   rotaIds: 'PXXXXXX,PYYYYYY,PZZZZZZ',
 *   since: '2024-01-01T00:00:00Z',
 *   until: '2024-01-31T23:59:59Z',
 *   timeZoneId: 'Europe/London',
 *   key: 'your-api-token',
 *   outputFile: './output/oncall-payments.csv'
 * });
 * ```
 *
 * @see {@link CommandLineOptions}
 * @see {@link OnCallPaymentsCalculator}
 * @see {@link CsvWriter}
 * @see {@link extractOnCallUsersFromFinalSchedule}
 *
 * @since 2.0.0 - Refactored to use async/await for sequential processing
 * @since 2.1.0 - Added optional return type for testing and monitoring
 */
export declare function calOohPay(cliOptions: CommandLineOptions, logger?: Logger, returnResults?: boolean): Promise<CalOohPayResult | undefined>;
//# sourceMappingURL=CalOohPay.d.ts.map