#discord #bots #dbl

topgg

The official Rust wrapper for the Top.gg API

8 stable releases

1.2.0 Oct 28, 2023
1.1.1 Jun 1, 2023
1.1.0 May 15, 2023
1.0.4 Apr 26, 2023
1.0.0 Apr 25, 2023

#57 in HTTP client

39 downloads per month

MIT license

81KB
1K SLoC

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. If not, then view this tutorial on how to retrieve yours. After that, add the following line to the dependencies section of your Cargo.toml:

topgg = "1.2"

Features

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

  • api: Interacting with the Top.gg API and accessing the top.gg/api/* endpoints. (enabled by default)
    • autoposter: Automating the process of periodically posting bot statistics to the Top.gg API.
  • webhook: Accessing the serde deserializable topgg::Vote struct.
    • actix-web: Wrapper for working with the actix-web web framework.
    • axum: Wrapper for working with the axum web framework.
    • rocket: Wrapper for working with the rocket web framework.
    • warp: Wrapper for working with the warp web framework.

Examples

More things can be read in the documentation.

api: Fetching a single Discord user from it's Discord ID
use topgg::Client;

#[tokio::main]
async fn main() {
  let client = Client::new(env!("TOPGG_TOKEN").to_string());
  
  let user = client.get_user(661200758510977084).await.unwrap();
  
  assert_eq!(user.username, "null");
  assert_eq!(user.id, 661200758510977084);
  
  println!("{:?}", user);
}
api: Fetching a single Discord bot from it's Discord ID
use topgg::Client;

#[tokio::main]
async fn main() {
  let client = Client::new(env!("TOPGG_TOKEN").to_string());
  
  let bot = client.get_bot(264811613708746752).await.unwrap();
  
  assert_eq!(bot.username, "Luca");
  assert_eq!(bot.discriminator, "1375");
  assert_eq!(bot.id, 264811613708746752);
  
  println!("{:?}", bot);
}
api: Querying several Discord bots
use topgg::{Client, Query};

#[tokio::main]
async fn main() {
  let client = Client::new(env!("TOPGG_TOKEN").to_string());

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

  let query = Query::new()
    .limit(250)
    .skip(50)
    .username("shiro")
    .certified(true);

  for bot in client.get_bots(query).await.unwrap() {
    println!("{:?}", bot);
  }
}
api: Posting your Discord bot's statistics
use topgg::Client;

#[tokio::main]
async fn main() {
  let client = Client::new(env!("TOPGG_TOKEN").to_string());

  let server_count = 12345;
  client
    .post_stats(Stats::count_based(server_count, None))
    .await
    .unwrap();
}
api: Checking if a user has voted for your Discord bot
use topgg::Client;

#[tokio::main]
async fn main() {
  let client = Client::new(env!("TOPGG_TOKEN").to_string());

  if client.has_voted(661200758510977084).await.unwrap() {
    println!("checks out");
  }
}
autoposter: Automating the process of periodically posting your Discord bot's statistics

In your Cargo.toml:

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

In your code:

use core::time::Duration;
use topgg::{Client, Stats};

#[tokio::main]
async fn main() {
  let client = Client::new(env!("TOPGG_TOKEN").to_string());

  // creates an autoposter that posts data to Top.gg every 1800 seconds (30 minutes).
  // the autopost thread will stop once it's dropped.
  let autoposter = client.new_autoposter(Duration::from_secs(1800));

  // ... then in some on ready/new guild event ...
  let server_count = 12345;
  autoposter
    .feed(Stats::count_based(server_count, None))
    .await;
}
actix-web: Writing an actix-web webhook for listening to your bot/server's vote events

In your Cargo.toml:

[dependencies]
topgg = { version = "1.2", default-features = false, features = ["actix-web"] }

In your code:

use actix_web::{
  error::{Error, ErrorUnauthorized},
  get, post, App, HttpServer,
};
use std::io;
use topgg::IncomingVote;

#[get("/")]
async fn index() -> &'static str {
  "Hello, World!"
}

#[post("/webhook")]
async fn webhook(vote: IncomingVote) -> Result<&'static str, Error> {
  match vote.authenticate(env!("TOPGG_WEBHOOK_PASSWORD")) {
    Some(vote) => {
      println!("{:?}", vote);

      Ok("ok")
    }
    _ => Err(ErrorUnauthorized("401")),
  }
}

#[actix_web::main]
async fn main() -> io::Result<()> {
  HttpServer::new(|| App::new().service(index).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:

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

In your code:

use axum::{routing::get, Router, Server};
use std::{net::SocketAddr, sync::Arc};
use topgg::{Vote, VoteHandler};

struct MyVoteHandler {}

#[axum::async_trait]
impl VoteHandler for MyVoteHandler {
  async fn voted(&self, vote: Vote) {
    println!("{:?}", vote);
  }
}

async fn index() -> &'static str {
  "Hello, World!"
}

#[tokio::main]
async fn main() {
  let state = Arc::new(MyVoteHandler {});

  let app = Router::new().route("/", get(index)).nest(
    "/webhook",
    topgg::axum::webhook(env!("TOPGG_WEBHOOK_PASSWORD").to_string(), Arc::clone(&state)),
  );

  let addr: SocketAddr = "127.0.0.1:8080".parse().unwrap();

  Server::bind(&addr)
    .serve(app.into_make_service())
    .await
    .unwrap();
}
rocket: Writing a rocket webhook for listening to your bot/server's vote events

In your Cargo.toml:

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

In your code:

#![feature(decl_macro)]

use rocket::{get, http::Status, post, routes};
use topgg::IncomingVote;

#[get("/")]
fn index() -> &'static str {
  "Hello, World!"
}

#[post("/webhook", data = "<vote>")]
fn webhook(vote: IncomingVote) -> Status {
  match vote.authenticate(env!("TOPGG_WEBHOOK_PASSWORD")) {
    Some(vote) => {
      println!("{:?}", vote);

      Status::Ok
    },
    _ => {
      println!("found an unauthorized attacker.");

      Status::Unauthorized
    }
  }
}

fn main() {
  rocket::ignite()
    .mount("/", routes![index, webhook])
    .launch();
}
warp: Writing a warp webhook for listening to your bot/server's vote events

In your Cargo.toml:

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

In your code:

use std::{net::SocketAddr, sync::Arc};
use topgg::{Vote, VoteHandler};
use warp::Filter;

struct MyVoteHandler {}

#[async_trait::async_trait]
impl VoteHandler for MyVoteHandler {
  async fn voted(&self, vote: Vote) {
    println!("{:?}", vote);
  }
}

#[tokio::main]
async fn main() {
  let state = Arc::new(MyVoteHandler {});

  // POST /webhook
  let webhook = topgg::warp::webhook(
    "webhook",
    env!("TOPGG_WEBHOOK_PASSWORD").to_string(),
    Arc::clone(&state),
  );

  let routes = warp::get().map(|| "Hello, World!").or(webhook);

  let addr: SocketAddr = "127.0.0.1:8080".parse().unwrap();

  warp::serve(routes).run(addr).await
}

Dependencies

~0.5–15MB
~212K SLoC