litchee 0.1.5

Async, builder-pattern Rust client for the Lichess API: full endpoint coverage, NDJSON streaming, and OAuth2 PKCE ('Log in with Lichess').
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! The Games API: export games (JSON, NDJSON, or PGN) and import PGN.
//!
//! Reached through [`LichessClient::games`].

use reqwest::Method;

use crate::client::LichessClient;
use crate::config::Host;
use crate::error::Result;
use crate::http;

mod export;
mod model;
mod stream;

pub use export::{
    CurrentGameRequest, ExportBookmarksRequest, ExportByIdsRequest, GameExportRequest, GameSort,
    UserGamesRequest,
};
pub use model::{
    LichessGame, LichessGameArenaTour, LichessGameChatMessage, LichessGameClock,
    LichessGameDivision, LichessGameMoveAnalysis, LichessGameMoveUpdate, LichessGameOpening,
    LichessGamePlayer, LichessGamePlayers, LichessGameStatusName, LichessGameSwissTour,
    LichessImportedGame, LichessMoveJudgment, LichessNowPlaying, LichessNowPlayingGame,
    LichessNowPlayingOpponent, LichessPlayerAnalysis,
};

/// Accessor for the Games API.
#[derive(Debug)]
pub struct GamesApi<'a> {
    client: &'a LichessClient,
}

impl<'a> GamesApi<'a> {
    /// Binds the accessor to a client.
    pub(crate) fn new(client: &'a LichessClient) -> Self {
        Self { client }
    }

    /// Starts a single-game export. `GET /game/export/{gameId}`
    ///
    /// Finish with [`json`](GameExportRequest::json) or
    /// [`pgn`](GameExportRequest::pgn).
    #[must_use]
    pub fn export(&self, game_id: &'a str) -> GameExportRequest<'a> {
        GameExportRequest::new(self.client, game_id)
    }

    /// Starts a user's games export. `GET /api/games/user/{username}`
    ///
    /// Finish with [`stream`](UserGamesRequest::stream) or
    /// [`pgn`](UserGamesRequest::pgn).
    #[must_use]
    pub fn export_user(&self, username: &'a str) -> UserGamesRequest<'a> {
        UserGamesRequest::new(self.client, username)
    }

    /// Starts an export of the game a user is currently playing, if any.
    ///
    /// Finish with [`json`](CurrentGameRequest::json) or
    /// [`pgn`](CurrentGameRequest::pgn). `GET /api/user/{username}/current-game`
    #[must_use]
    pub fn current_game(&self, username: &'a str) -> CurrentGameRequest<'a> {
        CurrentGameRequest::new(self.client, username)
    }

    /// Starts an export of several games by id. `POST /api/games/export/_ids`
    ///
    /// Finish with [`stream`](ExportByIdsRequest::stream) or
    /// [`pgn`](ExportByIdsRequest::pgn).
    #[must_use]
    pub fn export_by_ids(&self, ids: &[&str]) -> ExportByIdsRequest<'a> {
        ExportByIdsRequest::new(self.client, ids)
    }

    /// Starts an export of the authenticated user's bookmarked games.
    ///
    /// Finish with [`stream`](ExportBookmarksRequest::stream) or
    /// [`pgn`](ExportBookmarksRequest::pgn). `GET /api/games/export/bookmarks`
    #[must_use]
    pub fn export_bookmarks(&self) -> ExportBookmarksRequest<'a> {
        ExportBookmarksRequest::new(self.client)
    }

    /// Imports a game from its PGN.
    ///
    /// Requires authentication. `POST /api/import`
    pub async fn import_game(&self, pgn: &str) -> Result<LichessImportedGame> {
        let request = self
            .client
            .request(Method::POST, Host::Default, "/api/import")
            .form(&[("pgn", pgn)]);
        http::json(request, "LichessImportedGame").await
    }

    /// Gets the games the authenticated user is currently playing.
    ///
    /// `nb` limits the number of games returned. `GET /api/account/playing`
    pub async fn now_playing(&self, nb: Option<u32>) -> Result<LichessNowPlaying> {
        let request = self
            .client
            .request(Method::GET, Host::Default, "/api/account/playing")
            .query(&[("nb", nb)]);
        http::json(request, "LichessNowPlaying").await
    }

    /// Gets the spectator chat of a game. `GET /api/game/{gameId}/chat`
    pub async fn chat(&self, game_id: &str) -> Result<Vec<LichessGameChatMessage>> {
        let path = format!("/api/game/{}/chat", http::segment(game_id));
        let request = self.client.request(Method::GET, Host::Default, &path);
        http::json(request, "Vec<LichessGameChatMessage>").await
    }
}

impl LichessClient {
    /// Games API: export and import games.
    #[must_use]
    pub fn games(&self) -> GamesApi<'_> {
        GamesApi::new(self)
    }
}