[feat,doc]: add error handling and documentation tweaks

Author: null8626

README.md

@@ -1,57 +1,220 @@
-# [Top.gg](https://top.gg) Ruby
+# Top.gg Ruby SDK
+
+The community-maintained Ruby library for Top.gg.
+
+## Chapters
+
+- [Installation](#installation)
+- [Setting up](#setting-up)
+- [Usage](#usage)
+  - [API v1](#api-v1)
+    - [Getting your project's vote information of a user](#getting-your-projects-vote-information-of-a-user)
+    - [Posting your bot's application commands list](#posting-your-bots-application-commands-list)
+  - [API v0](#api-v0)
+    - [Getting a bot](#getting-a-bot)
+    - [Getting several bots](#getting-several-bots)
+    - [Getting your project's voters](#getting-your-projects-voters)
+    - [Check if a user has voted for your project](#check-if-a-user-has-voted-for-your-project)
+    - [Getting your bot's statistics](#getting-your-bots-statistics)
+    - [Posting your bot's statistics](#posting-your-bots-statistics)
+    - [Automatically posting your bot's statistics every few minutes](#automatically-posting-your-bots-statistics-every-few-minutes)
+    - [Checking if the weekend vote multiplier is active](#checking-if-the-weekend-vote-multiplier-is-active)
+    - [Generating widget URLs](#generating-widget-urls)
+  - [Webhooks](#webhooks)
+    - [Being notified whenever someone voted for your project](#being-notified-whenever-someone-voted-for-your-project)
 
-The Top.gg Ruby SDK is a lighweight package, that allows you 
-to fetch data from the top.gg api and post data such as statistics to the website.
+## Installation
 
-It provides you with numerous methods to interact with the API.
-## Dependencies
+```sh
+$ gem install topgg
+```
 
-* Ruby 
+## Setting up
 
-## Installation
+### API v1
+
+> **NOTE**: API v1 also includes API v0.
+
+```rb
+require "topgg"
+
+client = V1Topgg.new(ENV["TOPGG_TOKEN"])
+```
+
+### API v0
+
+```rb
+require "topgg"
 
-``` bash
+client = Topgg.new(ENV["TOPGG_TOKEN"])
+```
+
+## Usage
+
+### API v1
 
-gem install topgg
+#### Getting your project's vote information of a user
 
+```rb
+vote = client.vote("661200758510977084")
 ```
-## Note
 
-You require a Token to interact with the Api.
-The token can be found at `https://top.gg/bot/[YOUR_BOT_ID]/webhooks` 
+#### Posting your bot's application commands list
 
-## Example
+##### Discordrb
 
-Here's a straightforward example of how to request data with the wrapper.
+```rb
+commands = bot.rest.api.get_global_application_commands(bot.application_id).to_json
 
-```ruby
-require 'topgg'
+client.post_commands(commands)
+```
 
-client = Topgg.new("AUTH_TOKEN", "BOTID")
+##### Raw
 
-client.get_bot("1234").defAvatar
-# returns
-# "6debd47ed13483642cf09e832ed0bc1b"
+```rb
+commands = "[{\"options\":[],\"name\":\"test\",\"name_localizations\":null,\"description\":\"command description\",\"description_localizations\":null,\"contexts\":[],\"default_permission\":null,\"default_member_permissions\":null,\"dm_permission\":false,\"integration_types\":[],\"nsfw\":false}]"
 
+client.post_commands(commands)
 ```
-### Auto Posting
 
-The library provides you with autoposting functionality, and autoposts at an interval of 30 minutes.
-Here's how you can use it
+### API v0
 
-```ruby
-require 'topgg'
-require 'discordrb'
+#### Getting a bot
 
-bot = Discordrb::Bot.new token: "TOKEN"
+```rb
+bot = client.get_bot("264811613708746752")
+```
 
-client = Topgg.new("AUTH_TOKEN", "BOTID")
- bot.ready do |event|
- client.auto_post_stats(bot) # The discordrb bot client.
+#### Getting several bots
+
+```rb
+bots = client.search_bot({ sort: "id", limit: 50, offset: 0 })
+
+for bot in bots.results do
+  puts bot.username
 end
+```
+
+#### Getting your project's voters
+
+##### First page
+
+```rb
+voters = client.votes
+
+for voter in voters.results do
+  puts voter.username
+end
+```
+
+##### Subsequent pages
+
+```rb
+voters = client.votes(2)
+
+for voter in voters.results do
+  puts voter.username
+end
+```
+
+#### Check if a user has voted for your project
+
+```rb
+has_voted = client.voted?("8226924471638491136")
+```
+
+#### Getting your bot's statistics
+
+```rb
+stats = client.get_stats
+```
+
+#### Posting your bot's statistics
+
+```rb
+client.post_stats(bot.server_count)
+```
+
+#### Automatically posting your bot's statistics every few minutes
+
+With Discordrb:
+
+```rb
+require "discordrb"
+
+bot = Discordrb::Bot.new(token: env["BOT_TOKEN"], intents: [:servers])
+
+bot.ready do |event|
+  client.auto_post_stats(bot)
+  
+  puts("Bot is now ready!")
+end
+
 bot.run
 ```
 
-# Documentation
+#### Checking if the weekend vote multiplier is active
+
+```rb
+is_weekend = client.is_weekend?
+```
+
+#### Generating widget URLs
+
+##### Large
+
+```rb
+widget_url = Dbl::Widget.large(:discord_bot, "574652751745777665")
+```
+
+##### Votes
+
+```rb
+widget_url = Dbl::Widget.votes(:discord_bot, "574652751745777665")
+```
+
+##### Owner
+
+```rb
+widget_url = Dbl::Widget.owner(:discord_bot, "574652751745777665")
+```
+
+##### Social
+
+```rb
+widget_url = Dbl::Widget.social(:discord_bot, "574652751745777665")
+```
+
+### Webhooks
+
+#### Being notified whenever someone voted for your project
 
-Check out the api reference [here](https://rubydoc.info/gems/topgg/)
+##### Ruby on Rails
+
+In your `config/application.rb`:
+
+```rb
+module MyServer
+  class Application < Rails::Application
+    # ...
+
+    config.middleware.use Dbl::Webhook,
+    type: Dbl::Webhook::VOTE,
+    path: "/votes",
+    auth: ENV["MY_TOPGG_WEBHOOK_SECRET"] do |vote|
+      Rails.logger.info "A user with the ID of #{vote.voter_id} has voted us on Top.gg!"
+    end
+  end
+end
+```
+
+##### Sinatra
+
+```rb
+use Dbl::Webhook,
+type: Dbl::Webhook::VOTE,
+path: "/votes",
+auth: ENV["MY_TOPGG_WEBHOOK_SECRET"] do |vote|
+  puts "A user with the ID of #{vote.voter_id} has voted us on Top.gg!"
+end
+```

lib/lib.rb

@@ -14,10 +14,10 @@
 require_relative "topgg/utils/request"
 
 # Class Topgg
-# The class instantiates all the methods for API requests and posts.
+# Top.gg API v0 client
 class Topgg
-  # initializes the class attributes.
-  # @param token [String] The authorization token from top.gg
+  # Initializes the client
+  # @param token [String] Your Top.gg API token
   def initialize(token)
     begin
       token_section = token.split('.')[1]
@@ -35,14 +35,14 @@ def initialize(token)
     @request = Dbl::Utils::Request.new(token)
   end
 
-  # Fetches bot statistics from top.gg
+  # Get Discord bot statistics from top.gg
   # @param id [String] The bot's ID
   # @return [Dbl::Bot] The Bot Object
   def get_bot(id)
     Dbl::Bot.new(@request.get("bots/#{id}"))
   end
 
-  # Searches bots from Top.gg using a keyword query.
+  # Searches Discord bots from Top.gg using a keyword query.
   # @param [Object] params The parameters that can be used to query a search
   # To know what the parameters are check it out here
   # @return [Dbl::BotSearch] The BotSearch Object
@@ -61,9 +61,7 @@ def user(id)
   # @param id [String] The bot's ID. Unused, no longer has an effect.
   # @return [Dbl::Stats]
   def get_stats(id = nil)
-    resp = @request.get("bots/stats")
-
-    Dbl::Stats.new(resp)
+    Dbl::Stats.new(@request.get("bots/stats"))
   end
 
   # Mini-method to query if your project was voted by the user in the past 12 hours.
@@ -87,12 +85,11 @@ def is_weekend?
   def votes(page = 1)
     page = page.to_i
     page = 1 if page < 1
-    resp = @request.get("bots/#{@id}/votes", { page: page })
 
-    Dbl::Votes.new(resp)
+    Dbl::Votes.new(@request.get("bots/#{@id}/votes", { page: page }))
   end
 
-  # Posts your Discord bot's server count to the API. This will update the server count in your bot's Top.gg page.
+  # Posts your Discord bot's statistics to the API. This will update the statistics in your Discord bot's Top.gg page.
   # @param server_count [Integer] The amount of servers the bot is in. Must not be less than 1.
   # @param shards [Integer] The amount of servers the bot is in per shard. Unused, no longer has an effect.
   # @param shard_count [Integer] The total number of shards. Unused, no longer has an effect.
@@ -106,7 +103,7 @@ def post_stats(server_count, shards = nil, shard_count = nil)
     )
   end
 
-  # Auto-posts stats to the Top.gg website
+  # Auto-posts your Discord bot's stats to the Top.gg website
   # @param client [Discordrb::Bot] instanceof discordrb client.
   def auto_post_stats(client)
     semaphore = Mutex.new
@@ -136,3 +133,27 @@ def interval(seconds)
     end
   end
 end
+
+# Top.gg API v1 client
+class V1Topgg < Topgg
+  # Updates the application commands list in your Discord bot's Top.gg page.
+  # @param commands [String] A list of application commands in raw Discord API JSON objects. This cannot be empty.
+  def post_commands(commands)
+    @request.post("v1/projects/@me/commands", commands)
+  end
+  
+  # Get the latest vote information of a Top.gg user on your project.
+  # @param id [String] The user's ID.
+  # @param source [String] The ID type to use. Defaults to "discord".
+  # @return [Dbl::Vote]
+  def vote(id, source = "discord")
+    raise ArgumentError, "source must be either \"discord\" or \"topgg\"" unless source == "discord" or source == "topgg"
+
+    begin
+      Dbl::Vote.new(@request.get("v1/projects/@me/votes/#{id}", { source: source }))
+    rescue Net::HTTPError => err
+      return nil if err.response.code == "404"
+      raise
+    end
+  end
+end

lib/topgg/utils/request.rb

@@ -24,6 +24,8 @@ def get(params, query=nil)
         request.add_field "Authorization", "Bearer #{@token}"
 
         response = http.request(request)
+        raise Net::HTTPError.new("Top.gg HTTP error: #{response.code}", response) unless response.code.start_with?('2')
+
         JSON.parse(response.body)
       end