vox 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4525b927b8d1067a91aa3062e4d72674958b11c4aa216a290824262a359c21eb
-  data.tar.gz: 7dac51047015695c88c46113cdd78424c483bada9456f068f96169645001381a
+  metadata.gz: 0fc0a12db6533b317311269a8b02a540fc66ad6c6a2486f299d03cefe1a27ff9
+  data.tar.gz: 7ca31f77aa563b70b4167a1efc6fe81a08ca4485ce665ddb67fa87e3c8f75791
 SHA512:
-  metadata.gz: 99abfab082caef047c4e244ef345353f5b98db418b1f1477abaa07c8bceab883e256045e039dd5d9850c2ebe2b8089b7bd9d57386db51c2df9daba1d2b5062f8
-  data.tar.gz: d760f0c0e5df2edc43ea4b17e0e3fabeccfa557cbd69def6963733177a5ab9b68a889a25ff857caaa978ac96cabd649fe00e6ac8428dd9728e593b8c1da1a0c5
+  metadata.gz: 2720562c8fd00799fa024abe36a7f89265ec11aea9d84d47e26e6c018fad5cd07c7d103933d71bdb4782ab1af92260caa67a7960a36b3c41b01e4c89fbf2aafe
+  data.tar.gz: 153e83e5ce4651f12c63b67452ba60c58a0e01cb7c1f0ecefb21641cebbe414dc6f2ba34812bb2bb609e80564c2a1f325e324742c7696f4c543d7bedfcb68c34

data/.github/workflows/rspec.yml

@@ -25,5 +25,16 @@ jobs:
         bundler-cache: true
     - name: Install dependencies
       run: bundle install
+    - name: Prepare CodeClimate Reporter
+      if: ${{ matrix.ruby == 2.7 && matrix.os == 'ubuntu-20.04' }}
+      run: |
+        curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+        chmod +x ./cc-test-reporter
+        ./cc-test-reporter before-build
     - name: Run RSpec
       run: bundle exec rake
+    - name: Upload CodeClimate coverage
+      env:
+        CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID}}
+      if: ${{ matrix.ruby == 2.7 && matrix.os == 'ubuntu-20.04' }}
+      run: ./cc-test-reporter after-build

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2020-8-29
+### Added
+- Rate limiter
+- Logging middleware
+- HTTP client
+- API route containers
+- Initial release at 0.2.1, due to previous gem owner having yanked versions below 0.2

data/README.md

@@ -1,8 +1,12 @@
 # Vox
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/vox`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Maintainability](https://api.codeclimate.com/v1/badges/769cea19478c3d5cdfeb/maintainability)](https://codeclimate.com/github/swarley/vox/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/769cea19478c3d5cdfeb/test_coverage)](https://codeclimate.com/github/swarley/vox/test_coverage)
+[![Gem Version](https://badge.fury.io/rb/vox.svg)](https://badge.fury.io/rb/vox)
+[![Inline docs](http://inch-ci.org/github/swarley/vox.svg?branch=main)](http://inch-ci.org/github/swarley/vox)
 
-TODO: Delete this and the text above, and describe your gem
+A gem for interacting with the Discord API. Intends to cover the entire API, have high spec coverage, complete documentation coverage, and
+be as modular as possible with room for flexibility of use at every level.
 
 ## Installation
 
@@ -22,13 +26,8 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Currently only the HTTP API has been implemented, and it does not return abstracted objects. Rather it is simply a client to assist
+in making requests and handling rate limiting.
 
 ## Contributing
 

data/lib/vox/http/client.rb

@@ -109,10 +109,10 @@ module Vox
 
         data = raw ? resp.body : MultiJson.load(resp.body, symbolize_keys: true)
         case resp.status
-        when 200
-          data
         when 204, 304
           nil
+        when 200..300
+          data
         when 400
           raise Error::BadRequest.new(data, req_id)
         when 401

data/lib/vox/http/error.rb

@@ -10,6 +10,10 @@ module Vox
       # @return [String, nil] The trace identifier this error originated from.
       attr_reader :trace
 
+      # @!visibility private
+      # Create an error from an API response.
+      # @param data [Hash<Symbol, Object>] The error object from the API.
+      # @param req_id [String] The trace ID for the originating request.
       def initialize(data, req_id = nil)
         @data = data
         @trace = req_id
@@ -46,6 +50,9 @@ module Vox
 
       # Status Code 5XX
       class ServerError < StandardError
+        # @!visibility private
+        # Create an API error that does not have a JSON body.
+        # @param req_id [String] The trace ID of the request.
         def initialize(req_id)
           @trace = req_id
           super('Internal Server Error')

data/lib/vox/http/route.rb

@@ -24,6 +24,7 @@ module Vox
       #   the API path.
       attr_reader :params
 
+      # Create a new route to be used with {Client#request}
       # @param verb [#to_sym] The HTTP verb to be used when accessing the API path.
       # @param key [String] The unformatted route using Kernel.format syntax to
       #   incorporate the data provided in `params`.

data/lib/vox/http/routes/guild.rb

@@ -24,6 +24,16 @@ module Vox
         # @param afk_timeout [Integer] AFK timeout in seconds.
         # @param system_channel_id [String, Integer] The ID of the channel where guild notices such as welcome messages
         #   and boost events are posted
+        # @return [Hash<Symbol, Object>] The created [guild](https://discord.com/developers/docs/resources/guild#guild-object)
+        #   object.
+        # @note This endpoint can only be used by bots in less than 10 guilds.
+        # @note When using the `roles` parameter, the first member of the array is used to modify the `@everyone` role.
+        # @note When using the `role` parameter, the `id` field in each object is an integer placeholder that will be
+        #   replaced by the api. The integer placeholder you use is for reference in channel permission overwrites.
+        # @note When using the `channels` parameter, the `position` field is ignored.
+        # @note When using the `channels` parameter, the `id` field is an integer placeholder that will be replaced by
+        #   the api. This is used for `GUILD_CATEGORY` channel types to allow you to reference a `parent_id` in other
+        #   channels.
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild
         def create_guild(name:, region: :undef, icon: :undef, verification_level: :undef,
                          default_message_notifications: :undef, explicit_content_filter: :undef,
@@ -40,12 +50,44 @@ module Vox
           request(Route.new(:POST, '/guilds'), json: json)
         end
 
-        # @param guild_id [String, Integer]
+        # Get the guild object for the given ID.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param with_counts [true, false] Whether the response should include `approximate_member_count`
+        #   and `approximate_presence_count` fields.
+        # @return [Hash<Symbol, Object>] The target [guild](https://discord.com/developers/docs/resources/guild#guild-object)
+        #   object.
+        # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild
+        def get_guild(guild_id, with_counts: :undef)
+          params = filter_undef({ with_counts: with_counts })
+          request(Route.new(:GET, '/guilds/%{guild_id}', guild_id: guild_id), query: params)
+        end
+
+        # Get a guild preview for a public guild, even if the user is not in the guild.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @return [Hash<Symbol, Object>] The target [guild](https://discord.com/developers/docs/resources/guild#guild-object)
+        #   object.
+        # @note This endpoint is only for public guilds.
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-preview
         def get_guild_preview(guild_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/preview', guild_id: guild_id))
         end
 
+        # @param guild_id [String, Integer]
+        # @param name [String]
+        # @param region [String]
+        # @param verification_level [Integer]
+        # @param default_message_notifications [Integer]
+        # @param explicit_content_filter [Integer]
+        # @param splash [String]
+        # @param banner [String]
+        # @param system_channel_id [String, Integer]
+        # @param rules_channel_id [String, Integer]
+        # @param public_updates_channel_id [String, Integer]
+        # @param preferred_locale [String]
+        # @param reason [String]
+        # @return [Hash<Symbol, Object>] The modified [guild](https://discord.com/developers/docs/resources/guild#guild-object)
+        #   object.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild
         def modify_guild(guild_id, name: :undef, region: :undef, verification_level: :undef,
                          default_message_notifications: :undef, explicit_content_filter: :undef,
@@ -66,16 +108,43 @@ module Vox
           request(Route.new(:PATCH, '/guilds/%{guild_id}', guild_id: guild_id), json: json, reason: reason)
         end
 
+        # Delete a guild by ID.
+        # @param guild_id [String, Integer]  The ID of the guild to be deleted.
+        # @return [nil] Returns `nil` on success.
+        # @note The user must be the server owner.
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#delete-guild
         def delete_guild(guild_id)
           request(Route.new(:DELETE, '/guilds/%{guild_id}', guild_id: guild_id))
         end
 
+        # Get a list of channels for a guild.
+        # @param guild_id [String, Integer] The ID of the guild to fetch the channels of.
+        # @return [Array<Hash<Symbol, Object>>] A list of [channel](https://discord.com/developers/docs/resources/channel#channel-object)
+        #   objects.
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-channels
         def get_guild_channels(guild_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/channels', guild_id: guild_id))
         end
 
+        # Create a new channel in a guild.
+        # @param guild_id [String, Integer] The ID of the channel to create a channel in.
+        # @param name [String] The name of the channel.
+        # @param type [Integer] The [type](https://discord.com/developers/docs/resources/channel#channel-object-channel-types)
+        #   of channel to create.
+        # @param topic [String] The channel topic, between 0-1024 characters.
+        # @param bitrate [Integer] The bitrate for the voice channel (voice only).
+        # @param user_limit [Integer] The user limit of the voice channel (voice only).
+        # @param rate_limit_per_user [Integer] The amount of seconds a user has to wait before sending another message,
+        #   between 0-21600. Bots and users with `MANAGE_MESSAGES` or `MANAGE_CHANNELS` are unaffected.
+        # @param position [Integer] The sorting position of this channel.
+        # @param permission_overwrites [Array<Hash<Symbol, Integer>>] An array of [permission overwrite](https://discord.com/developers/docs/resources/channel#overwrite-object)
+        #   objects.
+        # @param parent_id [String, Integer] The ID of the parent category for a channel.
+        # @param nsfw [true, false] Whether the channel is NSFW.
+        # @param reason [String] The reason this channel is being created.
+        # @return [Hash<Symbol, Object>] The created [channel](https://discord.com/developers/docs/resources/channel#channel-object)
+        #   object.
+        # @vox.permissions MANAGE_CHANNELS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild-channel
         def create_guild_channel(guild_id, name: :undef, type: :undef, topic: :undef, bitrate: :undef,
                                  user_limit: :undef, rate_limit_per_user: :undef, position: :undef,
@@ -90,30 +159,73 @@ module Vox
           request(Route.new(:POST, '/guilds/%{guild_id}/channels', guild_id: guild_id), json: json, reason: reason)
         end
 
+        # Modify the positions of a set of channels.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param positions
+        # @param reason [String]
+        # @return [nil] Returns `nil` on success.
+        # @note Only channels to be modified are required, with the minimum count being two channels.
+        # @vox.permissions MANAGE_CHANNELS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-channel-positions
         def modify_guild_channel_positions(guild_id, positions, reason: nil)
           route = Route.new(:PATCH, '/guilds/%{guild_id}/channels', guild_id: guild_id)
           request(route, json: positions, reason: reason)
         end
 
+        # Fetch information about a guild member.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param user_id [String, Integer] The ID of the target user.
+        # @return [Hash<Symbol, Object>] The target [guild member](https://discord.com/developers/docs/resources/guild#guild-member-object)
+        #   object.
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-member
         def get_guild_member(guild_id, user_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/members/%{user_id}', guild_id: guild_id, user_id: user_id))
         end
 
+        # Fetch a list of guild members.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param limit [Integer] The maximum amount of guild members to return.
+        # @param after [String, Integer] Fetch users after this ID.
+        # @return [Array<Hash<Symbol, Object>>] A list of [guild member](https://discord.com/developers/docs/resources/guild#guild-member-object)
+        #   objects.
+        # @note In the future this will require [priviledged intents](https://discord.com/developers/docs/topics/gateway#privileged-intents).
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#list-guild-members
         def list_guild_members(guild_id, limit: :undef, after: :undef)
           params = filter_undef({ limit: limit, after: after })
           request(Route.new(:GET, '/guilds/%{guild_id}/members', guild_id: guild_id), query: params)
         end
 
+        # Add a member using an `access_token`.
+        # @param guild_id [String, Integer] The ID of the guild to join the user to.
+        # @return [Hash<Symbol, Object>] The created [guild member](https://discord.com/developers/docs/resources/guild#guild-member-object)
+        #   object.
         # @vox.oauth_scope guilds.join
+        # @vox.permissions CREATE_INSTANT_INVITE
+        # @vox.api_docs https://discord.com/developers/docs/resources/guild#add-guild-member
         def add_guild_member(guild_id, user_id, access_token:, nick: :undef, roles: :undef, mute: :undef, deaf: :undef)
           json = filter_undef({ access_token: access_token, nick: nick, roles: roles, mute: mute, deaf: deaf })
           route = Route.new(:PUT, '/guilds/%{guild_id}/members/%{user_id}', guild_id: guild_id, user_id: user_id)
           request(route, json: json)
         end
 
+        # Modify attributes of a guild member.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param user_id [String, Integer] The ID of the target user.
+        # @param nick [String] The user's nickname.
+        # @param roles [Array<String, Integer>] An array of IDs for roles the member is assigned.
+        # @param mute [true, false] Whether the member is muted in voice channels.
+        # @param deaf [true, false] Whether the member is deafened in voice channels.
+        # @param channel_id [String, Integer] The ID of a channel to move a user to, if they are connected
+        #   to voice.
+        # @param reason [String]
+        # @return [Hash<Symbol, Object>] The modified [guild member](https://discord.com/developers/docs/resources/guild#guild-member-object)
+        #   object.
+        # @note `mute` and `deaf` parameters will result in a {Error::BadRequest} if the target user is not
+        #   in a voice channel.
+        # @vox.permissions MANAGE_NICKNAMES (nick), MANAGE_ROLES (roles), MUTE_MEMBERS (mute),
+        #   DEAFEN_MEMBERS (deafen), MOVE_MEMBERS (channel_id)
+        # @note When moving members to channels, the API user must have permissions to connect to both channels as well
+        #   as MOVE_MEMBERS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-member
         def modify_guild_member(guild_id, user_id, nick: :undef, roles: :undef, mute: :undef, deaf: :undef,
                                 channel_id: :undef, reason: nil)
@@ -122,6 +234,12 @@ module Vox
           request(route, json: json, reason: reason)
         end
 
+        # Update the nickname of the current user on a given guild.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param nick [String] The nickname to assign to the current user.
+        # @param reason [String] The reason the user's nickname is being changed.
+        # @return [Hash<:name, String>] The updated nickname.
+        # @vox.permissions CHANGE_NICKNAME
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-current-user-nick
         def modify_current_user_nick(guild_id, nick: :undef, reason: nil)
           json = filter_undef({ nick: nick })
@@ -129,6 +247,13 @@ module Vox
           request(route, json: json, reason: reason)
         end
 
+        # Add a role to a guild member.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param user_id [String, Integer] The ID of the user to assign role to.
+        # @param role_id [String, Integer] The ID of the role to assign to a user.
+        # @param reason [String] The reason a role is being added to a user.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions MANAGE_ROLES
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#add-guild-member-role
         def add_guild_member_role(guild_id, user_id, role_id, reason: nil)
           route = Route.new(:PUT, '/guilds/%{guild_id}/members/%{user_id}/roles/%{role_id}',
@@ -136,6 +261,13 @@ module Vox
           request(route, reason: reason)
         end
 
+        # Remove a role from a guild member.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param user_id [String, Integer] The ID of the target user to remove a role from.
+        # @param role_id [String, Integer] The ID of the role to remove from a target user.
+        # @param reason [String] The reason a role is being removed from a user.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions MANAGE_ROLES
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#remove-guild-member-role
         def remove_guild_member_role(guild_id, user_id, role_id, reason: nil)
           route = Route.new(:DELETE, '/guilds/%{guild_id}/members/%{user_id}/roles/%{role_id}',
@@ -143,22 +275,46 @@ module Vox
           request(route, reason: reason)
         end
 
+        # Kick a member from a guild.
+        # @param guild_id [String, Integer] The ID of the guild to kick the user from.
+        # @param user_id [String, Integer] The ID of the user being kicked.
+        # @param reason [String] The reason a user is being kicked.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions KICK_MEMBERS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#remove-guild-member
         def remove_guild_member(guild_id, user_id, reason: nil)
           route = Route.new(:DELETE, '/guilds/%{guild_id}/members/%{user_id}', guild_id: guild_id, user_id: user_id)
           request(route, reason: reason)
         end
 
+        # Fetch a list of bans for a guild.
+        # @param guild_id [String, Integer] The ID of a guild to fetch bans for.
+        # @return [Array<Hash<Symbol, Object>>] A list of [ban](https://discord.com/developers/docs/resources/guild#ban-object)
+        #   objects for the guild.
+        # @vox.permissions BAN_MEMBERS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-bans
         def get_guild_bans(guild_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/bans', guild_id: guild_id))
         end
 
+        # Get a ban object for a given user.
+        # @param guild_id [String, Integer] The ID of the target guild to retrieve a ban from.
+        # @param user_id [String, Integer] The ID of a user to retrieve a ban for.
+        # @return [Hash<Symbol, Object>] The target [ban](https://discord.com/developers/docs/resources/guild#ban-object)
+        #   object.
+        # @vox.permissions BAN_MEMBERS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-ban
         def get_guild_ban(guild_id, user_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/bans/%{user_id}', guild_id: guild_id, user_id: user_id))
         end
 
+        # Ban a user from a guild.
+        # @param guild_id [String, Integer] The ID of a guild to ban a user from.
+        # @param user_id [String, Integer] The ID of a user to ban.
+        # @param deleted_message_days [Integer] The number of days to delete messages for, between 0-7.
+        # @param reason [String] The reason a user is being banned.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions BAN_MEMBERS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild-ban
         def create_guild_ban(guild_id, user_id, deleted_message_days: :undef, reason: :undef)
           json = filter_undef({ deleted_message_days: deleted_message_days, reason: reason })
@@ -166,17 +322,38 @@ module Vox
           request(route, json: json)
         end
 
+        # Unban a user from a guild.
+        # @param guild_id [String, Integer] The ID of a guild to remove a ban from.
+        # @param user_id [String, Integer] The ID of a user to unban.
+        # @param reason [String] The reason a user is being unbanned.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions BAN_MEMBERS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#remove-guild-ban
         def remove_guild_ban(guild_id, user_id, reason: nil)
           route = Route.new(:DELETE, '/guilds/%{guild_id}/bans/%{user_id}', guild_id: guild_id, user_id: user_id)
           request(route, reason: reason)
         end
 
+        # Fetch a list of roles for a guild.
+        # @param guild_id [String, Integer] The ID of a guild to retrieve roles for.
+        # @return [Array<Hash<Symbol, Object>>] A list of [role](https://discord.com/developers/docs/topics/permissions#role-object)
+        #   objects for the guild.
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-roles
         def get_guild_roles(guild_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/roles', guild_id: guild_id))
         end
 
+        # Create a role in a guild.
+        # @param guild_id [String, Integer] The ID of a guild to create a role in.
+        # @param name [String] The name for the role.
+        # @param permissions [String, Integer] The bitwise value of the enabled/disabled permissions.
+        # @param color [Integer] The RGB color value of the role.
+        # @param hoist [true, false] Whether the role should be displayed separately in the sidebar.
+        # @param mentionable [true, false] Whether the role should be mentionable.
+        # @param reason [String] The reason a role is being created.
+        # @return [Hash<Symbol, Object>] The created [role](https://discord.com/developers/docs/topics/permissions#role-object)
+        #   object.
+        # @vox.permissions MANAGE_ROLES
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild-role
         def create_guild_role(guild_id, name: :undef, permissions: :undef, color: :undef, hoist: :undef,
                               mentionable: :undef, reason: nil)
@@ -185,11 +362,31 @@ module Vox
           request(Route.new(:POST, '/guilds/%{guild_id}/roles', guild_id: guild_id), json: json, reason: reason)
         end
 
+        # Modify the positions of a set of role objects.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param positions [Array<Hash<:id, Integer>>] An array of objects mapping channel ID to position.
+        # @param reason [String] The reason channel positions are being modified.
+        # @return [Array<Hash<Symbol, Object>>] A list of the guild's [role](https://discord.com/developers/docs/topics/permissions#role-object)
+        #   objects.
+        # @vox.permissions MANAGE_ROLES
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-role-positions
         def modify_guild_role_positions(guild_id, positions, reason: nil)
           request(Route.new(:PATCH, '/guilds/%{guild_id}/roles', guild_id: guild_id), json: positions, reason: reason)
         end
 
+        # Modify a guild role.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param role_id [String, Integer] The ID of a role to be modified.
+        # @param name [String] The name of the role.
+        # @param permissions [String, Integer] A bitwise value of the enabled/disabled permissions.
+        # @param color [Integer] An RGB color value.
+        # @param hoist [true, false] Whether the role should be displayed separately in the
+        #   sidebar.
+        # @param mentionable [true, false] Whether the role should be mentionable.
+        # @param reason [String]
+        # @return [Hash<Symbol, Object>] The modified [role](https://discord.com/developers/docs/topics/permissions#role-object)
+        #   object.
+        # @vox.permissions MANAGE_ROLES
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-role
         def modify_guild_role(guild_id, role_id, name: :undef, permissions: :undef, color: :undef, hoist: :undef,
                               mentionable: :undef, reason: nil)
@@ -199,46 +396,103 @@ module Vox
           request(route, json: json, reason: reason)
         end
 
+        # Delete a guild role.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param role_id [String, Integer] The ID of the role to be deleted.
+        # @param reason [String] The reason a role is being deleted.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions MANAGE_ROLES
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#delete-guild-role
         def delete_guild_role(guild_id, role_id, reason: nil)
           route = Route.new(:DELETE, '/guilds/%{guild_id}/roles/%{role_id}', guild_id: guild_id, role_id: role_id)
           request(route, reason: reason)
         end
 
+        # Get the result of a potential guild prune.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param days [Integer] The number of days to count prune for, 1 or more.
+        # @param include_roles [Array<String, Integer>] Roles to include when calculating prune count.
+        # @return [Hash<:pruned, Integer>] An object with a `pruned` key indicating how many members
+        #   would be removed in a prune operation.
+        # @vox.permissions KICK_MEMBERS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-prune-count
         def get_guild_prune_count(guild_id, days: :undef, include_roles: :undef)
+          include_roles = include_roles.is_a?(Array) ? include_roles.join(',') : include_roles
           params = filter_undef({ days: days, include_roles: include_roles })
           request(Route.new(:GET, '/guilds/%{guild_id}/prune', guild_id: guild_id), query: params)
         end
 
+        # Kick members that have been inactive for a provided duration.
+        # @param guild_id [String, Integer] The ID of the guild to prune.
+        # @param days [Integer] The number of days to prune, 1 or more.
+        # @param compute_prune_count [true, false] Whether the `pruned` key is returned. Discouraged for
+        #   large guilds.
+        # @param include_roles [Array<String, Integer>] Roles to include in the prune.
+        # @param reason [String] The reason a prune is being initiated.
+        # @return [Hash<:pruned, (Integer, nil)>] An object with a `pruned` key indicating how many members
+        #   were removed. Will be `nil` if `compute_prune_count` is set to false.
+        # @vox.permissions KICK_MEMBERS
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#begin-guild-prune
         def begin_guild_prune(guild_id, days: :undef, compute_prune_count: :undef, include_roles: :undef, reason: nil)
+          include_roles = include_roles.is_a?(Array) ? include_roles.join(',') : include_roles
           json = filter_undef({ days: days, compute_prune_count: compute_prune_count, include_roles: include_roles })
           route = Route.new(:POST, '/guilds/%{guild_id}/prune', guild_id: guild_id)
           request(route, json: json, reason: reason)
         end
 
+        # Fetch a list of voice regions for a guild.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @return [Array<Hash<Symbol, Object>>] A list of [voice region](https://discord.com/developers/docs/resources/voice#voice-region-object)
+        #   objects for the guild.
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-voice-regions
         def get_guild_voice_regions(guild_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/regions', guild_id: guild_id))
         end
 
+        # Fetch a list of invites for a guild.
+        # @param guild_id [String, Integer] The ID of the guild to fetch invites from.
+        # @return [Array<Hash<Symbol, Object>>] A list of [invite](https://discord.com/developers/docs/resources/invite#invite-object)
+        #   objects with additional [invite metadata](https://discord.com/developers/docs/resources/invite#invite-metadata-object)
+        #   fields.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-invites
         def get_guild_invites(guild_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/invites', guild_id: guild_id))
         end
 
+        # Fetch a list of integrations for a guild.
+        # @param guild_id [String, Integer] The ID of the guild to fetch integrations for.
+        # @return [Array<Hash<Symbol, Object>>] A list of [integration](https://discord.com/developers/docs/resources/guild#integration-object)
+        #   objects for the guild.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-integrations
         def get_guild_integrations(guild_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/integrations', guild_id: guild_id))
         end
 
+        # Create an integration for a guild.
+        # @param guild_id [String, Integer] The ID of the guild to create an integration for.
+        # @param type [Integer] The integration type.
+        # @param id [String, Integer] The ID of the integration to add.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild-integration
         def create_guild_integration(guild_id, type:, id:)
           json = { type: type, id: id }
           request(Route.new(:POST, '/guilds/%{guild_id}/integrations', guild_id: guild_id), json: json)
         end
 
+        # Modify a guild integration.
+        # @param guild_id [String, Integer] The ID of a guild to modify an integration for.
+        # @param integration_id [String, Integer] The ID of the integration to modify.
+        # @param expire_behavior [Integer] The [expire behavior](https://discord.com/developers/docs/resources/guild#integration-object-integration-expire-behaviors)
+        #   for this integration.
+        # @param expire_grace_period The grace period in days before expiring subscribers.
+        # @param enable_emoticons [true, false] Whether emoticons hsould be synced for this integration.
+        #   Currently, twitch only.
+        # @param reason [String] The reason an integration is being modified.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-integration
         def modify_guild_integration(guild_id, integration_id, expire_behavior: :undef, expire_grace_period: :undef,
                                      enable_emoticons: :undef, reason: nil)
@@ -249,6 +503,12 @@ module Vox
           request(route, json: json, reason: reason)
         end
 
+        # Delete a guild integration.
+        # @param guild_id [String, Integer] The ID of a guild to delete an integration for.
+        # @param integration_id [String, Integer] The ID of an integration to delete.
+        # @param reason [String] The reason an integration is being deleted.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#delete-guild-integration
         def delete_guild_integration(guild_id, integration_id, reason: nil)
           route = Route.new(:DELETE, '/guilds/%{guild_id}/integrations/%{integration_id}',
@@ -256,6 +516,12 @@ module Vox
           request(route, reason: reason)
         end
 
+        # Sync a guild integration.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param integration_id [String, Integer] The ID of the integration to sync.
+        # @param reason [String] The reason an integration is being synced.
+        # @return [nil] Returns `nil` on success.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#sync-guild-integration
         def sync_guild_integration(guild_id, integration_id, reason: nil)
           route = Route.new(:POST, '/guilds/%{guild_id}/integrations/%{integration_id}/sync',
@@ -263,11 +529,24 @@ module Vox
           request(route, reason: reason)
         end
 
+        # Fetch the guild widget object for a guild.
+        # @param guild_id [String, Integer] The ID of a target guild.
+        # @return [Hash<Symbol, Object>] The target [guild widget](https://discord.com/developers/docs/resources/guild#guild-widget-object)
+        #   object.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-widget
         def get_guild_widget(guild_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/widget', guild_id: guild_id))
         end
 
+        # Modify a guild widget object.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @param enabled [true, false] Whether or not to enable the widget.
+        # @param channel_id [String, Integer] The ID of the target channel.
+        # @param reason [String] The reason this widget is being modified.
+        # @return [Hash<Symbol, Object>] The modified [guild widget](https://discord.com/developers/docs/resources/guild#guild-widget-object)
+        #   object.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-widget
         def modify_guild_widget(guild_id, enabled: :undef, channel_id: :undef, reason: nil)
           json = filter_undef({ enabled: enabled, channel_id: channel_id })
@@ -275,11 +554,22 @@ module Vox
           request(route, json: json, reason: reason)
         end
 
+        # Get the vanity url for a guild.
+        # @param guild_id [String, Integer] The ID of the target guild.
+        # @return [Hash<(:code, :uses), Object>] A partial [invite](https://discord.com/developers/docs/resources/invite#invite-object)
+        #   object with `code`, and `uses` keys. `code` will be `nil` if a vanity url is not set
+        #   for the guild.
+        # @vox.permissions MANAGE_GUILD
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-vanity-url
         def get_guild_vanity_url(guild_id)
           request(Route.new(:GET, '/guilds/%{guild_id}/vanity-url', guild_id: guild_id))
         end
 
+        # Get the widget image of guild.
+        # @param guild_id [String, Integer] The ID of a target guild.
+        # @param style [String] The [widget style](https://discord.com/developers/docs/resources/guild#get-guild-widget-image-widget-style-options)
+        #   to fetch.
+        # @return [String] The PNG image data for the guild widget image.
         # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-widget-image
         def get_guild_widget_image(guild_id, style: :undef)
           params = filter_undef({ style: style })

data/lib/vox/version.rb

@@ -2,5 +2,5 @@
 
 module Vox
   # Overall gem version, each component also contains its own version
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/vox.gemspec

@@ -37,6 +37,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop', '~> 0.89.1'
   spec.add_development_dependency 'rubocop-performance', '~> 1.7.1'
   spec.add_development_dependency 'rubocop-rspec', '~> 1.42.0'
-  spec.add_development_dependency 'simplecov', '~> 0.19.0'
+  spec.add_development_dependency 'simplecov', '~> 0.17.1'
   spec.add_development_dependency 'yard', '~> 0.9.25'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vox
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Matthew Carey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-08-28 00:00:00.000000000 Z
+date: 2020-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -142,14 +142,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.19.0
+        version: 0.17.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.19.0
+        version: 0.17.1
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement