onyxcord 1.1.0

data/lib/onyxcord/data/server_preview.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # Publicly accessible information about a discoverable server.
+  class ServerPreview
+    include IDObject
+    include ServerAttributes
+
+    # @return [String, nil] the ID of the server's invite splash screen.
+    # @see #splash_url
+    attr_reader :splash_id
+
+    # @return [String, nil] the ID of the server's discovery splash screen.
+    # @see #discovery_splash_url
+    attr_reader :discovery_splash_id
+
+    # @return [Hash<Integer => Emoji>] a hash of all the emojis usable on this server.
+    attr_reader :emojis
+
+    # @return [Array<Symbol>] the features of this server, e.g. `:banner` or `:verified`.
+    attr_reader :features
+
+    # @return [Integer] the approximate number of members on this server, offline or not.
+    attr_reader :member_count
+
+    # @return [Integer] the approximate number of members that aren't offline on this server.
+    attr_reader :presence_count
+
+    # @return [String, nil] the description of this server that's shown in the discovery tab.
+    attr_reader :description
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+      @id = data['id'].to_i
+      @name = data['name']
+      @icon_id = data['icon']
+      @splash_id = data['splash']
+      @description = data['description']
+      @discovery_splash_id = data['discovery_splash']
+      @member_count = data['approximate_member_count']
+      @presence_count = data['approximate_presence_count']
+      @features = data['features'].map { |feature| feature.downcase.to_sym }
+      @emojis = data['emojis'].to_h { |emoji| [emoji['id'].to_i, Emoji.new(emoji, bot)] }
+    end
+
+    # Get the server associated with this server preview.
+    # @return [Server] the server associated with this server preview.
+    # @raise [OnyxCord::Errors::NoPermission] this can happen when the bot is not in the associated server.
+    def server
+      @bot.server(@id)
+    end
+
+    # Utility method to get a server preview's splash URL.
+    # @param format [String] the URL will default to `webp`. You can otherwise specify one of `jpg` or `png` to override this.
+    # @return [String, nil] the URL to the server's splash image, or `nil` if the server doesn't have a splash image.
+    def splash_url(format = 'webp')
+      API.splash_url(@id, @splash_id, format) if @splash_id
+    end
+
+    # Utility method to get a server preview's discovery splash URL.
+    # @param format [String] the URL will default to `webp`. You can otherwise specify one of `jpg` or `png` to override this.
+    # @return [String, nil] the URL to the server's discovery splash image, or `nil` if the server doesn't have a discovery splash image.
+    def discovery_splash_url(format = 'webp')
+      API.discovery_splash_url(@id, @discovery_splash_id, format) if @discovery_splash_id
+    end
+  end
+end

data/lib/onyxcord/data/snapshot.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # A partial and immutable copy of a message that has been forwarded.
+  class Snapshot
+    # @return [Integer] the message type of the message snapshot.
+    attr_reader :type
+
+    # @return [String] the text content of the message snapshot.
+    attr_reader :content
+
+    # @return [Array<Embed>] the embeds attached to the message snapshot.
+    attr_reader :embeds
+
+    # @return [Array<Attachment>] the files attached to the message snapshot.
+    attr_reader :attachments
+
+    # @return [Time] the time at which the message snapshot was created.
+    attr_reader :created_at
+
+    # @return [Time, nil] the time at which the message snapshot was edited.
+    attr_reader :edited_at
+
+    # @return [Integer] the flags that have been set on the message snapshot.
+    attr_reader :flags
+
+    # @return [Array<User>] the users that were mentioned in the message snapshot.
+    attr_reader :mentions
+
+    # @return [Array<Component>] the interaction components associated with the message snapshot.
+    attr_reader :components
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+      @type = data['type']
+      @flags = data['flags'] || 0
+      @content = data['content']
+      @mention_roles = data['mention_roles']&.map(&:resolve_id) || []
+      @embeds = data['embeds']&.map { |embed| Embed.new(embed, self) } || []
+      @attachments = data['attachments']&.map { |file| Attachment.new(file, self, @bot) } || []
+      @created_at = data['timestamp'] ? Time.parse(data['timestamp']) : nil
+      @edited_at = data['edited_timestamp'] ? Time.parse(data['edited_timestamp']) : nil
+      @mentions = data['mentions']&.map { |mention| @bot.ensure_user(mention) } || []
+      @components = data['components']&.map { |component| Components.from_data(component, @bot) } || []
+    end
+
+    # Check whether the message snapshot has been edited.
+    # @return [true, false] whether the snapshot was edited or not.
+    def edited?
+      !@edited_at.nil?
+    end
+
+    # Check whether the message snapshot contains any custom emojis.
+    # @return [true, false]  whether or not any emoji were used in the snapshot.
+    def emojis?
+      emojis.any?
+    end
+
+    # Get the custom emojis that were used in the message snapshot.
+    # @return [Array<Emoji>] the emojis used in the message snapshot.
+    def emojis
+      return [] if @content.nil? || @content.empty?
+
+      @emojis ||= @bot.parse_mentions(@content).select { |parsed| parsed.is_a?(Emoji) }
+    end
+
+    # Get the roles that were mentioned in the message snapshot.
+    # @return [Array<Role>] the roles that were mentioned in the message snapshot.
+    # @note this can only resolve roles in servers that the bot has access to via {Bot#servers}.
+    def role_mentions
+      return [] if @mention_roles.empty?
+
+      return @role_mentions if @role_mentions
+
+      roles = @bot.servers.values.flat_map(&:roles)
+
+      @role_mentions = @mention_roles.filter_map { |id| roles.find { |r| r.id == id } }
+    end
+
+    # Get the buttons that were used in the message snapshot.
+    # @return [Array<Components::Button>] the button components used in the message snapshot.
+    def buttons
+      buttons = @components.flat_map do |component|
+        case component
+        when Components::Button
+          component
+        when Components::Section
+          component.accessory if component.accessory.is_a?(Components::Button)
+        when Components::ActionRow, Components::Container
+          component.buttons
+        end
+      end
+
+      buttons.compact
+    end
+
+    # @see OnyxCord::Message::FLAGS
+    Message::FLAGS.each do |name, value|
+      define_method("#{name}?") do
+        @flags.anybits?(value)
+      end
+    end
+
+    # @see OnyxCord::Message::TYPES
+    Message::TYPES.each do |name, value|
+      define_method("#{name}?") do
+        @type == value
+      end
+    end
+  end
+end

data/lib/onyxcord/data/team.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # A group of users that can manage applications.
+  class Team
+    include IDObject
+
+    # @return [String] the name of this team.
+    attr_reader :name
+
+    # @return [Member] the owner of this team.
+    attr_reader :owner
+
+    # @return [String, nil] the ID of this team's icon.
+    # @see #icon_url
+    attr_reader :icon_id
+
+    # @return [Array<Member>] the members that are a part of this team.
+    attr_reader :members
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+      @id = data['id'].to_i
+      @name = data['name']
+      @icon_id = data['icon']
+      @members = data['members'].map { |member| Member.new(member, self, bot) }
+      @owner = @members.find { |member| member.user.id == data['owner_user_id'].to_i }
+    end
+
+    # Utility method to get a team's icon URL.
+    # @param format [String] The URL will default to `webp`. You can otherwise specify one of `webp`, `jpg`, or `png` to override this.
+    # @return [String, nil] the URL to the icon image (nil if no image is set).
+    def icon_url(format = 'webp')
+      API.team_icon_url(@id, @icon_id, format) if @icon_id
+    end
+
+    # A member that has been invited to a team.
+    class Member
+      # @return [Symbol] the role of this team member.
+      attr_reader :role
+
+      # @return [Team] the team this member is a part of.
+      attr_reader :team
+
+      # @return [Integer] the membership state of this team member.
+      attr_reader :state
+
+      # @return [Integer] the user associated with this team member.
+      attr_reader :user
+
+      # @!visibility private
+      def initialize(data, team, bot)
+        @bot = bot
+        @team = team
+        @role = data['role'].to_sym
+        @state = data['membership_state']
+        @user = bot.ensure_user(data['user'])
+      end
+
+      # Whether this team member has been invited to the team, but hasn't accepted the invite yet.
+      # @return [true, false]
+      def pending?
+        @state == 1
+      end
+
+      # Whether this team member is the owner of the team.
+      # @return [true, false]
+      def owner?
+        @team.owner == self
+      end
+
+      # @!method admin?
+      #   @return [true, false] whether this team member is an admin.
+      # @!method developer?
+      #   @return [true, false] whether this team member is a developer.
+      # @!method read_only?
+      #   @return [true, false] whether this team member is a read only developer.
+      %i[admin developer read_only].each do |role|
+        define_method("#{role}?") do
+          @role == role
+        end
+      end
+
+      # Comparison based off of user ID and team ID.
+      # @return [true, false] if the two objects are equal.
+      def ==(other)
+        return false unless other.is_a?(Member)
+
+        return false unless @team == other.team
+
+        OnyxCord.id_compare?(other.user.id, @user.id)
+      end
+
+      alias_method :eql?, :==
+    end
+  end
+end

data/lib/onyxcord/data/timestamp.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # A timestamp referenced in a message via markdown.
+  class TimestampMarkdown
+    # Mapping of timestamp styles.
+    STYLES = {
+      short_time: 't', # 16:20
+      long_time: 'T', # 16:20:30
+      short_date: 'd', # 20/04/2021
+      long_date: 'D', # 20 April 2021
+      short_datetime: 'f', # 20 April 2021 16:20
+      long_datetime: 'F', # Tuesday, 20 April 2021 16:20
+      relative: 'R', # 2 months ago
+      simple_datetime: 's', # 20/04/2021, 16:20
+      medium_datetime: 'S' # 20/04/2021, 16:20:30
+    }.freeze
+
+    # @return [Time] the time that the timestamp is referencing.
+    attr_reader :time
+
+    # @!visibility private
+    def initialize(time, style)
+      @time = time
+      @style = style
+    end
+
+    # Get the specifier used to determine the style of the timestamp.
+    # @return [String] the formatting specifier used to display the timestamp.
+    def style
+      @style || 'f'
+    end
+
+    # Get a string that will allow you to display the time in the Discord client.
+    # @return [String] The timestamp serialized as a string for the Discord client.
+    def to_s
+      OnyxCord.timestamp(@time, @style)
+    end
+
+    # @!visibility private
+    def inspect
+      "<TimestampMarkdown time=#{@time.to_i} style=\"#{style}\">"
+    end
+
+    # @!method short_time?
+    #   @return [true, false] whether or not the timestamp is displayed in a format such as `16:20`.
+    # @!method long_time?
+    #   @return [true, false] whether or not the timestamp is displayed in a format such as `16:20:30`.
+    # @!method short_date?
+    #   @return [true, false] whether or not the timestamp is displayed in a format such as `20/04/2021`.
+    # @!method long_date?
+    #   @return [true, false] whether or not the timestamp is displayed in a format such as `20 April 2021`.
+    # @!method short_datetime?
+    #   @return [true, false] whether or not the timestamp is displayed in a format such as `20 April 2021 16:20`.
+    # @!method long_datetime?
+    #   @return [true, false] whether or not the timestamp is displayed in a format such as `Tuesday, 20 April 2021 16:20`.
+    # @!method relative?
+    #   @return [true, false] whether or not the timestamp is displayed in a format such as `2 months ago`.
+    # @!method simple_datetime?
+    #   @return [true, false] whether or not the timestamp is displayed in a format such as `20/04/2021, 16:20`.
+    # @!method medium_datetime?
+    #   @return [true, false] whether or not the timestamp is displayed in a format such as ` 20/04/2021, 16:20:30`.
+    STYLES.each do |name, value|
+      define_method("#{name}?") do
+        style == value
+      end
+    end
+  end
+end

data/lib/onyxcord/data/user.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # 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
+
+    # @return [true, false] whether the user is an offical Discord System user (part of the urgent message system).
+    attr_reader :system_account
+    alias_method :system_account?, :system_account
+
+    # @return [AvatarDecoration, nil] the current user's avatar decoration, or nil if the user doesn't have one.
+    attr_reader :avatar_decoration
+
+    # @return [Collectibles] the collectibles that this user has collected.
+    attr_reader :collectibles
+
+    # @return [PrimaryServer, nil] the server tag the user has adopted, or nil if the user doesn't have one displayed.
+    attr_reader :primary_server
+    alias_method :server_tag, :primary_server
+
+    # 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.anybits?(value)
+      end
+    end
+
+    # Utility function to get a user's banner URL.
+    # @param format [String, nil] If `nil`, the URL will default to `png` for static banners and will detect if the user has a `gif` banner.
+    # You can otherwise specify one of `webp`, `jpg`, `png`, or `gif` to override this.
+    # @return [String, nil] the URL to the banner image or nil if the user doesn't have one.
+    def banner_url(format = nil)
+      API::User.banner_url(@id, banner_id, format) if banner_id
+    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']
+      @activities = OnyxCord::ActivitySet.new
+      @public_flags = data['public_flags'] || 0
+      @bot_account = data['bot'] || false
+      @webhook_account = data['_webhook'] || false
+
+      @status = :offline
+      @client_status = process_client_status(data['client_status'])
+      @banner_id = data['banner']
+      @system_account = data['system'] || false
+      @avatar_decoration = process_avatar_decoration(data['avatar_decoration_data'])
+      @collectibles = Collectibles.new(data['collectibles'] || {}, bot)
+
+      @primary_server = process_primary_server(data['primary_guild'] || {})
+    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
+
+    # @return [String, nil] the ID of this user's current banner, can be used to generate a banner URL.
+    # @see #banner_url
+    def banner_id
+      @banner_id ||= JSON.parse(API::User.resolve(@bot.token, @id))['banner']
+    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 avatar_decoration
+    # @note For internal use only.
+    # @!visibility private
+    def update_avatar_decoration(decoration)
+      @avatar_decoration = process_avatar_decoration(decoration)
+    end
+
+    # Set the user's collectibles
+    # @note For internal use only.
+    # @!visibility private
+    def update_collectibles(collectibles)
+      @collectibles = Collectibles.new(collectibles || {}, @bot)
+    end
+
+    # Set the user's primary server
+    # @note For internal use only.
+    # @!visibility private
+    def update_primary_server(server)
+      @primary_server = process_primary_server(server || {})
+    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 = OnyxCord::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, OnyxCord::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!(OnyxCord::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
+
+    # @!visibility private
+    def process_avatar_decoration(decoration)
+      decoration ? AvatarDecoration.new(decoration, @bot) : nil
+    end
+
+    # @!visibility private
+    def process_primary_server(server)
+      PrimaryServer.new(server, @bot) if server['identity_enabled']
+    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