iracing-data-client/README.md

Fully-typed HTTP Client for the iRacing Data API with automatic code generation, built-in caching, smart authentication, and comprehensive error handling.

# iRacing Data Client

A TypeScript Data Client for the iRacing Data API with full type safety and authentication handling.

## Features

- 🏎️ Complete coverage of iRacing Data API (72+ endpoints)
- 🔒 Built-in authentication with cookie management
- 📝 Full TypeScript support with generated types
- 🎯 Tree-shakeable imports using Zod schemas
- 🚀 Modular architecture with service-based organization
- 🛡️ Proper error handling with maintenance mode detection
- 🔄 Automatic camelCase conversion for JavaScript conventions

## Installation

```bash
npm install iracing-data-client
# or
pnpm add iracing-data-client
# or
yarn add iracing-data-client
```

## Quick Start

```typescript
import { IRacingDataClient } from 'iracing-data-client';

// Initialize with credentials
const dataClient = new IRacingDataClient({
  email: 'your-email@example.com',
  password: 'your-password'
});

// Fetch track data
const tracks = await dataClient.track.get();
console.log(tracks);

// Get member info
const member = await dataClient.member.get({ custIds: [123456] });
console.log(member);
```

## Environment Variables

For testing and development, create a `.env` file:

```env
EMAIL=your-iracing-email@example.com
PASSWORD=your-iracing-password
```

## Available Services

The Data Client is organized into the following services:

- **car** - Car assets and information
- **carclass** - Car class data
- **constants** - Categories, divisions, event types
- **driverStatsByCategory** - Driver statistics by category
- **hosted** - Hosted session data
- **league** - League information and standings
- **lookup** - Countries, drivers, licenses, etc.
- **member** - Member profiles, awards, participation
- **results** - Race results and lap data  
- **season** - Season information and race guides
- **series** - Series data and statistics
- **stats** - Member statistics and world records
- **team** - Team membership data
- **timeAttack** - Time attack season results
- **track** - Track assets and configuration

## Error Handling

The Data Client includes proper error handling for common iRacing API scenarios:

```typescript
import { IRacingDataClient, IRacingError } from 'iracing-data-client';

try {
  const data = await dataClient.member.get({ custIds: [123] });
} catch (error) {
  if (error instanceof IRacingError) {
    if (error.isMaintenanceMode) {
      console.log('iRacing is in maintenance mode');
      // Handle gracefully
      return;
    }
    
    console.log(`API Error: ${error.message}`);
    console.log(`Status: ${error.status}`);
  }
}
```

## Configuration Options

```typescript
const dataClient = new IRacingDataClient({
  email: 'your-email@example.com',        // iRacing account email
  password: 'your-password',              // iRacing account password
  headers: { 'User-Agent': 'MyApp/1.0' }, // Custom headers (optional)
  fetchFn: customFetch,                   // Custom fetch function (optional)
  validateParams: true                    // Enable parameter validation (optional)
});
```

## Development

### Scripts

- `npm run sdk:generate` - Generate Data Client from API documentation
- `npm run sdk:test` - Test the Data Client with live API calls
- `npm run typecheck` - Run TypeScript type checking
- `npm run test` - Run unit tests

### Generating the Data Client

The Data Client is auto-generated from iRacing's API documentation:

```bash
npm run sdk:generate
```

This creates:
- Individual service files in `src/[service]/service.ts`
- Type definitions in `src/[service]/types.ts`  
- Main export file `src/index.ts`
- HTTP client with authentication in `src/client.ts`

### Testing

Test the Data Client against the live iRacing API:

```bash
npm run sdk:test
```

Make sure your credentials are in the `.env` file.

## API Reference

### Authentication

The Data Client handles iRacing's cookie-based authentication automatically. On first request, it will:

1. Log in with your credentials
2. Store authentication cookies
3. Follow S3 redirect links to fetch actual data
4. Handle CSV responses where applicable

### Response Types

All endpoints return fully typed responses. For example:

```typescript
// Member service
const members = await dataClient.member.get({ custIds: [123456] });
// members is typed as MemberGetResponse[]

// Track service  
const tracks = await dataClient.track.get();
// tracks is typed as TrackGetResponse (TrackGetItem[])
```

### Parameter Validation

When `validateParams: true` is set, the Data Client validates all parameters using Zod schemas:

```typescript
const dataClient = new IRacingDataClient({ 
  email: 'test@example.com',
  password: 'password',
  validateParams: true 
});

// This will throw if seasonId is not a number
await dataClient.season.list({ seasonId: 'invalid' }); // ❌ Validation error
await dataClient.season.list({ seasonId: 12345 });     // ✅ Valid
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run type checking (`npm run typecheck`)
5. Test with the live API (`npm run sdk:test`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## License

ISC License - see LICENSE file for details.

## Disclaimer

This is an unofficial Data Client for the iRacing Data API. iRacing is a trademark of iRacing.com Motorsport Simulations, LLC.