# CalOohPay v1.0.0 Release Documentation

## 📦 Release Information

- **Version**: 1.0.0
- **Release Date**: October 25, 2025
- **Type**: Stable Release
- **Compatibility**: Single-timezone teams
- **Test Coverage**: 20 tests

## 🎯 Overview

Version 1.0.0 is the first stable release of CalOohPay, providing reliable on-call compensation calculations for teams working in a single timezone.

## ✨ Features

### Core Functionality

- **PagerDuty Integration**: Fetch on-call schedules directly from PagerDuty API
- **Multiple Schedules**: Process multiple schedule IDs in a single run
- **Flexible Date Ranges**: Custom date ranges or automatic previous month calculation
- **Compensation Calculation**: 
  - Weekdays (Mon-Thu): £50 per day
  - Weekends (Fri-Sun): £75 per day
- **Auditable Reports**: Clear breakdown by user with day counts

### Command Line Interface

```bash
# Basic usage
caloohpay -r "SCHEDULE_ID"

# Multiple schedules
caloohpay -r "SCHEDULE_ID1,SCHEDULE_ID2"

# Custom date range
caloohpay -r "SCHEDULE_ID" -s "2024-01-01" -u "2024-01-31"

# Override API token
caloohpay -r "SCHEDULE_ID" -k "your_api_token"

# Specify timezone (uses local if not specified)
caloohpay -r "SCHEDULE_ID" -t "Europe/London"
```

### Available Options

| Option | Short | Description | Required | Default |
|--------|-------|-------------|----------|---------|
| `--rota-ids` | `-r` | PagerDuty schedule ID(s) | ✅ | - |
| `--since` | `-s` | Start date (YYYY-MM-DD) | ❌ | First day of previous month |
| `--until` | `-u` | End date (YYYY-MM-DD) | ❌ | First day of current month |
| `--timeZoneId` | `-t` | Timezone ID | ❌ | Local system timezone |
| `--key` | `-k` | API token override | ❌ | From `.env` file |
| `--output-file` | `-o` | Output file path | ❌ | Console output |
| `--help` | `-h` | Show help | ❌ | - |

## 📋 Prerequisites

- **Node.js**: v14 or higher
- **npm**: v6 or higher
- **PagerDuty API Token**: User token with schedule read permissions

## 🚀 Installation

### Step 1: Clone and Checkout

```bash
git clone https://github.com/lonelydev/caloohpay.git
cd caloohpay
git checkout v1.0.0
```

### Step 2: Install Dependencies

```bash
npm install
```

### Step 3: Build

```bash
npm run build
```

### Step 4: Configure Environment

Create a `.env` file in the project root:

```env
API_TOKEN=your_pagerduty_api_token_here
```

### Step 5: Link Globally (Optional)

```bash
npm link
```

Now you can use `caloohpay` from anywhere in your terminal.

## 🧪 Testing

Run the test suite to verify installation:

```bash
npm test
```

Expected output:
```
Test Suites: 4 passed, 4 total
Tests:       20 passed, 20 total
```

## 📖 Usage Examples

### Example 1: Basic Monthly Calculation

Calculate on-call pay for the previous month:

```bash
caloohpay -r "PQRSTUV"
```

**Output:**
```
┌─────────────────┬─────────────────────────────────────┐
│ rotaIds         │ 'PQRSTUV'                           │
│ timeZoneId      │ 'Europe/London'                     │
│ since           │ '2024-09-01T00:00:00.000+01:00'    │
│ until           │ '2024-10-01T10:00:00.000+01:00'    │
└─────────────────┴─────────────────────────────────────┘
────────────────────────────────────────
Schedule name: Engineering Team Alpha
Schedule URL: https://company.pagerduty.com/schedules/PQRSTUV
User, TotalComp, Mon-Thu, Fri-Sun
John Smith, 275, 3, 2
Jane Doe, 200, 4, 0
```

### Example 2: Multiple Schedules

Process multiple teams at once:

```bash
caloohpay -r "SCHEDULE1,SCHEDULE2,SCHEDULE3"
```

### Example 3: Custom Date Range

Calculate for a specific period:

```bash
caloohpay -r "PQRSTUV" -s "2024-08-01" -u "2024-08-31"
```

### Example 4: CI/CD Integration

Use API token override for automation:

```bash
caloohpay -r "PQRSTUV" -k "${PAGERDUTY_API_TOKEN}"
```

## ⚠️ Important Notes

### Timezone Handling

- **v1.0.0 uses your local system timezone** for all calculations
- If your team spans multiple timezones, consider upgrading to v2.0.0
- All team members should use the same timezone setting for consistency

### Known Limitations

1. **Single Timezone**: All calculations use local timezone, not suitable for distributed teams
2. **Fixed Rates**: Compensation rates are hardcoded (£50/£75)
3. **No CSV Export**: Console output only
4. **Manual Execution**: No scheduled automation

## 🔧 Troubleshooting

### Issue: "Command not found: caloohpay"

**Solution:**
```bash
cd /path/to/caloohpay
npm link
```

### Issue: "Invalid API Token"

**Solution:**
1. Verify token in `.env` file
2. Check token has no extra spaces
3. Ensure token has schedule read permissions
4. Try using `--key` option directly

### Issue: "No schedule entries found"

**Solution:**
1. Verify schedule ID is correct
2. Check date range includes on-call periods
3. Ensure you have permissions to view the schedule

## 📊 Understanding the Output

### Columns Explained

- **User**: Name of the on-call person from PagerDuty
- **TotalComp**: Total compensation in GBP (£)
- **Mon-Thu**: Number of OOH weekdays
- **Fri-Sun**: Number of OOH weekends

### Calculation Logic

A day counts as OOH if:
1. The shift spans multiple days (doesn't start and end same day)
2. The shift extends past 17:30 (5:30 PM)
3. The shift is longer than 6 hours

**Formula:**
```
Total Compensation = (Weekdays × £50) + (Weekends × £75)
```

## 🔄 Upgrading to v2.0.0

If you need multi-timezone support, see [CHANGELOG.md](CHANGELOG.md) for upgrade instructions.

**Key differences in v2.0.0:**
- Automatic timezone detection from PagerDuty
- Better handling of distributed teams
- More accurate OOH calculations across timezones

## 📝 Configuration Tips

### Best Practices

1. **Store API token securely**: Never commit `.env` to version control
2. **Use consistent timezone**: Ensure all team members use same timezone setting
3. **Test with small date ranges**: Verify calculations before running full months
4. **Document your rates**: Update README if you modify compensation rates

### Environment Variables

```bash
# Required
API_TOKEN=your_token_here

# Optional (if you prefer env vars over CLI)
DEFAULT_TIMEZONE=Europe/London
```

## 🐛 Reporting Issues

Found a bug? Please report it:

1. Check [existing issues](https://github.com/lonelydev/caloohpay/issues)
2. Create a new issue with:
   - Version: v1.0.0
   - Operating system
   - Node.js version
   - Steps to reproduce
   - Expected vs actual behaviour

## 📄 License

ISC License - See [LICENSE](LICENSE) file

## 🙏 Support

- ⭐ Star the repository
- 🐛 Report bugs
- 💡 Suggest features
- ☕ [Buy me a coffee](https://buymeacoffee.com/swcraftsperson)

---

**Version**: v1.0.0  
**Last Updated**: October 25, 2025  
**Maintained**: Yes (security fixes only, feature development on v2.0.0)