# CalOohPay v2.1.0 Release Documentation

## 📦 Release Information

- **Version**: 2.1.0
- **Release Date**: November 21, 2025
- **Type**: Minor Release (New Features, No Breaking Changes)
- **Compatibility**: Browser and Node.js environments
- **Test Coverage**: 342 tests (14 new export structure tests)

## 🎯 Overview

Version 2.1.0 introduces browser compatibility by restructuring the package into modular exports. The core calculation engine now works in any JavaScript environment (browsers, Node.js, Deno, etc.), making it perfect for web applications built with Next.js, React, Vue, Angular, or vanilla JavaScript.

**Key Achievement**: Complete separation of browser-compatible core from Node.js-specific dependencies while maintaining 100% backward compatibility.

## ✨ New Features

### 1. Browser-Compatible Core Module

The new `caloohpay/core` export provides a pure JavaScript calculation engine with **zero Node.js dependencies**:

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

// Works in browsers, Node.js, Deno, etc.
const calculator = new OnCallPaymentsCalculator(60, 90);
const user = new OnCallUser('id', 'John Doe', [
  new OnCallPeriod(startDate, endDate, 'UTC')
]);
const amount = calculator.calculateOnCallPayment(user);
```

**What's included in `core`:**

- ✅ `OnCallPaymentsCalculator` - Compensation calculation engine
- ✅ `OnCallUser`, `OnCallPeriod` - Domain models
- ✅ `DEFAULT_RATES`, constants - Configuration data
- ✅ `InputValidator` - Validation utilities
- ✅ `convertTimezone` - Date utilities
- ✅ All TypeScript types and interfaces

**What's NOT in `core`** (Node.js only):

- ❌ `ConfigLoader` (uses `fs` module)
- ❌ `CsvWriter` (uses `fs` module)
- ❌ `calOohPay` function (uses PagerDuty API)
- ❌ CLI tools

### 2. Node.js-Specific Module

The new `caloohpay/node` export provides all Node.js-specific functionality plus everything from core:

```typescript
import { 
  ConfigLoader, 
  CsvWriter, 
  calOohPay,
  OnCallPaymentsCalculator // Also includes all core exports
} from 'caloohpay/node';

const loader = new ConfigLoader();
const rates = loader.loadRates(); // Reads .caloohpay.json from filesystem
const calculator = new OnCallPaymentsCalculator(rates.weekdayRate, rates.weekendRate);
```

### 3. Package Exports Field

Modern package.json exports enable better module resolution:

```json
{
  "exports": {
    ".": "./dist/src/index.js",           // Default (backward compatible)
    "./core": "./dist/src/core.js",        // Browser-compatible
    "./node": "./dist/src/node.js"         // Node.js-specific
  }
}
```

This allows bundlers (webpack, Vite, Rollup, etc.) to optimize tree-shaking and reduce bundle sizes for web applications.

## 🌐 Web Framework Integration

### Next.js Example

```typescript
'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 with your on-call data from API
  return (
    <div>
      <input value={weekdayRate} onChange={(e) => setWeekdayRate(Number(e.target.value))} />
      <input value={weekendRate} onChange={(e) => setWeekendRate(Number(e.target.value))} />
    </div>
  );
}
```

### React Example

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

function calculateCompensation(scheduleData, rates) {
  const user = new OnCallUser(
    scheduleData.userId,
    scheduleData.userName,
    scheduleData.periods.map(p => 
      new OnCallPeriod(new Date(p.start), new Date(p.end), p.timezone)
    )
  );
  
  const calculator = new OnCallPaymentsCalculator(rates.weekday, rates.weekend);
  return calculator.calculateOnCallPayment(user);
}
```

### Vue Example

```vue
<script setup>
import { ref, computed } from 'vue';
import { OnCallPaymentsCalculator, DEFAULT_RATES } from 'caloohpay/core';

const weekdayRate = ref(DEFAULT_RATES.weekdayRate);
const weekendRate = ref(DEFAULT_RATES.weekendRate);

const calculator = computed(() => 
  new OnCallPaymentsCalculator(weekdayRate.value, weekendRate.value)
);
</script>
```

## 🔄 Migration Guide

### No Changes Required for Existing Users

Version 2.1.0 is **100% backward compatible**. Existing v2.0.x code continues to work without any modifications:

```typescript
// ✅ This still works exactly as before
import { ConfigLoader, OnCallPaymentsCalculator } from 'caloohpay';

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

### Recommended Updates for New Code

For new projects, use the explicit import paths:

**For Browser/Web Apps:**

```typescript
// ✅ Use caloohpay/core
import { OnCallPaymentsCalculator } from 'caloohpay/core';
```

**For Node.js Apps:**

```typescript
// ✅ Use caloohpay/node
import { ConfigLoader, CsvWriter } from 'caloohpay/node';
```

**For Mixed Environments:**

```typescript
// Browser bundle - only includes core
import { OnCallPaymentsCalculator } from 'caloohpay/core';

// Server-side - includes everything
import { ConfigLoader } from 'caloohpay/node';
```

## 📊 Bundle Size Impact

For web applications, using `caloohpay/core` significantly reduces bundle size:

- **Before v2.1.0** (importing from `caloohpay`): Includes all Node.js dependencies
- **After v2.1.0** (importing from `caloohpay/core`): Zero Node.js dependencies

Example bundle size reduction (approximate):

- Full package: ~850KB (includes @pagerduty/pdjs, yargs, dotenv, fs polyfills)
- Core only: ~45KB (just calculation engine and Luxon)

**Savings: ~805KB (~94% reduction)**

## 🏗️ Architecture Changes

### Module Structure

```text
caloohpay/
├── core.ts          # Browser-compatible exports (NEW)
├── node.ts          # Node.js-specific exports (NEW)
└── index.ts         # Re-exports from node.ts (backward compatible)
```

### Dependency Separation

**Core Module Dependencies:**

- ✅ `luxon` - Date/time handling (works in browsers)
- ✅ TypeScript built-in types
- ❌ No `fs`, `path`, `process`, or other Node.js modules

**Node Module Additional Dependencies:**

- `fs` - File system operations (ConfigLoader, CsvWriter)
- `@pagerduty/pdjs` - PagerDuty API client
- `yargs` - CLI argument parsing
- `dotenv` - Environment variable loading

## 🧪 Testing

All 342 tests pass, including 14 new tests specifically for the export structure:

### New Test Coverage

- ✅ Core exports work without Node.js dependencies
- ✅ Node exports include all functionality
- ✅ Main index maintains backward compatibility
- ✅ Browser-style usage with hardcoded rates
- ✅ Node.js usage with ConfigLoader
- ✅ v2.0.x code compatibility

### Test Command

```bash
npm test  # All 342 tests pass
```

## 📝 Documentation Updates

### Updated Files

1. **README.md**: Added "Browser Compatibility" section with Next.js/React examples
2. **CHANGELOG.md**: Comprehensive v2.1.0 release notes with migration guide
3. **docs/index.md**: Updated package structure and usage examples
4. **docs/v2.1.0-RELEASE.md**: This release documentation
5. **package.json**: Updated description, keywords, and exports field

### API Documentation

All three entry points have comprehensive JSDoc documentation:

- `src/core.ts` - Browser usage examples
- `src/node.ts` - Node.js usage examples
- `src/index.ts` - Backward compatibility notes

Generate updated docs:

```bash
npm run docs
```

## 🚀 Publishing

### NPM Package Updates

- Version: `2.1.0`
- Description: Now mentions browser compatibility
- Keywords: Added `browser`, `nextjs`, `react`, `web`
- Exports field: Three entry points defined

### Installation

```bash
# Latest version (2.1.0)
npm install caloohpay

# Specific version
npm install caloohpay@2.1.0
```

## 🔮 Future Enhancements

This modular architecture enables future possibilities:

1. **Deno Support**: Core module already works in Deno
2. **CDN Distribution**: Browser bundle can be served via CDN (unpkg, jsDelivr)
3. **WebAssembly**: Potential for WASM compilation of core
4. **Mobile Apps**: React Native compatibility
5. **Edge Computing**: Cloudflare Workers, Vercel Edge Functions

## 🎯 Use Cases Unlocked

With browser compatibility, CalOohPay can now power:

1. **Internal Dashboards**: Real-time compensation calculators in company portals
2. **HR Systems**: Integration into payroll management UIs
3. **Mobile Apps**: React Native or Ionic applications
4. **Static Sites**: JAMstack sites with client-side calculation
5. **Analytics Platforms**: Embedded compensation widgets
6. **Team Tools**: Slack/Teams apps with embedded calculators

## 📞 Support

- **Issues**: <https://github.com/lonelydev/caloohpay/issues>
- **Discussions**: <https://github.com/lonelydev/caloohpay/discussions>
- **Documentation**: <https://lonelydev.github.io/caloohpay/>

## 🙏 Credits

This release was made possible by restructuring the codebase to separate concerns while maintaining complete backward compatibility. Special thanks to TypeScript's module system and modern package.json exports for enabling this architecture.

---

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