hypixel 0.1.0

Rust wrapper for the Hypixel public API.
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

//! This module provides structs and functions for easy access to 
//! Hypixel player data.
//! 
//! Create a player data client using the associated Client struct.
//! 
//! # Example
//! 
//! ```no_run
//! use hypixel::handler::player_data::Client; // Damn.
//! 
//! let client = Client::login("hypixel-API-key");
//! // Now do something with it.
//! ````
use crate::api::http;
use crate::objects::{Player, PlayerResponse, Guild, GuildResponse};
use crate::Error;

/// This struct only stores an API key to make it easier for
/// the user to interact with the Hypixel API.
/// 
/// This struct only handles getting information from players.
pub struct Client {
    key: String
}

impl Client {
    /// Returns a Client struct with the provided API key.
    /// 
    /// # Arguments
    /// 
    /// * `key` - Your Hypixel API key.
    pub fn login(key: &str) -> Self {
        Self { key: key.to_string() }
    }

    /// Gets a specific player's data from the Hypixel API. 
    /// 
    /// # Arguments
    /// 
    /// * `uuid` - UUID of the player.
    /// 
    /// # Example
    /// 
    /// ```no_run
    /// let player = client.player_from_uuid("uuid").await?;
    /// 
    /// println!("{player:?}");
    /// ```
    /// 
    /// # Errors
    /// 
    /// Returns a `FailedResponse` error if the provided API key was invalid
    /// or the player does not exist.
    pub async fn player_from_uuid(&self, uuid: &str) -> Result<Player, Error> {
        let res = http::fetch::<PlayerResponse>(
            &format!("player?uuid={uuid}&key={}", &self.key)
        ).await?;

        Ok(res.player)
    }

    /// Returns a Hypixel guild by name. This can be nothing if it the name does 
    /// not match any existing guilds.
    /// 
    /// # Arguments
    /// 
    /// * `name` - Name of the guild.
    /// 
    /// # Example
    /// 
    /// ```no_run
    /// let guild = client.guild_from_name("guild-name").await?;
    /// // Something...
    /// ```
    /// 
    /// # Errors
    /// 
    /// Returns a `FailedResponse` error if the API key is invalid.
    pub async fn guild_from_name(&self, name: &str) -> Result<Option<Guild>, Error> {
        let res = http::fetch::<GuildResponse>(
            &format!("guild?name={name}&key={}", &self.key)
        ).await?;

        Ok(res.guild)
    }

    /// Returns a Hypixel guild by it's ID. This can be nothing if it the ID does 
    /// not match any existing guilds.
    /// 
    /// # Arguments
    /// 
    /// * `id` - ID if the guild.
    /// 
    /// # Errors
    /// 
    /// Returns a `FailedResponse` error if the API key is invalid.
    pub async fn guild_from_id(&self, id: &str) -> Result<Option<Guild>, Error> {
        let res = http::fetch::<GuildResponse>(
            &format!("guild?id={id}&key={}", &self.key)
        ).await?;

        Ok(res.guild)
    }

    /// Returns the API key provided when the client was created.
    pub fn key(&self) -> &str {
        &self.key
    } 
}