@esportsapp/sdk/README.md

Type-safe SDK for the public endpoints of the eSportsApp

# EsportsApp SDK

A type-safe SDK for the EsportsApp OpenAPI, built with TypeScript and designed for maximum developer experience.

## Features

- **Type-safe**: Full TypeScript support with inferred types
- **Fluent API**: Prisma-like query builder for easy configuration
- **Extensible**: Modular architecture for adding new API endpoints
- **Lightweight**: Minimal dependencies, built for performance

## Installation

```bash
# If using npm
npm install @esportsapp/sdk

# If using bun (recommended)
bun add @esportsapp/sdk
```

## Quick Start

```typescript
import { createSDK } from '@esportsapp/sdk';

// Create SDK instance with your API key
const sdk = createSDK({
  apiKey: 'your-api-key',
  userAgent: 'MyApp/1.0'
});

// NEW: Intuitive season/mode chaining (like Prisma!)
const playerStats = await sdk.r6
  .stats('SomePlayer', 'uplay')
  .season('solar-raid').mode('casual')          // Solar Raid with casual mode
  .season('commanding-force').mode('ranked');   // Commanding Force with ranked mode

console.log(playerStats.profile.displayName);
console.log(playerStats.seasonalRecords?.['solar-raid']?.casual);
console.log(playerStats.seasonalRecords?.['commanding-force']?.ranked);
```

## 🔥 Improved UX Features

### No More `.execute()` - Direct Await
```typescript
// Old way
const stats = await sdk.r6.stats('player').execute();

// New way - just await directly!
const stats = await sdk.r6.stats('player');
```

### Prisma-like Season/Mode Chaining
```typescript
// Intuitive chaining - specify exactly what you want
const stats = await sdk.r6
  .stats('player')
  .season('solar-raid').mode('casual')
  .season('commanding-force').mode('ranked')
  .season('dread-factor').mode('casual').mode('ranked'); // Multiple modes per season
```

### Object-based Configuration
```typescript
// Alternative object syntax for complex configurations
const stats = await sdk.r6
  .stats('player')
  .where({
    seasons: {
      'solar-raid': { casual: true },
      'commanding-force': { ranked: true },
      'dread-factor': { casual: true, ranked: true }
    }
  });
```

## API Reference

### SDK Configuration

```typescript
interface SDKConfig {
  apiKey: string;      // Your API key for authentication
  userAgent: string;   // User agent string for requests
  baseURL?: string;    // API base URL (defaults to http://localhost:3005)
}
```

### R6 Stats API

#### Basic Usage

```typescript
// Simple stats lookup - no .execute() needed!
const stats = await sdk.r6.stats('playername');

// With platform specification
const stats = await sdk.r6.stats('playername', 'psn');
```

#### Field Selection

```typescript
// Select specific fields (similar to Prisma)
const stats = await sdk.r6
  .stats('playername')
  .select(['profile', 'seasonalRecords']);

// Include additional fields
const stats = await sdk.r6
  .stats('playername')
  .select(['profile'])
  .include(['rankedStats']);
```

#### NEW: Intuitive Season/Mode Chaining

```typescript
// Chain seasons and modes individually - much more intuitive!
const stats = await sdk.r6
  .stats('playername')
  .season('solar-raid').mode('casual')
  .season('commanding-force').mode('ranked')
  .season('dread-factor').mode('casual').mode('ranked');

// You can also use object-based configuration
const stats = await sdk.r6
  .stats('playername')
  .where({
    seasons: {
      'solar-raid': { casual: true },
      'commanding-force': { ranked: true },
      'dread-factor': { casual: true, ranked: true }
    }
  });
```

#### Traditional Season and Mode Filtering

```typescript
// Traditional array-based filtering still works
const stats = await sdk.r6
  .stats('playername')
  .seasons(['solar-raid', 'commanding-force'])
  .modes(['ranked', 'casual']);
```

#### Raw Response

```typescript
// Get raw API response without shaping
const rawStats = await sdk.r6
  .stats('playername')
  .raw()
  .execute();
```

### Error Handling

```typescript
try {
  // Direct await - no .execute() needed!
  const stats = await sdk.r6.stats('playername');
  console.log(stats);
} catch (error) {
  console.error('API Error:', error.message);
}
```

## Available Seasons

The following seasons are supported:

```
black-ice, dust-line, skull-rain, red-crow, velvet-shell, operation-health,
blood-orchid, white-noise, chimera, para-bellum, grim-sky, wind-bastion,
burnt-horizon, phantom-sight, ember-rise, shifting-tides, void-edge,
steel-wave, shadow-legacy, neon-dawn, crimson-heist, north-star,
crystal-guard, high-calibre, demon-veil, vector-glare, brutal-swarm,
solar-raid, commanding-force, dread-factor, heavy-mettle, deep-freeze,
deadly-omen, new-blood, twin-shells, collision-point, prep-phase, daybreak,
high-stakes
```

## Available Game Modes

- `casual`
- `standard`
- `ranked`

## Available Platforms

- `uplay` (default)
- `xbl` (Xbox Live)
- `psn` (PlayStation Network)

## Extending the SDK

The SDK is designed to be easily extensible. To add new API endpoints:

1. Create a new module in `src/`
2. Define your types in a `types.ts` file
3. Implement the client in a `client.ts` file
4. Export everything from an `index.ts` file
5. Add exports to the main `index.ts`

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT