rubycord 1.0.0

data/lib/rubycord/id_object.rb

@@ -0,0 +1,37 @@
+module Rubycord
+  # Mixin for objects that have IDs
+  module IDObject
+    # @return [Integer] the ID which uniquely identifies this object across Discord.
+    attr_reader :id
+    alias_method :resolve_id, :id
+    alias_method :hash, :id
+
+    # ID based comparison
+    def ==(other)
+      Rubycord.id_compare(@id, other)
+    end
+
+    alias_method :eql?, :==
+
+    # Estimates the time this object was generated on based on the beginning of the ID. This is fairly accurate but
+    # shouldn't be relied on as Discord might change its algorithm at any time
+    # @return [Time] when this object was created at
+    def creation_time
+      # Milliseconds
+      ms = (@id >> 22) + DISCORD_EPOCH
+      Time.at(ms / 1000.0)
+    end
+
+    # Creates an artificial snowflake at the given point in time. Useful for comparing against.
+    # @param time [Time] The time the snowflake should represent.
+    # @return [Integer] a snowflake with the timestamp data as the given time
+    def self.synthesise(time)
+      ms = (time.to_f * 1000).to_i
+      (ms - DISCORD_EPOCH) << 22
+    end
+
+    class << self
+      alias_method :synthesize, :synthesise
+    end
+  end
+end

data/lib/rubycord/light/data.rb

@@ -0,0 +1,60 @@
+require "rubycord/data"
+
+module Rubycord::Light
+  # Represents the bot account used for the light bot, but without any methods to change anything.
+  class LightProfile
+    include Rubycord::IDObject
+    include Rubycord::UserAttributes
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+
+      @username = data["username"]
+      @id = data["id"].to_i
+      @discriminator = data["discriminator"]
+      @avatar_id = data["avatar"]
+
+      @bot_account = false
+      @bot_account = true if data["bot"]
+
+      @verified = data["verified"]
+
+      @email = data["email"]
+    end
+  end
+
+  # A server that only has an icon, a name, and an ID associated with it, like for example an integration's server.
+  class UltraLightServer
+    include Rubycord::IDObject
+    include Rubycord::ServerAttributes
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+
+      @id = data["id"].to_i
+
+      @name = data["name"]
+      @icon_id = data["icon"]
+    end
+  end
+
+  # Represents a light server which only has a fraction of the properties of any other server.
+  class LightServer < UltraLightServer
+    # @return [true, false] whether or not the LightBot this server belongs to is the owner of the server.
+    attr_reader :bot_is_owner
+    alias_method :bot_is_owner?, :bot_is_owner
+
+    # @return [Rubycord::Permissions] the permissions the LightBot has on this server
+    attr_reader :bot_permissions
+
+    # @!visibility private
+    def initialize(data, bot)
+      super
+
+      @bot_is_owner = data["owner"]
+      @bot_permissions = Rubycord::Permissions.new(data["permissions"])
+    end
+  end
+end

data/lib/rubycord/light/integrations.rb

@@ -0,0 +1,71 @@
+require "rubycord/data"
+require "rubycord/light/data"
+
+module Rubycord::Light
+  # A connection of your Discord account to a particular other service (currently, Twitch and YouTube)
+  class Connection
+    # @return [Symbol] what type of connection this is (either :twitch or :youtube currently)
+    attr_reader :type
+
+    # @return [true, false] whether this connection is revoked
+    attr_reader :revoked
+    alias_method :revoked?, :revoked
+
+    # @return [String] the name of the connected account
+    attr_reader :name
+
+    # @return [String] the ID of the connected account
+    attr_reader :id
+
+    # @return [Array<Integration>] the integrations associated with this connection
+    attr_reader :integrations
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+
+      @revoked = data["revoked"]
+      @type = data["type"].to_sym
+      @name = data["name"]
+      @id = data["id"]
+
+      @integrations = data["integrations"].map { |e| Integration.new(e, self, bot) }
+    end
+  end
+
+  # An integration of a connection into a particular server, for example being a member of a subscriber-only Twitch
+  # server.
+  class Integration
+    include Rubycord::IDObject
+
+    # @return [UltraLightServer] the server associated with this integration
+    attr_reader :server
+
+    # @note The connection returned by this method will have no integrations itself, as Discord doesn't provide that
+    #   data. Also, it will always be considered not revoked.
+    # @return [Connection] the server's underlying connection (for a Twitch subscriber-only server, it would be the
+    #   Twitch account connection of the server owner).
+    attr_reader :server_connection
+
+    # @return [Connection] the connection integrated with the server (i.e. your connection)
+    attr_reader :integrated_connection
+
+    # @!visibility private
+    def initialize(data, integrated, bot)
+      @bot = bot
+      @integrated_connection = integrated
+
+      @server = UltraLightServer.new(data["guild"], bot)
+
+      # Restructure the given data so we can reuse the Connection initializer
+      restructured = {}
+
+      restructured["type"] = data["type"]
+      restructured["id"] = data["account"]["id"]
+      restructured["name"] = data["account"]["name"]
+      restructured["integrations"] = []
+
+      @server_connection = Connection.new(restructured, bot)
+    end
+  end
+end

data/lib/rubycord/light/light_bot.rb

@@ -0,0 +1,56 @@
+require "rubycord/api"
+require "rubycord/api/invite"
+require "rubycord/api/user"
+require "rubycord/light/data"
+require "rubycord/light/integrations"
+
+# This module contains classes to allow connections to bots without a connection to the gateway socket, i.e. bots
+# that only use the REST part of the API.
+module Rubycord::Light
+  # A bot that only uses the REST part of the API. Hierarchically unrelated to the regular {Rubycord::Bot}. Useful to
+  # make applications integrated to Discord over OAuth, for example.
+  class LightBot
+    # Create a new LightBot. This does no networking yet, all networking is done by the methods on this class.
+    # @param token [String] The token that should be used to authenticate to Discord. Can be an OAuth token or a regular
+    #   user account token.
+    def initialize(token)
+      if token.respond_to? :token
+        # Parse AccessTokens from the OAuth2 gem
+        token = token.token
+      end
+
+      unless token.include? "."
+        # Discord user/bot tokens always contain two dots, so if there's none we can assume it's an OAuth token.
+        token = "Bearer #{token}" # OAuth tokens have to be prefixed with 'Bearer' for Discord to be able to use them
+      end
+
+      @token = token
+    end
+
+    # @return [LightProfile] the details of the user this bot is connected to.
+    def profile
+      response = Rubycord::API::User.profile(@token)
+      LightProfile.new(JSON.parse(response), self)
+    end
+
+    # @return [Array<LightServer>] the servers this bot is connected to.
+    def servers
+      response = Rubycord::API::User.servers(@token)
+      JSON.parse(response).map { |e| LightServer.new(e, self) }
+    end
+
+    # Joins a server using an instant invite.
+    # @param code [String] The code part of the invite (for example 0cDvIgU2voWn4BaD if the invite URL is
+    #   https://discord.gg/0cDvIgU2voWn4BaD)
+    def join(code)
+      Rubycord::API::Invite.accept(@token, code)
+    end
+
+    # Gets the connections associated with this account.
+    # @return [Array<Connection>] this account's connections.
+    def connections
+      response = Rubycord::API::User.connections(@token)
+      JSON.parse(response).map { |e| Connection.new(e, self) }
+    end
+  end
+end

data/lib/rubycord/light.rb

@@ -0,0 +1,6 @@
+require "rubycord/light/light_bot"
+
+# This module contains classes to allow connections to bots without a connection to the gateway socket, i.e. bots
+# that only use the REST part of the API.
+module Rubycord::Light
+end

data/lib/rubycord/logger.rb

@@ -0,0 +1,118 @@
+module Rubycord
+  # The format log timestamps should be in, in strftime format
+  LOG_TIMESTAMP_FORMAT = "%Y-%m-%d %H:%M:%S.%L"
+
+  # Logs debug messages
+  class Logger
+    # @return [true, false] whether this logger is in extra-fancy mode!
+    attr_writer :fancy
+
+    # @return [String, nil] The bot token to be redacted or nil if it shouldn't.
+    attr_writer :token
+
+    # @return [Array<IO>, Array<#puts & #flush>] the streams the logger should write to.
+    attr_accessor :streams
+
+    # Creates a new logger.
+    # @param fancy [true, false] Whether this logger uses fancy mode (ANSI escape codes to make the output colourful)
+    # @param streams [Array<IO>, Array<#puts & #flush>] the streams the logger should write to.
+    def initialize(fancy = false, streams = [$stdout])
+      @fancy = fancy
+      self.mode = :normal
+
+      @streams = streams
+    end
+
+    # The modes this logger can have. This is probably useless unless you want to write your own Logger
+    MODES = {
+      debug: {long: "DEBUG", short: "D", format_code: ""},
+      good: {long: "GOOD", short: "✓", format_code: "\u001B[32m"}, # green
+      info: {long: "INFO", short: "i", format_code: ""},
+      warn: {long: "WARN", short: "!", format_code: "\u001B[33m"}, # yellow
+      error: {long: "ERROR", short: "✗", format_code: "\u001B[31m"}, # red
+      out: {long: "OUT", short: "→", format_code: "\u001B[36m"}, # cyan
+      in: {long: "IN", short: "←", format_code: "\u001B[35m"}, # purple
+      ratelimit: {long: "RATELIMIT", short: "R", format_code: "\u001B[41m"} # red background
+    }.freeze
+
+    # The ANSI format code that resets formatting
+    FORMAT_RESET = "\u001B[0m"
+
+    # The ANSI format code that makes something bold
+    FORMAT_BOLD = "\u001B[1m"
+
+    MODES.each do |mode, hash|
+      define_method(mode) do |message|
+        write(message.to_s, hash) if @enabled_modes.include? mode
+      end
+    end
+
+    # Sets the logging mode to :debug
+    # @param value [true, false] Whether debug mode should be on. If it is off the mode will be set to :normal.
+    def debug=(value)
+      self.mode = value ? :debug : :normal
+    end
+
+    # Sets the logging mode
+    # Possible modes are:
+    #  * :debug logs everything
+    #  * :verbose logs everything except for debug messages
+    #  * :normal logs useful information, warnings and errors
+    #  * :quiet only logs warnings and errors
+    #  * :silent logs nothing
+    # @param value [Symbol] What logging mode to use
+    def mode=(value)
+      case value
+      when :debug
+        @enabled_modes = %i[debug good info warn error out in ratelimit]
+      when :verbose
+        @enabled_modes = %i[good info warn error out in ratelimit]
+      when :normal
+        @enabled_modes = %i[info warn error ratelimit]
+      when :quiet
+        @enabled_modes = %i[warn error]
+      when :silent
+        @enabled_modes = %i[]
+      end
+    end
+
+    # Logs an exception to the console.
+    # @param e [Exception] The exception to log.
+    def log_exception(e)
+      error("Exception: #{e.inspect}")
+      e.backtrace.each { |line| error(line) }
+    end
+
+    private
+
+    def write(message, mode)
+      thread_name = Thread.current[:rubycord_name]
+      timestamp = Time.now.strftime(LOG_TIMESTAMP_FORMAT)
+
+      # Redact token if set
+      log = if @token && @token != ""
+        message.to_s.gsub(@token, "REDACTED_TOKEN")
+      else
+        message.to_s
+      end
+
+      @streams.each do |stream|
+        if @fancy && !stream.is_a?(File)
+          fancy_write(stream, log, mode, thread_name, timestamp)
+        else
+          simple_write(stream, log, mode, thread_name, timestamp)
+        end
+      end
+    end
+
+    def fancy_write(stream, message, mode, thread_name, timestamp)
+      stream.puts "#{timestamp} #{FORMAT_BOLD}#{thread_name.ljust(16)}#{FORMAT_RESET} #{mode[:format_code]}#{mode[:short]}#{FORMAT_RESET} #{message}"
+      stream.flush
+    end
+
+    def simple_write(stream, message, mode, thread_name, timestamp)
+      stream.puts "[#{mode[:long]} : #{thread_name} @ #{timestamp}] #{message}"
+      stream.flush
+    end
+  end
+end

data/lib/rubycord/paginator.rb

@@ -0,0 +1,55 @@
+module Rubycord
+  # Utility class for wrapping paginated endpoints. It is [Enumerable](https://ruby-doc.org/core-2.5.1/Enumerable.html),
+  # similar to an `Array`, so most of the same methods can be used to filter the results of the request
+  # that it wraps. If you simply want an array of all of the results, `#to_a` can be called.
+  class Paginator
+    include Enumerable
+
+    # Creates a new {Paginator}
+    # @param limit [Integer] the maximum number of items to request before stopping
+    # @param direction [:up, :down] the order in which results are returned in
+    # @yield [Array, nil] the last page of results, or nil if this is the first iteration.
+    #   This should be used to request the next page of results.
+    # @yieldreturn [Array] the next page of results
+    def initialize(limit, direction, &block)
+      @count = 0
+      @limit = limit
+      @direction = direction
+      @block = block
+    end
+
+    # Yields every item produced by the wrapped request, until it returns
+    # no more results or the configured `limit` is reached.
+    def each
+      last_page = nil
+      until limit_check
+        page = @block.call(last_page)
+        return if page.empty?
+
+        enumerator = case @direction
+        when :down
+          page.each
+        when :up
+          page.reverse_each
+        end
+
+        enumerator.each do |item|
+          yield item
+          @count += 1
+          break if limit_check
+        end
+
+        last_page = page
+      end
+    end
+
+    private
+
+    # Whether the paginator limit has been exceeded
+    def limit_check
+      return false if @limit.nil?
+
+      @count >= @limit
+    end
+  end
+end

data/lib/rubycord/permissions.rb

@@ -0,0 +1,251 @@
+module Rubycord
+  # List of permissions Discord uses
+  class Permissions
+    # This hash maps bit positions to logical permissions.
+    #   see https://discord.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags
+    FLAGS = {
+      # Bit => Permission # Value
+      0 => :create_instant_invite,                # 1
+      1 => :kick_members,                         # 2
+      2 => :ban_members,                          # 4
+      3 => :administrator,                        # 8
+      4 => :manage_channels,                      # 16
+      5 => :manage_server,                        # 32
+      6 => :add_reactions,                        # 64
+      7 => :view_audit_log,                       # 128
+      8 => :priority_speaker,                     # 256
+      9 => :stream,                               # 512
+      10 => :view_channel,                        # 1024 (which includes reading messages in text channels and joining voice channels)
+      11 => :send_messages,                       # 2048
+      12 => :send_tts_messages,                   # 4096
+      13 => :manage_messages,                     # 8192
+      14 => :embed_links,                         # 16384
+      15 => :attach_files,                        # 32768
+      16 => :read_message_history,                # 65536
+      17 => :mention_everyone,                    # 131072
+      18 => :use_external_emojis,                 # 262144
+      19 => :view_server_insights,                # 524288
+      20 => :connect,                             # 1048576
+      21 => :speak,                               # 2097152
+      22 => :mute_members,                        # 4194304
+      23 => :deafen_members,                      # 8388608
+      24 => :move_members,                        # 16777216
+      25 => :use_vad,                             # 33554432 (voice-activity-detection in a voice channel)
+      26 => :change_nickname,                     # 67108864
+      27 => :manage_nicknames,                    # 134217728
+      28 => :manage_roles,                        # 268435456 (roles & roles permissions)
+      29 => :manage_webhooks,                     # 536870912
+      30 => :manage_server_expressions,           # 1073741824 (emojis, stickers, and soundboard)
+      31 => :use_application_commands,            # 2147483648 (to use application commands, including slash commands and context menu commands)
+      32 => :request_to_speak,                    # 4294967296
+      33 => :manage_events,                       # 8589934592
+      34 => :manage_threads,                      # 17179869184
+      35 => :create_public_threads,               # 34359738368 (for creating public and announcement threads)
+      36 => :create_private_threads,              # 68719476736
+      37 => :use_external_stickers,               # 137438953472
+      38 => :send_messages_in_threads,            # 274877906944
+      39 => :use_embedded_activities,             # 549755813888
+      40 => :moderate_members,                    # 1099511627776
+      41 => :view_creator_monetization_analytics, # 2199023255552
+      42 => :use_soundboard,                      # 4398046511104
+      43 => :create_server_expressions,           # 8796093022208 (for creating emojis, stickers, and soundboard sounds, and editing and deleting)
+      44 => :create_events,                       # 17592186044416 (for creating scheduled events, and editing and deleting those created by the current user)
+      45 => :use_external_sounds,                 # 35184372088832
+      46 => :send_voice_messages,                 # 70368744177664
+      49 => :send_polls,                          # 562949953421312
+      50 => :use_external_apps                    # 1125899906842624
+    }.freeze
+
+    FLAGS.each do |position, flag|
+      attr_reader flag
+
+      define_method :"can_#{flag}=" do |value|
+        new_bits = @bits
+        if value
+          new_bits |= (1 << position)
+        else
+          new_bits &= ~(1 << position)
+        end
+        @writer&.write(new_bits)
+        @bits = new_bits
+        init_vars
+      end
+    end
+
+    alias_method :can_administrate=, :can_administrator=
+    alias_method :administrate, :administrator
+
+    attr_reader :bits
+
+    # Set the raw bitset of this permission object
+    # @param bits [Integer] A number whose binary representation is the desired bitset.
+    def bits=(bits)
+      @bits = bits
+      init_vars
+    end
+
+    # Initialize the instance variables based on the bitset.
+    def init_vars
+      FLAGS.each do |position, flag|
+        flag_set = ((@bits >> position) & 0x1) == 1
+        instance_variable_set :"@#{flag}", flag_set
+      end
+    end
+
+    # Return the corresponding bits for an array of permission flag symbols.
+    # This is a class method that can be used to calculate bits instead
+    # of instancing a new Permissions object.
+    # @example Get the bits for permissions that could allow/deny read messages, connect, and speak
+    #   Permissions.bits [:view_channel, :connect, :speak] #=> 3146752
+    # @param list [Array<Symbol>]
+    # @return [Integer] the computed permissions integer
+    def self.bits(list)
+      value = 0
+
+      FLAGS.each do |position, flag|
+        value += 2**position if list.include? flag
+      end
+
+      value
+    end
+
+    # Create a new Permissions object either as a blank slate to add permissions to (for example for
+    #   {Channel#define_overwrite}) or from existing bit data to read out.
+    # @example Create a permissions object that could allow/deny read messages, connect, and speak by setting flags
+    #   permission = Permissions.new
+    #   permission.can_view_channel = true
+    #   permission.can_connect = true
+    #   permission.can_speak = true
+    # @example Create a permissions object that could allow/deny read messages, connect, and speak by an array of symbols
+    #   Permissions.new [:view_channel, :connect, :speak]
+    # @param bits [String, Integer, Array<Symbol>] The permission bits that should be set from the beginning, or an array of permission flag symbols
+    # @param writer [RoleWriter] The writer that should be used to update data when a permission is set.
+    def initialize(bits = 0, writer = nil)
+      @writer = writer
+
+      @bits = if bits.is_a? Array
+        self.class.bits(bits)
+      else
+        bits.to_i
+      end
+
+      init_vars
+    end
+
+    # Return an array of permission flag symbols for this class's permissions
+    # @example Get the permissions for the bits "9"
+    #   permissions = Permissions.new(9)
+    #   permissions.defined_permissions #=> [:create_instant_invite, :administrator]
+    # @return [Array<Symbol>] the permissions
+    def defined_permissions
+      FLAGS.filter_map { |value, name| (@bits & (1 << value)).positive? ? name : nil }
+    end
+
+    # Comparison based on permission bits
+    def ==(other)
+      false unless other.is_a? Rubycord::Permissions
+      bits == other.bits
+    end
+  end
+
+  # Mixin to calculate resulting permissions from overrides etc.
+  module PermissionCalculator
+    # Checks whether this user can do the particular action, regardless of whether it has the permission defined,
+    # through for example being the server owner or having the Manage Roles permission
+    # @param action [Symbol] The permission that should be checked. See also {Permissions::FLAGS} for a list.
+    # @param channel [Channel, nil] If channel overrides should be checked too, this channel specifies where the overrides should be checked.
+    # @example Check if the bot can send messages to a specific channel in a server.
+    #   bot_profile = bot.profile.on(event.server)
+    #   can_send_messages = bot_profile.permission?(:send_messages, channel)
+    # @return [true, false] whether or not this user has the permission.
+    def permission?(action, channel = nil)
+      # If the member is the server owner, it irrevocably has all permissions.
+      return true if owner?
+
+      # First, check whether the user has Manage Roles defined.
+      # (Coincidentally, Manage Permissions is the same permission as Manage Roles, and a
+      # Manage Permissions deny overwrite will override Manage Roles, so we can just check for
+      # Manage Roles once and call it a day.)
+      return true if defined_permission?(:administrator, channel)
+
+      # Otherwise, defer to defined_permission
+      defined_permission?(action, channel)
+    end
+
+    # Checks whether this user has a particular permission defined (i.e. not implicit, through for example
+    # Manage Roles)
+    # @param action [Symbol] The permission that should be checked. See also {Permissions::FLAGS} for a list.
+    # @param channel [Channel, nil] If channel overrides should be checked too, this channel specifies where the overrides should be checked.
+    # @example Check if a member has the Manage Channels permission defined in the server.
+    #   has_manage_channels = member.defined_permission?(:manage_channels)
+    # @return [true, false] whether or not this user has the permission defined.
+    def defined_permission?(action, channel = nil)
+      # For slash commands we may not have access to the server or role
+      # permissions. In this case we use the permissions given to us by the
+      # interaction. If attempting to check against a specific channel the check
+      # is skipped.
+      return @permissions.__send__(action) if @permissions && channel.nil?
+
+      # Get the permission the user's roles have
+      role_permission = defined_role_permission?(action, channel)
+
+      # Once we have checked the role permission, we have to check the channel overrides for the
+      # specific user
+      user_specific_override = permission_overwrite(action, channel, id) # Use the ID reader as members have no ID instance variable
+
+      # Merge the two permissions - if an override is defined, it has to be allow, otherwise we only care about the role
+      return role_permission unless user_specific_override
+
+      user_specific_override == :allow
+    end
+
+    # Define methods for querying permissions
+    Rubycord::Permissions::FLAGS.each_value do |flag|
+      define_method :"can_#{flag}?" do |channel = nil|
+        permission? flag, channel
+      end
+    end
+
+    alias_method :can_administrate?, :can_administrator?
+
+    private
+
+    def defined_role_permission?(action, channel)
+      roles_to_check = [@server.everyone_role] + roles
+
+      # For each role, check if
+      #   (1) the channel explicitly allows or permits an action for the role and
+      #   (2) if the user is allowed to do the action if the channel doesn't specify
+      roles_to_check.sort_by(&:position).reduce(false) do |can_act, role|
+        # Get the override defined for the role on the channel
+        channel_allow = permission_overwrite(action, channel, role.id)
+        if channel_allow
+          # If the channel has an override, check whether it is an allow - if yes,
+          # the user can act, if not, it can't
+          break true if channel_allow == :allow
+
+          false
+        else
+          # Otherwise defer to the role
+          role.permissions.instance_variable_get(:"@#{action}") || can_act
+        end
+      end
+    end
+
+    def permission_overwrite(action, channel, id)
+      # If no overwrites are defined, or no channel is set, no overwrite will be present
+      return nil unless channel && channel.permission_overwrites[id]
+
+      # Otherwise, check the allow and deny objects
+      allow = channel.permission_overwrites[id].allow
+      deny = channel.permission_overwrites[id].deny
+      if allow.instance_variable_get(:"@#{action}")
+        :allow
+      elsif deny.instance_variable_get(:"@#{action}")
+        :deny
+      end
+
+      # If there's no variable defined, nil will implicitly be returned
+    end
+  end
+end

data/lib/rubycord/version.rb

@@ -0,0 +1,5 @@
+# Rubycord and all its functionality, in this case only the version.
+module Rubycord
+  # The current version of rubycord.
+  VERSION = "1.0.0" unless const_defined?(:VERSION)
+end