discordrb 3.3.0 → 3.4.0

data/lib/discordrb/data/user.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # Mixin for the attributes users should have
+  module UserAttributes
+    # @return [String] this user's username
+    attr_reader :username
+    alias_method :name, :username
+
+    # @return [String] this user's discriminator which is used internally to identify users with identical usernames.
+    attr_reader :discriminator
+    alias_method :discrim, :discriminator
+    alias_method :tag, :discriminator
+    alias_method :discord_tag, :discriminator
+
+    # @return [true, false] whether this user is a Discord bot account
+    attr_reader :bot_account
+    alias_method :bot_account?, :bot_account
+
+    # @return [String] the ID of this user's current avatar, can be used to generate an avatar URL.
+    # @see #avatar_url
+    attr_accessor :avatar_id
+
+    # Utility function to mention users in messages
+    # @return [String] the mention code in the form of <@id>
+    def mention
+      "<@#{@id}>"
+    end
+
+    # Utility function to get Discord's distinct representation of a user, i.e. username + discriminator
+    # @return [String] distinct representation of user
+    def distinct
+      "#{@username}##{@discriminator}"
+    end
+
+    # Utility function to get a user's avatar URL.
+    # @param format [String, nil] If `nil`, the URL will default to `webp` for static avatars, and will detect if the user has a `gif` avatar. You can otherwise specify one of `webp`, `jpg`, `png`, or `gif` to override this. Will always be PNG for default avatars.
+    # @return [String] the URL to the avatar image.
+    def avatar_url(format = nil)
+      return API::User.default_avatar(@discriminator) unless @avatar_id
+
+      API::User.avatar_url(@id, @avatar_id, format)
+    end
+  end
+
+  # User on Discord, including internal data like discriminators
+  class User
+    include IDObject
+    include UserAttributes
+
+    # @return [Symbol] the current online status of the user (`:online`, `:offline` or `:idle`)
+    attr_reader :status
+
+    # @return [ActivitySet] the activities of the user
+    attr_reader :activities
+
+    # @return [Hash<Symbol, Symbol>] the current online status (`:online`, `:idle` or `:dnd`) of the user
+    #   on various device types (`:desktop`, `:mobile`, or `:web`). The value will be `nil` if the user is offline or invisible.
+    attr_reader :client_status
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+
+      @username = data['username']
+      @id = data['id'].to_i
+      @discriminator = data['discriminator']
+      @avatar_id = data['avatar']
+      @roles = {}
+      @activities = Discordrb::ActivitySet.new
+
+      @bot_account = false
+      @bot_account = true if data['bot']
+
+      @status = :offline
+      @client_status = process_client_status(data['client_status'])
+    end
+
+    # Get a user's PM channel or send them a PM
+    # @overload pm
+    #   Creates a private message channel for this user or returns an existing one if it already exists
+    #   @return [Channel] the PM channel to this user.
+    # @overload pm(content)
+    #   Sends a private to this user.
+    #   @param content [String] The content to send.
+    #   @return [Message] the message sent to this user.
+    def pm(content = nil)
+      if content
+        # Recursively call pm to get the channel, then send a message to it
+        channel = pm
+        channel.send_message(content)
+      else
+        # If no message was specified, return the PM channel
+        @bot.pm_channel(@id)
+      end
+    end
+
+    alias_method :dm, :pm
+
+    # Send the user a file.
+    # @param file [File] The file to send to the user
+    # @param caption [String] The caption of the file being sent
+    # @param filename [String] Overrides the filename of the uploaded file
+    # @param spoiler [true, false] Whether or not this file should appear as a spoiler.
+    # @return [Message] the message sent to this user.
+    # @example Send a file from disk
+    #   user.send_file(File.open('rubytaco.png', 'r'))
+    def send_file(file, caption = nil, filename: nil, spoiler: nil)
+      pm.send_file(file, caption: caption, filename: filename, spoiler: spoiler)
+    end
+
+    # Set the user's name
+    # @note for internal use only
+    # @!visibility private
+    def update_username(username)
+      @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
+      @client_status = process_client_status(data['client_status'])
+
+      @activities = Discordrb::ActivitySet.new(data['activities'].map { |act| Activity.new(act, @bot) })
+    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
+    def await(key, attributes = {}, &block)
+      @bot.add_await(key, Discordrb::Events::MessageEvent, { from: @id }.merge(attributes), &block)
+    end
+
+    # Add a blocking 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!
+    def await!(attributes = {}, &block)
+      @bot.add_await!(Discordrb::Events::MessageEvent, { from: @id }.merge(attributes), &block)
+    end
+
+    # Gets the member this user is on a server
+    # @param server [Server] The server to get the member for
+    # @return [Member] this user as a member on a particular server
+    def on(server)
+      id = server.resolve_id
+      @bot.server(id).member(@id)
+    end
+
+    # Is the user the bot?
+    # @return [true, false] whether this user is the bot
+    def current_bot?
+      @bot.profile.id == @id
+    end
+
+    # @return [true, false] whether this user is a fake user for a webhook message
+    def webhook?
+      @discriminator == Message::ZERO_DISCRIM
+    end
+
+    # @!visibility private
+    def process_client_status(client_status)
+      (client_status || {}).map { |k, v| [k.to_sym, v.to_sym] }.to_h
+    end
+
+    # @!method offline?
+    #   @return [true, false] whether this user is offline.
+    # @!method idle?
+    #   @return [true, false] whether this user is idle.
+    # @!method online?
+    #   @return [true, false] whether this user is online.
+    # @!method dnd?
+    #   @return [true, false] whether this user is set to do not disturb.
+    %i[offline idle online dnd].each do |e|
+      define_method("#{e}?") do
+        @status.to_sym == e
+      end
+    end
+
+    # @return [String, nil] the game the user is currently playing, or `nil` if nothing is being played.
+    # @deprecated Please use {ActivitySet#games} for information about the user's game activity
+    def game
+      @activities.games.first&.name
+    end
+
+    # @return [Integer] returns 1 for twitch streams, or 0 for no stream.
+    # @deprecated Please use {ActivitySet#streaming} for information about the user's stream activity
+    def stream_type
+      @activities.streaming ? 1 : 0
+    end
+
+    # @return [String, nil] the URL to the stream, if the user is currently streaming something
+    # @deprecated Please use {ActivitySet#streaming} for information about the user's stream activity
+    def stream_url
+      @activities.streaming.first&.url
+    end
+
+    # The inspect method is overwritten to give more useful output
+    def inspect
+      "<User username=#{@username} id=#{@id} discriminator=#{@discriminator}>"
+    end
+  end
+end

data/lib/discordrb/data/voice_region.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # Voice regions are the locations of servers that handle voice communication in Discord
+  class VoiceRegion
+    # @return [String] unique ID for the region
+    attr_reader :id
+    alias_method :to_s, :id
+
+    # @return [String] name of the region
+    attr_reader :name
+
+    # @return [String] an example hostname for the region
+    attr_reader :sample_hostname
+
+    # @return [Integer] an example port for the region
+    attr_reader :sample_port
+
+    # @return [true, false] if this is a VIP-only server
+    attr_reader :vip
+
+    # @return [true, false] if this voice server is the closest to the client
+    attr_reader :optimal
+
+    # @return [true, false] whether this is a deprecated voice region (avoid switching to these)
+    attr_reader :deprecated
+
+    # @return [true, false] whether this is a custom voice region (used for events/etc)
+    attr_reader :custom
+
+    def initialize(data)
+      @id = data['id']
+
+      @name = data['name']
+
+      @sample_hostname = data['sample_hostname']
+      @sample_port = data['sample_port']
+
+      @vip = data['vip']
+      @optimal = data['optimal']
+      @deprecated = data['deprecated']
+      @custom = data['custom']
+    end
+  end
+end

data/lib/discordrb/data/voice_state.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # A voice state represents the state of a member's connection to a voice channel. It includes data like the voice
+  # channel the member is connected to and mute/deaf flags.
+  class VoiceState
+    # @return [Integer] the ID of the user whose voice state is represented by this object.
+    attr_reader :user_id
+
+    # @return [true, false] whether this voice state's member is muted server-wide.
+    attr_reader :mute
+
+    # @return [true, false] whether this voice state's member is deafened server-wide.
+    attr_reader :deaf
+
+    # @return [true, false] whether this voice state's member has muted themselves.
+    attr_reader :self_mute
+
+    # @return [true, false] whether this voice state's member has deafened themselves.
+    attr_reader :self_deaf
+
+    # @return [Channel] the voice channel this voice state's member is in.
+    attr_reader :voice_channel
+
+    # @!visibility private
+    def initialize(user_id)
+      @user_id = user_id
+    end
+
+    # Update this voice state with new data from Discord
+    # @note For internal use only.
+    # @!visibility private
+    def update(channel, mute, deaf, self_mute, self_deaf)
+      @voice_channel = channel
+      @mute = mute
+      @deaf = deaf
+      @self_mute = self_mute
+      @self_deaf = self_deaf
+    end
+  end
+end

data/lib/discordrb/data/webhook.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # A webhook on a server channel
+  class Webhook
+    include IDObject
+
+    # @return [String] the webhook name.
+    attr_reader :name
+
+    # @return [Channel] the channel that the webhook is currently connected to.
+    attr_reader :channel
+
+    # @return [Server] the server that the webhook is currently connected to.
+    attr_reader :server
+
+    # @return [String, nil] the webhook's token, if this is an Incoming Webhook.
+    attr_reader :token
+
+    # @return [String] the webhook's avatar id.
+    attr_reader :avatar
+
+    # @return [Integer] the webhook's type (1: Incoming, 2: Channel Follower)
+    attr_reader :type
+
+    # Gets the user object of the creator of the webhook. May be limited to username, discriminator,
+    # ID and avatar if the bot cannot reach the owner
+    # @return [Member, User, nil] the user object of the owner or nil if the webhook was requested using the token.
+    attr_reader :owner
+
+    def initialize(data, bot)
+      @bot = bot
+
+      @name = data['name']
+      @id = data['id'].to_i
+      @channel = bot.channel(data['channel_id'])
+      @server = @channel.server
+      @token = data['token']
+      @avatar = data['avatar']
+      @type = data['type']
+
+      # Will not exist if the data was requested through a webhook token
+      return unless data['user']
+
+      @owner = @server.member(data['user']['id'].to_i)
+      return if @owner
+
+      Discordrb::LOGGER.debug("Member with ID #{data['user']['id']} not cached (possibly left the server).")
+      @owner = @bot.ensure_user(data['user'])
+    end
+
+    # Sets the webhook's avatar.
+    # @param avatar [String, #read] The new avatar, in base64-encoded JPG format.
+    def avatar=(avatar)
+      update_webhook(avatar: avatarise(avatar))
+    end
+
+    # Deletes the webhook's avatar.
+    def delete_avatar
+      update_webhook(avatar: nil)
+    end
+
+    # Sets the webhook's channel
+    # @param channel [Channel, String, Integer] The channel the webhook should use.
+    def channel=(channel)
+      update_webhook(channel_id: channel.resolve_id)
+    end
+
+    # Sets the webhook's name.
+    # @param name [String] The webhook's new name.
+    def name=(name)
+      update_webhook(name: name)
+    end
+
+    # Updates the webhook if you need to edit more than 1 attribute.
+    # @param data [Hash] the data to update.
+    # @option data [String, #read, nil] :avatar The new avatar, in base64-encoded JPG format, or nil to delete the avatar.
+    # @option data [Channel, String, Integer] :channel The channel the webhook should use.
+    # @option data [String] :name The webhook's new name.
+    # @option data [String] :reason The reason for the webhook changes.
+    def update(data)
+      # Only pass a value for avatar if the key is defined as sending nil will delete the
+      data[:avatar] = avatarise(data[:avatar]) if data.key?(:avatar)
+      data[:channel_id] = data[:channel].resolve_id
+      data.delete(:channel)
+      update_webhook(data)
+    end
+
+    # Deletes the webhook.
+    # @param reason [String] The reason the invite is being deleted.
+    def delete(reason = nil)
+      if token?
+        API::Webhook.token_delete_webhook(@token, @id, reason)
+      else
+        API::Webhook.delete_webhook(@bot.token, @id, reason)
+      end
+    end
+
+    # Utility function to get a webhook's avatar URL.
+    # @return [String] the URL to the avatar image
+    def avatar_url
+      return API::User.default_avatar unless @avatar
+
+      API::User.avatar_url(@id, @avatar)
+    end
+
+    # The `inspect` method is overwritten to give more useful output.
+    def inspect
+      "<Webhook name=#{@name} id=#{@id}>"
+    end
+
+    # Utility function to know if the webhook was requested through a webhook token, rather than auth.
+    # @return [true, false] whether the webhook was requested by token or not.
+    def token?
+      @owner.nil?
+    end
+
+    private
+
+    def avatarise(avatar)
+      if avatar.respond_to? :read
+        "data:image/jpg;base64,#{Base64.strict_encode64(avatar.read)}"
+      else
+        avatar
+      end
+    end
+
+    def update_internal(data)
+      @name = data['name']
+      @avatar_id = data['avatar']
+      @channel = @bot.channel(data['channel_id'])
+    end
+
+    def update_webhook(new_data)
+      reason = new_data.delete(:reason)
+      data = JSON.parse(if token?
+                          API::Webhook.token_update_webhook(@token, @id, new_data, reason)
+                        else
+                          API::Webhook.update_webhook(@bot.token, @id, new_data, reason)
+                        end)
+      # Only update cache if API call worked
+      update_internal(data) if data['name']
+    end
+  end
+end

data/lib/discordrb/errors.rb

@@ -43,7 +43,7 @@ module Discordrb
     end
 
     # Create a new code error class
-    # rubocop:disable Style/MethodName
+    # rubocop:disable Naming/MethodName
     def self.Code(code)
       classy = Class.new(CodeError)
       classy.instance_variable_set('@code', code)
@@ -53,6 +53,7 @@ module Discordrb
 
       classy
     end
+    # rubocop:enable Naming/MethodName
 
     # @param code [Integer] The code to check
     # @return [Class] the error class for the given code