Class Client

java.lang.Object
chariot.internal.ClientBase
chariot.Client
Direct Known Subclasses:
ClientAuth
public class Client extends chariot.internal.ClientBase

Provides access to the Lichess API.

This interface provides access to the public API of Lichess (which doesn't need a Lichess account.) The ClientAuth interface provides access to the authenticated API of Lichess (which needs a Lichess account.)

Example of how to get a reference to a Client interface

Client client = Client.basic();

// Tada!

// And then use it...
var user = client.users().byId("lichess");

For accessing authenticated parts of the API, one needs a token with appropriate access rights / scopes. This library support PKCE Authorization Code flow (auth(Consumer, Consumer)), but one can also create a Personal Access Token manually.

Example of how to get a reference to a ClientAuth interface

String token = ... // Token with scope email:read
ClientAuth client = Client.auth(token);

// Tada!

// And then use it...
var email = client.account().emailAddress();

The responses from the API are modelled with One<T> and Many<T> "containers".
Their documentation covers different ways of accessing the contents of the containers.
The contents of the containers are typically data models from the chariot.model package.

  • Method Details

    • users

      public UsersApi users()
      Access registered users on Lichess.

    • analysis

      public AnalysisApi analysis()
      Access Lichess cloud evaluations database.
      Overrides:
      analysis in class chariot.internal.ClientBase

    • bot

      public BotApi bot()
      Access Lichess online bots.
      For more bot operations, see ClientAuth.bot()
      Overrides:
      bot in class chariot.internal.ClientBase

    • broadcasts

      public BroadcastsApi broadcasts()
      Relay chess events on Lichess.

      Official broadcasts are maintained by Lichess, but you can create your own broadcasts to cover any live game or chess event. You will need to publish PGN on a public URL so that Lichess can pull updates from it. Alternatively, you can push PGN updates to Lichess using this API.

      Broadcasts are organized in tournaments, which have several rounds, which have several games. You must first create a tournament, then you can add rounds to them.

      Overrides:
      broadcasts in class chariot.internal.ClientBase

    • challenges

      public ChallengesApi challenges()
      Open-ended challenges. For authenticated challenges, see ChallengesApiAuth
      Overrides:
      challenges in class chariot.internal.ClientBase

    • externalEngine

      public ExternalEngineApi externalEngine()
      External engine. For engine management, see ExternalEngineApiAuth
      Overrides:
      externalEngine in class chariot.internal.ClientBase

    • fide

      public FideApi fide()
      Download FIDE player info
      Overrides:
      fide in class chariot.internal.ClientBase

    • games

      public GamesApi games()
      Access games and TV channels, played on Lichess.
      Overrides:
      games in class chariot.internal.ClientBase

    • openingExplorer

      public OpeningExplorerApi openingExplorer()
      Lookup positions from the Lichess opening explorer.
      Overrides:
      openingExplorer in class chariot.internal.ClientBase

    • puzzles

      public PuzzlesApi puzzles()
      Access Lichess puzzle history and dashboard.
      Overrides:
      puzzles in class chariot.internal.ClientBase

    • simuls

      public SimulsApi simuls()
      Access simuls played on Lichess.
      Overrides:
      simuls in class chariot.internal.ClientBase

    • studies

      public StudiesApi studies()
      Access Lichess studies.
      Overrides:
      studies in class chariot.internal.ClientBase

    • tablebase

      public TablebaseApi tablebase()
      Lookup positions from the Lichess tablebase server.
      Overrides:
      tablebase in class chariot.internal.ClientBase

    • teams

      public TeamsApi teams()
      Access and manage Lichess teams and their members.
      Overrides:
      teams in class chariot.internal.ClientBase

    • tournaments

      public TournamentsApi tournaments()
      Access Arena and Swiss tournaments played on Lichess.
      Overrides:
      tournaments in class chariot.internal.ClientBase

    • custom

      public CustomApi custom()
      Use chariot for custom endpoints
      Overrides:
      custom in class chariot.internal.ClientBase

    • store

      public boolean store(Preferences prefs)
      Stores the client configuration into the provided preferences node
      Overrides:
      store in class chariot.internal.ClientBase
      Parameters:
      prefs - The preferences node to store this client configuration to

    • basic

      public static Client basic()
      Creates a default client

    • auth

      public static ClientAuth auth(String token)
      Creates a default client using the provided token to use the authenticated parts of the API
      Parameters:
      token - A token to use for the authenticated parts of the API

    • basic

      public static Client basic(Consumer<Builders.ConfigBuilder> params)
      Creates a customized client
      Parameters:
      params - A configuration parameters builder

    • withToken

      public ClientAuth withToken(String token)

      Use a pre-created Personal Access Token to use the authenticated API

      String token = ...
Client basic = Client.basic();
ClientAuth auth = basic.withToken(token);

var challengeResult = auth.challenges().challenge(...);
      Parameters:
      token - pre-created Personal Access Token - @see Personal Access Token

    • withToken

      public ClientAuth withToken(Supplier<char[]> token)

      Use a pre-created Personal Access Token to use the authenticated API

      Supplier<char[]> token = ...
Client basic = Client.basic();
ClientAuth auth = basic.withToken(token);

var challengeResult = auth.challenges().challenge(...);
      Parameters:
      token - pre-created Personal Access Token - @see Personal Access Token

    • auth

      public static ClientAuth auth(Consumer<Builders.ConfigBuilder> params, Supplier<char[]> token)
      Creates a customizable client using the provided configuration parameters builder.
      Parameters:
      params - A configuration parameters builder

    • auth

      public static ClientAuth auth(Consumer<Builders.ConfigBuilder> params, String token)
      Creates a customizable client using the provided configuration parameters builder.
      Parameters:
      params - A configuration parameters builder

    • auth

      public static ClientAuth auth(Supplier<char[]> token)
      Creates a default client using the provided token to use the authenticated parts of the API
      Parameters:
      token - A token to use for the authenticated parts of the API

    • withPkce

      public Client.AuthResult withPkce(Consumer<URI> uriHandler, Consumer<Client.PkceConfig> pkce)

      Use OAuth PKCE flow to make it possible for your user to grant access to your application.

      Client basic = Chariot.basic();

AuthResult authResult = basic.withPkce(
    uri -> System.out.format("Visit %s to review and grant access%n", uri),
    pkce -> pkce.scope(Scope.challenge_read, Scope.challenge_write));

if (! (authResult instanceof AuthOk ok)) return;

ClientAuth auth = ok.client();
var challengeResult = auth.challenges().challenge(...);
      Parameters:
      uriHandler - The generated Lichess URI that your user can visit to review and approve granting access to your application
      pkce - Configuration of for instance which scopes if any that the resulting Access Token should include.

    • auth

      public static Client.AuthResult auth(Consumer<URI> uriHandler, Consumer<Client.PkceConfig> pkce)

      Use OAuth PKCE flow to make it possible for your user to grant access to your application.

      AuthResult authResult = Client.auth(
    uri -> System.out.format("Visit %s to review and grant access%n", uri),
    pkce -> pkce.scope(Scope.challenge_read, Scope.challenge_write));

if (! (authResult instanceof AuthOk ok)) return;

ClientAuth auth = ok.client();
var challengeResult = auth.challenges().challenge(...);
      Parameters:
      uriHandler - The generated Lichess URI that your user can visit to review and approve granting access to your application
      pkce - Configuration of for instance which scopes if any that the resulting Access Token should include.

    • auth

      public static Client.AuthResult auth(Consumer<Builders.ConfigBuilder> config, Consumer<URI> uriHandler, Consumer<Client.PkceConfig> pkce)

      Use OAuth PKCE flow to make it possible for your user to grant access to your application.

      AuthResult authResult = Client.auth(
    conf -> conf.api("http://localhost:9663"),
    uri -> System.out.format("Visit %s to review and grant access%n", uri),
    pkce -> pkce.scope(Scope.challenge_read, Scope.challenge_write));

if (! (authResult instanceof AuthOk ok)) return;

ClientAuth auth = ok.client();
var challengeResult = auth.challenges().challenge(...);
      Parameters:
      config - Customized client configuration such as enabling logging and number of retries etc.
      uriHandler - The generated Lichess URI that your user can visit to review and approve granting access to your application
      pkce - Configuration of for instance which scopes if any that the resulting Access Token should include.

    • load

      public static Client load(Preferences prefs)
      Creates a customized client from a preferences node
      See store(Preferences)
      Parameters:
      prefs -

      A configuration preferences node

        if (client instanceof ClientAuth auth) ...

    • load

      public static ClientAuth load(Preferences prefs, String token)
      Creates an authenticated customized client from a preferences node with provided token
      Parameters:
      prefs - A configuration preferences node
      token - A token to use for the authenticated parts of the API

    • asAuth

      public Opt<ClientAuth> asAuth()
      Retrieves an Opt containing a ClientAuth if this is such a client, otherwise empty.

    • logging

      public void logging(Consumer<Builders.LoggingBuilder> params)
      Configure logging levels