onyxcord 1.1.0

data/lib/onyxcord/data/recipient.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # 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/onyxcord/data/role.rb

@@ -0,0 +1,449 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # 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
+    alias_method :hoist?, :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 primary colour of this role.
+    attr_reader :colour
+    alias_method :color, :colour
+
+    # @return [Integer] the position of this role in the hierarchy
+    attr_reader :position
+
+    # @return [String, nil] The icon hash for this role.
+    attr_reader :icon
+
+    # @return [Tags, nil] The role tags.
+    attr_reader :tags
+
+    # @return [Integer] The flags for this role.
+    attr_reader :flags
+
+    # @return [String, nil] The unicode emoji of this role, or nil.
+    attr_reader :unicode_emoji
+
+    # @return [ColourRGB, nil] the secondary colour of this role.
+    attr_reader :secondary_colour
+    alias_method :secondary_color, :secondary_colour
+
+    # @return [ColourRGB, nil] the tertiary colour of this role.
+    attr_reader :tertiary_colour
+    alias_method :tertiary_color, :tertiary_colour
+
+    # Wrapper for the role tags
+    class Tags
+      # @return [Integer, nil] The ID of the bot this role belongs to
+      attr_reader :bot_id
+
+      # @return [Integer, nil] The ID of the integration this role belongs to
+      attr_reader :integration_id
+
+      # @return [true, false] Whether this is the guild's Booster role
+      attr_reader :premium_subscriber
+      alias_method :premium_subscriber?, :premium_subscriber
+
+      # @return [Integer, nil] The id of this role's subscription sku and listing
+      attr_reader :subscription_listing_id
+
+      # @return [true, false] Whether this role is available for purchase
+      attr_reader :available_for_purchase
+      alias_method :available_for_purchase?, :available_for_purchase
+
+      # @return [true, false] Whether this role is a guild's linked role
+      attr_reader :guild_connections
+      alias_method :guild_connections?, :guild_connections
+      alias_method :server_connections?, :guild_connections
+
+      # @!visibility private
+      def initialize(data)
+        @bot_id = data['bot_id']&.resolve_id
+        @integration_id = data['integration_id']&.resolve_id
+        @premium_subscriber = data.key?('premium_subscriber')
+        @subscription_listing_id = data['subscription_listing_id']&.resolve_id
+        @available_for_purchase = data.key?('available_for_purchase')
+        @guild_connections = data.key?('guild_connections')
+      end
+    end
+
+    # 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'].to_i, 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']
+
+      colours = data['colors']
+      @colour = ColourRGB.new(colours['primary_color'])
+
+      @icon = data['icon']
+
+      @tags = Tags.new(data['tags']) if data['tags']
+
+      @flags = data['flags']
+
+      @unicode_emoji = data['unicode_emoji']
+
+      @tertiary_colour = ColourRGB.new(colours['tertiary_color']) if colours['tertiary_color']
+      @secondary_colour = ColourRGB.new(colours['secondary_color']) if colours['secondary_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 a hash containing data
+    # @note For internal use only
+    # @!visibility private
+    def update_data(new_data)
+      @name = new_data['name']
+      @hoist = new_data['hoist']
+      @icon = new_data['icon']
+      @unicode_emoji = new_data['unicode_emoji']
+      @position = new_data['position']
+      @mentionable = new_data['mentionable']
+      @flags = new_data['flags']
+      colours = new_data['colors']
+      @managed = new_data['managed']
+      @permissions.bits = new_data['permissions'].to_i
+      @colour = ColourRGB.new(colours['primary_color'])
+      @tags = Tags.new(new_data['tags']) if new_data['tags']
+      @tertiary_colour = colours['tertiary_color'] ? ColourRGB.new(colours['tertiary_color']) : nil
+      @secondary_colour = colours['secondary_color'] ? ColourRGB.new(colours['secondary_color']) : nil
+    end
+
+    # Sets the role name to something new
+    # @param name [String, nil] The name that should be set.
+    def name=(name)
+      modify(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)
+      modify(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)
+      modify(mentionable: mentionable)
+    end
+
+    # Sets the primary role colour to something new.
+    # @param colour [ColourRGB, Integer, nil] The new colour.
+    def colour=(colour)
+      modify(colour: colour)
+    end
+
+    # Sets the secondary role colour to something new.
+    # @param colour [ColourRGB, Integer, nil] The new secondary colour.
+    def secondary_colour=(colour)
+      modify(secondary_colour: colour)
+    end
+
+    # Sets the tertiary role colour to something new.
+    # @param colour [ColourRGB, Integer, nil] The new tertiary colour.
+    def tertiary_colour=(colour)
+      modify(tertiary_colour: colour)
+    end
+
+    # Sets whether the role colour should be a holographic style.
+    # @param holographic [true, false] whether the role colour should be a holographic style.
+    def holographic=(holographic)
+      update_colours(holographic: holographic)
+    end
+
+    # Upload a role icon for servers with the ROLE_ICONS feature.
+    # @param file [File, nil] File like object that responds to #read, or nil.
+    def icon=(file)
+      modify(icon: file)
+    end
+
+    # Set a role icon to a unicode emoji for servers with the ROLE_ICONS feature.
+    # @param emoji [String, nil] The new unicode emoji for this role, or nil.
+    def unicode_emoji=(emoji)
+      modify(unicode_emoji: emoji)
+    end
+
+    # @param format ['webp', 'png', 'jpeg']
+    # @return [String] URL to the icon on Discord's CDN.
+    def icon_url(format = 'webp')
+      API.role_icon_url(@id, @icon, format) if @icon
+    end
+
+    # Get the icon that a role has displayed.
+    # @return [String, nil] Icon URL, the unicode emoji, or nil if this role doesn't have any icon.
+    # @note A role can have a unicode emoji, and an icon, but only the icon will be shown in the UI.
+    def display_icon
+      icon_url || unicode_emoji
+    end
+
+    # Set the icon this role is displaying.
+    # @param icon [File, String, nil] File like object that responds to #read, unicode emoji, or nil.
+    # @note Setting the icon to nil will remove the unicode emoji **and** the custom icon.
+    def display_icon=(icon)
+      modify(display_icon: icon)
+    end
+
+    # Whether or not the role is of the holographic style.
+    # @return [true, false]
+    def holographic?
+      !@tertiary_colour.nil?
+    end
+
+    # Whether or not the role has a two-point gradient.
+    # @return [true, false]
+    def gradient?
+      !@secondary_colour.nil? && @tertiary_colour.nil?
+    end
+
+    alias_method :color=, :colour=
+    alias_method :secondary_color=, :secondary_colour=
+    alias_method :tertiary_color=, :tertiary_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 permissions [Integer, nil] 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. This is deprecated and no longer functional. Permissions data is always updated.
+    def packed=(permissions, _update_perms = true)
+      modify(permissions: permissions)
+    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
+    # @deprecated Please migrate to using {#move} with the `above` or `below` KWARGS.
+    def sort_above(other = nil)
+      other ? move(above: other) : move(bottom: true)
+    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
+
+    # Move the position of this role in the roles list.
+    # @example This will move the role 2 places above the `@everyone` role.
+    #   role.move(bottom: true, offset: 2)
+    # @example This will move the role above the `@muted` role.
+    #   role.move(above: 257017090932867072)
+    # @example This will move the role 3 spots below the `@moderator` role.
+    #   role.move(below: 254077236989132800, offset: -3)
+    # @param bottom [true, false, nil] Whether to move the roles to the bottom of the role list.
+    # @param above [Integer, String, Role, nil] The role that this role should be moved above.
+    # @param below [Integer, String, Role, nil] The role that this role should be moved below.
+    # @param offset [Integer, nil] The number of roles to offset the new position by. A positive number will
+    #   move the role above, and a negative number will move the role below. This parameter is relative and
+    #   calculated after the `bottom`, `above`, and `below` parameters.
+    # @param reason [String, nil] The audit log reason to show for moving the role.
+    # @return [Integer] The new position of the role.
+    def move(bottom: nil, above: nil, below: nil, offset: 0, reason: nil)
+      if [bottom, above, below].count(&:itself) > 1
+        raise ArgumentError, "'bottom', 'above', and 'below' are mutually exclusive"
+      end
+
+      if (above || below) && !(target = @server.role(above || below))
+        raise ArgumentError, "The given 'above' or 'below' options are not valid"
+      end
+
+      if (below && target&.id == @server.id) || (@id == target&.id)
+        raise ArgumentError, 'The target role that was provded is not valid'
+      end
+
+      roles = @server.roles.sort_by { |role| [role.position, role.id] }
+
+      # Make sure we remove the current role.
+      myself = roles.rindex(@id).tap { |index| roles.delete_at(index) }
+
+      index = if bottom
+                1
+              elsif below
+                roles.rindex(target)
+              elsif above
+                roles.rindex(target) + 1
+              else
+                myself
+              end
+
+      roles.insert([index + (offset || 0), 1].max, self)
+
+      roles = roles.map.with_index do |role, new_position|
+        { id: role.resolve_id, position: new_position }
+      end
+
+      @server.update_role_positions(roles, reason: reason)
+      @position
+    end
+
+    # A rich interface designed to make working with role colours simple.
+    # @param primary [ColourRGB, Integer, nil] The new primary/base colour of this role, or nil to clear the primary colour.
+    # @param secondary [ColourRGB, Integer, nil] The new secondary colour of this role, or nil to clear the secondary colour.
+    # @param tertiary [ColourRGB, Integer,nil] The new tertiary colour of this role, or nil to clear the tertiary colour.
+    # @param holographic [true, false] Whether to apply or remove the holographic style to the role colour, overriding any other
+    #   arguments that were passed. Using this argument is recommended over passing individual colours.
+    # @param reason [String, nil] The audit log reason to show for updating the role's colours.
+    def update_colours(primary: :undef, secondary: :undef, tertiary: :undef, holographic: :undef, reason: nil)
+      colours = {
+        color: (primary == :undef ? @colour : primary)&.to_i,
+        tertiary_color: (tertiary == :undef ? @tertiary_colour : tertiary)&.to_i,
+        secondary_color: (secondary == :undef ? @secondary_colour : secondary)&.to_i
+      }
+
+      holographic_colours = {
+        color: 11_127_295,
+        tertiary_color: 16_761_760,
+        secondary_color: 16_759_788
+      }
+
+      # Only set the tertiary_color to `nil` if holographic is explicitly set to false.
+      (colours[:tertiary_color] = nil) if holographic.is_a?(FalseClass)
+
+      modify(reason: reason, **(holographic ? holographic_colours : colours))
+    end
+
+    alias_method :update_colors, :update_colours
+
+    # Modify the properties of the role.
+    # @param name [String, nil] The new 1-100 character name of the role.
+    # @param mentionable [true, false, nil] Whether or not anyone should be able to ping the role.
+    # @param hoist [true, false, nil] Whether or not members who have the role should be shown seperately in the sidebar.
+    # @param unicode_emoji [String, nil] The new unicode emoji to set as the role's icon.
+    # @param icon [#read, File, nil] The new custom icon of the role. Must be a file-like object that responds to `#read`.
+    # @param display_icon [String, #read, File, nil] The new display icon of the role. Mutually exclusive with `icon:` and `unicode_emoji:`.
+    # @param colour [ColourRGB, Integer, nil] The new primary colour of the role. Can also be passed as `color:`.
+    # @param secondary_colour [ColourRGB, Integer, nil] The new secondary colour of the role. Can also be passed as `secondary_color:`.
+    # @param tertiary_colour [ColourRGB, Integer, nil] The new tertiary colour of the role. Can also be passed as `tertiary_color:`.
+    # @param permissions [String, Integer, nil] The new permissions to set for the role.
+    # @param reason [String, nil] The reason to show in the server's audit log for modifying the role.
+    # @yieldparam builder [Permissions] An optional permissions builder. Arguments passed to the method overwrite builder data.
+    # @return [nil]
+    def modify(
+      name: :undef, mentionable: :undef, hoist: :undef, unicode_emoji: :undef, icon: :undef,
+      display_icon: :undef, color: :undef, colour: :undef, secondary_color: :undef,
+      secondary_colour: :undef, tertiary_color: :undef, tertiary_colour: :undef,
+      permissions: :undef, reason: nil
+    )
+      if display_icon != :undef
+        if icon != :undef || unicode_emoji != :undef
+          raise ArgumentError, "'display_icon' is mutually exclusive with 'icon' and 'unicode_emoji'"
+        end
+
+        if display_icon.nil?
+          icon = nil
+          unicode_emoji = nil
+        elsif display_icon.is_a?(String)
+          icon = nil
+          unicode_emoji = display_icon
+        elsif display_icon.respond_to?(:read)
+          icon = display_icon
+          unicode_emoji = nil
+        end
+      end
+
+      if block_given? && permissions == :undef
+        yield((builder = Permissions.new(@permissions.bits)))
+        permissions = builder.bits
+      end
+
+      data = {
+        name: name,
+        mentionable: mentionable,
+        hoist: hoist,
+        unicode_emoji: unicode_emoji,
+        icon: icon.respond_to?(:read) ? OnyxCord.encode64(icon) : icon,
+        permissions: permissions == :undef ? permissions : permissions&.to_s,
+        reason: reason
+      }
+
+      color = (colour == :undef ? color : colour)
+      tertiary = (tertiary_colour == :undef ? tertiary_color : tertiary_colour)
+      secondary = (secondary_colour == :undef ? secondary_color : secondary_colour)
+
+      if color != :undef || secondary != :undef || tertiary != :undef
+        data[:colors] = {
+          primary_color: (color == :undef ? @colour : color)&.to_i,
+          tertiary_color: (tertiary == :undef ? @tertiary_colour : tertiary)&.to_i,
+          secondary_color: (secondary == :undef ? @secondary_colour : secondary)&.to_i
+        }
+      end
+
+      update_data(JSON.parse(API::Server.update_role!(@bot.token, @server.id, @id, **data)))
+      nil
+    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} unicode_emoji=#{@unicode_emoji} flags=#{@flags}>"
+    end
+  end
+end

data/lib/onyxcord/data/role_connection_data.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # Metadata about a role's linked connection.
+  class RoleConnectionMetadata
+    # Map of connection types.
+    TYPES = {
+      integer_less_than_or_equal: 1,
+      integer_greater_than_or_equal: 2,
+      integer_equal: 3,
+      integer_not_equal: 4,
+      datetime_less_than_or_equal: 5,
+      datetime_greater_than_or_equal: 6,
+      boolean_equal: 7,
+      boolean_not_equal: 8
+    }.freeze
+
+    # @return [String] the key of the metadata field.
+    attr_reader :key
+
+    # @return [String] the name of the metadata field.
+    attr_reader :name
+
+    # @return [Integer] the value of the metadata field.
+    attr_reader :type
+
+    # @return [String] the description of the metadata field.
+    attr_reader :description
+
+    # @return [Hash<String => String>] the name localizations of the metadata field.
+    attr_reader :name_localizations
+
+    # @return [Hash<String => String>] the description localizations of the metadata field.
+    attr_reader :description_localizations
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+      @key = data['key']
+      @name = data['name']
+      @type = data['type']
+      @description = data['description']
+      @name_localizations = data['name_localizations'] || {}
+      @description_localizations = data['description_localizations'] || {}
+    end
+
+    # @!method integer_less_than_or_equal?
+    #   @return [true, false] whether the numeric metadata value is less than or equivalent to the server's configured numeric value.
+    # @!method integer_greater_than_or_equal?
+    #   @return [true, false] whether the numeric metadata value is greater than or equivalent to the server's configured numeric value.
+    # @!method integer_equal?
+    #   @return [true, false] whether the numeric metadata value is equivalent to the server's configured numeric value.
+    # @!method integer_not_equal?
+    #   @return [true, false] whether the numeric metadata value is not equivalent to the server's configured numeric value.
+    # @!method datetime_less_than_or_equal?
+    #   @return [true, false] whether the ISO8601 date is less than or equivalent to the server's configured number of days before a date.
+    # @!method datetime_greater_than_or_equal?
+    #   @return [true, false] whether the ISO8601 date is greater than or equivalent to the server's configured number of days before a date.
+    # @!method boolean_equal?
+    #   @return [true, false] whether the boolean metadata value is equivalent to the server's configured boolean value.
+    # @!method boolean_not_equal?
+    #   @return [true, false] whether the boolean metadata value is not equivalent to the server's configured boolean value.
+    TYPES.each do |name, value|
+      define_method("#{name}?") do
+        @type == value
+      end
+    end
+  end
+end

data/lib/onyxcord/data/role_subscription.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # Metadata about a purchase or renewal for a role subscription.
+  class RoleSubscriptionData
+    # @return [String] the name of the tier the user is subscribed to.
+    attr_reader :tier_name
+
+    # @return [Integer] the ID of the SKU and listing the user is subscribed to.
+    attr_reader :listing_id
+
+    # @return [true, false] whether the subscription notification is for a renewal.
+    attr_reader :renewal
+    alias_method :renewal?, :renewal
+
+    # @return [Integer] the total number of months the user has been subscribed for.
+    attr_reader :total_months_subscribed
+
+    # @!visibility private
+    def initialize(data, message, bot)
+      @bot = bot
+      @message = message
+      @renewal = data['is_renewal']
+      @tier_name = data['tier_name']
+      @listing_id = data['role_subscription_listing_id']&.to_i
+      @total_months_subscribed = data['total_months_subscribed']
+    end
+
+    # Check if this role subscription is a new purchase.
+    # @return [true, false] if this role subscription is a new purchase.
+    def new?
+      @renewal == false
+    end
+
+    # Get the role associated with the notification for this subscription.
+    # @return [Role, nil] the role that's associated with this subscription.
+    def role
+      @message.server.roles.find { |role| role.tags&.subscription_listing_id == @listing_id }
+    end
+  end
+end