npm package: @scorio/client-sdk
Description: TypeScript SDK for the Scorio Sports API — real-time odds, live scores, and historical price analytics across 80+ sports
Author: Scorio
Latest version: 1.0.5

# @scorio/client-sdk

**TypeScript SDK for the [Scorio Sports API](https://rapidapi.com/scorio-scorio-default/api/scorio) — real-time odds, live scores, price history & analytics across 80+ sports.**

Zero dependencies. Full type safety. Works in Node.js, Deno, Bun, and browsers.

```
npm i @scorio/client-sdk
```

---

## Quick Start

```typescript
import ScorioSDK from '@scorio/client-sdk';

const client = new ScorioSDK({
  apiKey: 'YOUR_RAPIDAPI_KEY',
  host: 'YOUR_RAPIDAPI_HOST',
});

// Get all sports
const sports = await client.getSports();
console.log(sports.data);
// [{ id: "01KNS...", name: "Football", alias: "Soccer", category: "sport" }, ...]

// Get live games with scores
const live = await client.getAllLiveGames();
for (const game of live.data) {
  console.log(`${game.home_team} ${game.score_text} ${game.away_team}`);
}
// Arsenal 2:1 (67') Chelsea
// Real Madrid 0:0 (12') Barcelona

// Get full game detail with all markets & odds
const detail = await client.getGameDetail('01TESTGAME00000LIVESOC01');
for (const market of detail.data.markets) {
  console.log(market.name, market.outcomes.map(o => `${o.name} @ ${o.price}`));
}
// Match Result ["Arsenal @ 1.85", "Draw @ 3.40", "Chelsea @ 4.50"]
// Total Goals  ["Over 2.5 @ 1.72", "Under 2.5 @ 2.10"]

// Track odds movements — find where sharp money is going
const movers = await client.getOddsMovers({ minutes: 60, limit: 10 });
// [{ event_name: "Chelsea", change_percent: 18.42, current_price: 4.50, opening_price: 3.80 }]
```

---

## What You Get

| Feature | Details |
|---------|---------|
| **Live scores & odds** | Sub-second pipeline, poll every 1-2s for in-play data |
| **Prematch coverage** | 150+ days ahead, full market depth |
| **Price history** | Every odds tick recorded, 60-day retention |
| **Odds intelligence** | Steam moves, min/max/avg summaries, % change tracking |
| **Full catalog** | Sports > Regions > Competitions hierarchy |
| **Search** | Find games by team name, browse by date, starting-soon filter |

### Data Coverage

- **80+ sports** — football, basketball, tennis, cricket, esports, virtuals, racing, MMA
- **150+ days** of prematch data ahead
- **60-day** historical price retention per outcome
- **Thousands of markets** per game for major competitions
- **Global coverage** — all major leagues, tournaments, and regions worldwide

---

## All Methods

### Catalog

| Method | Description |
|--------|-------------|
| `getSports()` | List all available sports |
| `getSportsCounts()` | Sports with live and prematch game counts |
| `getRegions(sportId)` | Regions (countries) for a sport |
| `getCompetitions(regionId)` | Competitions for a region |
| `getCompetitionsBySport(sportId)` | All competitions for a sport (flat list) |

### Live

| Method | Description |
|--------|-------------|
| `getAllLiveGames()` | Every live game across all sports |
| `getLiveGamesBySport(sportId)` | Live games for one sport |
| `getLiveSnapshot()` | Full dashboard: sport counts + all live games in one call |

### Prematch

| Method | Description |
|--------|-------------|
| `getPrematchGames(sportId, opts?)` | Upcoming games for a sport (paginated) |

### Games

| Method | Description |
|--------|-------------|
| `getGamesByCompetition(competitionId, opts?)` | Games for a competition (paginated) |
| `getGamesStartingSoon(opts?)` | Games starting within N minutes |
| `searchGames(query, opts?)` | Search by team name |
| `getGameDetail(gameId)` | Full game with all markets and odds |

### Odds Intelligence

| Method | Description |
|--------|-------------|
| `getGameOddsSummary(gameId)` | Min/max/avg price per outcome |
| `getOddsMovers(opts?)` | Biggest price movements (steam moves) |
| `getEventPriceHistory(eventId, opts?)` | Full tick-level price history for an outcome |

### Schedule

| Method | Description |
|--------|-------------|
| `getSchedule(opts?)` | Games by date or date range, filterable by sport/competition |

### System

| Method | Description |
|--------|-------------|
| `health()` | API health check (no auth required) |
| `ping()` | Connectivity check (no auth required) |

---

## Configuration

```typescript
const client = new ScorioSDK({
  apiKey: 'YOUR_RAPIDAPI_KEY',   // Required — from your RapidAPI subscription
  host: 'YOUR_RAPIDAPI_HOST',    // Required — RapidAPI proxy host
  logger: true,                   // Optional — log requests to stdout (default: false)
  timeout: 15_000,                // Optional — request timeout in ms (default: 30000)
});
```

---

## Response Format

All list endpoints return:

```typescript
{
  data: T[],
  meta: { count: number }
}
```

Single-resource endpoints return:

```typescript
{
  data: T
}
```

---

## Types

Every response is fully typed. Hover over any method to see JSDoc with plan info, polling recommendations, and examples.

```typescript
import type {
  Sport, SportCount, Region, Competition,
  Game, GameInfo, GameStats, Market, Outcome,
  LiveSnapshot, OddsSummary, OddsMover, PricePoint,
  ListResponse, SingleResponse,
} from '@scorio/client-sdk';
```

### Game Object

```typescript
interface Game {
  id: string;              // Stable ULID
  home_team: string;       // "Arsenal"
  away_team: string;       // "Chelsea"
  status: 'prematch' | 'live' | 'ended';
  start_time: number;      // Unix timestamp (seconds)
  is_live: boolean;
  markets_count: number;   // Number of available markets
  competition_id: string;
  sport_id: string;
  score_text: string;      // "2:1 (67')" or "" for prematch
  info: GameInfo | null;   // Structured scores, game state, timer
  stats: GameStats | null; // Goals, corners, cards, set scores
  updated_at: string;      // ISO 8601
  markets: Market[];       // Nested markets with outcomes
}
```

### Market & Outcome

```typescript
interface Market {
  id: string;
  name: string;            // "Match Result", "Total Goals"
  type: string;            // "P1XP2", "MatchTotal2"
  line: number | null;     // 2.5 for Over/Under, null for 1X2
  outcomes: Outcome[];
}

interface Outcome {
  id: string;
  name: string;            // "Arsenal", "Over 2.5"
  price: number;           // Decimal odds: 1.85
  is_suspended: boolean;
}
```

---

## Error Handling

```typescript
import { ScorioError, PlanLimitError, RateLimitError, NetworkError } from '@scorio/client-sdk';

try {
  const games = await client.getAllLiveGames();
} catch (err) {
  if (err instanceof PlanLimitError) {
    console.log(`Upgrade your plan. Current: ${err.currentPlan}`);
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof NetworkError) {
    console.log('Network error:', err.message);
  }
}
```

---

## Polling Recommendations

| Data | Interval | Use Case |
|------|----------|----------|
| Live games & odds | 1-2s | Live scoreboards, in-play betting |
| Prematch games | 10-30s | Upcoming fixtures, prematch odds |
| Catalog | 60s | Sport/region/competition navigation |
| Schedule | 60s | Daily fixture lists |
| Odds movers | 5-10s | Steam move alerts, sharp money tracking |
| Price history | On demand | Odds charts, trend analysis |

---

## Plans

| Feature | Free | Starter ($49/mo) | Pro ($149/mo) | Business ($399/mo) |
|---------|:----:|:-----------------:|:-------------:|:-------------------:|
| Catalog & search | Yes | Yes | Yes | Yes |
| Live scores & stats | -- | Yes | Yes | Yes |
| Prematch & schedule | -- | Yes | Yes | Yes |
| Markets & odds | -- | -- | Yes | Yes |
| Price history & movers | -- | -- | Yes | Yes |

[Subscribe on RapidAPI](https://rapidapi.com/scorio-scorio-default/api/scorio) to get your API key.

---

## Use Cases

**Sportsbook / Betting Platform** — Real-time odds feed with full market depth. Hundreds of markets per game. Sub-second updates.

**Live Scoreboard** — Live scores, game states, timers, and per-period statistics across 80+ sports. Build a multi-sport live ticker in minutes.

**Odds Comparison Site** — Track price movements across outcomes. Historical price data with tick-level granularity for charts and analysis.

**Analytics Dashboard** — Odds intelligence: steam moves, min/max/avg summaries. Identify sharp money and market inefficiencies.

**Sports Content Platform** — Schedule, fixtures, team search. Build editorial calendars and daily betting previews.

**Trading Bot** — Price history API gives you every odds tick for the last 60 days. Backtest strategies with real data.

---

## Requirements

- Node.js 18+ / Deno / Bun / Modern browsers (uses native `fetch`)
- TypeScript 5+ recommended (works with JavaScript too)

## License

MIT