CalOohPay API Documentation - v2.1.0
    Preparing search index...

    CalOohPay API Documentation - v2.1.0

    CalOohPay - Calculate Out-of-Hours Pay

    TypeScript Node.js PagerDuty npm version License: ISC Buy Me A Coffee

    A command-line tool that automates the calculation of out-of-hours (OOH) on-call compensation for engineering teams using PagerDuty schedules.

    CalOohPay eliminates the manual work of calculating on-call payments by:

    • Fetching schedule data directly from PagerDuty API
    • Calculating compensation based on weekday vs weekend rates
    • Supporting multiple teams and schedules simultaneously
    • Providing auditable records for payroll processing
    • Handling timezone conversions automatically

    In many organizations, engineers get compensated for going on-call outside of working hours. Managers typically spend 5-10 minutes per team each month reconciling on-call rotas for payroll. With multiple teams and distributed locations, this manual process quickly becomes time-consuming and error-prone.

    CalOohPay automates this entire process, turning hours of manual work into a single command.

    • Node.js (v14 or higher)
    • npm or yarn
    • PagerDuty API User Token (How to get one)
    npm install -g caloohpay

    No installation required, run directly with npx:

    npx caloohpay -r "SCHEDULE_ID"

    git clone https://github.com/lonelydev/caloohpay.git
    cd caloohpay
    npm install
    npm run build
    npm link

    Create a .env file in the project root:

    # .env
    API_TOKEN=your_pagerduty_api_token_here

    # Get help
    caloohpay --help

    # Calculate payments for a single schedule (previous month)
    caloohpay -r "PQRSTUV"

    # Calculate for multiple schedules with custom date range
    caloohpay -r "PQRSTUV,PSTUVQR" -s "2024-01-01" -u "2024-01-31"

    CalOohPay can be used as a library in both Node.js and browser environments.

    Node.js (with file system access and PagerDuty API):

    import { ConfigLoader, OnCallPaymentsCalculator } from 'caloohpay';

    const loader = new ConfigLoader();
    const rates = loader.loadRates();
    const calculator = new OnCallPaymentsCalculator(rates.weekdayRate, rates.weekendRate);

    Browser/Web Applications (Next.js, React, Vue, etc.):

    import { OnCallUser, OnCallPeriod, OnCallPaymentsCalculator } from 'caloohpay/core';

    // Create on-call periods from your data
    const user = new OnCallUser('user-id', 'John Doe', [
      new OnCallPeriod(
        new Date('2024-08-01T18:00:00Z'),
        new Date('2024-08-05T09:00:00Z'),
        'Europe/London'
      )
    ]);

    // Calculate with custom rates
    const calculator = new OnCallPaymentsCalculator(60, 90);
    const amount = calculator.calculateOnCallPayment(user);
    console.log(`Compensation: $${amount}`);

    📚 View Full API Documentation →

    CalOohPay now works in web browsers! The core calculation engine is completely independent of Node.js.

    // 🌐 Browser-compatible core (zero Node.js dependencies)
    import { OnCallPaymentsCalculator, OnCallUser, OnCallPeriod, DEFAULT_RATES } from 'caloohpay/core';

    // 🖥️ Node.js-specific features (ConfigLoader, CsvWriter, PagerDuty API)
    import { ConfigLoader, CsvWriter, calOohPay } from 'caloohpay/node';

    // 📦 Everything (backward compatible, Node.js only)
    import { ConfigLoader, OnCallPaymentsCalculator } from 'caloohpay';

    'use client'; // Next.js 13+ App Router

    import { useState } from 'react';
    import { OnCallPaymentsCalculator, DEFAULT_RATES } from 'caloohpay/core';

    export default function CompensationCalculator() {
      const [weekdayRate, setWeekdayRate] = useState(DEFAULT_RATES.weekdayRate);
      const [weekendRate, setWeekendRate] = useState(DEFAULT_RATES.weekendRate);
      
      const calculator = new OnCallPaymentsCalculator(weekdayRate, weekendRate);
      
      // Use calculator.calculateOnCallPayment(user) with your data
      
      return (
        <div>
          <input value={weekdayRate} onChange={(e) => setWeekdayRate(Number(e.target.value))} />
          <input value={weekendRate} onChange={(e) => setWeekendRate(Number(e.target.value))} />
          {/* Your UI here */}
        </div>
      );
    }

    What works in browsers:

    • ✅ Core calculation engine (OnCallPaymentsCalculator)
    • ✅ Models (OnCallUser, OnCallPeriod)
    • ✅ All constants and types
    • ✅ Date utilities and validation

    Node.js only:

    • ❌ ConfigLoader (uses fs module)
    • ❌ CsvWriter (uses fs module)
    • ❌ calOohPay function (uses PagerDuty API)
    • ❌ CLI tools
    Period Rate
    Weekdays (Mon-Thu) £50 per day
    Weekends (Fri-Sun) £75 per day

    You can customize compensation rates by creating a .caloohpay.json file:

    {
      "rates": {
        "weekdayRate": 60,
        "weekendRate": 90,
        "currency": "USD"
      }
    }

    The tool searches for this file in:

    1. Current working directory (project-specific rates)
    2. Home directory ~/.caloohpay.json (user-wide defaults)
    3. Built-in defaults if no config found

    Example config file: .caloohpay.json.example

    Development, testing, contributor workflow and git-hook guidance has moved to CONTRIBUTING.md. Please read that document for detailed setup and contribution instructions, including how to run tests, lint, generate docs, and prepare a pull request.

    Note on ESLint configuration: this project uses ESLint v9 with a flat config file located at eslint.config.cjs (instead of legacy .eslintrc.json). If you need to adjust lint rules or add new shareable configs, update eslint.config.cjs and run npm run lint to validate your changes.

    "Command not found: caloohpay"

    • Run npm link after building
    • Restart your terminal
    • Check if dist/src/CalOohPay.js exists

    "Invalid API Token"

    • Verify your .env file contains the correct token
    • Ensure no extra spaces or quotes around the token
    • Check token permissions in PagerDuty

    "No schedule entries found"

    • Verify the schedule ID is correct
    • Check the date range includes on-call periods
    • Ensure you have permissions to view the schedule

    Schedule IDs can be found in PagerDuty:

    1. Navigate to People → On-Call Schedules
    2. Click on your schedule
    3. The ID is in the URL: https://yourcompany.pagerduty.com/schedules/PQRSTUV

    To fetch schedule data from PagerDuty, you need an API User Token that provides the same permissions as your user account.

    1. Login to PagerDuty
    2. Navigate to Profile: Hover over your profile icon → My Profile
    3. Access Settings: Go to User Settings
    4. Create Token: Click Create API User Token
    5. Secure Storage: Store the token securely (e.g., 1Password, environment variable)

    ⚠️ Security Warning: Never commit your API token to version control!

    caloohpay -r "SCHEDULE_ID" [options]

    Common Options:

    • -r, --rota-ids - Schedule ID(s) (required)
    • -s, --since - Start date (YYYY-MM-DD)
    • -u, --until - End date (YYYY-MM-DD)
    • -o, --output-file - Save to CSV file
    • -t, --timeZoneId - Override timezone
    • -k, --key - API token override

    Examples:

    # Basic usage
    caloohpay -r "PQRSTUV"

    # Multiple schedules to CSV
    caloohpay -r "TEAM_A,TEAM_B" -o "./monthly-report.csv"

    # Custom date range
    caloohpay -r "PQRSTUV" -s "2024-01-01" -u "2024-01-31"
    • ✅ PagerDuty Integration: Fetches schedules with automatic timezone detection
    • ✅ Multi-Schedule Support: Process multiple schedules simultaneously
    • ✅ Configurable Rates: Custom weekday/weekend rates via .caloohpay.json
    • ✅ Timezone Support: Accurate OOH calculations for distributed teams
    • ✅ CSV Export: Google Sheets compatible payroll files
    • ✅ Comprehensive Testing: 328+ unit tests with full coverage
    # Automatic timezone detection (recommended)
    caloohpay -r "SCHEDULE_ID"

    # Override timezone if needed
    caloohpay -r "SCHEDULE_ID" -t "America/New_York"

    Recently Completed:

    • ✅ Configurable rates via config file
    • ✅ Full timezone support with automatic detection
    • ✅ CSV export for payroll systems

    Coming Soon:

    • Enhanced console output with colors
    • NPM package distribution
    • Automated monthly reporting

    This project is licensed under the ISC License - see the LICENSE file for details.

    If you encounter any issues or have questions:

    1. Check the troubleshooting section
    2. Search existing issues
    3. Create a new issue with detailed information

    If CalOohPay has saved you time and made your life easier, consider supporting its development!

    Buy Me A Coffee

    Your support helps me:

    • 🚀 Continue developing new features
    • 🐛 Fix bugs and improve stability
    • 📚 Maintain documentation
    • 💡 Explore new ideas and integrations

    Every coffee counts and is greatly appreciated! ☕

    Made with ❤️ for engineering teams who deserve fair compensation for their on-call dedication.

    Settings

    Member Visibility

    On This Page

    CalOohPay - Calculate Out-of-Hours Pay