onyxcord 1.1.0

data/lib/onyxcord/data/overwrite.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # A permissions overwrite, when applied to channels describes additional
+  # permissions a member needs to perform certain actions in context.
+  class Overwrite
+    # Types of overwrites mapped to their API value.
+    TYPES = {
+      role: 0,
+      member: 1
+    }.freeze
+
+    # @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 = OnyxCord::Permissions.new
+    #   allow.can_mention_everyone = true
+    #   allow.can_send_tts_messages = true
+    #
+    #   deny = OnyxCord::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, Symbol, Integer] the type of object this overwrite is for (only required if object is an Integer)
+    # @param allow [String, Integer, Permissions] allowed permissions for this overwrite, by bits or a Permissions object
+    # @param deny [String, 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 = TYPES.value?(type) ? TYPES.key(type) : type.to_sym
+        raise ArgumentError, 'Overwrite type must be :member or :role' unless type
+      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)
+      return false unless other.is_a?(OnyxCord::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: TYPES.key(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: TYPES[type],
+        allow: allow.bits,
+        deny: deny.bits
+      }
+    end
+  end
+end

data/lib/onyxcord/data/poll.rb

@@ -0,0 +1,365 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # A surface with selectable answers.
+  class Poll
+    # Mapping of layout types for polls.
+    LAYOUTS = {
+      default: 1
+    }.freeze
+
+    # @return [Integer] the layout type of the poll.
+    attr_reader :layout
+
+    # @return [Array<Answer>] the answers of the poll.
+    attr_reader :answers
+
+    # @return [Message] the message linked to the poll.
+    attr_reader :message
+
+    # @return [Media] the display-data for the poll question.
+    attr_reader :question
+
+    # @return [Time, nil] the time at when the poll will expire.
+    attr_reader :closes_at
+
+    # @return [true, false] whether or not Discord has precisely counted the votes yet.
+    attr_reader :finalised
+    alias finalised? finalised
+    alias finalized? finalised
+
+    # @return [true, false] whether or not users are allowed to vote for multiple answers.
+    attr_reader :multiselect
+    alias multiselect? multiselect
+
+    # @return [true, false] whether or not Discord did not fetch the results for the poll.
+    #   When this is `true`, the {#finalised?} method will always return a value of `false`,
+    #   and {Answer#votes} will always return a value of `0`.
+    attr_reader :unknown_results
+    alias unknown_results? unknown_results
+
+    # @!visibility private
+    def initialize(data, message, bot)
+      @bot = bot
+      @message = message
+      @layout = data['layout_type']
+      @question = Media.new(data['question'], @bot)
+      @multiselect = data['allow_multiselect']
+      @closes_at = Time.parse(data['expiry']) if data['expiry']
+      results = data['results']
+      @unknown_results = results.nil?
+      @finalised = results&.[]('is_finalized') || false
+      process_answers(data['answers'], results&.[]('answer_counts'))
+    end
+
+    # Get the total amount of votes cast on the poll.
+    # @return [Integer] The total amount of votes that the poll received.
+    def total_votes
+      @answers.sum(&:votes)
+    end
+
+    # Get a single answer for the poll by its ID.
+    # @param answer_id [Integer, String, Answer] The ID of the poll answer.
+    # @return [Answer, nil] The poll answer, or `nil` if it couldn't be found.
+    def answer(answer_id)
+      answer_id = if answer_id.is_a?(Answer)
+                    answer_id.id
+                  else
+                    answer_id.resolve_id
+                  end
+
+      @answers.find { |answer| answer.id == answer_id }
+    end
+
+    # Check if the poll has closed.
+    # @return [true, false] Whether or not the poll has closed.
+    def closed?
+      @finalised || (!@closes_at.nil? && Time.now > @closes_at)
+    end
+
+    # Get the poll answer that has the most amount of votes.
+    # @return [Answer, nil] The winning poll answer, or `nil` for no winner.
+    def winner
+      return unless (max = @answers.max_by(&:votes))&.votes&.nonzero?
+
+      @answers.one? { |answer| answer.votes == max&.votes } ? max : nil
+    end
+
+    # Prematurely end the poll, only functional for polls created by the current bot.
+    # @return [Message] The resulting message. Will fail if the poll was not sent by the current bot.
+    # @raise [OnyxCord::Errors::NoPermission] If the poll was not created by the current bot account.
+    def close
+      raise OnyxCord::Errors::NoPermission, 'Cannot close the poll' if !@message.from_bot? || closed?
+
+      Message.new(JSON.parse(API::Channel.end_poll(@bot.token, @message.channel.id, @message.id)), @bot)
+    end
+
+    # Check if two poll objects are equivalent.
+    # @param other [Object] The object to compare the poll object against.
+    # @return [true, false] Whether or not the poll objects are equivalent.
+    def ==(other)
+      other.is_a?(Poll) ? @message == other.message : false
+    end
+
+    alias_method :eql?, :==
+
+    # @!method default_layout?
+    #   @return [true, false] whether or not the poll is using the default layout.
+    LAYOUTS.each do |name, value|
+      define_method("#{name}_layout?") { @layout == value }
+    end
+
+    # @!visibility private
+    def inspect
+      "<Poll question=\"#{@question.text}\" unknown_results=#{@unknown_results}>"
+    end
+
+    # @!visibility private
+    def to_h
+      {
+        layout_type: @layout,
+        question: @question.to_h,
+        answers: @answers.map(&:to_h),
+        allow_multiselect: @multiselect,
+        duration: @closes_at ? ((@closes_at - @message.creation_time) / 3600).round : nil
+      }
+    end
+
+    private
+
+    # @!visibility private
+    def process_answers(answers, counts)
+      @answers = answers.map do |answer|
+        count_data = counts&.find { |count| count['id'] == answer['answer_id'] }
+
+        Answer.new(answer.tap { answer['_votes'] = count_data&.[]('count') }, self, @bot)
+      end
+    end
+
+    # A selectable poll answer.
+    class Answer
+      # @return [Integer] the ID of the poll answer.
+      attr_reader :id
+
+      # @return [Integer] the number of votes the answer has.
+      attr_reader :votes
+      alias vote_count votes
+
+      # @return [Integer] the ID of the message the answer is from.
+      attr_reader :message_id
+
+      # @!visibility private
+      def initialize(data, poll, bot)
+        @bot = bot
+        @poll = poll
+        @id = data['answer_id']
+        @votes = data['_votes'] || 0
+        @media = Media.new(data['poll_media'], @bot)
+        @channel_id = data['_channel_id'] unless @poll
+        @message_id = @poll&.message&.id || data['_message_id']&.to_i
+      end
+
+      # Get the text of the poll answer.
+      # @return [String] The text of the poll answer.
+      def text
+        @media.text
+      end
+
+      # Get the emoji of the poll answer.
+      # @return [Emoji, nil] The emoji of the poll answer.
+      def emoji
+        @media.emoji
+      end
+
+      # Check if the poll answer won the poll.
+      # @return [true, false] Whether or not the poll answer is the winner.
+      def winner?
+        @poll.nil? || @poll.winner&.id == @id
+      end
+
+      # Get the users who voted for the poll answer.
+      # @param after [Time, #resolve_id, nil] The ID or timestamp to start fetching voters from.
+      # @param limit [Integer, nil] The maximum number of voters to fetch, or `nil` to fetch all the voters.
+      # @return [Array<User>] The users who voted for the poll answer; ordered by user ID in ascending order.
+      def voters(after: nil, limit: 100)
+        stable = @poll.nil? || @poll.finalised?
+        channel_id = @channel_id || @poll.message.channel.id
+        after_time = after.is_a?(Time) ? IDObject.synthesise(after) : after&.resolve_id
+
+        get_users = lambda do |limit, after|
+          data = API::Channel.get_poll_voters(@bot.token, channel_id, @message_id, @id, after:, limit:)
+          JSON.parse(data)['users'].collect { |poll_voter_data| @bot.ensure_user(poll_voter_data) }
+        end
+
+        return get_users.call(limit, after_time) if limit && limit <= 100
+
+        paginator = Paginator.new(limit, :down) do |last_page|
+          if stable && last_page && last_page.count < 100
+            []
+          else
+            get_users.call(100, last_page&.last&.id || after_time)
+          end
+        end
+
+        paginator.to_a
+      end
+
+      # Check if two poll answers are equivalent.
+      # @param other [Object] The object to compare the poll answer against.
+      # @return [true, false] Whether or not the poll answers are equivalent.
+      def ==(other)
+        return false unless other.is_a?(Answer)
+
+        @message_id == other.message_id && @id == other.id
+      end
+
+      alias_method :eql?, :==
+
+      # @!visibility private
+      def to_h
+        { poll_media: @media.to_h }
+      end
+
+      # @!visibility private
+      def inspect
+        "<Answer id=#{@id} text=\"#{text}\" votes=#{@votes}>"
+      end
+    end
+
+    # Represents display-data for a poll.
+    class Media
+      # @return [String, nil] the text of the poll media.
+      attr_reader :text
+
+      # @return [Emoji, nil] the emoji of the poll media.
+      attr_reader :emoji
+
+      # @!visibility private
+      def initialize(data, bot)
+        @bot = bot
+        @text = data['text']
+        @emoji = Emoji.new(data['emoji'], @bot) if data['emoji']
+      end
+
+      # Check if two poll media objects are equivalent.
+      # @param other [Object] The object to compare the poll media against.
+      # @return [true, false] Whether or not the poll media objects are equivalent.
+      def ==(other)
+        return false unless other.is_a?(Media)
+
+        @text == other.text && @emoji == other.emoji
+      end
+
+      alias_method :eql?, :==
+
+      # @!visibility private
+      def to_h
+        { text: @text, emoji: @emoji&.to_h }.compact
+      end
+
+      # @!visibility private
+      def inspect
+        "<Media text=\"#{@text}\" emoji=#{@emoji.inspect}>"
+      end
+    end
+
+    # Finalised results for a poll.
+    class Result
+      # @return [Answer, nil] the answer that won the poll, if any.
+      attr_reader :winner
+      alias answer winner
+
+      # @return [Media] the display-data for the question of the poll.
+      attr_reader :question
+
+      # @return [Integer] the ID of the message the poll result is for.
+      attr_reader :message_id
+
+      # @return [Integer] the total amount of votes that the poll received.
+      attr_reader :total_votes
+
+      # @!visibility private
+      def initialize(embed, reference, bot)
+        @bot = bot
+        @message_id = reference['message_id'].to_i
+        embed = embed['fields'].to_h { |field| [field['name'], field['value']] }
+        @question = Media.new({ 'text' => embed['poll_question_text'] }, @bot)
+        @total_votes = embed['total_votes'].to_i
+        return unless (id = embed['victor_answer_id']&.to_i)
+
+        data = {
+          'poll_media' => {
+            'text' => embed['victor_answer_text']
+          },
+          'answer_id' => id,
+          '_message_id' => @message_id,
+          '_channel_id' => reference['channel_id'],
+          '_votes' => embed['victor_answer_votes'].to_i
+        }
+
+        if embed['victor_answer_emoji_id'] || embed['victor_answer_emoji_name']
+          data['poll_media']['emoji'] = {
+            'name' => embed['victor_answer_emoji_name'],
+            'id' => embed['victor_answer_emoji_id']&.to_i,
+            'animated' => embed['victor_answer_emoji_animated'] == 'true'
+          }
+        end
+
+        @winner = Answer.new(data, nil, @bot)
+      end
+
+      # Check if two result objects are equivalent.
+      # @param other [Object] The object to compare the result object against.
+      # @return [true, false] Whether or not the result objects are equivalent.
+      def ==(other)
+        other.is_a?(Result) ? @message_id == other.message_id : false
+      end
+
+      alias_method :eql?, :==
+
+      # @!visibility private
+      def inspect
+        "<Result winner=#{@winner.inspect} total_votes=#{@total_votes}>"
+      end
+    end
+
+    # Builder for polls.
+    class Builder
+      # Create a poll request object.
+      # @param question [String] The question of the poll; between 1-55 characters.
+      # @param layout [Integer, Symbol, nil] The layout type of the poll; see {LAYOUTS}.
+      # @param duration [Integer, Time, nil] The number of hours before the poll expires.
+      # @param multiselect [true, false, nil] Whether or not users can pick multiple answers.
+      def initialize(question:, layout: :default, duration: 24, multiselect: false)
+        @layout = layout
+        @answers = []
+        @question = question
+        @duration = duration || 24
+        @multiselect = multiselect
+      end
+
+      # Add an answer to the poll builder.
+      # @param text [String] The text of the poll answer.
+      # @param emoji [Emoji, Reaction, Integer, String, nil] The emoji of the poll answer.
+      # @return [void]
+      def answer(text:, emoji: nil)
+        emoji = Emoji.build_emoji_hash(emoji, prefix: false) if emoji
+
+        @answers << { poll_media: { text: text, emoji: emoji }.compact }
+      end
+
+      alias_method :add_answer, :answer
+
+      # @!visibility private
+      def to_h
+        {
+          question: { text: @question },
+          answers: @answers,
+          layout_type: LAYOUTS[@layout] || @layout,
+          allow_multiselect: @multiselect,
+          duration: @duration.is_a?(Time) ? ((@duration - Time.now) / 3600).round : @duration
+        }
+      end
+    end
+  end
+end

data/lib/onyxcord/data/primary_server.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # A server tag that a user has chosen to display on their profile.
+  class PrimaryServer
+    # @return [Integer] the ID of the server this primary server is for.
+    attr_reader :server_id
+
+    # @return [true, false] if the user is displaying the primary server's tag.
+    attr_reader :enabled
+    alias_method :enabled?, :enabled
+
+    # @return [String] the text of the primary server's tag. Limited to four characters.
+    attr_reader :name
+    alias_method :text, :name
+
+    # @return [String] the ID of the server tag's badge. Can be used to generate a badge URL.
+    # @see #badge_url
+    attr_reader :badge_id
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+      @server_id = data['identity_guild_id']&.to_i
+      @enabled = data['identity_enabled']
+      @name = data['tag']
+      @badge_id = data['badge']
+    end
+
+    # Get the server associated with this primary server.
+    # @return [Server] the server associated with this primary server.
+    # @raise [OnyxCord::Errors::NoPermission] this can happen when the bot is not in the associated server.
+    def server
+      @bot.server(@server_id)
+    end
+
+    # Get the server preview associated with this primary server.
+    # @return [ServerPreview, nil] the server preview associated with this primary server, or `nil` if it can't be accessed.
+    def server_preview
+      @bot.server_preview(@server_id)
+    end
+
+    # Utility method to get a server tag's badge URL.
+    # @param format [String] the URL will default to `webp`. You can otherwise specify one of `jpg` or `png` to override this.
+    # @return [String] the URL to the server tag's badge image.
+    def badge_url(format = 'webp')
+      API.server_tag_badge_url(@server_id, @badge_id, format)
+    end
+
+    # Comparison based off of server ID.
+    # @return [true, false] if the other object is equal to this primary server.
+    def ==(other)
+      return false unless other.is_a?(PrimaryServer)
+
+      OnyxCord.id_compare?(other.server_id, @server_id)
+    end
+
+    alias_method :eql?, :==
+  end
+end

data/lib/onyxcord/data/profile.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # 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, File, #read, nil] A file to be used as the avatar, either
+    #  something readable (e.g. File Object) or a data URI.
+    def avatar=(avatar)
+      if avatar.respond_to?(:read)
+        update_profile_data(avatar: OnyxCord.encode64(avatar))
+      else
+        update_profile_data(avatar: avatar)
+      end
+    end
+
+    # Changes the bot's banner.
+    # @param banner [String, File, #read, nil] A file to be used as the banner, either
+    #  something readable (e.g. File Object) or a data URI.
+    def banner=(banner)
+      if banner.respond_to?(:read)
+        update_profile_data(banner: OnyxCord.encode64(banner))
+      else
+        update_profile_data(banner: banner)
+      end
+    end
+
+    # Get the bot's global bio.
+    # @return [String] The bot's global bio, or an empty string if it doesn't have one set.
+    def bio
+      @bot.application.description
+    end
+
+    # Set the bot's global bio.
+    # @param bio [String, nil] The bot's new global bio, or `nil` to remove the current bio.
+    def bio=(bio)
+      @bot.application.modify(description: bio)
+    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']
+      @avatar_id = new_data['avatar']
+      @banner_id = new_data['banner']
+    end
+
+    # The inspect method is overwritten to give more useful output
+    def inspect
+      "<Profile user=#{super}>"
+    end
+
+    private
+
+    # @!visibility private
+    def update_profile_data(new_data)
+      update_data(JSON.parse(API::User.update_current_user(@bot.token,
+                                                           new_data[:username] || :undef,
+                                                           new_data.key?(:avatar) ? new_data[:avatar] : :undef,
+                                                           new_data.key?(:banner) ? new_data[:banner] : :undef)))
+    end
+  end
+end

data/lib/onyxcord/data/reaction.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # A reaction to a message.
+  class Reaction
+    # Map of reaction types.
+    TYPES = {
+      normal: 0,
+      burst: 1
+    }.freeze
+
+    # @return [Integer] the total amount of users who have reacted with this reaction (including burst reactions)
+    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
+
+    # @return [true, false] whether the current bot or user used this reaction as a burst reaction
+    attr_reader :me_burst
+    alias_method :me_burst?, :me_burst
+
+    # @return [Array<ColourRGB>] an array of colors used for animations in burst reactions
+    attr_reader :burst_colours
+    alias_method :burst_colors, :burst_colours
+
+    # @return [Integer] the total amount of users who have reacted with this reaction as a burst reaction
+    attr_reader :burst_count
+
+    # @return [Integer] the total amount of users who have reacted with this reaction as a normal reaction
+    attr_reader :normal_count
+
+    # @!visibility private
+    def initialize(data)
+      @count = data['count']
+      @me = data['me']
+      @id = data['emoji']['id']&.to_i
+      @name = data['emoji']['name']
+      @me_burst = data['me_burst']
+      @burst_colours = data['burst_colors'].map { |b| ColourRGB.new(b.delete('#')) }
+      @burst_count = data['count_details']['burst']
+      @normal_count = data['count_details']['normal']
+    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
+
+    # Converts this Reaction into a hash that can be sent back to Discord in other endpoints.
+    # @return [Hash] A hash representation of this reaction's emoji.
+    def to_h
+      id.nil? ? { name: name } : { id: id }
+    end
+  end
+end