Package Exports

core-bracket-client
core-bracket-client/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (core-bracket-client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Core Bracket Client SDK

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

Installation

npm install core-bracket-client

pnpm add core-bracket-client

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.