lichess

Documentation

Overview

Package lichess is the library behind the lichess command line: the HTTP client, request shaping, and the typed data models for Lichess.

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) GetGames(ctx context.Context, username string, limit int, perfType string) ([]Game, error)
  • func (c *Client) GetLeaderboard(ctx context.Context, nb int, perfType string) ([]LeaderEntry, error)
  • func (c *Client) GetPage(ctx context.Context, p string) (*Page, error)
  • func (c *Client) GetPerfStat(ctx context.Context, username, perfType string) (*PerfStat, error)
  • func (c *Client) GetPuzzle(ctx context.Context) (*Puzzle, error)
  • func (c *Client) GetPuzzleByID(ctx context.Context, id string) (*Puzzle, error)
  • func (c *Client) GetTV(ctx context.Context) (*TVGame, error)
  • func (c *Client) GetUser(ctx context.Context, username string) (*User, error)
  • func (c *Client) PageLinks(ctx context.Context, p string, limit int) ([]*Page, error)
• type Config
  • func DefaultConfig() Config
• 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 LeaderEntry
• type Page
• type PerfStat
• type Puzzle
• type TVGame
• type TopPlayer
• type User

Constants

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

BaseURL is the root every request is built from.

const DefaultUserAgent = "lichess-cli/0.1.0 (github.com/tamnd/lichess-cli)"

DefaultUserAgent identifies the client to Lichess.

const Host = "lichess.org"

Host is the site this client talks to.

Types

type Client

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

Client talks to Lichess over HTTP.

func NewClient

func NewClient(cfg Config) *Client

NewClient returns a Client with the given config.

func (*Client) GetGames

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

GetGames fetches recent games for a player as NDJSON.

func (*Client) GetLeaderboard

func (c *Client) GetLeaderboard(ctx context.Context, nb int, perfType string) ([]LeaderEntry, error)

GetLeaderboard fetches the leaderboard for a perf type.

func (*Client) GetPage

func (c *Client) GetPage(ctx context.Context, p string) (*Page, error)

GetPage fetches one page by its path.

func (*Client) GetPerfStat

func (c *Client) GetPerfStat(ctx context.Context, username, perfType string) (*PerfStat, error)

GetPerfStat fetches performance statistics for a player and perf type.

func (*Client) GetPuzzle

func (c *Client) GetPuzzle(ctx context.Context) (*Puzzle, error)

GetPuzzle fetches the daily puzzle.

func (*Client) GetPuzzleByID

func (c *Client) GetPuzzleByID(ctx context.Context, id string) (*Puzzle, error)

GetPuzzleByID fetches a puzzle by its ID.

func (*Client) GetTV

func (c *Client) GetTV(ctx context.Context) (*TVGame, error)

GetTV fetches the current TV game.

func (*Client) GetUser

func (c *Client) GetUser(ctx context.Context, username string) (*User, error)

GetUser fetches a player profile by username.

func (*Client) PageLinks

func (c *Client) PageLinks(ctx context.Context, p string, limit int) ([]*Page, error)

PageLinks is kept for the kit domain driver.

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 Lichess API.

type Domain

type Domain struct{}

Domain is the lichess 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 {
	ID      string `kit:"id" json:"id"`
	White   string `json:"white"`   // white player name
	Black   string `json:"black"`   // black player name
	Winner  string `json:"winner"`  // "white", "black", or ""
	Status  string `json:"status"`  // status.name
	Variant string `json:"variant"` // speed/perf name
	Moves   string `json:"moves"`   // first 20 space-separated moves
}

Game is one Lichess game record.

type LeaderEntry

type LeaderEntry = TopPlayer

LeaderEntry is an alias kept for backward compat within this package.

type Page

type Page struct {
	ID    string `json:"id" kit:"id"`
	URL   string `json:"url"`
	Title string `json:"title,omitempty"`
	Body  string `json:"body,omitempty" kit:"body"`
}

Page is used by the kit domain driver as the URI-addressable resource.

type PerfStat

type PerfStat struct {
	Username   string  `json:"username"`
	PerfType   string  `json:"perf_type"`
	Games      int     `json:"games"`
	Wins       int     `json:"wins"`
	Losses     int     `json:"losses"`
	Draws      int     `json:"draws"`
	Rating     int     `json:"rating,omitempty"`
	Rank       int     `json:"rank,omitempty"`
	Percentile float64 `json:"percentile,omitempty"`
	WinStreak  int     `json:"win_streak,omitempty"`
	PlayStreak int     `json:"play_streak,omitempty"`
}

PerfStat is performance statistics for one perf type.

type Puzzle

type Puzzle struct {
	ID       string `kit:"id" json:"id"`
	Rating   int    `json:"rating"`
	Plays    int    `json:"plays"`
	Themes   string `json:"themes"`   // comma-joined
	Solution string `json:"solution"` // space-joined moves
}

Puzzle is the daily Lichess puzzle.

type TVGame

type TVGame struct {
	ID          string `json:"id"`
	FEN         string `json:"fen"`
	Color       string `json:"color"`
	Speed       string `json:"speed"`
	WhitePlayer string `json:"white_player"`
	BlackPlayer string `json:"black_player"`
	WhiteRating int    `json:"white_rating,omitempty"`
	BlackRating int    `json:"black_rating,omitempty"`
}

TVGame is the current Lichess TV broadcast game.

type TopPlayer

type TopPlayer struct {
	Username string `kit:"id" json:"username"`
	Title    string `json:"title,omitempty"`
	Rating   int    `json:"rating"`
}

TopPlayer is one entry in a Lichess leaderboard.

type User

type User struct {
	Username     string `kit:"id" json:"username"`
	Title        string `json:"title,omitempty"`
	URL          string `json:"url,omitempty"`
	BulletRating int    `json:"bullet_rating,omitempty"`
	BlitzRating  int    `json:"blitz_rating,omitempty"`
	RapidRating  int    `json:"rapid_rating,omitempty"`
	TotalGames   int    `json:"total_games"`
	WinCount     int    `json:"wins"`
	LossCount    int    `json:"losses"`
	DrawCount    int    `json:"draws"`
}

User is a Lichess player profile.