discordrb 3.3.0 → 3.4.0

data/lib/discordrb/data/overwrite.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # A permissions overwrite, when applied to channels describes additional
+  # permissions a member needs to perform certain actions in context.
+  class Overwrite
+    # @return [Integer] ID of the thing associated with this overwrite type
+    attr_accessor :id
+
+    # @return [Symbol] either :role or :member
+    attr_accessor :type
+
+    # @return [Permissions] allowed permissions for this overwrite type
+    attr_accessor :allow
+
+    # @return [Permissions] denied permissions for this overwrite type
+    attr_accessor :deny
+
+    # Creates a new Overwrite object
+    # @example Create an overwrite for a role that can mention everyone, send TTS messages, but can't create instant invites
+    #   allow = Discordrb::Permissions.new
+    #   allow.can_mention_everyone = true
+    #   allow.can_send_tts_messages = true
+    #
+    #   deny = Discordrb::Permissions.new
+    #   deny.can_create_instant_invite = true
+    #
+    #   # Find some role by name
+    #   role = server.roles.find { |r| r.name == 'some role' }
+    #
+    #   Overwrite.new(role, allow: allow, deny: deny)
+    # @example Create an overwrite by ID and permissions bits
+    #   Overwrite.new(120571255635181568, type: 'member', allow: 1024, deny: 0)
+    # @param object [Integer, #id] the ID or object this overwrite is for
+    # @param type [String] the type of object this overwrite is for (only required if object is an Integer)
+    # @param allow [Integer, Permissions] allowed permissions for this overwrite, by bits or a Permissions object
+    # @param deny [Integer, Permissions] denied permissions for this overwrite, by bits or a Permissions object
+    # @raise [ArgumentError] if type is not :member or :role
+    def initialize(object = nil, type: nil, allow: 0, deny: 0)
+      if type
+        type = type.to_sym
+        raise ArgumentError, 'Overwrite type must be :member or :role' unless (type != :member) || (type != :role)
+      end
+
+      @id = object.respond_to?(:id) ? object.id : object
+
+      @type = case object
+              when User, Member, Recipient, Profile
+                :member
+              when Role
+                :role
+              else
+                type
+              end
+
+      @allow = allow.is_a?(Permissions) ? allow : Permissions.new(allow)
+      @deny = deny.is_a?(Permissions) ? deny : Permissions.new(deny)
+    end
+
+    # Comparison by attributes [:id, :type, :allow, :deny]
+    def ==(other)
+      false unless other.is_a? Discordrb::Overwrite
+      id == other.id &&
+        type == other.type &&
+        allow == other.allow &&
+        deny == other.deny
+    end
+
+    # @return [Overwrite] create an overwrite from a hash payload
+    # @!visibility private
+    def self.from_hash(data)
+      new(
+        data['id'].to_i,
+        type: data['type'],
+        allow: Permissions.new(data['allow']),
+        deny: Permissions.new(data['deny'])
+      )
+    end
+
+    # @return [Overwrite] copies an overwrite from another Overwrite
+    # @!visibility private
+    def self.from_other(other)
+      new(
+        other.id,
+        type: other.type,
+        allow: Permissions.new(other.allow.bits),
+        deny: Permissions.new(other.deny.bits)
+      )
+    end
+
+    # @return [Hash] hash representation of an overwrite
+    # @!visibility private
+    def to_hash
+      {
+        id: id,
+        type: type,
+        allow: allow.bits,
+        deny: deny.bits
+      }
+    end
+  end
+end

data/lib/discordrb/data/profile.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # This class is a special variant of User that represents the bot's user profile (things like own username and the avatar).
+  # It can be accessed using {Bot#profile}.
+  class Profile < User
+    # Whether or not the user is the bot. The Profile can only ever be the bot user, so this always returns true.
+    # @return [true]
+    def current_bot?
+      true
+    end
+
+    # Sets the bot's username.
+    # @param username [String] The new username.
+    def username=(username)
+      update_profile_data(username: username)
+    end
+
+    alias_method :name=, :username=
+
+    # Changes the bot's avatar.
+    # @param avatar [String, #read] A JPG file to be used as the avatar, either
+    #  something readable (e.g. File Object) or as a data URL.
+    def avatar=(avatar)
+      if avatar.respond_to? :read
+        # Set the file to binary mode if supported, so we don't get problems with Windows
+        avatar.binmode if avatar.respond_to?(:binmode)
+
+        avatar_string = 'data:image/jpg;base64,'
+        avatar_string += Base64.strict_encode64(avatar.read)
+        update_profile_data(avatar: avatar_string)
+      else
+        update_profile_data(avatar: avatar)
+      end
+    end
+
+    # Updates the cached profile data with the new one.
+    # @note For internal use only.
+    # @!visibility private
+    def update_data(new_data)
+      @username = new_data[:username] || @username
+      @avatar_id = new_data[:avatar_id] || @avatar_id
+    end
+
+    # Sets the user status setting to Online.
+    # @note Only usable on User accounts.
+    def online
+      update_profile_status_setting('online')
+    end
+
+    # Sets the user status setting to Idle.
+    # @note Only usable on User accounts.
+    def idle
+      update_profile_status_setting('idle')
+    end
+
+    # Sets the user status setting to Do Not Disturb.
+    # @note Only usable on User accounts.
+    def dnd
+      update_profile_status_setting('dnd')
+    end
+
+    alias_method(:busy, :dnd)
+
+    # Sets the user status setting to Invisible.
+    # @note Only usable on User accounts.
+    def invisible
+      update_profile_status_setting('invisible')
+    end
+
+    # The inspect method is overwritten to give more useful output
+    def inspect
+      "<Profile user=#{super}>"
+    end
+
+    private
+
+    # Internal handler for updating the user's status setting
+    def update_profile_status_setting(status)
+      API::User.change_status_setting(@bot.token, status)
+    end
+
+    def update_profile_data(new_data)
+      API::User.update_profile(@bot.token,
+                               nil, nil,
+                               new_data[:username] || @username,
+                               new_data.key?(:avatar) ? new_data[:avatar] : @avatar_id)
+      update_data(new_data)
+    end
+  end
+end

data/lib/discordrb/data/reaction.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # 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
+
+    # Converts this Reaction into a string that can be sent back to Discord in other reaction endpoints.
+    # If ID is present, it will be rendered into the form of `name:id`.
+    # @return [String] the name of this reaction, including the ID if it is a custom emoji
+    def to_s
+      id.nil? ? name : "#{name}:#{id}"
+    end
+  end
+end

data/lib/discordrb/data/recipient.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # Recipients are members on private channels - they exist for completeness purposes, but all
+  # the attributes will be empty.
+  class Recipient < DelegateClass(User)
+    include MemberAttributes
+
+    # @return [Channel] the private channel this recipient is the recipient of.
+    attr_reader :channel
+
+    # @!visibility private
+    def initialize(user, channel, bot)
+      @bot = bot
+      @channel = channel
+      raise ArgumentError, 'Tried to create a recipient for a public channel!' unless @channel.private?
+
+      @user = user
+      super @user
+
+      # Member attributes
+      @mute = @deaf = @self_mute = @self_deaf = false
+      @voice_channel = nil
+      @server = nil
+      @roles = []
+      @joined_at = @channel.creation_time
+    end
+
+    # Overwriting inspect for debug purposes
+    def inspect
+      "<Recipient user=#{@user.inspect} channel=#{@channel.inspect}>"
+    end
+  end
+end

data/lib/discordrb/data/role.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # A Discord role that contains permissions and applies to certain users
+  class Role
+    include IDObject
+
+    # @return [Permissions] this role's permissions.
+    attr_reader :permissions
+
+    # @return [String] this role's name ("new role" if it hasn't been changed)
+    attr_reader :name
+
+    # @return [Server] the server this role belongs to
+    attr_reader :server
+
+    # @return [true, false] whether or not this role should be displayed separately from other users
+    attr_reader :hoist
+
+    # @return [true, false] whether or not this role is managed by an integration or a bot
+    attr_reader :managed
+    alias_method :managed?, :managed
+
+    # @return [true, false] whether this role can be mentioned using a role mention
+    attr_reader :mentionable
+    alias_method :mentionable?, :mentionable
+
+    # @return [ColourRGB] the role colour
+    attr_reader :colour
+    alias_method :color, :colour
+
+    # @return [Integer] the position of this role in the hierarchy
+    attr_reader :position
+
+    # This class is used internally as a wrapper to a Role object that allows easy writing of permission data.
+    class RoleWriter
+      # @!visibility private
+      def initialize(role, token)
+        @role = role
+        @token = token
+      end
+
+      # Write the specified permission data to the role, without updating the permission cache
+      # @param bits [Integer] The packed permissions to write.
+      def write(bits)
+        @role.send(:packed=, bits, false)
+      end
+
+      # The inspect method is overridden, in this case to prevent the token being leaked
+      def inspect
+        "<RoleWriter role=#{@role} token=...>"
+      end
+    end
+
+    # @!visibility private
+    def initialize(data, bot, server = nil)
+      @bot = bot
+      @server = server
+      @permissions = Permissions.new(data['permissions'], RoleWriter.new(self, @bot.token))
+      @name = data['name']
+      @id = data['id'].to_i
+
+      @position = data['position']
+
+      @hoist = data['hoist']
+      @mentionable = data['mentionable']
+      @managed = data['managed']
+
+      @colour = ColourRGB.new(data['color'])
+    end
+
+    # @return [String] a string that will mention this role, if it is mentionable.
+    def mention
+      "<@&#{@id}>"
+    end
+
+    # @return [Array<Member>] an array of members who have this role.
+    # @note This requests a member chunk if it hasn't for the server before, which may be slow initially
+    def members
+      @server.members.select { |m| m.role? self }
+    end
+
+    alias_method :users, :members
+
+    # Updates the data cache from another Role object
+    # @note For internal use only
+    # @!visibility private
+    def update_from(other)
+      @permissions = other.permissions
+      @name = other.name
+      @hoist = other.hoist
+      @colour = other.colour
+      @position = other.position
+      @managed = other.managed
+    end
+
+    # Updates the data cache from a hash containing data
+    # @note For internal use only
+    # @!visibility private
+    def update_data(new_data)
+      @name = new_data[:name] || new_data['name'] || @name
+      @hoist = new_data['hoist'] unless new_data['hoist'].nil?
+      @hoist = new_data[:hoist] unless new_data[:hoist].nil?
+      @colour = new_data[:colour] || (new_data['color'] ? ColourRGB.new(new_data['color']) : @colour)
+    end
+
+    # Sets the role name to something new
+    # @param name [String] The name that should be set
+    def name=(name)
+      update_role_data(name: name)
+    end
+
+    # Changes whether or not this role is displayed at the top of the user list
+    # @param hoist [true, false] The value it should be changed to
+    def hoist=(hoist)
+      update_role_data(hoist: hoist)
+    end
+
+    # Changes whether or not this role can be mentioned
+    # @param mentionable [true, false] The value it should be changed to
+    def mentionable=(mentionable)
+      update_role_data(mentionable: mentionable)
+    end
+
+    # Sets the role colour to something new
+    # @param colour [ColourRGB] The new colour
+    def colour=(colour)
+      update_role_data(colour: colour)
+    end
+
+    alias_method :color=, :colour=
+
+    # Changes this role's permissions to a fixed bitfield. This allows setting multiple permissions at once with just
+    # one API call.
+    #
+    # Information on how this bitfield is structured can be found at
+    # https://discord.com/developers/docs/topics/permissions.
+    # @example Remove all permissions from a role
+    #   role.packed = 0
+    # @param packed [Integer] A bitfield with the desired permissions value.
+    # @param update_perms [true, false] Whether the internal data should also be updated. This should always be true
+    #   when calling externally.
+    def packed=(packed, update_perms = true)
+      update_role_data(permissions: packed)
+      @permissions.bits = packed if update_perms
+    end
+
+    # Moves this role above another role in the list.
+    # @param other [Role, String, Integer, nil] The role, or its ID, above which this role should be moved. If it is `nil`,
+    #   the role will be moved above the @everyone role.
+    # @return [Integer] the new position of this role
+    def sort_above(other = nil)
+      other = @server.role(other.resolve_id) if other
+      roles = @server.roles.sort_by(&:position)
+      roles.delete_at(@position)
+
+      index = other ? roles.index { |role| role.id == other.id } + 1 : 1
+      roles.insert(index, self)
+
+      updated_roles = roles.map.with_index { |role, position| { id: role.id, position: position } }
+      @server.update_role_positions(updated_roles)
+      index
+    end
+
+    alias_method :move_above, :sort_above
+
+    # Deletes this role. This cannot be undone without recreating the role!
+    # @param reason [String] the reason for this role's deletion
+    def delete(reason = nil)
+      API::Server.delete_role(@bot.token, @server.id, @id, reason)
+      @server.delete_role(@id)
+    end
+
+    # The inspect method is overwritten to give more useful output
+    def inspect
+      "<Role name=#{@name} permissions=#{@permissions.inspect} hoist=#{@hoist} colour=#{@colour.inspect} server=#{@server.inspect} position=#{@position} mentionable=#{@mentionable}>"
+    end
+
+    private
+
+    def update_role_data(new_data)
+      API::Server.update_role(@bot.token, @server.id, @id,
+                              new_data[:name] || @name,
+                              (new_data[:colour] || @colour).combined,
+                              new_data[:hoist].nil? ? @hoist : new_data[:hoist],
+                              new_data[:mentionable].nil? ? @mentionable : new_data[:mentionable],
+                              new_data[:permissions] || @permissions.bits)
+      update_data(new_data)
+    end
+  end
+end