topstats 0.1.0

Rust SDK for the TopStats.gg API - Discord bot statistics tracking
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

//! # `TopStats` Rust SDK
//!
//! A Rust SDK for interacting with the [TopStats.gg API](https://topstats.gg),
//! which provides statistics for Discord bots listed on Top.gg.
//!
//! ## Features
//!
//! - **Async-first** design with optional blocking mode
//! - **Multiple HTTP backends**: reqwest (async) or ureq (blocking)
//! - **Built-in rate limiting** with automatic retry for short delays
//! - **Type-safe** models with serde serialization
//! - **Tracing** support for logging (optional)
//!
//! ## Quick Start (Async)
//!
//! ```rust,no_run
//! use topstats::Client;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), topstats::Error> {
//!     let client = Client::new("your-api-token")?;
//!
//!     // Get bot information
//!     let bot = client.get_bot(432610292342587392).await?;
//!     println!("Bot: {} has {} monthly votes", bot.name, bot.monthly_votes);
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Blocking Mode
//!
//! For synchronous code, disable default features and enable `blocking`:
//!
//! ```toml
//! [dependencies]
//! topstats = { version = "0.1", default-features = false, features = ["blocking", "ureq-client"] }
//! ```
//!
//! ```rust,ignore
//! use topstats::Client;
//!
//! fn main() -> Result<(), topstats::Error> {
//!     let client = Client::new("your-api-token")?;
//!     let bot = client.get_bot(432610292342587392)?;
//!     println!("Bot: {}", bot.name);
//!     Ok(())
//! }
//! ```
//!
//! ## Feature Flags
//!
//! - `async` (default): Enable async mode
//! - `blocking`: Enable blocking/sync mode (mutually exclusive with `async`)
//! - `reqwest-client` (default): Use reqwest as the HTTP backend (async)
//! - `ureq-client`: Use ureq as the HTTP backend (blocking)
//! - `rustls-tls` (default): Use rustls for TLS
//! - `native-tls`: Use native TLS implementation
//! - `tracing`: Enable tracing/logging support

#![cfg_attr(docsrs, feature(doc_cfg))]
// Clippy lints
#![warn(clippy::all)]
#![warn(clippy::nursery)]
#![warn(clippy::pedantic)]
#![warn(missing_docs)]
#![warn(rust_2018_idioms)]
#![deny(unsafe_code)]
// Allow some overly strict pedantic lints
#![allow(clippy::return_self_not_must_use)]
#![allow(clippy::similar_names)]
#![allow(clippy::module_name_repetitions)]

// Compile-time check: async and blocking are mutually exclusive
#[cfg(all(feature = "async", feature = "blocking"))]
compile_error!(
    "Features `async` and `blocking` are mutually exclusive. \
     Use `default-features = false` and enable only one."
);

// Compile-time check: at least one mode must be enabled
#[cfg(not(any(feature = "async", feature = "blocking")))]
compile_error!(
    "Either `async` or `blocking` feature must be enabled. \
     The `async` feature is enabled by default."
);

mod client;
#[doc(hidden)]
pub mod endpoints;
pub mod error;
pub(crate) mod http;
pub mod models;

// Re-exports
pub use client::{Client, ClientBuilder, ClientConfig};
pub use error::{Error, Result};
pub use models::*;

/// The default base URL for the `TopStats` API.
pub const DEFAULT_BASE_URL: &str = "https://api.topstats.gg";

/// The SDK version.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// The User-Agent string sent with requests.
pub const USER_AGENT: &str = concat!(
    "topstats-rust-sdk/",
    env!("CARGO_PKG_VERSION"),
    " (https://github.com/top-stats/rust-sdk)"
);