@scorio/client-sdk 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,289 @@
+# @scorio/client-sdk
+
+**TypeScript SDK for the [Scorio Sports API](https://rapidapi.com/tronin-UvwhI8kCA/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/tronin-UvwhI8kCA/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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@scorio/client-sdk",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"description": "TypeScript SDK for the Scorio Sports API — real-time odds, live scores, and historical price analytics across 80+ sports",
 	"type": "module",
 	"main": "dist/index.js",
@@ -42,7 +42,7 @@
 	"homepage": "https://github.com/ts-ign0re/scorio#readme",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/ts-ign0re/scorio.git",
+		"url": "git+https://github.com/ts-ign0re/scorio.git",
 		"directory": "packages/scorio-sdk"
 	},
 	"scripts": {