top-gg 0.1.0-alpha.0

//! The client implementation around the API, and finalizer requests for
//! configuring optional parameters.
//!
//! Refer to the [`Client`] struct for more information and examples.
//!
//! [`Client`]: struct.Client.html

pub mod request;

use crate::{
    endpoints,
    error::{ChunkingText, Deserializing, InvalidHeaderValue, InvalidUrl, Result, TokenMissing},
    model::*,
};
use request::SearchBots;
use reqwest::{
    header::{HeaderValue, AUTHORIZATION},
    Client as HttpClient, Url,
};
use serde::de::DeserializeOwned;
use snafu::{OptionExt, ResultExt};
use std::sync::Arc;

#[derive(Debug)]
struct ClientRef {
    http: Arc<HttpClient>,
    token: Option<String>,
}

/// Struct which defines the methods necessary to interact with the service.
#[derive(Clone, Debug)]
pub struct Client(Arc<ClientRef>);

impl Client {
    /// Creates a new client to interact with the API.
    ///
    /// This accepts an existing reqwest Client so a single HTTP client may be
    /// shared across your application.
    ///
    /// This method doesn't require authentication.
    ///
    /// # Examples
    ///
    /// Create a new API client:
    ///
    /// ```no_run
    /// use reqwest::Client as HttpClient;
    /// use top_gg::Client;
    ///
    /// let http_client = HttpClient::new();
    /// let client = Client::new(http_client, None);
    /// ```
    pub fn new(http_client: impl Into<Arc<HttpClient>>, token: impl Into<Option<String>>) -> Self {
        Self(Arc::new(ClientRef {
            http: http_client.into(),
            token: token.into(),
        }))
    }

    /// Retrieves information about a bot.
    ///
    /// This method doesn't require authentication.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use reqwest::Client as HttpClient;
    /// use top_gg::Client;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// let http_client = HttpClient::new();
    /// let client = Client::new(http_client, None);
    ///
    /// let bot = client.get_bot(270198738570444801).await?;
    ///
    /// println!("Bot's name: {}", bot.username);
    /// # Ok(()) }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::ChunkingText`] when the response body couldn't be
    /// chunked as a valid UTF-8 string.
    ///
    /// Returns [`Error::Deserializing`] if there was an issue deserializing the
    /// response body.
    ///
    /// Returns [`Error::Request`] if there was an issue building the request.
    /// This probably won't happen.
    ///
    /// [`Error::ChunkingText`]: ../error/enum.Error.html#variant.ChunkingText
    /// [`Error::Deserializing`]: ../error/enum.Error.html#variant.Deserializing
    /// [`Error::Request`]: ../error/enum.Error.html#variant.Request
    pub async fn get_bot(&self, user_id: u64) -> Result<Bot> {
        let url = url(endpoints::bot(user_id))?;

        self.get(url).await
    }

    /// Retrieves a list of bots via a search.
    ///
    /// This method doesn't require authentication.
    ///
    /// # Examples
    ///
    /// Get 500 bots, skipping the first 250 bots:
    ///
    /// ```no_run
    /// use reqwest::Client as HttpClient;
    /// use top_gg::Client;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// let http_client = HttpClient::new();
    /// let client = Client::new(http_client, None);
    ///
    /// let bots = client.get_bots().limit(500).offset(250).await?;
    ///
    /// println!("Got {} bots", bots.total);
    /// # Ok(()) }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::ChunkingText`] when the response body couldn't be
    /// chunked as a valid UTF-8 string.
    ///
    /// Returns [`Error::Deserializing`] if there was an issue deserializing the
    /// response body.
    ///
    /// Returns [`Error::Request`] if there was an issue building the request.
    /// This probably won't happen.
    ///
    /// [`Error::ChunkingText`]: ../error/enum.Error.html#variant.ChunkingText
    /// [`Error::Deserializing`]: ../error/enum.Error.html#variant.Deserializing
    /// [`Error::Request`]: ../error/enum.Error.html#variant.Request
    pub fn get_bots(&self) -> SearchBots<'_> {
        SearchBots::new(self)
    }

    /// Retrieves information about a bot's specific stats.
    ///
    /// This method doesn't require authentication.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use reqwest::Client as HttpClient;
    /// use top_gg::Client;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// let http_client = HttpClient::new();
    /// let client = Client::new(http_client, None);
    ///
    /// let bot = client.get_bot_stats(270_198_738_570_444_801).await?;
    ///
    /// if let Some(server_count) = bot.server_count {
    ///     println!("This bot is in {} servers", server_count);
    /// }
    /// # Ok(()) }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::ChunkingText`] when the response body couldn't be
    /// chunked as a valid UTF-8 string.
    ///
    /// Returns [`Error::Deserializing`] if there was an issue deserializing the
    /// response body.
    ///
    /// Returns [`Error::Request`] if there was an issue building the request.
    /// This probably won't happen.
    ///
    /// [`Error::ChunkingText`]: ../error/enum.Error.html#variant.ChunkingText
    /// [`Error::Deserializing`]: ../error/enum.Error.html#variant.Deserializing
    /// [`Error::Request`]: ../error/enum.Error.html#variant.Request
    pub async fn get_bot_stats(&self, user_id: u64) -> Result<BotStats> {
        let url = url(endpoints::bot_stats(user_id))?;

        self.get(url).await
    }

    /// Retrieve whether a user has upvoted a bot in the last 24 hours.
    ///
    /// You can use this if your bot has over 1000 votes.
    ///
    /// This method requires authentication.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use reqwest::Client as HttpClient;
    /// use std::env;
    /// use top_gg::Client;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// let http_client = HttpClient::new();
    /// let token = env::var("TOP_GG_TOKEN")?;
    /// let client = Client::new(http_client, token);
    ///
    /// let voted = client.get_bot_vote_check(270_198_738_570_444_801, 114_941_315_417_899_012).await?;
    ///
    /// if voted {
    ///     println!("This user voted");
    /// } else {
    ///     println!("This user has not voted");
    /// }
    /// # Ok(()) }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::ChunkingText`] when the response body couldn't be
    /// chunked as a valid UTF-8 string.
    ///
    /// Returns [`Error::Deserializing`] if there was an issue deserializing the
    /// response body.
    ///
    /// Returns [`Error::Request`] if there was an issue building the request.
    /// This probably won't happen.
    ///
    /// Returns [`Error::TokenMissing`] if a token is needed for authentication
    /// but it wasn't present.
    ///
    /// [`Error::ChunkingText`]: ../error/enum.Error.html#variant.ChunkingText
    /// [`Error::Deserializing`]: ../error/enum.Error.html#variant.Deserializing
    /// [`Error::Request`]: ../error/enum.Error.html#variant.Request
    /// [`Error::TokenMissing`]: ../error/enum.Error.html#variant.TokenMissing
    pub async fn get_bot_vote_check(&self, bot_id: u64, user_id: u64) -> Result<bool> {
        let token = self.0.token.as_ref().context(TokenMissing)?;

        let path = endpoints::bot_vote_check(bot_id, user_id);
        let user_id = user_id.to_string();
        let params = [("userId", user_id.as_ref())];
        let url = url_params(path, &params)?;
        let header_value = auth(token)?;

        let text = self
            .0
            .http
            .get(url)
            .header(AUTHORIZATION, header_value)
            .send()
            .await?
            .text()
            .await
            .context(ChunkingText)?;
        let body = deser::<ResponseUserVoted>(text)?;

        Ok(body.voted == 1)
    }

    /// Retrieves information to see who has upvoted a bot.
    ///
    /// This method does not require authentication.
    ///
    /// **Note**: If your bot has over 1000 votes per month, then this can not
    /// be used. Webhooks must instead be used.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use reqwest::Client as HttpClient;
    /// use top_gg::{
    ///     model::BotVotes,
    ///     Client,
    /// };
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// let http_client = HttpClient::new();
    /// let client = Client::new(http_client, None);
    ///
    /// let votes = client.get_bot_votes(270_198_738_570_444_801).await?;
    ///
    /// match votes {
    ///     BotVotes::Ids(ids) => println!("There are {} votes", ids.len()),
    ///     BotVotes::Users(users) => println!("There are {} votes", users.len()),
    /// }
    /// # Ok(()) }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::ChunkingText`] when the response body couldn't be
    /// chunked as a valid UTF-8 string.
    ///
    /// Returns [`Error::Deserializing`] if there was an issue deserializing the
    /// response body.
    ///
    /// Returns [`Error::Request`] if there was an issue building the request.
    /// This probably won't happen.
    ///
    /// [`Error::ChunkingText`]: ../error/enum.Error.html#variant.ChunkingText
    /// [`Error::Deserializing`]: ../error/enum.Error.html#variant.Deserializing
    /// [`Error::Request`]: ../error/enum.Error.html#variant.Request
    pub async fn get_bot_votes(&self, bot_id: u64) -> Result<BotVotes> {
        let url = url(endpoints::bot_votes(bot_id))?;

        self.get(url).await
    }

    /// Retrieves information about a user.
    ///
    /// This method doesn't require authentication.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use reqwest::Client as HttpClient;
    /// use top_gg::Client;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// let http_client = HttpClient::new();
    /// let client = Client::new(http_client, None);
    ///
    /// let user = client.get_user(114_941_315_417_899_012).await?;
    ///
    /// println!("The user's name is {}", user.username);
    /// # Ok(()) }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::ChunkingText`] when the response body couldn't be
    /// chunked as a valid UTF-8 string.
    ///
    /// Returns [`Error::Deserializing`] if there was an issue deserializing the
    /// response body.
    ///
    /// Returns [`Error::Request`] if there was an issue building the request.
    /// This probably won't happen.
    ///
    /// [`Error::ChunkingText`]: ../error/enum.Error.html#variant.ChunkingText
    /// [`Error::Deserializing`]: ../error/enum.Error.html#variant.Deserializing
    /// [`Error::Request`]: ../error/enum.Error.html#variant.Request
    pub async fn get_user(&self, user_id: u64) -> Result<User> {
        let url = url(endpoints::user(user_id))?;

        self.get(url).await
    }

    /// Posts a bot's shard stats.
    ///
    /// This method requires authentication.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use reqwest::Client as HttpClient;
    /// use std::env;
    /// use top_gg::{
    ///     model::ShardStats,
    ///     Client,
    /// };
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// let http_client = HttpClient::new();
    /// let token = env::var("TOP_GG_TOKEN")?;
    /// let client = Client::new(http_client, token);
    ///
    /// let shard_stats = ShardStats::Shard {
    ///     guild_count: 1123,
    ///     shard_count: 10,
    ///     shard_id: 6,
    /// };
    ///
    /// client.post_stats(270_198_738_570_444_801, &shard_stats).await?;
    /// # Ok(()) }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::Request`] if there was an issue building the request.
    /// This probably won't happen.
    ///
    /// Returns [`Error::TokenMissing`] if a token is needed for authentication
    /// but it wasn't present.
    ///
    /// [`Error::Request`]: ../error/enum.Error.html#variant.Request
    /// [`Error::TokenMissing`]: ../error/enum.Error.html#variant.TokenMissing
    pub async fn post_stats<'a>(&'a self, bot_id: u64, stats: &'a ShardStats) -> Result<()> {
        let token = self.0.token.as_ref().context(TokenMissing)?;
        let url = url(endpoints::bot_stats(bot_id))?;
        let header_value = auth(token)?;

        self.0
            .http
            .post(url)
            .header(AUTHORIZATION, header_value)
            .json(stats)
            .send()
            .await?;

        Ok(())
    }

    async fn get<T: DeserializeOwned>(&self, url: Url) -> Result<T> {
        let text = self
            .0
            .http
            .get(url)
            .send()
            .await?
            .text()
            .await
            .context(ChunkingText)?;

        deser(text)
    }
}

impl From<(Arc<HttpClient>, Option<String>)> for Client {
    fn from((client, token): (Arc<HttpClient>, Option<String>)) -> Self {
        Self::new(client, token)
    }
}

fn auth(token: &str) -> Result<HeaderValue> {
    HeaderValue::from_str(token).with_context(|| InvalidHeaderValue {
        name: AUTHORIZATION,
        value: token.to_owned(),
    })
}

fn deser<T: DeserializeOwned>(text: String) -> Result<T> {
    serde_json::from_str(&text).with_context(|| Deserializing { text })
}

fn url(uri: String) -> Result<Url> {
    Url::parse(&uri).with_context(|| InvalidUrl { uri })
}

fn url_params<'a>(uri: String, params: &[(&'a str, &'a str)]) -> Result<Url> {
    Url::parse_with_params(&uri, params.iter()).with_context(|| InvalidUrl { uri })
}