Function calOohPay

calOohPay(
    cliOptions: CommandLineOptions,
    logger?: Logger,
    returnResults?: boolean,
): Promise<CalOohPayResult | undefined>
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
Parameters
- cliOptions: CommandLineOptions
  Command line options containing schedule IDs, date range, timezone, and output settings
- Optionallogger: Logger
- returnResults: boolean = false
Returns Promise<CalOohPayResult | undefined>
A Promise that resolves when all schedules have been processed
Throws
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
```
// 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
Since
2.0.0 - Refactored to use async/await for sequential processing

Since
2.1.0 - Added optional return type for testing and monitoring
- Defined in CalOohPay.ts:436