npm package: @loterias-api/sdk
Description: Official TypeScript/JavaScript SDK for Loterias API
Author: Loterias API
Latest version: 1.0.0

# @loteria-api/sdk

Official TypeScript/JavaScript SDK for [Loteria API](https://loteria-api.com).

## Installation

```bash
npm install @loteria-api/sdk
# or
yarn add @loteria-api/sdk
# or
pnpm add @loteria-api/sdk
```

## Quick Start

```typescript
import { LoteriaApi } from '@loteria-api/sdk';

const api = new LoteriaApi({
  apiKey: 'lat_xxx...' // Get your API key at https://loteria-api.com
});

// Get latest Euromillones result
const { data } = await api.results.getLatest('euromillones');
console.log(data.combination); // [4, 15, 23, 38, 42]
console.log(data.resultData.estrellas); // [3, 9]
```

## Usage Examples

### Get Latest Results

```typescript
// Latest result for a specific game
const euromillones = await api.results.getLatest('euromillones');
const primitiva = await api.results.getLatest('primitiva');
const bonoloto = await api.results.getLatest('bonoloto');

// Latest results for ALL games
const all = await api.results.getLatestAll();
console.log(all.data.euromillones.combination);
console.log(all.data.primitiva.combination);
```

### Check Your Numbers

```typescript
const { data } = await api.results.checkNumbers('euromillones', {
  numbers: [4, 15, 23, 38, 42],
  extraNumbers: [3, 11] // Stars for Euromillones
});

if (data.isWinner) {
  console.log(`You won! Prize: ${data.prize.formattedPrize}`);
  console.log(`Category: ${data.prize.categoryName}`);
} else {
  console.log(`No luck. You matched ${data.mainNumbersMatched} numbers.`);
}
```

### Query Historical Results

```typescript
// Results from a date range
const results = await api.results.getByDateRange(
  'euromillones',
  '2024-01-01',
  '2024-12-31',
  { page: 1, limit: 10 }
);

// Results from a specific date
const dateResults = await api.results.getByDate('primitiva', '2024-06-15');

// Filter by minimum jackpot
const bigJackpots = await api.results.listByGame('euromillones', {
  minJackpot: 100000000, // 100 million
  year: 2024
});
```

### Get Upcoming Draws

```typescript
// All upcoming draws
const upcoming = await api.draws.listUpcoming();

// Next draw for each game
const next = await api.draws.getNextAll();
console.log(`Next Euromillones: ${next.data.euromillones?.drawDate}`);
console.log(`Jackpot: ${next.data.euromillones?.jackpotFormatted}`);

// Upcoming draws for a specific game
const euromillonesDraws = await api.draws.listUpcomingByGame('euromillones');
```

## Available Game Types

| Slug | Name |
|------|------|
| `bonoloto` | Bonoloto |
| `euromillones` | Euromillones |
| `primitiva` | La Primitiva |
| `gordo` | El Gordo |
| `nacional` | Loteria Nacional |
| `eurodreams` | EuroDreams |
| `quiniela` | La Quiniela |
| `quinigol` | Quinigol |
| `lototurf` | Lototurf |
| `quintuple` | Quintuple Plus |

## Error Handling

```typescript
import { LoteriaApi, LoteriaApiError } from '@loteria-api/sdk';

try {
  const result = await api.results.getLatest('euromillones');
} catch (error) {
  if (error instanceof LoteriaApiError) {
    console.error(`API Error: ${error.code}`);
    console.error(`Message: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);

    if (error.code === 'RATE_LIMIT_EXCEEDED') {
      // Wait and retry
    }
    if (error.code === 'TOKEN_LIMIT_EXCEEDED') {
      // Upgrade plan or wait for reset
    }
  }
}
```

## TypeScript Support

This SDK is written in TypeScript and provides full type definitions:

```typescript
import type {
  Result,
  Draw,
  GameType,
  CheckNumbersResult
} from '@loteria-api/sdk';

const gameType: GameType = 'euromillones';
const result: Result = await api.results.getLatest(gameType).then(r => r.data);
```

## Configuration

```typescript
const api = new LoteriaApi({
  apiKey: 'lat_xxx...',           // Required
  baseUrl: 'https://custom.url',  // Optional (default: https://api.loteria-api.com/api/v1)
  timeout: 60000                  // Optional (default: 30000ms)
});
```

## License

MIT