discordrb 3.3.0 → 3.5.0

data/lib/discordrb/data/user.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # Mixin for the attributes users should have
+  module UserAttributes
+    # rubocop:disable Naming/VariableNumber
+    FLAGS = {
+      staff: 1 << 0,
+      partner: 1 << 1,
+      hypesquad: 1 << 2,
+      bug_hunter_level_1: 1 << 3,
+      hypesquad_online_house_1: 1 << 6,
+      hypesquad_online_house_2: 1 << 7,
+      hypesquad_online_house_3: 1 << 8,
+      premium_early_supporter: 1 << 9,
+      team_pseudo_user: 1 << 10,
+      bug_hunter_level_2: 1 << 14,
+      verified_bot: 1 << 16,
+      verified_developer: 1 << 17,
+      certified_moderator: 1 << 18,
+      bot_http_interactions: 1 << 19,
+      active_developer: 1 << 22
+    }.freeze
+    # rubocop:enable Naming/VariableNumber
+
+    # @return [String] this user's username
+    attr_reader :username
+    alias_method :name, :username
+
+    # @return [String, nil] this user's global name
+    attr_reader :global_name
+
+    # @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 [true, false] whether this is fake user for a webhook message
+    attr_reader :webhook_account
+    alias_method :webhook_account?, :webhook_account
+    alias_method :webhook?, :webhook_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 get Discord's display name of a user not in server
+    # @return [String] the name the user displays as (global_name if they have one, username otherwise)
+    def display_name
+      global_name || username
+    end
+
+    # 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
+    # TODO: Maybe change this method again after discriminator removal ?
+    def distinct
+      if @discriminator && @discriminator != '0'
+        "#{@username}##{@discriminator}"
+      else
+        @username.to_s
+      end
+    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.
+    # TODO: Maybe change this method again after discriminator removal ?
+    def avatar_url(format = nil)
+      unless @avatar_id
+        return API::User.default_avatar(@discriminator, legacy: true) if @discriminator && @discriminator != '0'
+
+        return API::User.default_avatar(@id)
+      end
+
+      API::User.avatar_url(@id, @avatar_id, format)
+    end
+
+    # @return [Integer] the public flags on a user's account
+    attr_reader :public_flags
+
+    FLAGS.each do |name, value|
+      define_method("#{name}?") do
+        (@public_flags & value).positive?
+      end
+    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']
+      @global_name = data['global_name']
+      @id = data['id'].to_i
+      @discriminator = data['discriminator']
+      @avatar_id = data['avatar']
+      @roles = {}
+      @activities = Discordrb::ActivitySet.new
+      @public_flags = data['public_flags'] || 0
+
+      @bot_account = false
+      @bot_account = true if data['bot']
+
+      @webhook_account = false
+      @webhook_account = true if data['_webhook']
+
+      @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 username
+    # @note for internal use only
+    # @!visibility private
+    def update_username(username)
+      @username = username
+    end
+
+    # Set the user's global_name
+    # @note For internal use only.
+    # @!visibility private
+    def update_global_name(global_name)
+      @global_name = global_name
+    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
+
+    # @!visibility private
+    def process_client_status(client_status)
+      (client_status || {}).to_h { |k, v| [k.to_sym, v.to_sym] }
+    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,238 @@
+# frozen_string_literal: true
+
+require 'discordrb/webhooks/builder'
+require 'discordrb/webhooks/view'
+
+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 webhook 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
+
+    # Execute a webhook.
+    # @param content [String] The content of the message. May be 2000 characters long at most.
+    # @param username [String] The username the webhook will display as. If this is not set, the default username set in the webhook's settings.
+    # @param avatar_url [String] The URL of an image file to be used as an avatar. If this is not set, the default avatar from the webhook's
+    # @param tts [true, false] Whether this message should use TTS or not. By default, it doesn't.
+    # @param file [File] File to be sent together with the message. Mutually exclusive with embeds; a webhook message can contain
+    #   either a file to be sent or embeds.
+    # @param embeds [Array<Webhooks::Embed, Hash>] Embeds to attach to this message.
+    # @param allowed_mentions [AllowedMentions, Hash] Mentions that are allowed to ping in the `content`.
+    # @param wait [true, false] Whether Discord should wait for the message to be successfully received by clients, or
+    #   whether it should return immediately after sending the message. If `true` a {Message} object will be returned.
+    # @yield [builder] Gives the builder to the block to add additional steps, or to do the entire building process.
+    # @yieldparam builder [Builder] The builder given as a parameter which is used as the initial step to start from.
+    # @example Execute the webhook with kwargs
+    #   client.execute(
+    #     content: 'Testing',
+    #     username: 'discordrb',
+    #     embeds: [
+    #       { timestamp: Time.now.iso8601, title: 'testing', image: { url: 'https://i.imgur.com/PcMltU7.jpg' } }
+    #     ])
+    # @example Execute the webhook with an already existing builder
+    #   builder = Discordrb::Webhooks::Builder.new # ...
+    #   client.execute(builder)
+    # @example Execute the webhook by building a new message
+    #   client.execute do |builder|
+    #     builder.content = 'Testing'
+    #     builder.username = 'discordrb'
+    #     builder.add_embed do |embed|
+    #       embed.timestamp = Time.now
+    #       embed.title = 'Testing'
+    #       embed.image = Discordrb::Webhooks::EmbedImage.new(url: 'https://i.imgur.com/PcMltU7.jpg')
+    #     end
+    #   end
+    # @return [Message, nil] If `wait` is `true`, a {Message} will be returned. Otherwise this method will return `nil`.
+    # @note This is only available to webhooks with publically exposed tokens. This excludes channel follow webhooks and webhooks retrieved
+    #   via the audit log.
+    def execute(content: nil, username: nil, avatar_url: nil, tts: nil, file: nil, embeds: nil, allowed_mentions: nil, wait: true, builder: nil, components: nil)
+      raise Discordrb::Errors::UnauthorizedWebhook unless @token
+
+      params = { content: content, username: username, avatar_url: avatar_url, tts: tts, file: file, embeds: embeds, allowed_mentions: allowed_mentions }
+
+      builder ||= Webhooks::Builder.new
+      view = Webhooks::View.new
+
+      yield(builder, view) if block_given?
+
+      data = builder.to_json_hash.merge(params.compact)
+      components ||= view
+
+      resp = API::Webhook.token_execute_webhook(@token, @id, wait, data[:content], data[:username], data[:avatar_url], data[:tts], data[:file], data[:embeds], data[:allowed_mentions], nil, components.to_a)
+
+      Message.new(JSON.parse(resp), @bot) if wait
+    end
+
+    # Delete a message created by this webhook.
+    # @param message [Message, String, Integer] The ID of the message to delete.
+    def delete_message(message)
+      raise Discordrb::Errors::UnauthorizedWebhook unless @token
+
+      API::Webhook.token_delete_message(@token, @id, message.resolve_id)
+    end
+
+    # Edit a message created by this webhook.
+    # @param message [Message, String, Integer] The ID of the message to edit.
+    # @param content [String] The content of the message. May be 2000 characters long at most.
+    # @param embeds [Array<Webhooks::Embed, Hash>] Embeds to be attached to the message.
+    # @param allowed_mentions [AllowedMentions, Hash] Mentions that are allowed to ping in the `content`.
+    # @param builder [Builder, nil] The builder to start out with, or nil if one should be created anew.
+    # @yield [builder] Gives the builder to the block to add additional steps, or to do the entire building process.
+    # @yieldparam builder [Webhooks::Builder] The builder given as a parameter which is used as the initial step to start from.
+    # @return [Message] The updated message.
+    # @param components [View, Array<Hash>] Interaction components to associate with this message.
+    # @note When editing `allowed_mentions`, it will update visually in the client but not alert the user with a notification.
+    def edit_message(message, content: nil, embeds: nil, allowed_mentions: nil, builder: nil, components: nil)
+      raise Discordrb::Errors::UnauthorizedWebhook unless @token
+
+      params = { content: content, embeds: embeds, allowed_mentions: allowed_mentions }.compact
+
+      builder ||= Webhooks::Builder.new
+      view ||= Webhooks::View.new
+
+      yield(builder, view) if block_given?
+
+      data = builder.to_json_hash.merge(params.compact)
+      components ||= view
+
+      resp = API::Webhook.token_edit_message(@token, @id, message.resolve_id, data[:content], data[:embeds], data[:allowed_mentions], components.to_a)
+      Message.new(JSON.parse(resp), @bot)
+    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(@id) 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