topgg crates.io crates.io downloads license BLAZINGLY FAST!!!

The official Rust SDK for the Top.gg API.

Getting Started

Make sure to have a Top.gg API token handy, you can have an API token if you own a listed Discord bot on Top.gg (open the edit page, see in Webhooks section) then add the following to your Cargo.toml's dependencies:

toml topgg = "1.0"

Features

This library provides several feature flags that can be enabled/disabled in Cargo.toml. Such as:

Examples

More things can be read on the documentation.

api: Fetching a single Discord user from it's Discord ID

```rust,no_run use topgg::Client;

[tokio::main]

async fn main() { let token = env!("TOPGGTOKEN").toowned(); let client = Client::new(token);

let user = client.get_user(661200758510977084u64).await.unwrap();

asserteq!(user.username, "null"); asserteq!(user.discriminator, "8626"); assert_eq!(user.id, 661200758510977084u64);

println!("{:?}", user); } ```

api: Fetching a single Discord bot from it's Discord ID

```rust,no_run use topgg::Client;

[tokio::main]

async fn main() { let token = env!("TOPGGTOKEN").toowned(); let client = Client::new(token);

let bot = client.get_bot(264811613708746752u64).await.unwrap();

asserteq!(bot.username, "Luca"); asserteq!(bot.discriminator, "1375"); assert_eq!(bot.id, 264811613708746752u64);

println!("{:?}", bot); } ```

api: Querying several Discord bots

```rust,no_run use topgg::{Client, Filter, Query};

[tokio::main]

async fn main() { let token = env!("TOPGGTOKEN").toowned(); let client = Client::new(token);

// inputting a string searches a bot that matches that username for bot in client.get_bots("shiro").await.unwrap() { println!("{:?}", bot); }

// advanced query with filters let filter = Filter::new() .username("shiro") .certified(true);

let query = Query::new() .limit(250) .skip(50) .filter(filter);

for bot in client.get_bots(query).await.unwrap() { println!("{:?}", bot); } } ```

api: Posting your Discord bot's statistics

```rust,no_run use topgg::{Client, NewStats};

[tokio::main]

async fn main() { let token = env!("TOPGGTOKEN").toowned(); let client = Client::new(token);

let servercount = 1234; // be TRUTHFUL! let shardcount = 10;

let stats = NewStats::countbased(servercount, Some(shard_count));

client.post_stats(stats).await.unwrap(); } ```

api: Checking if a user has voted for your Discord bot

```rust,no_run use topgg::Client;

[tokio::main]

async fn main() { let token = env!("TOPGGTOKEN").toowned(); let client = Client::new(token);

if client.has_voted(661200758510977084u64).await.unwrap() { println!("checks out"); } } ```

autoposter: Automating the process of periodically posting your Discord bot's statistics

In your Cargo.toml:

toml [dependencies] topgg = { version = "1.0", features = ["autoposter"] }

In your code:

```rust,no_run use topgg::{Autoposter, Client, NewStats};

[tokio::main]

async fn main() { let token = env!("TOPGGTOKEN").toowned(); let client = Client::new(token);

// make sure to make this autoposter instance live // throughout most of the bot's lifetime to keep running! let autoposter = client.new_autoposter(1800);

// ... then in some on ready/new guild event ... let servercount = 12345; let stats = NewStats::countbased(server_count, None); autoposter.feed(stats).await; } ```

actix: Writing an actix-web webhook for listening to your bot/server's vote events

In your Cargo.toml:

toml [dependencies] topgg = { version = "1.0", default-features = false, features = ["actix"] }

In your code:

```rust,norun use actixweb::{post, App, HttpServer, Responder}; use std::io;

[post("/dblwebhook")]

async fn webhook(vote: topgg::IncomingVote) -> impl Responder { match vote.authenticate(env!("TOPGGWEBHOOKPASSWORD")) { Some(vote) => /* your application logic here... /, _ => / handle 401 here... */, } }

[tokio::main]

async fn main() -> io::Result<()> { HttpServer::new(|| { App::new().service(webhook) }) .bind(("127.0.0.1", 8080))? .run() .await } ```

axum: Writing an axum webhook for listening to your bot/server's vote events

In your Cargo.toml:

toml [dependencies] topgg = { version = "1.0", default-features = false, features = ["axum"] }

In your code:

```rust,no_run use axum::{Router, Server}; use std::net::SocketAddr;

struct MyVoteHandler {}

[asynctrait::asynctrait]

impl topgg::VoteHandler for MyVoteHandler { async fn voted(&self, vote: topgg::Vote) { // your application logic here } }

[tokio::main]

async fn main() { let password = env!("TOPGGWEBHOOKPASSWORD").to_owned(); let state = MyVoteHandler {};

let app = Router::new() .nest("/dblwebhook", topgg::axum::webhook(password, state));

let addr = SocketAddr::from(([127, 0, 0, 1], 3000));

Server::bind(&addr) .serve(app.intomakeservice()) .await .unwrap(); } ```

rocket: Writing a rocket webhook for listening to your bot/server's vote events

In your Cargo.toml:

toml [dependencies] topgg = { version = "1.0", default-features = false, features = ["rocket"] }

In your code:

```rust,no_run

![feature(procmacrohygiene, decl_macro)]

[macro_use]

extern crate rocket;

use rocket::http::Status;

[post("/", data = "")]

fn webhook(vote: topgg::IncomingVote) -> Status { match vote.authenticate(env!("TOPGGWEBHOOKPASSWORD")) { Some(vote) => /* your application logic here... /, _ => / handle 401 here... */, } }

fn main() { rocket::ignite() .mount("/dblwebhook", routes![webhook]) .launch(); } ```

warp: Writing a warp webhook for listening to your bot/server's vote events

In your Cargo.toml:

toml [dependencies] topgg = { version = "1.0", default-features = false, features = ["warp"] }

In your code:

```rust,no_run struct MyVoteHandler {}

[asynctrait::asynctrait]

impl topgg::VoteHandler for MyVoteHandler { async fn voted(&self, vote: topgg::Vote) { // your application logic here } }

[tokio::main]

async fn main() { let password = env!("TOPGGWEBHOOKPASSWORD").to_owned(); let state = MyVoteHandler {};

// POST /dblwebhook let webhook = topgg::warp::webhook("dblwebhook", password, state);
let routes = warp::post().and(webhook);

warp::serve(routes).run(([127, 0, 0, 1], 3030)).await; } ```