vox 0.2.0 → 0.2.1

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4525b927b8d1067a91aa3062e4d72674958b11c4aa216a290824262a359c21eb
4
- data.tar.gz: 7dac51047015695c88c46113cdd78424c483bada9456f068f96169645001381a
3
+ metadata.gz: 0fc0a12db6533b317311269a8b02a540fc66ad6c6a2486f299d03cefe1a27ff9
4
+ data.tar.gz: 7ca31f77aa563b70b4167a1efc6fe81a08ca4485ce665ddb67fa87e3c8f75791
5
5
  SHA512:
6
- metadata.gz: 99abfab082caef047c4e244ef345353f5b98db418b1f1477abaa07c8bceab883e256045e039dd5d9850c2ebe2b8089b7bd9d57386db51c2df9daba1d2b5062f8
7
- data.tar.gz: d760f0c0e5df2edc43ea4b17e0e3fabeccfa557cbd69def6963733177a5ab9b68a889a25ff857caaa978ac96cabd649fe00e6ac8428dd9728e593b8c1da1a0c5
6
+ metadata.gz: 2720562c8fd00799fa024abe36a7f89265ec11aea9d84d47e26e6c018fad5cd07c7d103933d71bdb4782ab1af92260caa67a7960a36b3c41b01e4c89fbf2aafe
7
+ data.tar.gz: 153e83e5ce4651f12c63b67452ba60c58a0e01cb7c1f0ecefb21641cebbe414dc6f2ba34812bb2bb609e80564c2a1f325e324742c7696f4c543d7bedfcb68c34
@@ -25,5 +25,16 @@ jobs:
25
25
  bundler-cache: true
26
26
  - name: Install dependencies
27
27
  run: bundle install
28
+ - name: Prepare CodeClimate Reporter
29
+ if: ${{ matrix.ruby == 2.7 && matrix.os == 'ubuntu-20.04' }}
30
+ run: |
31
+ curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
32
+ chmod +x ./cc-test-reporter
33
+ ./cc-test-reporter before-build
28
34
  - name: Run RSpec
29
35
  run: bundle exec rake
36
+ - name: Upload CodeClimate coverage
37
+ env:
38
+ CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID}}
39
+ if: ${{ matrix.ruby == 2.7 && matrix.os == 'ubuntu-20.04' }}
40
+ run: ./cc-test-reporter after-build
@@ -0,0 +1,15 @@
1
+ # Changelog
2
+ All notable changes to this project will be documented in this file.
3
+
4
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
5
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.2.1] - 2020-8-29
10
+ ### Added
11
+ - Rate limiter
12
+ - Logging middleware
13
+ - HTTP client
14
+ - API route containers
15
+ - Initial release at 0.2.1, due to previous gem owner having yanked versions below 0.2
data/README.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # Vox
2
2
 
3
- 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.
3
+ [![Maintainability](https://api.codeclimate.com/v1/badges/769cea19478c3d5cdfeb/maintainability)](https://codeclimate.com/github/swarley/vox/maintainability)
4
+ [![Test Coverage](https://api.codeclimate.com/v1/badges/769cea19478c3d5cdfeb/test_coverage)](https://codeclimate.com/github/swarley/vox/test_coverage)
5
+ [![Gem Version](https://badge.fury.io/rb/vox.svg)](https://badge.fury.io/rb/vox)
6
+ [![Inline docs](http://inch-ci.org/github/swarley/vox.svg?branch=main)](http://inch-ci.org/github/swarley/vox)
4
7
 
5
- TODO: Delete this and the text above, and describe your gem
8
+ A gem for interacting with the Discord API. Intends to cover the entire API, have high spec coverage, complete documentation coverage, and
9
+ be as modular as possible with room for flexibility of use at every level.
6
10
 
7
11
  ## Installation
8
12
 
@@ -22,13 +26,8 @@ Or install it yourself as:
22
26
 
23
27
  ## Usage
24
28
 
25
- TODO: Write usage instructions here
26
-
27
- ## Development
28
-
29
- 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.
30
-
31
- 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).
29
+ Currently only the HTTP API has been implemented, and it does not return abstracted objects. Rather it is simply a client to assist
30
+ in making requests and handling rate limiting.
32
31
 
33
32
  ## Contributing
34
33
 
@@ -109,10 +109,10 @@ module Vox
109
109
 
110
110
  data = raw ? resp.body : MultiJson.load(resp.body, symbolize_keys: true)
111
111
  case resp.status
112
- when 200
113
- data
114
112
  when 204, 304
115
113
  nil
114
+ when 200..300
115
+ data
116
116
  when 400
117
117
  raise Error::BadRequest.new(data, req_id)
118
118
  when 401
@@ -10,6 +10,10 @@ module Vox
10
10
  # @return [String, nil] The trace identifier this error originated from.
11
11
  attr_reader :trace
12
12
 
13
+ # @!visibility private
14
+ # Create an error from an API response.
15
+ # @param data [Hash<Symbol, Object>] The error object from the API.
16
+ # @param req_id [String] The trace ID for the originating request.
13
17
  def initialize(data, req_id = nil)
14
18
  @data = data
15
19
  @trace = req_id
@@ -46,6 +50,9 @@ module Vox
46
50
 
47
51
  # Status Code 5XX
48
52
  class ServerError < StandardError
53
+ # @!visibility private
54
+ # Create an API error that does not have a JSON body.
55
+ # @param req_id [String] The trace ID of the request.
49
56
  def initialize(req_id)
50
57
  @trace = req_id
51
58
  super('Internal Server Error')
@@ -24,6 +24,7 @@ module Vox
24
24
  # the API path.
25
25
  attr_reader :params
26
26
 
27
+ # Create a new route to be used with {Client#request}
27
28
  # @param verb [#to_sym] The HTTP verb to be used when accessing the API path.
28
29
  # @param key [String] The unformatted route using Kernel.format syntax to
29
30
  # incorporate the data provided in `params`.
@@ -24,6 +24,16 @@ module Vox
24
24
  # @param afk_timeout [Integer] AFK timeout in seconds.
25
25
  # @param system_channel_id [String, Integer] The ID of the channel where guild notices such as welcome messages
26
26
  # and boost events are posted
27
+ # @return [Hash<Symbol, Object>] The created [guild](https://discord.com/developers/docs/resources/guild#guild-object)
28
+ # object.
29
+ # @note This endpoint can only be used by bots in less than 10 guilds.
30
+ # @note When using the `roles` parameter, the first member of the array is used to modify the `@everyone` role.
31
+ # @note When using the `role` parameter, the `id` field in each object is an integer placeholder that will be
32
+ # replaced by the api. The integer placeholder you use is for reference in channel permission overwrites.
33
+ # @note When using the `channels` parameter, the `position` field is ignored.
34
+ # @note When using the `channels` parameter, the `id` field is an integer placeholder that will be replaced by
35
+ # the api. This is used for `GUILD_CATEGORY` channel types to allow you to reference a `parent_id` in other
36
+ # channels.
27
37
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild
28
38
  def create_guild(name:, region: :undef, icon: :undef, verification_level: :undef,
29
39
  default_message_notifications: :undef, explicit_content_filter: :undef,
@@ -40,12 +50,44 @@ module Vox
40
50
  request(Route.new(:POST, '/guilds'), json: json)
41
51
  end
42
52
 
43
- # @param guild_id [String, Integer]
53
+ # Get the guild object for the given ID.
54
+ # @param guild_id [String, Integer] The ID of the target guild.
55
+ # @param with_counts [true, false] Whether the response should include `approximate_member_count`
56
+ # and `approximate_presence_count` fields.
57
+ # @return [Hash<Symbol, Object>] The target [guild](https://discord.com/developers/docs/resources/guild#guild-object)
58
+ # object.
59
+ # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild
60
+ def get_guild(guild_id, with_counts: :undef)
61
+ params = filter_undef({ with_counts: with_counts })
62
+ request(Route.new(:GET, '/guilds/%{guild_id}', guild_id: guild_id), query: params)
63
+ end
64
+
65
+ # Get a guild preview for a public guild, even if the user is not in the guild.
66
+ # @param guild_id [String, Integer] The ID of the target guild.
67
+ # @return [Hash<Symbol, Object>] The target [guild](https://discord.com/developers/docs/resources/guild#guild-object)
68
+ # object.
69
+ # @note This endpoint is only for public guilds.
44
70
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-preview
45
71
  def get_guild_preview(guild_id)
46
72
  request(Route.new(:GET, '/guilds/%{guild_id}/preview', guild_id: guild_id))
47
73
  end
48
74
 
75
+ # @param guild_id [String, Integer]
76
+ # @param name [String]
77
+ # @param region [String]
78
+ # @param verification_level [Integer]
79
+ # @param default_message_notifications [Integer]
80
+ # @param explicit_content_filter [Integer]
81
+ # @param splash [String]
82
+ # @param banner [String]
83
+ # @param system_channel_id [String, Integer]
84
+ # @param rules_channel_id [String, Integer]
85
+ # @param public_updates_channel_id [String, Integer]
86
+ # @param preferred_locale [String]
87
+ # @param reason [String]
88
+ # @return [Hash<Symbol, Object>] The modified [guild](https://discord.com/developers/docs/resources/guild#guild-object)
89
+ # object.
90
+ # @vox.permissions MANAGE_GUILD
49
91
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild
50
92
  def modify_guild(guild_id, name: :undef, region: :undef, verification_level: :undef,
51
93
  default_message_notifications: :undef, explicit_content_filter: :undef,
@@ -66,16 +108,43 @@ module Vox
66
108
  request(Route.new(:PATCH, '/guilds/%{guild_id}', guild_id: guild_id), json: json, reason: reason)
67
109
  end
68
110
 
111
+ # Delete a guild by ID.
112
+ # @param guild_id [String, Integer] The ID of the guild to be deleted.
113
+ # @return [nil] Returns `nil` on success.
114
+ # @note The user must be the server owner.
69
115
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#delete-guild
70
116
  def delete_guild(guild_id)
71
117
  request(Route.new(:DELETE, '/guilds/%{guild_id}', guild_id: guild_id))
72
118
  end
73
119
 
120
+ # Get a list of channels for a guild.
121
+ # @param guild_id [String, Integer] The ID of the guild to fetch the channels of.
122
+ # @return [Array<Hash<Symbol, Object>>] A list of [channel](https://discord.com/developers/docs/resources/channel#channel-object)
123
+ # objects.
74
124
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-channels
75
125
  def get_guild_channels(guild_id)
76
126
  request(Route.new(:GET, '/guilds/%{guild_id}/channels', guild_id: guild_id))
77
127
  end
78
128
 
129
+ # Create a new channel in a guild.
130
+ # @param guild_id [String, Integer] The ID of the channel to create a channel in.
131
+ # @param name [String] The name of the channel.
132
+ # @param type [Integer] The [type](https://discord.com/developers/docs/resources/channel#channel-object-channel-types)
133
+ # of channel to create.
134
+ # @param topic [String] The channel topic, between 0-1024 characters.
135
+ # @param bitrate [Integer] The bitrate for the voice channel (voice only).
136
+ # @param user_limit [Integer] The user limit of the voice channel (voice only).
137
+ # @param rate_limit_per_user [Integer] The amount of seconds a user has to wait before sending another message,
138
+ # between 0-21600. Bots and users with `MANAGE_MESSAGES` or `MANAGE_CHANNELS` are unaffected.
139
+ # @param position [Integer] The sorting position of this channel.
140
+ # @param permission_overwrites [Array<Hash<Symbol, Integer>>] An array of [permission overwrite](https://discord.com/developers/docs/resources/channel#overwrite-object)
141
+ # objects.
142
+ # @param parent_id [String, Integer] The ID of the parent category for a channel.
143
+ # @param nsfw [true, false] Whether the channel is NSFW.
144
+ # @param reason [String] The reason this channel is being created.
145
+ # @return [Hash<Symbol, Object>] The created [channel](https://discord.com/developers/docs/resources/channel#channel-object)
146
+ # object.
147
+ # @vox.permissions MANAGE_CHANNELS
79
148
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild-channel
80
149
  def create_guild_channel(guild_id, name: :undef, type: :undef, topic: :undef, bitrate: :undef,
81
150
  user_limit: :undef, rate_limit_per_user: :undef, position: :undef,
@@ -90,30 +159,73 @@ module Vox
90
159
  request(Route.new(:POST, '/guilds/%{guild_id}/channels', guild_id: guild_id), json: json, reason: reason)
91
160
  end
92
161
 
162
+ # Modify the positions of a set of channels.
163
+ # @param guild_id [String, Integer] The ID of the target guild.
164
+ # @param positions
165
+ # @param reason [String]
166
+ # @return [nil] Returns `nil` on success.
167
+ # @note Only channels to be modified are required, with the minimum count being two channels.
168
+ # @vox.permissions MANAGE_CHANNELS
93
169
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-channel-positions
94
170
  def modify_guild_channel_positions(guild_id, positions, reason: nil)
95
171
  route = Route.new(:PATCH, '/guilds/%{guild_id}/channels', guild_id: guild_id)
96
172
  request(route, json: positions, reason: reason)
97
173
  end
98
174
 
175
+ # Fetch information about a guild member.
176
+ # @param guild_id [String, Integer] The ID of the target guild.
177
+ # @param user_id [String, Integer] The ID of the target user.
178
+ # @return [Hash<Symbol, Object>] The target [guild member](https://discord.com/developers/docs/resources/guild#guild-member-object)
179
+ # object.
99
180
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-member
100
181
  def get_guild_member(guild_id, user_id)
101
182
  request(Route.new(:GET, '/guilds/%{guild_id}/members/%{user_id}', guild_id: guild_id, user_id: user_id))
102
183
  end
103
184
 
185
+ # Fetch a list of guild members.
186
+ # @param guild_id [String, Integer] The ID of the target guild.
187
+ # @param limit [Integer] The maximum amount of guild members to return.
188
+ # @param after [String, Integer] Fetch users after this ID.
189
+ # @return [Array<Hash<Symbol, Object>>] A list of [guild member](https://discord.com/developers/docs/resources/guild#guild-member-object)
190
+ # objects.
191
+ # @note In the future this will require [priviledged intents](https://discord.com/developers/docs/topics/gateway#privileged-intents).
104
192
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#list-guild-members
105
193
  def list_guild_members(guild_id, limit: :undef, after: :undef)
106
194
  params = filter_undef({ limit: limit, after: after })
107
195
  request(Route.new(:GET, '/guilds/%{guild_id}/members', guild_id: guild_id), query: params)
108
196
  end
109
197
 
198
+ # Add a member using an `access_token`.
199
+ # @param guild_id [String, Integer] The ID of the guild to join the user to.
200
+ # @return [Hash<Symbol, Object>] The created [guild member](https://discord.com/developers/docs/resources/guild#guild-member-object)
201
+ # object.
110
202
  # @vox.oauth_scope guilds.join
203
+ # @vox.permissions CREATE_INSTANT_INVITE
204
+ # @vox.api_docs https://discord.com/developers/docs/resources/guild#add-guild-member
111
205
  def add_guild_member(guild_id, user_id, access_token:, nick: :undef, roles: :undef, mute: :undef, deaf: :undef)
112
206
  json = filter_undef({ access_token: access_token, nick: nick, roles: roles, mute: mute, deaf: deaf })
113
207
  route = Route.new(:PUT, '/guilds/%{guild_id}/members/%{user_id}', guild_id: guild_id, user_id: user_id)
114
208
  request(route, json: json)
115
209
  end
116
210
 
211
+ # Modify attributes of a guild member.
212
+ # @param guild_id [String, Integer] The ID of the target guild.
213
+ # @param user_id [String, Integer] The ID of the target user.
214
+ # @param nick [String] The user's nickname.
215
+ # @param roles [Array<String, Integer>] An array of IDs for roles the member is assigned.
216
+ # @param mute [true, false] Whether the member is muted in voice channels.
217
+ # @param deaf [true, false] Whether the member is deafened in voice channels.
218
+ # @param channel_id [String, Integer] The ID of a channel to move a user to, if they are connected
219
+ # to voice.
220
+ # @param reason [String]
221
+ # @return [Hash<Symbol, Object>] The modified [guild member](https://discord.com/developers/docs/resources/guild#guild-member-object)
222
+ # object.
223
+ # @note `mute` and `deaf` parameters will result in a {Error::BadRequest} if the target user is not
224
+ # in a voice channel.
225
+ # @vox.permissions MANAGE_NICKNAMES (nick), MANAGE_ROLES (roles), MUTE_MEMBERS (mute),
226
+ # DEAFEN_MEMBERS (deafen), MOVE_MEMBERS (channel_id)
227
+ # @note When moving members to channels, the API user must have permissions to connect to both channels as well
228
+ # as MOVE_MEMBERS
117
229
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-member
118
230
  def modify_guild_member(guild_id, user_id, nick: :undef, roles: :undef, mute: :undef, deaf: :undef,
119
231
  channel_id: :undef, reason: nil)
@@ -122,6 +234,12 @@ module Vox
122
234
  request(route, json: json, reason: reason)
123
235
  end
124
236
 
237
+ # Update the nickname of the current user on a given guild.
238
+ # @param guild_id [String, Integer] The ID of the target guild.
239
+ # @param nick [String] The nickname to assign to the current user.
240
+ # @param reason [String] The reason the user's nickname is being changed.
241
+ # @return [Hash<:name, String>] The updated nickname.
242
+ # @vox.permissions CHANGE_NICKNAME
125
243
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-current-user-nick
126
244
  def modify_current_user_nick(guild_id, nick: :undef, reason: nil)
127
245
  json = filter_undef({ nick: nick })
@@ -129,6 +247,13 @@ module Vox
129
247
  request(route, json: json, reason: reason)
130
248
  end
131
249
 
250
+ # Add a role to a guild member.
251
+ # @param guild_id [String, Integer] The ID of the target guild.
252
+ # @param user_id [String, Integer] The ID of the user to assign role to.
253
+ # @param role_id [String, Integer] The ID of the role to assign to a user.
254
+ # @param reason [String] The reason a role is being added to a user.
255
+ # @return [nil] Returns `nil` on success.
256
+ # @vox.permissions MANAGE_ROLES
132
257
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#add-guild-member-role
133
258
  def add_guild_member_role(guild_id, user_id, role_id, reason: nil)
134
259
  route = Route.new(:PUT, '/guilds/%{guild_id}/members/%{user_id}/roles/%{role_id}',
@@ -136,6 +261,13 @@ module Vox
136
261
  request(route, reason: reason)
137
262
  end
138
263
 
264
+ # Remove a role from a guild member.
265
+ # @param guild_id [String, Integer] The ID of the target guild.
266
+ # @param user_id [String, Integer] The ID of the target user to remove a role from.
267
+ # @param role_id [String, Integer] The ID of the role to remove from a target user.
268
+ # @param reason [String] The reason a role is being removed from a user.
269
+ # @return [nil] Returns `nil` on success.
270
+ # @vox.permissions MANAGE_ROLES
139
271
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#remove-guild-member-role
140
272
  def remove_guild_member_role(guild_id, user_id, role_id, reason: nil)
141
273
  route = Route.new(:DELETE, '/guilds/%{guild_id}/members/%{user_id}/roles/%{role_id}',
@@ -143,22 +275,46 @@ module Vox
143
275
  request(route, reason: reason)
144
276
  end
145
277
 
278
+ # Kick a member from a guild.
279
+ # @param guild_id [String, Integer] The ID of the guild to kick the user from.
280
+ # @param user_id [String, Integer] The ID of the user being kicked.
281
+ # @param reason [String] The reason a user is being kicked.
282
+ # @return [nil] Returns `nil` on success.
283
+ # @vox.permissions KICK_MEMBERS
146
284
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#remove-guild-member
147
285
  def remove_guild_member(guild_id, user_id, reason: nil)
148
286
  route = Route.new(:DELETE, '/guilds/%{guild_id}/members/%{user_id}', guild_id: guild_id, user_id: user_id)
149
287
  request(route, reason: reason)
150
288
  end
151
289
 
290
+ # Fetch a list of bans for a guild.
291
+ # @param guild_id [String, Integer] The ID of a guild to fetch bans for.
292
+ # @return [Array<Hash<Symbol, Object>>] A list of [ban](https://discord.com/developers/docs/resources/guild#ban-object)
293
+ # objects for the guild.
294
+ # @vox.permissions BAN_MEMBERS
152
295
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-bans
153
296
  def get_guild_bans(guild_id)
154
297
  request(Route.new(:GET, '/guilds/%{guild_id}/bans', guild_id: guild_id))
155
298
  end
156
299
 
300
+ # Get a ban object for a given user.
301
+ # @param guild_id [String, Integer] The ID of the target guild to retrieve a ban from.
302
+ # @param user_id [String, Integer] The ID of a user to retrieve a ban for.
303
+ # @return [Hash<Symbol, Object>] The target [ban](https://discord.com/developers/docs/resources/guild#ban-object)
304
+ # object.
305
+ # @vox.permissions BAN_MEMBERS
157
306
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-ban
158
307
  def get_guild_ban(guild_id, user_id)
159
308
  request(Route.new(:GET, '/guilds/%{guild_id}/bans/%{user_id}', guild_id: guild_id, user_id: user_id))
160
309
  end
161
310
 
311
+ # Ban a user from a guild.
312
+ # @param guild_id [String, Integer] The ID of a guild to ban a user from.
313
+ # @param user_id [String, Integer] The ID of a user to ban.
314
+ # @param deleted_message_days [Integer] The number of days to delete messages for, between 0-7.
315
+ # @param reason [String] The reason a user is being banned.
316
+ # @return [nil] Returns `nil` on success.
317
+ # @vox.permissions BAN_MEMBERS
162
318
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild-ban
163
319
  def create_guild_ban(guild_id, user_id, deleted_message_days: :undef, reason: :undef)
164
320
  json = filter_undef({ deleted_message_days: deleted_message_days, reason: reason })
@@ -166,17 +322,38 @@ module Vox
166
322
  request(route, json: json)
167
323
  end
168
324
 
325
+ # Unban a user from a guild.
326
+ # @param guild_id [String, Integer] The ID of a guild to remove a ban from.
327
+ # @param user_id [String, Integer] The ID of a user to unban.
328
+ # @param reason [String] The reason a user is being unbanned.
329
+ # @return [nil] Returns `nil` on success.
330
+ # @vox.permissions BAN_MEMBERS
169
331
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#remove-guild-ban
170
332
  def remove_guild_ban(guild_id, user_id, reason: nil)
171
333
  route = Route.new(:DELETE, '/guilds/%{guild_id}/bans/%{user_id}', guild_id: guild_id, user_id: user_id)
172
334
  request(route, reason: reason)
173
335
  end
174
336
 
337
+ # Fetch a list of roles for a guild.
338
+ # @param guild_id [String, Integer] The ID of a guild to retrieve roles for.
339
+ # @return [Array<Hash<Symbol, Object>>] A list of [role](https://discord.com/developers/docs/topics/permissions#role-object)
340
+ # objects for the guild.
175
341
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-roles
176
342
  def get_guild_roles(guild_id)
177
343
  request(Route.new(:GET, '/guilds/%{guild_id}/roles', guild_id: guild_id))
178
344
  end
179
345
 
346
+ # Create a role in a guild.
347
+ # @param guild_id [String, Integer] The ID of a guild to create a role in.
348
+ # @param name [String] The name for the role.
349
+ # @param permissions [String, Integer] The bitwise value of the enabled/disabled permissions.
350
+ # @param color [Integer] The RGB color value of the role.
351
+ # @param hoist [true, false] Whether the role should be displayed separately in the sidebar.
352
+ # @param mentionable [true, false] Whether the role should be mentionable.
353
+ # @param reason [String] The reason a role is being created.
354
+ # @return [Hash<Symbol, Object>] The created [role](https://discord.com/developers/docs/topics/permissions#role-object)
355
+ # object.
356
+ # @vox.permissions MANAGE_ROLES
180
357
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild-role
181
358
  def create_guild_role(guild_id, name: :undef, permissions: :undef, color: :undef, hoist: :undef,
182
359
  mentionable: :undef, reason: nil)
@@ -185,11 +362,31 @@ module Vox
185
362
  request(Route.new(:POST, '/guilds/%{guild_id}/roles', guild_id: guild_id), json: json, reason: reason)
186
363
  end
187
364
 
365
+ # Modify the positions of a set of role objects.
366
+ # @param guild_id [String, Integer] The ID of the target guild.
367
+ # @param positions [Array<Hash<:id, Integer>>] An array of objects mapping channel ID to position.
368
+ # @param reason [String] The reason channel positions are being modified.
369
+ # @return [Array<Hash<Symbol, Object>>] A list of the guild's [role](https://discord.com/developers/docs/topics/permissions#role-object)
370
+ # objects.
371
+ # @vox.permissions MANAGE_ROLES
188
372
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-role-positions
189
373
  def modify_guild_role_positions(guild_id, positions, reason: nil)
190
374
  request(Route.new(:PATCH, '/guilds/%{guild_id}/roles', guild_id: guild_id), json: positions, reason: reason)
191
375
  end
192
376
 
377
+ # Modify a guild role.
378
+ # @param guild_id [String, Integer] The ID of the target guild.
379
+ # @param role_id [String, Integer] The ID of a role to be modified.
380
+ # @param name [String] The name of the role.
381
+ # @param permissions [String, Integer] A bitwise value of the enabled/disabled permissions.
382
+ # @param color [Integer] An RGB color value.
383
+ # @param hoist [true, false] Whether the role should be displayed separately in the
384
+ # sidebar.
385
+ # @param mentionable [true, false] Whether the role should be mentionable.
386
+ # @param reason [String]
387
+ # @return [Hash<Symbol, Object>] The modified [role](https://discord.com/developers/docs/topics/permissions#role-object)
388
+ # object.
389
+ # @vox.permissions MANAGE_ROLES
193
390
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-role
194
391
  def modify_guild_role(guild_id, role_id, name: :undef, permissions: :undef, color: :undef, hoist: :undef,
195
392
  mentionable: :undef, reason: nil)
@@ -199,46 +396,103 @@ module Vox
199
396
  request(route, json: json, reason: reason)
200
397
  end
201
398
 
399
+ # Delete a guild role.
400
+ # @param guild_id [String, Integer] The ID of the target guild.
401
+ # @param role_id [String, Integer] The ID of the role to be deleted.
402
+ # @param reason [String] The reason a role is being deleted.
403
+ # @return [nil] Returns `nil` on success.
404
+ # @vox.permissions MANAGE_ROLES
202
405
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#delete-guild-role
203
406
  def delete_guild_role(guild_id, role_id, reason: nil)
204
407
  route = Route.new(:DELETE, '/guilds/%{guild_id}/roles/%{role_id}', guild_id: guild_id, role_id: role_id)
205
408
  request(route, reason: reason)
206
409
  end
207
410
 
411
+ # Get the result of a potential guild prune.
412
+ # @param guild_id [String, Integer] The ID of the target guild.
413
+ # @param days [Integer] The number of days to count prune for, 1 or more.
414
+ # @param include_roles [Array<String, Integer>] Roles to include when calculating prune count.
415
+ # @return [Hash<:pruned, Integer>] An object with a `pruned` key indicating how many members
416
+ # would be removed in a prune operation.
417
+ # @vox.permissions KICK_MEMBERS
208
418
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-prune-count
209
419
  def get_guild_prune_count(guild_id, days: :undef, include_roles: :undef)
420
+ include_roles = include_roles.is_a?(Array) ? include_roles.join(',') : include_roles
210
421
  params = filter_undef({ days: days, include_roles: include_roles })
211
422
  request(Route.new(:GET, '/guilds/%{guild_id}/prune', guild_id: guild_id), query: params)
212
423
  end
213
424
 
425
+ # Kick members that have been inactive for a provided duration.
426
+ # @param guild_id [String, Integer] The ID of the guild to prune.
427
+ # @param days [Integer] The number of days to prune, 1 or more.
428
+ # @param compute_prune_count [true, false] Whether the `pruned` key is returned. Discouraged for
429
+ # large guilds.
430
+ # @param include_roles [Array<String, Integer>] Roles to include in the prune.
431
+ # @param reason [String] The reason a prune is being initiated.
432
+ # @return [Hash<:pruned, (Integer, nil)>] An object with a `pruned` key indicating how many members
433
+ # were removed. Will be `nil` if `compute_prune_count` is set to false.
434
+ # @vox.permissions KICK_MEMBERS
214
435
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#begin-guild-prune
215
436
  def begin_guild_prune(guild_id, days: :undef, compute_prune_count: :undef, include_roles: :undef, reason: nil)
437
+ include_roles = include_roles.is_a?(Array) ? include_roles.join(',') : include_roles
216
438
  json = filter_undef({ days: days, compute_prune_count: compute_prune_count, include_roles: include_roles })
217
439
  route = Route.new(:POST, '/guilds/%{guild_id}/prune', guild_id: guild_id)
218
440
  request(route, json: json, reason: reason)
219
441
  end
220
442
 
443
+ # Fetch a list of voice regions for a guild.
444
+ # @param guild_id [String, Integer] The ID of the target guild.
445
+ # @return [Array<Hash<Symbol, Object>>] A list of [voice region](https://discord.com/developers/docs/resources/voice#voice-region-object)
446
+ # objects for the guild.
221
447
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-voice-regions
222
448
  def get_guild_voice_regions(guild_id)
223
449
  request(Route.new(:GET, '/guilds/%{guild_id}/regions', guild_id: guild_id))
224
450
  end
225
451
 
452
+ # Fetch a list of invites for a guild.
453
+ # @param guild_id [String, Integer] The ID of the guild to fetch invites from.
454
+ # @return [Array<Hash<Symbol, Object>>] A list of [invite](https://discord.com/developers/docs/resources/invite#invite-object)
455
+ # objects with additional [invite metadata](https://discord.com/developers/docs/resources/invite#invite-metadata-object)
456
+ # fields.
457
+ # @vox.permissions MANAGE_GUILD
226
458
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-invites
227
459
  def get_guild_invites(guild_id)
228
460
  request(Route.new(:GET, '/guilds/%{guild_id}/invites', guild_id: guild_id))
229
461
  end
230
462
 
463
+ # Fetch a list of integrations for a guild.
464
+ # @param guild_id [String, Integer] The ID of the guild to fetch integrations for.
465
+ # @return [Array<Hash<Symbol, Object>>] A list of [integration](https://discord.com/developers/docs/resources/guild#integration-object)
466
+ # objects for the guild.
467
+ # @vox.permissions MANAGE_GUILD
231
468
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-integrations
232
469
  def get_guild_integrations(guild_id)
233
470
  request(Route.new(:GET, '/guilds/%{guild_id}/integrations', guild_id: guild_id))
234
471
  end
235
472
 
473
+ # Create an integration for a guild.
474
+ # @param guild_id [String, Integer] The ID of the guild to create an integration for.
475
+ # @param type [Integer] The integration type.
476
+ # @param id [String, Integer] The ID of the integration to add.
477
+ # @return [nil] Returns `nil` on success.
478
+ # @vox.permissions MANAGE_GUILD
236
479
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#create-guild-integration
237
480
  def create_guild_integration(guild_id, type:, id:)
238
481
  json = { type: type, id: id }
239
482
  request(Route.new(:POST, '/guilds/%{guild_id}/integrations', guild_id: guild_id), json: json)
240
483
  end
241
484
 
485
+ # Modify a guild integration.
486
+ # @param guild_id [String, Integer] The ID of a guild to modify an integration for.
487
+ # @param integration_id [String, Integer] The ID of the integration to modify.
488
+ # @param expire_behavior [Integer] The [expire behavior](https://discord.com/developers/docs/resources/guild#integration-object-integration-expire-behaviors)
489
+ # for this integration.
490
+ # @param expire_grace_period The grace period in days before expiring subscribers.
491
+ # @param enable_emoticons [true, false] Whether emoticons hsould be synced for this integration.
492
+ # Currently, twitch only.
493
+ # @param reason [String] The reason an integration is being modified.
494
+ # @return [nil] Returns `nil` on success.
495
+ # @vox.permissions MANAGE_GUILD
242
496
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-integration
243
497
  def modify_guild_integration(guild_id, integration_id, expire_behavior: :undef, expire_grace_period: :undef,
244
498
  enable_emoticons: :undef, reason: nil)
@@ -249,6 +503,12 @@ module Vox
249
503
  request(route, json: json, reason: reason)
250
504
  end
251
505
 
506
+ # Delete a guild integration.
507
+ # @param guild_id [String, Integer] The ID of a guild to delete an integration for.
508
+ # @param integration_id [String, Integer] The ID of an integration to delete.
509
+ # @param reason [String] The reason an integration is being deleted.
510
+ # @return [nil] Returns `nil` on success.
511
+ # @vox.permissions MANAGE_GUILD
252
512
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#delete-guild-integration
253
513
  def delete_guild_integration(guild_id, integration_id, reason: nil)
254
514
  route = Route.new(:DELETE, '/guilds/%{guild_id}/integrations/%{integration_id}',
@@ -256,6 +516,12 @@ module Vox
256
516
  request(route, reason: reason)
257
517
  end
258
518
 
519
+ # Sync a guild integration.
520
+ # @param guild_id [String, Integer] The ID of the target guild.
521
+ # @param integration_id [String, Integer] The ID of the integration to sync.
522
+ # @param reason [String] The reason an integration is being synced.
523
+ # @return [nil] Returns `nil` on success.
524
+ # @vox.permissions MANAGE_GUILD
259
525
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#sync-guild-integration
260
526
  def sync_guild_integration(guild_id, integration_id, reason: nil)
261
527
  route = Route.new(:POST, '/guilds/%{guild_id}/integrations/%{integration_id}/sync',
@@ -263,11 +529,24 @@ module Vox
263
529
  request(route, reason: reason)
264
530
  end
265
531
 
532
+ # Fetch the guild widget object for a guild.
533
+ # @param guild_id [String, Integer] The ID of a target guild.
534
+ # @return [Hash<Symbol, Object>] The target [guild widget](https://discord.com/developers/docs/resources/guild#guild-widget-object)
535
+ # object.
536
+ # @vox.permissions MANAGE_GUILD
266
537
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-widget
267
538
  def get_guild_widget(guild_id)
268
539
  request(Route.new(:GET, '/guilds/%{guild_id}/widget', guild_id: guild_id))
269
540
  end
270
541
 
542
+ # Modify a guild widget object.
543
+ # @param guild_id [String, Integer] The ID of the target guild.
544
+ # @param enabled [true, false] Whether or not to enable the widget.
545
+ # @param channel_id [String, Integer] The ID of the target channel.
546
+ # @param reason [String] The reason this widget is being modified.
547
+ # @return [Hash<Symbol, Object>] The modified [guild widget](https://discord.com/developers/docs/resources/guild#guild-widget-object)
548
+ # object.
549
+ # @vox.permissions MANAGE_GUILD
271
550
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#modify-guild-widget
272
551
  def modify_guild_widget(guild_id, enabled: :undef, channel_id: :undef, reason: nil)
273
552
  json = filter_undef({ enabled: enabled, channel_id: channel_id })
@@ -275,11 +554,22 @@ module Vox
275
554
  request(route, json: json, reason: reason)
276
555
  end
277
556
 
557
+ # Get the vanity url for a guild.
558
+ # @param guild_id [String, Integer] The ID of the target guild.
559
+ # @return [Hash<(:code, :uses), Object>] A partial [invite](https://discord.com/developers/docs/resources/invite#invite-object)
560
+ # object with `code`, and `uses` keys. `code` will be `nil` if a vanity url is not set
561
+ # for the guild.
562
+ # @vox.permissions MANAGE_GUILD
278
563
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-vanity-url
279
564
  def get_guild_vanity_url(guild_id)
280
565
  request(Route.new(:GET, '/guilds/%{guild_id}/vanity-url', guild_id: guild_id))
281
566
  end
282
567
 
568
+ # Get the widget image of guild.
569
+ # @param guild_id [String, Integer] The ID of a target guild.
570
+ # @param style [String] The [widget style](https://discord.com/developers/docs/resources/guild#get-guild-widget-image-widget-style-options)
571
+ # to fetch.
572
+ # @return [String] The PNG image data for the guild widget image.
283
573
  # @vox.api_docs https://discord.com/developers/docs/resources/guild#get-guild-widget-image
284
574
  def get_guild_widget_image(guild_id, style: :undef)
285
575
  params = filter_undef({ style: style })
@@ -2,5 +2,5 @@
2
2
 
3
3
  module Vox
4
4
  # Overall gem version, each component also contains its own version
5
- VERSION = '0.2.0'
5
+ VERSION = '0.2.1'
6
6
  end
@@ -37,6 +37,6 @@ Gem::Specification.new do |spec|
37
37
  spec.add_development_dependency 'rubocop', '~> 0.89.1'
38
38
  spec.add_development_dependency 'rubocop-performance', '~> 1.7.1'
39
39
  spec.add_development_dependency 'rubocop-rspec', '~> 1.42.0'
40
- spec.add_development_dependency 'simplecov', '~> 0.19.0'
40
+ spec.add_development_dependency 'simplecov', '~> 0.17.1'
41
41
  spec.add_development_dependency 'yard', '~> 0.9.25'
42
42
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: vox
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.2.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Matthew Carey
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2020-08-28 00:00:00.000000000 Z
11
+ date: 2020-08-29 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: faraday
@@ -142,14 +142,14 @@ dependencies:
142
142
  requirements:
143
143
  - - "~>"
144
144
  - !ruby/object:Gem::Version
145
- version: 0.19.0
145
+ version: 0.17.1
146
146
  type: :development
147
147
  prerelease: false
148
148
  version_requirements: !ruby/object:Gem::Requirement
149
149
  requirements:
150
150
  - - "~>"
151
151
  - !ruby/object:Gem::Version
152
- version: 0.19.0
152
+ version: 0.17.1
153
153
  - !ruby/object:Gem::Dependency
154
154
  name: yard
155
155
  requirement: !ruby/object:Gem::Requirement