Core Bracket Client SDK

Official JavaScript/TypeScript client for the Core Bracket tournament management service.

Installation

npm install core-bracket-client

or

pnpm add core-bracket-client

or

yarn add core-bracket-client

Quick Start

import { CoreBracketClient, TournamentFormat } from 'core-bracket-client';

// Initialize the client
const client = new CoreBracketClient({
  baseUrl: 'https://your-api-url.com',
  apiKey: 'your-api-key'
});

// Create a team
const team = await client.teams.create({
  id: 'team-1',
  name: 'Manchester United',
  seed: 1,
  stats: {
    wins: 0,
    draws: 0,
    losses: 0,
    points: 0,
    goalsFor: 0,
    goalsAgainst: 0,
    goalDifference: 0
  }
});

// Create a tournament
const tournament = await client.tournaments.create({
  id: 'tournament-1',
  name: 'Spring Championship 2025',
  format: TournamentFormat.SINGLE_ELIMINATION,
  teamIds: ['team-1', 'team-2', 'team-3', 'team-4']
});

// Start the tournament
await client.tournaments.start('tournament-1');

// Get tournament standings
const standings = await client.tournaments.getStandings('tournament-1');

Configuration

CoreBracketClientConfig

interface CoreBracketClientConfig {
  baseUrl: string;        // Required: Base URL of your API service
  apiKey: string;         // Required: Your API key (X-API-KEY header)
  timeout?: number;       // Optional: Request timeout in ms (default: 30000)
}

API Reference

Teams

Get All Teams

const teams = await client.teams.getAll();

Get Team by ID

const team = await client.teams.getById('team-1');

Create Team

const team = await client.teams.create({
  id: 'team-1',
  name: 'Manchester United',
  seed: 1,
  stats: {
    wins: 0,
    draws: 0,
    losses: 0,
    points: 0,
    goalsFor: 0,
    goalsAgainst: 0,
    goalDifference: 0
  },
  metadata: {
    country: 'England',
    founded: 1878
  }
});

Update Team

const team = await client.teams.update('team-1', {
  name: 'Manchester United FC',
  seed: 2
});

Delete Team

await client.teams.delete('team-1');

Tournaments

Get All Tournaments

// Get all tournaments
const tournaments = await client.tournaments.getAll();

// Filter by status
const activeTournaments = await client.tournaments.getAll({
  status: 'IN_PROGRESS'
});

// Filter by format
const singleEliminationTournaments = await client.tournaments.getAll({
  format: 'SINGLE_ELIMINATION'
});

Get Tournament by ID

const tournament = await client.tournaments.getById('tournament-1');

Get Tournament Details

Returns tournament with teams and matches included.

const details = await client.tournaments.getDetails('tournament-1');
console.log(details.teams);     // Array of Team objects
console.log(details.matches);   // Array of Match objects

Get Tournament Standings

const standings = await client.tournaments.getStandings('tournament-1');

Get Team Journey

Track a team's progression through a tournament.

const journey = await client.tournaments.getTeamJourney('tournament-1', 'team-1');
console.log(journey.matchesPlayed);  // Number of matches played
console.log(journey.matchesWon);     // Number of matches won
console.log(journey.matches);        // Array of all matches

Create Tournament

const tournament = await client.tournaments.create({
  id: 'tournament-1',
  name: 'Spring Championship',
  format: TournamentFormat.SINGLE_ELIMINATION,
  teamIds: ['team-1', 'team-2', 'team-3', 'team-4'],
  config: {
    thirdPlaceMatch: true
  }
});

Update Tournament

const tournament = await client.tournaments.update('tournament-1', {
  name: 'Updated Championship Name'
});

Start Tournament

const tournament = await client.tournaments.start('tournament-1');

Complete Tournament

const tournament = await client.tournaments.complete('tournament-1', 'team-1');

Cancel Tournament

const tournament = await client.tournaments.cancel('tournament-1');

Advance Stage (Multi-Stage Only)

const tournament = await client.tournaments.advanceStage('tournament-1', {
  method: 'ranking',
  reverse: false
});

Delete Tournament

await client.tournaments.delete('tournament-1');

Matches

Get All Matches

// Get all matches
const matches = await client.matches.getAll();

// Filter by tournament
const tournamentMatches = await client.matches.getAll({
  tournamentId: 'tournament-1'
});

// Filter by tournament and round
const roundMatches = await client.matches.getAll({
  tournamentId: 'tournament-1',
  round: 2
});

// Filter by team
const teamMatches = await client.matches.getAll({
  teamId: 'team-1'
});

Get Pending Matches

const pendingMatches = await client.matches.getPending('tournament-1');

Get Match by ID

const match = await client.matches.getById('match-1');

Create Match

const match = await client.matches.create({
  id: 'match-1',
  tournamentId: 'tournament-1',
  round: 1,
  matchNumber: 1,
  team1Id: 'team-1',
  team2Id: 'team-2',
  status: MatchStatus.PENDING
});

Update Match

const match = await client.matches.update('match-1', {
  scheduledTime: new Date('2025-12-25T15:00:00Z')
});

Record Match Result

const match = await client.matches.recordResult('match-1', {
  team1Id: 'team-1',
  team2Id: 'team-2',
  team1Score: 3,
  team2Score: 1
});

Delete Match

await client.matches.delete('match-1');

TypeScript Support

This library is written in TypeScript and includes full type definitions.

Available Types

import {
  Team,
  Tournament,
  Match,
  TournamentFormat,
  TournamentStatus,
  MatchStatus,
  CreateTeamDto,
  UpdateTeamDto,
  CreateTournamentDto,
  UpdateTournamentDto,
  CreateMatchDto,
  UpdateMatchDto,
  RecordMatchResultDto,
  TournamentWithDetails,
  TeamJourney,
} from 'core-bracket-client';

Enums

// Tournament formats
enum TournamentFormat {
  ROUND_ROBIN = 'ROUND_ROBIN',
  SINGLE_ELIMINATION = 'SINGLE_ELIMINATION',
  DOUBLE_ELIMINATION = 'DOUBLE_ELIMINATION',
  PLAYOFF = 'PLAYOFF',
  MULTI_STAGE = 'MULTI_STAGE',
}

// Tournament status
enum TournamentStatus {
  PENDING = 'PENDING',
  IN_PROGRESS = 'IN_PROGRESS',
  COMPLETED = 'COMPLETED',
  CANCELLED = 'CANCELLED',
}

// Match status
enum MatchStatus {
  PENDING = 'PENDING',
  COMPLETED = 'COMPLETED',
  BYE = 'BYE',
  CANCELLED = 'CANCELLED',
}

Error Handling

The client will throw errors for failed requests. Use try-catch to handle them:

try {
  const tournament = await client.tournaments.getById('non-existent');
} catch (error) {
  if (error.response) {
    // Server responded with error
    console.error('Status:', error.response.status);
    console.error('Message:', error.response.data.message);
  } else if (error.request) {
    // No response received
    console.error('No response from server');
  } else {
    // Request setup error
    console.error('Error:', error.message);
  }
}

Examples

Complete Tournament Workflow

import { CoreBracketClient, TournamentFormat, MatchStatus } from 'core-bracket-client';

const client = new CoreBracketClient({
  baseUrl: 'https://api.example.com',
  apiKey: 'your-api-key'
});

async function runTournament() {
  // 1. Create teams
  const teams = await Promise.all([
    client.teams.create({ id: 'team-1', name: 'Team A', seed: 1, stats: {...} }),
    client.teams.create({ id: 'team-2', name: 'Team B', seed: 2, stats: {...} }),
    client.teams.create({ id: 'team-3', name: 'Team C', seed: 3, stats: {...} }),
    client.teams.create({ id: 'team-4', name: 'Team D', seed: 4, stats: {...} }),
  ]);

  // 2. Create tournament
  const tournament = await client.tournaments.create({
    id: 'my-tournament',
    name: 'Championship 2025',
    format: TournamentFormat.SINGLE_ELIMINATION,
    teamIds: teams.map(t => t.id)
  });

  // 3. Start tournament
  await client.tournaments.start(tournament.id);

  // 4. Create matches
  const match1 = await client.matches.create({
    id: 'match-1',
    tournamentId: tournament.id,
    round: 1,
    matchNumber: 1,
    team1Id: 'team-1',
    team2Id: 'team-2',
    status: MatchStatus.PENDING
  });

  // 5. Record results
  await client.matches.recordResult(match1.id, {
    team1Id: 'team-1',
    team2Id: 'team-2',
    team1Score: 3,
    team2Score: 1
  });

  // 6. Get standings
  const standings = await client.tournaments.getStandings(tournament.id);
  console.log('Standings:', standings);

  // 7. Complete tournament
  await client.tournaments.complete(tournament.id, 'team-1');
}

runTournament().catch(console.error);

Multi-Stage Tournament

const tournament = await client.tournaments.create({
  id: 'world-cup',
  name: 'World Cup 2025',
  format: TournamentFormat.MULTI_STAGE,
  teamIds: ['team-1', 'team-2', 'team-3', 'team-4', 'team-5', 'team-6', 'team-7', 'team-8'],
  currentStageIndex: 0,
  stages: [
    {
      id: 'group-stage',
      name: 'Group Stage',
      format: 'ROUND_ROBIN',
      teamIds: ['team-1', 'team-2', 'team-3', 'team-4', 'team-5', 'team-6', 'team-7', 'team-8'],
      config: { advancingTeams: 4 }
    },
    {
      id: 'knockout',
      name: 'Knockout Stage',
      format: 'SINGLE_ELIMINATION',
      teamIds: [],
      config: { thirdPlaceMatch: true }
    }
  ]
});

// After group stage completes
await client.tournaments.advanceStage('world-cup');

License

MIT

Support

For issues and questions, please visit the GitHub repository.