discordrb 3.2.1 → 3.3.0

data/lib/discordrb/api/user.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # API calls for User object
 module Discordrb::API::User
   module_function
@@ -27,7 +29,7 @@ module Discordrb::API::User
   end
 
   # Change the current bot's nickname on a server
-  def change_own_nickname(token, server_id, nick)
+  def change_own_nickname(token, server_id, nick, reason = nil)
     Discordrb::API.request(
       :guilds_sid_members_me_nick,
       server_id, # This is technically a guild endpoint
@@ -35,7 +37,8 @@ module Discordrb::API::User
       "#{Discordrb::API.api_base}/guilds/#{server_id}/members/@me/nick",
       { nick: nick }.to_json,
       Authorization: token,
-      content_type: :json
+      content_type: :json,
+      'X-Audit-Log-Reason': reason
     )
   end
 
@@ -128,8 +131,19 @@ module Discordrb::API::User
     )
   end
 
+  # Returns one of the "default" discord avatars from the CDN given a discriminator
+  def default_avatar(discrim = 0)
+    index = discrim.to_i % 5
+    "#{Discordrb::API.cdn_url}/embed/avatars/#{index}.png"
+  end
+
   # Make an avatar URL from the user and avatar IDs
-  def avatar_url(user_id, avatar_id)
-    "#{Discordrb::API.api_base}/users/#{user_id}/avatars/#{avatar_id}.jpg"
+  def avatar_url(user_id, avatar_id, format = nil)
+    format ||= if avatar_id.start_with?('a_')
+                 'gif'
+               else
+                 'webp'
+               end
+    "#{Discordrb::API.cdn_url}/avatars/#{user_id}/#{avatar_id}.#{format}"
   end
 end

data/lib/discordrb/api/webhook.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# API calls for Webhook object
+module Discordrb::API::Webhook
+  module_function
+
+  # Get a webhook
+  # https://discordapp.com/developers/docs/resources/webhook#get-webhook
+  def webhook(token, webhook_id)
+    Discordrb::API.request(
+      :webhooks_wid,
+      nil,
+      :get,
+      "#{Discordrb::API.api_base}/webhooks/#{webhook_id}",
+      Authorization: token
+    )
+  end
+
+  # Get a webhook via webhook token
+  # https://discordapp.com/developers/docs/resources/webhook#get-webhook-with-token
+  def token_webhook(webhook_token, webhook_id)
+    Discordrb::API.request(
+      :webhooks_wid,
+      nil,
+      :get,
+      "#{Discordrb::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}"
+    )
+  end
+
+  # Update a webhook
+  # https://discordapp.com/developers/docs/resources/webhook#modify-webhook
+  def update_webhook(token, webhook_id, data, reason = nil)
+    Discordrb::API.request(
+      :webhooks_wid,
+      webhook_id,
+      :patch,
+      "#{Discordrb::API.api_base}/webhooks/#{webhook_id}",
+      data.to_json,
+      Authorization: token,
+      content_type: :json,
+      'X-Audit-Log-Reason': reason
+    )
+  end
+
+  # Update a webhook via webhook token
+  # https://discordapp.com/developers/docs/resources/webhook#modify-webhook-with-token
+  def token_update_webhook(webhook_token, webhook_id, data, reason = nil)
+    Discordrb::API.request(
+      :webhooks_wid,
+      webhook_id,
+      :patch,
+      "#{Discordrb::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}",
+      data.to_json,
+      content_type: :json,
+      'X-Audit-Log-Reason': reason
+    )
+  end
+
+  # Deletes a webhook
+  # https://discordapp.com/developers/docs/resources/webhook#delete-webhook
+  def delete_webhook(token, webhook_id, reason = nil)
+    Discordrb::API.request(
+      :webhooks_wid,
+      webhook_id,
+      :delete,
+      "#{Discordrb::API.api_base}/webhooks/#{webhook_id}",
+      Authorization: token,
+      'X-Audit-Log-Reason': reason
+    )
+  end
+
+  # Deletes a webhook via webhook token
+  # https://discordapp.com/developers/docs/resources/webhook#delete-webhook-with-token
+  def token_delete_webhook(webhook_token, webhook_id, reason = nil)
+    Discordrb::API.request(
+      :webhooks_wid,
+      webhook_id,
+      :delete,
+      "#{Discordrb::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}",
+      'X-Audit-Log-Reason': reason
+    )
+  end
+end

data/lib/discordrb/await.rb

@@ -41,7 +41,7 @@ module Discordrb
     # @return [Array] This await's key and whether or not it should be deleted. If there was no match, both are nil.
     def match(event)
       dummy_handler = EventContainer.handler_class(@type).new(@attributes, @bot)
-      return [nil, nil] unless dummy_handler.matches?(event)
+      return [nil, nil] unless event.instance_of?(@type) && dummy_handler.matches?(event)
 
       should_delete = nil
       should_delete = true if (@block && @block.call(event) != false) || !@block

data/lib/discordrb/bot.rb

@@ -17,6 +17,7 @@ require 'discordrb/events/await'
 require 'discordrb/events/bans'
 require 'discordrb/events/raw'
 require 'discordrb/events/reactions'
+require 'discordrb/events/webhooks'
 
 require 'discordrb/api'
 require 'discordrb/api/channel'
@@ -42,11 +43,12 @@ module Discordrb
     # @return [Array<Thread>] The threads.
     attr_reader :event_threads
 
-    # Whether or not the bot should parse its own messages. Off by default.
+    # @return [true, false] whether or not the bot should parse its own messages. Off by default.
     attr_accessor :should_parse_self
 
     # The bot's name which discordrb sends to Discord when making any request, so Discord can identify bots with the
     # same codebase. Not required but I recommend setting it anyway.
+    # @return [String] The bot's name.
     attr_accessor :name
 
     # @return [Array(Integer, Integer)] the current shard key
@@ -76,7 +78,8 @@ module Discordrb
     # @param token [String] The token that should be used to log in. If your bot is a bot account, you have to specify
     #   this. If you're logging in as a user, make sure to also set the account type to :user so discordrb doesn't think
     #   you're trying to log in as a bot.
-    # @param client_id [Integer] If you're logging in as a bot, the bot's client ID.
+    # @param client_id [Integer] If you're logging in as a bot, the bot's client ID. This is optional, and may be fetched
+    #   from the API by calling {Bot#bot_application} (see {Application}).
     # @param type [Symbol] This parameter lets you manually overwrite the account type. This needs to be set when
     #   logging in as a user, otherwise discordrb will treat you as a bot account. Valid values are `:user` and `:bot`.
     # @param name [String] Your bot's name. This will be sent to Discord with any API requests, who will use this to
@@ -89,24 +92,23 @@ module Discordrb
     # @param parse_self [true, false] Whether the bot should react on its own messages. It's best to turn this off
     #   unless you really need this so you don't inadvertently create infinite loops.
     # @param shard_id [Integer] The number of the shard this bot should handle. See
-    #   https://github.com/hammerandchisel/discord-api-docs/issues/17 for how to do sharding.
+    #   https://github.com/discordapp/discord-api-docs/issues/17 for how to do sharding.
     # @param num_shards [Integer] The total number of shards that should be running. See
-    #   https://github.com/hammerandchisel/discord-api-docs/issues/17 for how to do sharding.
+    #   https://github.com/discordapp/discord-api-docs/issues/17 for how to do sharding.
     # @param redact_token [true, false] Whether the bot should redact the token in logs. Default is true.
     # @param ignore_bots [true, false] Whether the bot should ignore bot accounts or not. Default is false.
+    # @param compress_mode [:none, :large, :stream] Sets which compression mode should be used when connecting
+    #   to Discord's gateway. `:none` will request that no payloads are received compressed (not recommended for
+    #   production bots). `:large` will request that large payloads are received compressed. `:stream` will request
+    #   that all data be received in a continuous compressed stream.
     def initialize(
         log_mode: :normal,
         token: nil, client_id: nil,
         type: nil, name: '', fancy_log: false, suppress_ready: false, parse_self: false,
-        shard_id: nil, num_shards: nil, redact_token: true, ignore_bots: false
+        shard_id: nil, num_shards: nil, redact_token: true, ignore_bots: false,
+        compress_mode: :stream
     )
-
-      LOGGER.mode = if log_mode.is_a? TrueClass # Specifically check for `true` because people might not have updated yet
-                      :debug
-                    else
-                      log_mode
-                    end
-
+      LOGGER.mode = log_mode
       LOGGER.token = token if redact_token
 
       @should_parse_self = parse_self
@@ -121,8 +123,10 @@ module Discordrb
       LOGGER.fancy = fancy_log
       @prevent_ready = suppress_ready
 
+      @compress_mode = compress_mode
+
       @token = process_token(@type, token)
-      @gateway = Gateway.new(self, @token, @shard_key)
+      @gateway = Gateway.new(self, @token, @shard_key, @compress_mode)
 
       init_cache
 
@@ -142,6 +146,7 @@ module Discordrb
     # @return [Hash<Integer => User>] The users by ID.
     def users
       gateway_check
+      unavailable_servers_check
       @users
     end
 
@@ -149,29 +154,27 @@ module Discordrb
     # @return [Hash<Integer => Server>] The servers by ID.
     def servers
       gateway_check
+      unavailable_servers_check
       @servers
     end
 
     # @overload emoji(id)
     #   Return an emoji by its ID
-    #   @param id [Integer] The emoji's ID.
-    #   @return emoji [GlobalEmoji, nil] the emoji object. `nil` if the emoji was not found.
+    #   @param id [Integer, #resolve_id] The emoji's ID.
+    #   @return [Emoji, nil] the emoji object. `nil` if the emoji was not found.
     # @overload emoji
     #   The list of emoji the bot can use.
-    #   @return [Array<GlobalEmoji>] the emoji available.
+    #   @return [Array<Emoji>] the emoji available.
     def emoji(id = nil)
       gateway_check
+      unavailable_servers_check
+
+      emoji_hash = @servers.values.map(&:emoji).reduce(&:merge)
       if id
-        emoji
-        @emoji.find { |sth| sth.id == id }
+        id = id.resolve_id
+        emoji_hash[id]
       else
-        emoji = {}
-        @servers.each do |_, server|
-          server.emoji.values.each do |element|
-            emoji[element.name] = GlobalEmoji.new(element, self)
-          end
-        end
-        @emoji = emoji.values
+        emoji_hash.values
       end
     end
 
@@ -199,8 +202,7 @@ module Discordrb
     # The bot's OAuth application.
     # @return [Application, nil] The bot's application info. Returns `nil` if bot is not a bot account.
     def bot_application
-      gateway_check
-      return nil unless @type == :bot
+      return unless @type == :bot
       response = API.oauth_application(token)
       Application.new(JSON.parse(response), self)
     end
@@ -215,31 +217,40 @@ module Discordrb
       @token
     end
 
-    # @return the raw token, without any prefix
+    # @return [String] the raw token, without any prefix
     # @see #token
     def raw_token
       @token.split(' ').last
     end
 
-    # Runs the bot, which logs into Discord and connects the WebSocket. This prevents all further execution unless it is executed with `async` = `:async`.
-    # @param async [Symbol] If it is `:async`, then the bot will allow further execution.
-    #   It doesn't necessarily have to be that, anything truthy will work,
-    #   however it is recommended to use `:async` for code readability reasons.
-    #   If the bot is run in async mode, make sure to eventually run {#sync} so
-    #   the script doesn't stop prematurely.
-    def run(async = false)
+    # Runs the bot, which logs into Discord and connects the WebSocket. This
+    # prevents all further execution unless it is executed with
+    # `backround` = `true`.
+    # @param background [true, false] If it is `true`, then the bot will run in
+    #   another thread to allow further execution. If it is `false`, this method
+    #   will block until {#stop} is called. If the bot is run with `true`, make
+    #   sure to eventually call {#join} so the script doesn't stop prematurely.
+    # @note Running the bot in the background means that you can call some
+    #   methods that require a gateway connection *before* that connection is
+    #   established. In most cases an exception will be raised if you try to do
+    #   this. If you need a way to safely run code after the bot is fully
+    #   connected, use a {#ready} event handler instead.
+    def run(background = false)
       @gateway.run_async
-      return if async
+      return if background
 
       debug('Oh wait! Not exiting yet as run was run synchronously.')
       @gateway.sync
     end
 
-    # Blocks execution until the websocket stops, which should only happen manually triggered
-    # or due to an error. This is necessary to have a continuously running bot.
-    def sync
+    # Joins the bot's connection thread with the current thread.
+    # This blocks execution until the websocket stops, which should only happen
+    # manually triggered. or due to an error. This is necessary to have a
+    # continuously running bot.
+    def join
       @gateway.sync
     end
+    alias_method :sync, :join
 
     # Stops the bot gracefully, disconnecting the websocket without immediately killing the thread. This means that
     # Discord is immediately aware of the closed connection and makes the bot appear offline instantly.
@@ -255,18 +266,17 @@ module Discordrb
 
     # Makes the bot join an invite to a server.
     # @param invite [String, Invite] The invite to join. For possible formats see {#resolve_invite_code}.
-    def join(invite)
+    def accept_invite(invite)
       resolved = invite(invite).code
       API::Invite.accept(token, resolved)
     end
 
     # Creates an OAuth invite URL that can be used to invite this bot to a particular server.
-    # Requires the application ID to have been set during initialization.
     # @param server [Server, nil] The server the bot should be invited to, or nil if a general invite should be created.
     # @param permission_bits [Integer, String] Permission bits that should be appended to invite url.
     # @return [String] the OAuth invite URL.
     def invite_url(server: nil, permission_bits: nil)
-      raise 'No application ID has been set during initialization! Add one as the `client_id` named parameter while creating your bot.' unless @client_id
+      @client_id ||= bot_application.id
 
       server_id_str = server ? "&guild_id=#{server.id}" : ''
       permission_bits_str = permission_bits ? "&permissions=#{permission_bits}" : ''
@@ -279,7 +289,7 @@ module Discordrb
     # Gets the voice bot for a particular server or channel. You can connect to a new channel using the {#voice_connect}
     # method.
     # @param thing [Channel, Server, Integer] the server or channel you want to get the voice bot for, or its ID.
-    # @return [VoiceBot, nil] the VoiceBot for the thing you specified, or nil if there is no connection yet
+    # @return [Voice::VoiceBot, nil] the VoiceBot for the thing you specified, or nil if there is no connection yet
     def voice(thing)
       id = thing.resolve_id
       return @voices[id] if @voices[id]
@@ -297,7 +307,7 @@ module Discordrb
     # data can then be sent. After connecting, the bot can also be accessed using {#voice}. If the bot is already
     # connected to voice, the existing connection will be terminated - you don't have to call
     # {Discordrb::Voice::VoiceBot#destroy} before calling this method.
-    # @param chan [Channel] The voice channel to connect to.
+    # @param chan [Channel, Integer, #resolve_id] The voice channel to connect to.
     # @param encrypted [true, false] Whether voice communication should be encrypted using RbNaCl's SecretBox
     #   (uses an XSalsa20 stream cipher for encryption and Poly1305 for authentication)
     # @return [Voice::VoiceBot] the initialized bot over which audio data can then be sent.
@@ -326,13 +336,14 @@ module Discordrb
 
     # Disconnects the client from a specific voice connection given the server ID. Usually it's more convenient to use
     # {Discordrb::Voice::VoiceBot#destroy} rather than this.
-    # @param server_id [Integer] The ID of the server the voice connection is on.
+    # @param server [Server, Integer, #resolve_id] The server the voice connection is on.
     # @param destroy_vws [true, false] Whether or not the VWS should also be destroyed. If you're calling this method
     #   directly, you should leave it as true.
-    def voice_destroy(server_id, destroy_vws = true)
-      @gateway.send_voice_state_update(server_id.to_s, nil, false, false)
-      @voices[server_id].destroy if @voices[server_id] && destroy_vws
-      @voices.delete(server_id)
+    def voice_destroy(server, destroy_vws = true)
+      server = server.resolve_id
+      @gateway.send_voice_state_update(server.to_s, nil, false, false)
+      @voices[server].destroy if @voices[server] && destroy_vws
+      @voices.delete(server)
     end
 
     # Revokes an invite to a server. Will fail unless you have the *Manage Server* permission.
@@ -344,32 +355,32 @@ module Discordrb
     end
 
     # Sends a text message to a channel given its ID and the message's content.
-    # @param channel_id [Integer] The ID that identifies the channel to send something to.
+    # @param channel [Channel, Integer, #resolve_id] The channel to send something to.
     # @param content [String] The text that should be sent as a message. It is limited to 2000 characters (Discord imposed).
     # @param tts [true, false] Whether or not this message should be sent using Discord text-to-speech.
     # @param embed [Hash, Discordrb::Webhooks::Embed, nil] The rich embed to append to this message.
     # @return [Message] The message that was sent.
-    def send_message(channel_id, content, tts = false, embed = nil)
-      channel_id = channel_id.resolve_id
-      debug("Sending message to #{channel_id} with content '#{content}'")
+    def send_message(channel, content, tts = false, embed = nil)
+      channel = channel.resolve_id
+      debug("Sending message to #{channel} with content '#{content}'")
 
-      response = API::Channel.create_message(token, channel_id, content, [], tts, embed ? embed.to_hash : nil)
+      response = API::Channel.create_message(token, channel, content, tts, embed ? embed.to_hash : nil)
       Message.new(JSON.parse(response), self)
     end
 
     # Sends a text message to a channel given its ID and the message's content,
     # then deletes it after the specified timeout in seconds.
-    # @param channel_id [Integer] The ID that identifies the channel to send something to.
+    # @param channel [Channel, Integer, #resolve_id] The channel to send something to.
     # @param content [String] The text that should be sent as a message. It is limited to 2000 characters (Discord imposed).
     # @param timeout [Float] The amount of time in seconds after which the message sent will be deleted.
     # @param tts [true, false] Whether or not this message should be sent using Discord text-to-speech.
     # @param embed [Hash, Discordrb::Webhooks::Embed, nil] The rich embed to append to this message.
-    def send_temporary_message(channel_id, content, timeout, tts = false, embed = nil)
+    def send_temporary_message(channel, content, timeout, tts = false, embed = nil)
       Thread.new do
-        message = send_message(channel_id, content, tts, embed)
+        Thread.current[:discordrb_name] = "#{@current_thread}-temp-msg"
 
+        message = send_message(channel, content, tts, embed)
         sleep(timeout)
-
         message.delete
       end
 
@@ -378,12 +389,15 @@ module Discordrb
 
     # Sends a file to a channel. If it is an image, it will automatically be embedded.
     # @note This executes in a blocking way, so if you're sending long files, be wary of delays.
-    # @param channel_id [Integer] The ID that identifies the channel to send something to.
+    # @param channel [Channel, Integer, #resolve_id] The channel to send something to.
     # @param file [File] The file that should be sent.
     # @param caption [string] The caption for the file.
     # @param tts [true, false] Whether or not this file's caption should be sent using Discord text-to-speech.
-    def send_file(channel_id, file, caption: nil, tts: false)
-      response = API::Channel.upload_file(token, channel_id, file, caption: caption, tts: tts)
+    # @example Send a file from disk
+    #   bot.send_file(83281822225530880, File.open('rubytaco.png', 'r'))
+    def send_file(channel, file, caption: nil, tts: false)
+      channel = channel.resolve_id
+      response = API::Channel.upload_file(token, channel, file, caption: caption, tts: tts)
       Message.new(JSON.parse(response), self)
     end
 
@@ -391,19 +405,9 @@ module Discordrb
     # @note Discord's API doesn't directly return the server when creating it, so this method
     #   waits until the data has been received via the websocket. This may make the execution take a while.
     # @param name [String] The name the new server should have. Doesn't have to be alphanumeric.
-    # @param region [Symbol] The region where the server should be created. Possible regions are:
-    #
-    #   * `:london`
-    #   * `:amsterdam`
-    #   * `:frankfurt`
-    #   * `:us-east`
-    #   * `:us-west`
-    #   * `:us-south`
-    #   * `:us-central`
-    #   * `:singapore`
-    #   * `:sydney`
+    # @param region [Symbol] The region where the server should be created, for example 'eu-central' or 'hongkong'.
     # @return [Server] The server that was created.
-    def create_server(name, region = :london)
+    def create_server(name, region = :'eu-central')
       response = API::Server.create(token, name, region)
       id = JSON.parse(response)['id'].to_i
       sleep 0.1 until @servers[id]
@@ -432,45 +436,51 @@ module Discordrb
       API.update_oauth_application(@token, name, redirect_uris, description, icon)
     end
 
-    # Gets the user, role or emoji from a mention of the user, role or emoji.
-    # @param mention [String] The mention, which should look like `<@12314873129>`, `<@&123456789>` or `<:Name:126328:>`.
+    # Gets the user, channel, role or emoji from a mention of the user, channel, role or emoji.
+    # @param mention [String] The mention, which should look like `<@12314873129>`, `<#123456789>`, `<@&123456789>` or `<:name:126328:>`.
     # @param server [Server, nil] The server of the associated mention. (recommended for role parsing, to speed things up)
-    # @return [User, Role, Emoji] The user, role or emoji identified by the mention, or `nil` if none exists.
+    # @return [User, Channel, Role, Emoji] The user, channel, role or emoji identified by the mention, or `nil` if none exists.
     def parse_mention(mention, server = nil)
       # Mention format: <@id>
-      if /<@!?(?<id>\d+)>?/ =~ mention
-        user(id.to_i)
-      elsif /<@&(?<id>\d+)>?/ =~ mention
-        return server.role(id.to_i) if server
+      if /<@!?(?<id>\d+)>/ =~ mention
+        user(id)
+      elsif /<#(?<id>\d+)>/ =~ mention
+        channel(id, server)
+      elsif /<@&(?<id>\d+)>/ =~ mention
+        return server.role(id) if server
         @servers.values.each do |element|
-          role = element.role(id.to_i)
+          role = element.role(id)
           return role unless role.nil?
         end
 
         # Return nil if no role is found
         nil
-      elsif /<:(\w+):(?<id>\d+)>?/ =~ mention
-        emoji.find { |element| element.id.to_i == id.to_i }
+      elsif /<(?<animated>a)?:(?<name>\w+):(?<id>\d+)>/ =~ mention
+        emoji(id) || Emoji.new({ 'animated' => !animated.nil?, 'name' => name, 'id' => id }, self, nil)
       end
     end
 
     # Updates presence status.
-    # @param status [String] The status the bot should show up as.
-    # @param game [String, nil] The name of the game to be played/stream name on the stream.
+    # @param status [String] The status the bot should show up as. Can be `online`, `dnd`, `idle`, or `invisible`
+    # @param activity [String, nil] The name of the activity to be played/watched/listened to/stream name on the stream.
     # @param url [String, nil] The Twitch URL to display as a stream. nil for no stream.
     # @param since [Integer] When this status was set.
     # @param afk [true, false] Whether the bot is AFK.
+    # @param activity_type [Integer] The type of activity status to display. Can be 0 (Playing), 1 (Streaming), 2 (Listening), 3 (Watching)
     # @see Gateway#send_status_update
-    def update_status(status, game, url, since = 0, afk = false)
+    def update_status(status, activity, url, since = 0, afk = false, activity_type = 0)
       gateway_check
 
-      @game = game
+      @activity = activity
       @status = status
       @streamurl = url
-      type = url ? 1 : 0
+      type = url ? 1 : activity_type
+
+      activity_obj = activity || url ? { 'name' => activity, 'url' => url, 'type' => type } : nil
+      @gateway.send_status_update(status, since, activity_obj, afk)
 
-      game_obj = game || url ? { name: game, url: url, type: type } : nil
-      @gateway.send_status_update(status, since, game_obj, afk)
+      # Update the status in the cache
+      profile.update_presence('status' => status.to_s, 'game' => activity_obj)
     end
 
     # Sets the currently playing game to the specified game.
@@ -482,6 +492,26 @@ module Discordrb
       name
     end
 
+    alias_method :playing=, :game=
+
+    # Sets the current listening status to the specified name.
+    # @param name [String] The thing to be listened to.
+    # @return [String] The thing that is now being listened to.
+    def listening=(name)
+      gateway_check
+      update_status(@status, name, nil, nil, nil, 2)
+      name
+    end
+
+    # Sets the current watching status to the specified name.
+    # @param name [String] The thing to be watched.
+    # @return [String] The thing that is now being watched.
+    def watching=(name)
+      gateway_check
+      update_status(@status, name, nil, nil, nil, 3)
+      name
+    end
+
     # Sets the currently online stream to the specified name and Twitch URL.
     # @param name [String] The name of the stream to display.
     # @param url [String] The url of the current Twitch stream.
@@ -495,7 +525,7 @@ module Discordrb
     # Sets status to online.
     def online
       gateway_check
-      update_status(:online, @game, @streamurl)
+      update_status(:online, @activity, @streamurl)
     end
 
     alias_method :on, :online
@@ -503,7 +533,7 @@ module Discordrb
     # Sets status to idle.
     def idle
       gateway_check
-      update_status(:idle, @game, nil)
+      update_status(:idle, @activity, nil)
     end
 
     alias_method :away, :idle
@@ -511,13 +541,13 @@ module Discordrb
     # Sets the bot's status to DnD (red icon).
     def dnd
       gateway_check
-      update_status(:dnd, @game, nil)
+      update_status(:dnd, @activity, nil)
     end
 
     # Sets the bot's status to invisible (appears offline).
     def invisible
       gateway_check
-      update_status(:invisible, @game, nil)
+      update_status(:invisible, @activity, nil)
     end
 
     # Sets debug mode. If debug mode is on, many things will be outputted to STDOUT.
@@ -543,6 +573,7 @@ module Discordrb
     # @yield Is executed when the await is triggered.
     # @yieldparam event [Event] The event object that was triggered.
     # @return [Await] The await that was created.
+    # @deprecated Will be changed to blocking behavior in v4.0. Use {#add_await!} instead.
     def add_await(key, type, attributes = {}, &block)
       raise "You can't await an AwaitEvent!" if type == Discordrb::Events::AwaitEvent
       await = Await.new(self, key, type, attributes, block)
@@ -550,6 +581,43 @@ module Discordrb
       @awaits[key] = await
     end
 
+    # Awaits an event, blocking the current thread until a response is received.
+    # @param type [Class] The event class that should be listened for.
+    # @option attributes [Numeric] :timeout the amount of time to wait for a response before returning `nil`. Waits forever if omitted.
+    # @return [Event, nil] The event object that was triggered, or `nil` if a `timeout` was set and no event was raised in time.
+    # @raise [ArgumentError] if `timeout` is given and is not a positive numeric value
+    def add_await!(type, attributes = {})
+      raise "You can't await an AwaitEvent!" if type == Discordrb::Events::AwaitEvent
+
+      timeout = attributes[:timeout]
+      raise ArgumentError, 'Timeout must be a number > 0' if timeout && timeout.is_a?(Numeric) && timeout <= 0
+
+      mutex = Mutex.new
+      cv = ConditionVariable.new
+      response = nil
+      block = lambda do |event|
+        mutex.synchronize do
+          response = event
+          cv.signal
+        end
+      end
+
+      handler = register_event(type, attributes, block)
+
+      if timeout
+        Thread.new do
+          sleep timeout
+          mutex.synchronize { cv.signal }
+        end
+      end
+
+      mutex.synchronize { cv.wait(mutex) }
+
+      remove_handler(handler)
+      raise 'ConditionVariable was signaled without returning an event!' if response.nil? && timeout.nil?
+      response
+    end
+
     # Add a user to the list of ignored users. Those users will be ignored in message events at event processing level.
     # @note Ignoring a user only prevents any message events (including mentions, commands etc.) from them! Typing and
     #   presence and any other events will still be received.
@@ -591,6 +659,7 @@ module Discordrb
       raise_event(HeartbeatEvent.new(self))
     end
 
+    # Makes the bot leave any groups with no recipients remaining
     def prune_empty_groups
       @channels.each_value do |channel|
         channel.leave_group if channel.group? && channel.recipients.empty?
@@ -599,11 +668,18 @@ module Discordrb
 
     private
 
-    # Throws a useful exception if there's currently no gateway connection
+    # Throws a useful exception if there's currently no gateway connection.
     def gateway_check
-      return if connected?
+      raise "A gateway connection is necessary to call this method! You'll have to do it inside any event (e.g. `ready`) or after `bot.run :async`." unless connected?
+    end
 
-      raise "A gateway connection is necessary to call this method! You'll have to do it inside any event (e.g. `ready`) or after `bot.run :async`."
+    # Logs a warning if there are servers which are still unavailable.
+    # e.g. due to a Discord outage or because the servers are large and taking a while to load.
+    def unavailable_servers_check
+      # Return unless there are servers that are unavailable.
+      return unless @unavailable_servers && @unavailable_servers > 0
+      LOGGER.warn("#{@unavailable_servers} servers haven't been cached yet.")
+      LOGGER.warn('Servers may be unavailable due to an outage, or your bot is on very large servers that are taking a while to load.')
     end
 
     ### ##    ## ######## ######## ########  ##    ##    ###    ##        ######
@@ -813,7 +889,12 @@ module Discordrb
       server_id = data['guild_id'].to_i
       server = @servers[server_id]
       new_role = Role.new(role_data, self, server)
-      server.add_role(new_role)
+      existing_role = server.role(new_role.id)
+      if existing_role
+        existing_role.update_from(new_role)
+      else
+        server.add_role(new_role)
+      end
     end
 
     # Internal handler for GUILD_ROLE_DELETE
@@ -878,8 +959,8 @@ module Discordrb
       # Check whether there are still unavailable servers and there have been more than 10 seconds since READY
       if @unavailable_servers && @unavailable_servers > 0 && (Time.now - @unavailable_timeout_time) > 10
         # The server streaming timed out!
-        LOGGER.warn("Server streaming timed out with #{@unavailable_servers} servers remaining")
-        LOGGER.warn("This means some servers are unavailable due to an outage. Notifying ready now, we'll have to live without these servers")
+        LOGGER.debug("Server streaming timed out with #{@unavailable_servers} servers remaining")
+        LOGGER.debug('Calling ready now because server loading is taking a long time. Servers may be unavailable due to an outage, or your bot is on very large servers.')
 
         # Unset the unavailable server count so this doesn't get triggered again
         @unavailable_servers = 0
@@ -1014,11 +1095,15 @@ module Discordrb
       when :MESSAGE_REACTION_ADD
         add_message_reaction(data)
 
+        return if profile.id == data['user_id'].to_i && !should_parse_self
+
         event = ReactionAddEvent.new(data, self)
         raise_event(event)
       when :MESSAGE_REACTION_REMOVE
         remove_message_reaction(data)
 
+        return if profile.id == data['user_id'].to_i && !should_parse_self
+
         event = ReactionRemoveEvent.new(data, self)
         raise_event(event)
       when :MESSAGE_REACTION_REMOVE_ALL
@@ -1030,7 +1115,7 @@ module Discordrb
         # Ignore friends list presences
         return unless data['guild_id']
 
-        now_playing = data['game']
+        now_playing = data['game'].nil? ? nil : data['game']['name']
         presence_user = @users[data['user']['id'].to_i]
         played_before = presence_user.nil? ? nil : presence_user.game
         update_presence(data)
@@ -1177,6 +1262,9 @@ module Discordrb
           event = ServerEmojiUpdateEvent.new(server, old_emoji_data[e], new_emoji_data[e], self)
           raise_event(event)
         end
+      when :WEBHOOKS_UPDATE
+        event = WebhookUpdateEvent.new(data, self)
+        raise_event(event)
       else
         # another event that we don't support yet
         debug "Event #{type} has been received but is unsupported. Raising UnknownEvent"
@@ -1211,7 +1299,8 @@ module Discordrb
 
       @event_handlers ||= {}
       handlers = @event_handlers[event.class]
-      (handlers || []).each do |handler|
+      return unless handlers
+      handlers.dup.each do |handler|
         call_event(handler, event) if handler.matches?(event)
       end
     end