SportMonks SDK REPL (Interactive Console)

The SportMonks TypeScript SDK includes an interactive REPL (Read-Eval-Print Loop) for testing and exploring the API.

Installation & Usage

When installed via npm

After installing the SDK, you can use the REPL directly:

# Install the SDK
npm install @withqwerty/sportmonks-typescript-sdk

# Run the REPL
npx sportmonks-repl

# Run the advanced REPL
npx sportmonks-repl --advanced

When developing locally

If you’re working with the SDK source code:

# Simple REPL
npm run repl

# Advanced REPL
npm run repl:advanced

Features

  • 🚀 Interactive console with full SDK access
  • 🔍 Autocomplete support for resources and methods
  • 📝 Command history (persisted between sessions)
  • 🎨 Syntax highlighting and colored output
  • 📚 Built-in examples and documentation
  • 🛠️ Helper functions for data exploration

Getting Started

1. Set up your API key

Create a .env file in the project root:

SPORTMONKS_API_KEY=your_api_key_here

Or set it as an environment variable:

export SPORTMONKS_API_KEY=your_api_key_here

2. Start the REPL

npm run repl

Basic Usage

Simple Queries

// Get all leagues (limited to 5)
await client.leagues.all().limit(5).get();

// Get a specific team with includes
await client.teams.byId(1).include(['country', 'venue']).get();

// Search for players
await client.players.search('Ronaldo').limit(10).get();

Using Includes

// Get fixtures with team information
await client.fixtures.byDate('2024-01-15').include(['localteam', 'visitorteam']).get();

// Get league with nested includes
await client.leagues.byId(8).include(['country', 'seasons.stages']).get();

Complex Queries

// Filter national teams in a season
await client.teams.bySeason(19735).include(['country']).filter('national_team', 'true').get();

// Get head-to-head with full match details
await client.fixtures.headToHead(1, 14).include(['events', 'lineups']).limit(5).get();

// Get transfers between dates
await client.transfers
  .between('2024-01-01', '2024-01-31')
  .include(['player', 'fromteam', 'toteam'])
  .get();

Helper Functions

pp(response) - Pretty Print

Pretty prints the entire response object with proper formatting:

const response = await client.leagues.all().limit(3).get();
pp(response);

data(response) - Extract Data

Prints only the data array from the response:

const response = await client.teams.search('Manchester').get();
data(response);

examples() - Show Examples

Displays example queries you can run:

sportmonks > examples();

resources() - List Resources

Shows all available resources and their methods:

sportmonks > resources();

Available Resources

  • leagues - Football leagues and competitions
  • teams - Football teams
  • players - Player information
  • fixtures - Matches and game data
  • seasons - Season information
  • squads - Team squads by season
  • standings - League tables and standings
  • transfers - Player transfers
  • venues - Stadium information
  • coaches - Coach/manager data
  • referees - Referee information
  • livescores - Live match data

Protected Resources

The REPL automatically protects built-in resources and functions from being overwritten. If you try to use a protected name as a variable, you’ll get a helpful error:

// This will trigger a protective error:
const players = await players.search('Salah').get();

// Error message will suggest alternatives:
// Cannot use 'players' as a variable name!
// 'players' is a SportMonks resource and cannot be overwritten.
// Try using a different name like:
//   const playersResult = await players.search(...).get()
//   const myPlayers = await players.all().get()

Protected names include:

  • All resources: leagues, teams, players, fixtures, etc.
  • Helper functions: pp, data, type, browse, save
  • System variables: client, _

Tips and Tricks

1. Use Tab Completion

Press Tab to autocomplete resource names and methods:

sportmonks> client.lea[TAB]
sportmonks> client.leagues

2. Store Results in Variables

const leagues = await client.leagues.all().limit(10).get();
const premierLeague = leagues.data.find(l => l.name.includes('Premier'));

3. Explore Response Structure

const response = await client.teams.byId(1).get();
Object.keys(response); // See available fields

4. Use Async/Await

All API calls return promises, so use await:

// Good
const data = await client.players.byId(580).get();

// Without await (returns Promise)
const promise = client.players.byId(580).get();

5. Chain Multiple Operations

const teams = await client.teams
  .bySeason(19735)
  .include(['country', 'venue'])
  .filter('national_team', 'false')
  .page(1)
  .perPage(30)
  .get();

Keyboard Shortcuts

  • Tab - Autocomplete
  • ↑/↓ - Navigate command history
  • Ctrl+C - Cancel current input
  • Ctrl+D or .exit - Exit REPL
  • Ctrl+L - Clear screen

Error Handling

The REPL will show detailed error messages:

// API errors show full details
await client.teams.byId(999999).get();
// Error: Request failed with status code 404

// Validation errors
await client.fixtures.byDate('invalid-date').get();
// Error: Invalid date format: invalid-date. Expected YYYY-MM-DD

Environment Variables

  • SPORTMONKS_API_KEY - Your SportMonks API key
  • SPORTMONKS_TEST_API_KEY - Alternative key for testing

Notes

  • The REPL maintains a history file (.sportmonks_repl_history) for command persistence
  • All SDK features are available in the REPL
  • The client is pre-initialized and available as client
  • Use require() to load additional modules if needed