chesscom

Documentation

Overview

Package chesscom is the library behind the chesscom command line: the HTTP client, request shaping, and the typed data models for Chess.com.

The Client here is the spine every command shares. It sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public site throws under load.

Index

• Constants
• type Client
  • func NewClient(cfg Config) *Client
  • func (c *Client) GetArchives(ctx context.Context, username string) ([]string, error)
  • func (c *Client) GetCountry(ctx context.Context, code string) (*Country, error)
  • func (c *Client) GetGames(ctx context.Context, username, month string, limit int) ([]Game, error)
  • func (c *Client) GetGamesByURL(ctx context.Context, archiveURL string, limit int) ([]Game, error)
  • func (c *Client) GetLeaderboard(ctx context.Context, leaderType string, limit int) ([]Leader, error)
  • func (c *Client) GetPlayer(ctx context.Context, username string) (*Player, error)
  • func (c *Client) GetStats(ctx context.Context, username string) (*PlayerStats, error)
• type Config
  • func DefaultConfig() Config
• type Country
• type Domain
  • func (Domain) Classify(input string) (uriType, id string, err error)
  • func (Domain) Info() kit.DomainInfo
  • func (Domain) Locate(uriType, id string) (string, error)
  • func (Domain) Register(app *kit.App)
• type Game
• type Leader
• type Player
• type PlayerStats

Constants

const BaseURL = "https://" + Host + "/pub"

BaseURL is the root every request is built from.

const DefaultUserAgent = "chesscom-cli/0.1 (tamnd87@gmail.com)"

DefaultUserAgent identifies the client to Chess.com.

const Host = "api.chess.com"

Host is the site this client talks to.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client talks to Chess.com over HTTP.

func NewClient

func NewClient(cfg Config) *Client

NewClient returns a Client with the given config.

func (*Client) GetArchives

func (c *Client) GetArchives(ctx context.Context, username string) ([]string, error)

GetArchives fetches the list of game archive month URLs for a player.

func (*Client) GetCountry

func (c *Client) GetCountry(ctx context.Context, code string) (*Country, error)

GetCountry fetches country info by ISO code.

func (*Client) GetGames

func (c *Client) GetGames(ctx context.Context, username, month string, limit int) ([]Game, error)

GetGames fetches games for a player in a given month (YYYY/MM format or ""). If month is empty it auto-detects the most recent month from the archives.

func (*Client) GetGamesByURL

func (c *Client) GetGamesByURL(ctx context.Context, archiveURL string, limit int) ([]Game, error)

GetGamesByURL fetches games from an archive URL directly (e.g. .../games/2026/06).

func (*Client) GetLeaderboard

func (c *Client) GetLeaderboard(ctx context.Context, leaderType string, limit int) ([]Leader, error)

GetLeaderboard fetches leaderboard entries for the given type (rapid/blitz/bullet).

func (*Client) GetPlayer

func (c *Client) GetPlayer(ctx context.Context, username string) (*Player, error)

GetPlayer fetches a player profile by username.

func (*Client) GetStats

func (c *Client) GetStats(ctx context.Context, username string) (*PlayerStats, error)

GetStats fetches player rating stats.

type Config

type Config struct {
	BaseURL   string
	UserAgent string
	Rate      time.Duration
	Timeout   time.Duration
	Retries   int
}

Config holds all tunables for the client.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults for the Chess.com API.

type Country

type Country struct {
	Name string `json:"name"`
	Code string `json:"code"`
}

Country is Chess.com country info.

type Domain

type Domain struct{}

Domain is the chesscom driver. It carries no state; the per-run client is built by the factory Register hands kit.

func (Domain) Classify

func (Domain) Classify(input string) (uriType, id string, err error)

Classify turns any accepted input into the canonical (type, id).

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type Game

type Game struct {
	URL         string `kit:"id" json:"url"`
	White       string `json:"white"`
	WhiteRating int    `json:"white_rating"`
	Black       string `json:"black"`
	BlackRating int    `json:"black_rating"`
	Result      string `json:"result"` // white.result
	TimeClass   string `json:"time_class"`
	Rated       bool   `json:"rated"`
	EndTime     int64  `json:"end_time"`
}

Game is one Chess.com game.

type Leader

type Leader struct {
	Rank     int    `kit:"id" json:"rank"`
	Username string `json:"username"`
	Rating   int    `json:"rating"` // = score field
}

Leader is one entry from a Chess.com leaderboard.

type Player

type Player struct {
	Username  string `kit:"id" json:"username"`
	Name      string `json:"name"`
	Title     string `json:"title,omitempty"`
	Status    string `json:"status,omitempty"`
	Country   string `json:"country,omitempty"` // ISO code e.g. "US"
	Followers int    `json:"followers"`
	URL       string `json:"url"`
}

Player is a Chess.com player profile.

type PlayerStats

type PlayerStats struct {
	Username      string `kit:"id" json:"username"`
	RapidRating   int    `json:"rapid_rating,omitempty"`
	BlitzRating   int    `json:"blitz_rating,omitempty"`
	BulletRating  int    `json:"bullet_rating,omitempty"`
	TacticsRating int    `json:"tactics_rating,omitempty"`
	RapidWins     int    `json:"rapid_wins,omitempty"`
	BlitzWins     int    `json:"blitz_wins,omitempty"`
	BulletWins    int    `json:"bullet_wins,omitempty"`
}

PlayerStats holds rating info for a Chess.com player.