discordrb 3.1.1 → 3.2.0

data/lib/discordrb/data.rb

@@ -10,6 +10,7 @@ require 'discordrb/api/channel'
 require 'discordrb/api/server'
 require 'discordrb/api/invite'
 require 'discordrb/api/user'
+require 'discordrb/webhooks/embeds'
 require 'time'
 require 'base64'
 
@@ -84,6 +85,18 @@ module Discordrb
       ms = (@id >> 22) + DISCORD_EPOCH
       Time.at(ms / 1000.0)
     end
+
+    # Creates an artificial snowflake at the given point in time. Useful for comparing against.
+    # @param time [Time] The time the snowflake should represent.
+    # @return [Integer] a snowflake with the timestamp data as the given time
+    def self.synthesise(time)
+      ms = (time.to_f * 1000).to_i
+      (ms - DISCORD_EPOCH) << 22
+    end
+
+    class << self
+      alias_method :synthesize, :synthesise
+    end
   end
 
   # Mixin for the attributes users should have
@@ -104,7 +117,7 @@ module Discordrb
 
     # @return [String] the ID of this user's current avatar, can be used to generate an avatar URL.
     # @see #avatar_url
-    attr_reader :avatar_id
+    attr_accessor :avatar_id
 
     # Utility function to mention users in messages
     # @return [String] the mention code in the form of <@id>
@@ -130,13 +143,18 @@ module Discordrb
     include IDObject
     include UserAttributes
 
-    # @!attribute [r] status
-    #   @return [Symbol] the current online status of the user (`:online`, `:offline` or `:idle`)
-    attr_accessor :status
+    # @return [Symbol] the current online status of the user (`:online`, `:offline` or `:idle`)
+    attr_reader :status
+
+    # @return [String, nil] the game the user is currently playing, or `nil` if none is being played.
+    attr_reader :game
+
+    # @return [String, nil] the URL to the stream, if the user is currently streaming something.
+    attr_reader :stream_url
 
-    # @!attribute [r] game
-    #   @return [String, nil] the game the user is currently playing, or `nil` if none is being played.
-    attr_accessor :game
+    # @return [String, Integer, nil] the type of the stream. Can technically be set to anything, most of the time it
+    #   will be 0 for no stream or 1 for Twitch streams.
+    attr_reader :stream_type
 
     def initialize(data, bot)
       @bot = bot
@@ -189,6 +207,23 @@ module Discordrb
       @username = username
     end
 
+    # Set the user's presence data
+    # @note for internal use only
+    # @!visibility private
+    def update_presence(data)
+      @status = data['status'].to_sym
+
+      if data['game']
+        game = data['game']
+
+        @game = game['name']
+        @stream_url = game['url']
+        @stream_type = game['type']
+      else
+        @game = @stream_url = @stream_type = nil
+      end
+    end
+
     # Add an await for a message from this user. Specifically, this adds a global await for a MessageEvent with this
     # user's ID as a :from attribute.
     # @see Bot#add_await
@@ -418,6 +453,8 @@ module Discordrb
     end
   end
 
+  # A presence represents a
+
   # A member is a user on a server. It differs from regular users in that it has roles, voice statuses and things like
   # that.
   class Member < DelegateClass(User)
@@ -1031,6 +1068,7 @@ module Discordrb
     # `allow` and `deny` properties which are {Permissions} objects respectively.
     # @return [Hash<Integer => OpenStruct>] the channel's permission overwrites
     attr_reader :permission_overwrites
+    alias_method :overwrites, :permission_overwrites
 
     # @return [true, false] whether or not this channel is a PM or group channel.
     def private?
@@ -1119,9 +1157,10 @@ module Discordrb
     # Sends a message to this channel.
     # @param content [String] The content to send. Should not be longer than 2000 characters or it will result in an error.
     # @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(content, tts = false)
-      @bot.send_message(@id, content, tts, @server && @server.id)
+    def send_message(content, tts = false, embed = nil)
+      @bot.send_message(@id, content, tts, embed)
     end
 
     alias_method :send, :send_message
@@ -1130,8 +1169,26 @@ module Discordrb
     # @param content [String] The content to send. Should not be longer than 2000 characters or it will result in an error.
     # @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.
-    def send_temporary_message(content, timeout, tts = false)
-      @bot.send_temporary_message(@id, content, timeout, tts, @server && @server.id)
+    # @param embed [Hash, Discordrb::Webhooks::Embed, nil] The rich embed to append to this message.
+    def send_temporary_message(content, timeout, tts = false, embed = nil)
+      @bot.send_temporary_message(@id, content, timeout, tts, embed)
+    end
+
+    # Convenience method to send a message with an embed.
+    # @example Send a message with an embed
+    #   channel.send_embed do |embed|
+    #     embed.title = 'The Ruby logo'
+    #     embed.image = Discordrb::Webhooks::EmbedImage.new(url: 'https://www.ruby-lang.org/images/header-ruby-logo.png')
+    #   end
+    # @param message [String] The message that should be sent along with the embed. If this is the empty string, only the embed will be shown.
+    # @param embed [Discordrb::Webhooks::Embed, nil] The embed to start the building process with, or nil if one should be created anew.
+    # @yield [embed] Yields the embed to allow for easy building inside a block.
+    # @yieldparam embed [Discordrb::Webhooks::Embed] The embed from the parameters, or a new one.
+    # @return [Message] The resulting message.
+    def send_embed(message = '', embed = nil)
+      embed ||= Discordrb::Webhooks::Embed.new
+      yield(embed) if block_given?
+      send_message(message, false, embed)
     end
 
     # Sends multiple messages to a channel
@@ -1154,6 +1211,12 @@ module Discordrb
       @bot.send_file(@id, file, caption: caption, tts: tts)
     end
 
+    # Deletes a message on this channel. Mostly useful in case a message needs to be deleted when only the ID is known
+    # @param message [Message, String, Integer, #resolve_id] The message that should be deleted.
+    def delete_message(message)
+      API::Channel.delete_message(@bot.token, @id, message.resolve_id)
+    end
+
     # Permanently deletes this channel
     def delete
       API::Channel.delete(@bot.token, @id)
@@ -1230,12 +1293,25 @@ module Discordrb
       API::Channel.update_permission(@bot.token, @id, thing.id, allow_bits, deny_bits, type)
     end
 
+    # Deletes a permission overwrite for this channel
+    # @param target [Member, User, Role, Profile, Recipient, #resolve_id] What permission overwrite to delete
+    def delete_overwrite(target)
+      raise 'Tried deleting a overwrite for an invalid target' unless target.is_a?(Member) || target.is_a?(User) || target.is_a?(Role) || target.is_a?(Profile) || target.is_a?(Recipient) || target.respond_to?(:resolve_id)
+
+      API::Channel.delete_permission(@bot.token, @id, target.resolve_id)
+    end
+
     # Updates the cached data from another channel.
     # @note For internal use only
     # @!visibility private
     def update_from(other)
       @topic = other.topic
       @name = other.name
+      @position = other.position
+      @topic = other.topic
+      @recipients = other.recipients
+      @bitrate = other.bitrate
+      @user_limit = other.user_limit
       @permission_overwrites = other.permission_overwrites
     end
 
@@ -1270,7 +1346,7 @@ module Discordrb
     # @!visibility private
     def history_ids(amount, before_id = nil, after_id = nil)
       logs = API::Channel.messages(@bot.token, @id, amount, before_id, after_id)
-      JSON.parse(logs).map { |message| message['id'] }
+      JSON.parse(logs).map { |message| message['id'].to_i }
     end
 
     # Returns a single message from this channel's history by ID.
@@ -1294,22 +1370,26 @@ module Discordrb
 
     # Delete the last N messages on this channel.
     # @param amount [Integer] How many messages to delete. Must be a value between 2 and 100 (Discord limitation)
+    # @param strict [true, false] Whether an error should be raised when a message is reached that is too old to be bulk
+    #   deleted. If this is false only a warning message will be output to the console.
     # @raise [ArgumentError] if the amount of messages is not a value between 2 and 100
-    def prune(amount)
+    def prune(amount, strict = false)
       raise ArgumentError, 'Can only prune between 2 and 100 messages!' unless amount.between?(2, 100)
 
       messages = history_ids(amount)
-      API::Channel.bulk_delete_messages(@bot.token, @id, messages)
+      bulk_delete(messages, strict)
     end
 
     # Deletes a collection of messages
     # @param messages [Array<Message, Integer>] the messages (or message IDs) to delete. Total must be an amount between 2 and 100 (Discord limitation)
+    # @param strict [true, false] Whether an error should be raised when a message is reached that is too old to be bulk
+    #   deleted. If this is false only a warning message will be output to the console.
     # @raise [ArgumentError] if the amount of messages is not a value between 2 and 100
-    def delete_messages(messages)
+    def delete_messages(messages, strict = false)
       raise ArgumentError, 'Can only delete between 2 and 100 messages!' unless messages.count.between?(2, 100)
 
       messages.map!(&:resolve_id)
-      API::Channel.bulk_delete_messages(@bot.token, @id, messages)
+      bulk_delete(messages, strict)
     end
 
     # Updates the cached permission overwrites
@@ -1414,13 +1494,32 @@ module Discordrb
     # @note For internal use only
     # @!visibility private
     def remove_recipient(recipient)
-      raise 'Tried to add recipient to a non-group channel' unless group?
+      raise 'Tried to remove recipient from a non-group channel' unless group?
       raise ArgumentError, 'Tried to remove a non-recipient from a group' unless recipient.is_a?(Recipient)
       @recipients.delete(recipient)
     end
 
     private
 
+    # For bulk_delete checking
+    TWO_WEEKS = 86_400 * 14
+
+    # Deletes a list of messages on this channel using bulk delete
+    def bulk_delete(ids, strict = false)
+      min_snowflake = IDObject.synthesise(Time.now - TWO_WEEKS)
+
+      ids.reject! do |e|
+        next unless e < min_snowflake
+
+        message = "Attempted to bulk_delete message #{e} which is too old (min = #{min_snowflake})"
+        raise ArgumentError, message if strict
+        Discordrb::LOGGER.warn(message)
+        false
+      end
+
+      API::Channel.bulk_delete_messages(@bot.token, @id, ids)
+    end
+
     def update_channel_data
       API::Channel.update(@bot.token, @id, @name, @topic, @position, @bitrate, @user_limit)
     end
@@ -1597,7 +1696,8 @@ module Discordrb
     alias_method :text, :content
     alias_method :to_s, :content
 
-    # @return [Member] the user that sent this message.
+    # @return [Member, User] the user that sent this message. (Will be a {Member} most of the time, it should only be a
+    #   {User} for old messages when the author has left the server since then)
     attr_reader :author
     alias_method :user, :author
     alias_method :writer, :author
@@ -1624,6 +1724,9 @@ module Discordrb
     # @return [Array<Embed>] the embed objects contained in this message.
     attr_reader :embeds
 
+    # @return [Hash<String, Reaction>] the reaction objects attached to this message keyed by the name of the reaction
+    attr_reader :reactions
+
     # @return [true, false] whether the message used Text-To-Speech (TTS) or not.
     attr_reader :tts
     alias_method :tts?, :tts
@@ -1672,7 +1775,12 @@ module Discordrb
                     Recipient.new(bot.user(data['author']['id'].to_i), @channel, bot)
                   else
                     member = @channel.server.member(data['author']['id'].to_i)
-                    Discordrb::LOGGER.warn("Member with ID #{data['author']['id']} not cached even though it should be.") unless member
+
+                    unless member
+                      Discordrb::LOGGER.debug("Member with ID #{data['author']['id']} not cached (possibly left the server).")
+                      member = @bot.user(data['author']['id'].to_i)
+                    end
+
                     member
                   end
                 end
@@ -1686,19 +1794,31 @@ module Discordrb
 
       @emoji = []
 
+      @reactions = {}
+
+      if data['reactions']
+        data['reactions'].each do |element|
+          @reactions[element['emoji']['name']] = Reaction.new(element)
+        end
+      end
+
       @mentions = []
 
-      data['mentions'].each do |element|
-        @mentions << bot.ensure_user(element)
-      end if data['mentions']
+      if data['mentions']
+        data['mentions'].each do |element|
+          @mentions << bot.ensure_user(element)
+        end
+      end
 
       @role_mentions = []
 
       # Role mentions can only happen on public servers so make sure we only parse them there
       if @channel.text?
-        data['mention_roles'].each do |element|
-          @role_mentions << @channel.server.role(element.to_i)
-        end if data['mention_roles']
+        if data['mention_roles']
+          data['mention_roles'].each do |element|
+            @role_mentions << @channel.server.role(element.to_i)
+          end
+        end
       end
 
       @attachments = []
@@ -1717,9 +1837,10 @@ module Discordrb
     # Edits this message to have the specified content instead.
     # You can only edit your own messages.
     # @param new_content [String] the new content the message should have.
+    # @param new_embed [Hash, Discordrb::Webhooks::Embed, nil] The new embed the message should have. If nil the message will be changed to have no embed.
     # @return [Message] the resulting message.
-    def edit(new_content)
-      response = API::Channel.edit_message(@bot.token, @channel.id, @id, new_content)
+    def edit(new_content, new_embed = nil)
+      response = API::Channel.edit_message(@bot.token, @channel.id, @id, new_content, [], new_embed ? new_embed.to_hash : nil)
       Message.new(JSON.parse(response), @bot)
     end
 
@@ -1785,12 +1906,86 @@ module Discordrb
       return true unless emoji.empty?
     end
 
+    # Check if any reactions got used in this message
+    # @return [true, false] whether or not this message has reactions
+    def reactions?
+      @reactions.any?
+    end
+
+    # Returns the reactions made by the current bot or user
+    # @return [Array<Reaction>] the reactions
+    def my_reactions
+      @reactions.select(&:me)
+    end
+
+    # Reacts to a message
+    # @param [String, #to_reaction] the unicode emoji, Emoji, or GlobalEmoji
+    def create_reaction(reaction)
+      reaction = reaction.to_reaction if reaction.respond_to?(:to_reaction)
+      API::Channel.create_reaction(@bot.token, @channel.id, @id, reaction)
+      nil
+    end
+
+    alias_method :react, :create_reaction
+
+    # Returns the list of users who reacted with a certain reaction
+    # @param [String, #to_reaction] the unicode emoji, Emoji, or GlobalEmoji
+    # @return [Array<User>] the users who used this reaction
+    def reacted_with(reaction)
+      reaction = reaction.to_reaction if reaction.respond_to?(:to_reaction)
+      response = JSON.parse(API::Channel.get_reactions(@bot.token, @channel.id, @id, reaction))
+      response.map { |d| User.new(d, @bot) }
+    end
+
+    # Deletes a reaction made by a user on this message
+    # @param [User, #resolve_id] the user who used this reaction
+    # @param [String, #to_reaction] the reaction to remove
+    def delete_reaction(user, reaction)
+      reaction = reaction.to_reaction if reaction.respond_to?(:to_reaction)
+      API::Channel.delete_user_reaction(@bot.token, @channel.id, @id, reaction, user.resolve_id)
+    end
+
+    # Delete's this clients reaction on this message
+    # @param [String, #to_reaction] the reaction to remove
+    def delete_own_reaction(reaction)
+      reaction = reaction.to_reaction if reaction.respond_to?(:to_reaction)
+      API::Channel.delete_own_reaction(@bot.token, @channel.id, @id, reaction)
+    end
+
+    # Removes all reactions from this message
+    def delete_all_reactions
+      API::Channel.delete_all_reactions(@bot.token, @channel.id, @id)
+    end
+
     # The inspect method is overwritten to give more useful output
     def inspect
       "<Message content=\"#{@content}\" id=#{@id} timestamp=#{@timestamp} author=#{@author} channel=#{@channel}>"
     end
   end
 
+  # A reaction to a message
+  class Reaction
+    # @return [Integer] the amount of users who have reacted with this reaction
+    attr_reader :count
+
+    # @return [true, false] whether the current bot or user used this reaction
+    attr_reader :me
+    alias_method :me?, :me
+
+    # @return [Integer] the ID of the emoji, if it was custom
+    attr_reader :id
+
+    # @return [String] the name or unicode representation of the emoji
+    attr_reader :name
+
+    def initialize(data)
+      @count = data['count']
+      @me = data['me']
+      @id = data['emoji']['id'].nil? ? nil : data['emoji']['id'].to_i
+      @name = data['emoji']['name']
+    end
+  end
+
   # Server emoji
   class Emoji
     include IDObject
@@ -1810,7 +2005,7 @@ module Discordrb
 
       @name = data['name']
       @server = server
-      @id = data['id'].to_i
+      @id = data['id'].nil? ? nil : data['id'].to_i
 
       process_roles(data['roles']) if server
     end
@@ -1823,6 +2018,11 @@ module Discordrb
     alias_method :use, :mention
     alias_method :to_s, :mention
 
+    # @return [String] the layout to use this emoji in a reaction
+    def to_reaction
+      "#{@name}:#{@id}"
+    end
+
     # @return [String] the icon URL of the emoji
     def icon_url
       API.emoji_icon_url(@id)
@@ -1872,6 +2072,11 @@ module Discordrb
     alias_method :use, :mention
     alias_method :to_s, :mention
 
+    # @return [String] the layout to use this emoji in a reaction
+    def to_reaction
+      "#{@name}:#{@id}"
+    end
+
     # @return [String] the icon URL of the emoji
     def icon_url
       API.emoji_icon_url(@id)
@@ -2007,7 +2212,7 @@ module Discordrb
     # @return [Array<Role>] an array of all the roles created on this server.
     attr_reader :roles
 
-    # @return [Array<Emoji>] an array of all the emoji available on this server.
+    # @return [Hash<Integer, Emoji>] a hash of all the emoji available on this server.
     attr_reader :emoji
     alias_method :emojis, :emoji
 
@@ -2074,8 +2279,9 @@ module Discordrb
     alias_method :general_channel, :default_channel
 
     # Gets a role on this server based on its ID.
-    # @param id [Integer] The role ID to look for.
+    # @param id [Integer, String, #resolve_id] The role ID to look for.
     def role(id)
+      id = id.resolve_id
       @roles.find { |e| e.id == id }
     end
 
@@ -2107,7 +2313,7 @@ module Discordrb
 
     # @return [Array<Integration>] an array of all the integrations connected to this server.
     def integrations
-      integration = JSON.parse(API.server_integrations(@bot.token, @id))
+      integration = JSON.parse(API::Server.integrations(@bot.token, @id))
       integration.map { |element| Integration.new(element, @bot, self) }
     end
 
@@ -2115,7 +2321,7 @@ module Discordrb
     # @note For internal use only
     # @!visibility private
     def cache_embed
-      @embed = JSON.parse(API.server(@bot.token, @id))['embed_enabled'] if @embed.nil?
+      @embed ||= JSON.parse(API::Server.resolve(@bot.token, @id))['embed_enabled']
     end
 
     # @return [true, false] whether or not the server has widget enabled
@@ -2169,8 +2375,7 @@ module Discordrb
 
     # @return [String] the hexadecimal ID used to identify this server's splash image for their VIP invite page.
     def splash_id
-      @splash_id = JSON.parse(API.server(@bot.token, @id))['splash'] if @splash_id.nil?
-      @splash_id
+      @splash_id ||= JSON.parse(API::Server.resolve(@bot.token, @id))['splash']
     end
 
     # @return [String, nil] the splash image URL for the server's VIP invite page.
@@ -2411,6 +2616,30 @@ module Discordrb
       end
     end
 
+    # Adds a channel to this server's cache
+    # @note For internal use only
+    # @!visibility private
+    def add_channel(channel)
+      @channels << channel
+      @channels_by_id[channel.id] = channel
+    end
+
+    # Deletes a channel from this server's cache
+    # @note For internal use only
+    # @!visibility private
+    def delete_channel(id)
+      @channels.reject! { |e| e.id == id }
+      @channels_by_id.delete(id)
+    end
+
+    # Updates the cached emoji data with new data
+    # @note For internal use only
+    # @!visibility private
+    def update_emoji_data(new_data)
+      @emoji = {}
+      process_emoji(new_data['emojis'])
+    end
+
     # The inspect method is overwritten to give more useful output
     def inspect
       "<Server name=#{@name} id=#{@id} large=#{@large} region=#{@region} owner=#{@owner} afk_channel_id=#{@afk_channel_id} afk_timeout=#{@afk_timeout}>"
@@ -2465,8 +2694,7 @@ module Discordrb
         user_id = element['user']['id'].to_i
         user = @members[user_id]
         if user
-          user.status = element['status'].to_sym
-          user.game = element['game'] ? element['game']['name'] : nil
+          user.update_presence(element)
         else
           LOGGER.warn "Rogue presence update! #{element['user']['id']} on #{@id}"
         end