lichess_api/lib.rs
1//! A Rust client for [the Lichess API](https://lichess.org/api).
2//!
3//! [`client::LichessApi`] wraps an HTTP client (currently only `reqwest::Client`
4//! is supported) with an optional bearer token. Every operation is a method on
5//! `LichessApi<reqwest::Client>`, grouped into one [`api`] module per Lichess API
6//! category (`api::account`, `api::games`, `api::tv`, ...). The request/response
7//! types for a given operation live in the matching [`model`] module
8//! (`model::account`, `model::games`, ...).
9//!
10//! # Authentication
11//!
12//! Most endpoints take a bearer token. For your own account, generate a
13//! [personal API token](https://lichess.org/account/oauth/token) and pass it to
14//! [`client::LichessApi::new`]:
15//!
16//! ```no_run
17//! use lichess_api::client::LichessApi;
18//!
19//! # async fn run() -> lichess_api::error::Result<()> {
20//! let http_client = reqwest::Client::new();
21//! let token = std::env::var("LICHESS_TOKEN").ok();
22//! let api = LichessApi::new(http_client, token);
23//!
24//! let profile = api.get_profile().await?;
25//! println!("logged in as {}", profile.user.username);
26//! # Ok(())
27//! # }
28//! ```
29//!
30//! Public endpoints that don't require a token accept `LichessApi::new(client, None)`.
31//!
32//! To act on behalf of *other* users, use the OAuth2 authorization code flow
33//! with PKCE instead of a personal token — see
34//! [`model::oauth::authorize::AuthorizationUrl`] and
35//! [`model::oauth::PendingAuthorization`] for a full walkthrough, gated behind
36//! the default-on `oauth` feature.
37//!
38//! # Streamed endpoints
39//!
40//! Endpoints that stream newline-delimited JSON (board game state, TV feeds,
41//! broadcast rounds, ...) return a `Stream` of results instead of a single
42//! value, so results arrive as they're produced rather than after the whole
43//! response body has been read.
44//!
45//! # Errors
46//!
47//! Every operation returns [`error::Result`]; see [`error::Error`] for the
48//! failure cases (transport errors, non-2xx responses, deserialization
49//! failures, and OAuth-specific errors).
50
51pub mod api;
52pub mod client;
53pub mod error;
54pub mod model;