onyxcord 1.1.0

data/lib/onyxcord/data/voice_region.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # Voice regions are the locations of servers that handle voice communication in Discord
+  class VoiceRegion
+    # @return [String] unique ID for the region
+    attr_reader :id
+    alias_method :to_s, :id
+
+    # @return [String] name of the region
+    attr_reader :name
+
+    # @return [String] an example hostname for the region
+    attr_reader :sample_hostname
+
+    # @return [Integer] an example port for the region
+    attr_reader :sample_port
+
+    # @return [true, false] if this is a VIP-only server
+    attr_reader :vip
+
+    # @return [true, false] if this voice server is the closest to the client
+    attr_reader :optimal
+
+    # @return [true, false] whether this is a deprecated voice region (avoid switching to these)
+    attr_reader :deprecated
+
+    # @return [true, false] whether this is a custom voice region (used for events/etc)
+    attr_reader :custom
+
+    # @!visibility private
+    def initialize(data)
+      @id = data['id']
+
+      @name = data['name']
+
+      @sample_hostname = data['sample_hostname']
+      @sample_port = data['sample_port']
+
+      @vip = data['vip']
+      @optimal = data['optimal']
+      @deprecated = data['deprecated']
+      @custom = data['custom']
+    end
+  end
+end

data/lib/onyxcord/data/voice_state.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # A voice state represents the state of a member's connection to a voice channel. It includes data like the voice
+  # channel the member is connected to and mute/deaf flags.
+  class VoiceState
+    # @return [Integer] the ID of the user whose voice state is represented by this object.
+    attr_reader :user_id
+
+    # @return [true, false] whether this voice state's member is muted server-wide.
+    attr_reader :mute
+
+    # @return [true, false] whether this voice state's member is deafened server-wide.
+    attr_reader :deaf
+
+    # @return [true, false] whether this voice state's member has muted themselves.
+    attr_reader :self_mute
+
+    # @return [true, false] whether this voice state's member has deafened themselves.
+    attr_reader :self_deaf
+
+    # @return [Channel] the voice channel this voice state's member is in.
+    attr_reader :voice_channel
+
+    # @!visibility private
+    def initialize(user_id)
+      @user_id = user_id
+    end
+
+    # Update this voice state with new data from Discord
+    # @note For internal use only.
+    # @!visibility private
+    def update(channel, mute, deaf, self_mute, self_deaf)
+      @voice_channel = channel
+      @mute = mute
+      @deaf = deaf
+      @self_mute = self_mute
+      @self_deaf = self_deaf
+    end
+  end
+end

data/lib/onyxcord/data/webhook.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require 'onyxcord/webhooks/builder'
+require 'onyxcord/webhooks/view'
+require 'onyxcord/message_components'
+
+module OnyxCord
+  # A webhook on a server channel
+  class Webhook
+    include IDObject
+
+    # @return [String] the webhook name.
+    attr_reader :name
+
+    # @return [Channel] the channel that the webhook is currently connected to.
+    attr_reader :channel
+
+    # @return [Server] the server that the webhook is currently connected to.
+    attr_reader :server
+
+    # @return [String, nil] the webhook's token, if this is an Incoming Webhook.
+    attr_reader :token
+
+    # @return [String] the webhook's avatar id.
+    attr_reader :avatar
+
+    # @return [Integer] the webhook's type (1: Incoming, 2: Channel Follower)
+    attr_reader :type
+
+    # Gets the user object of the creator of the webhook. May be limited to username, discriminator,
+    # ID and avatar if the bot cannot reach the owner
+    # @return [Member, User, nil] the user object of the owner or nil if the webhook was requested using the token.
+    attr_reader :owner
+
+    # @!visibility private
+    def initialize(data, bot)
+      @bot = bot
+
+      @name = data['name']
+      @id = data['id'].to_i
+      @channel = bot.channel(data['channel_id'])
+      @server = @channel.server
+      @token = data['token']
+      @avatar = data['avatar']
+      @type = data['type']
+
+      # Will not exist if the data was requested through a webhook token
+      return unless data['user']
+
+      @owner = @server.member(data['user']['id'].to_i)
+      return if @owner
+
+      OnyxCord::LOGGER.debug("Member with ID #{data['user']['id']} not cached (possibly left the server).")
+      @owner = @bot.ensure_user(data['user'])
+    end
+
+    # Sets the webhook's avatar.
+    # @param avatar [String, #read] The new avatar, in base64-encoded JPG format.
+    def avatar=(avatar)
+      update_webhook(avatar: avatarise(avatar))
+    end
+
+    # Deletes the webhook's avatar.
+    def delete_avatar
+      update_webhook(avatar: nil)
+    end
+
+    # Sets the webhook's channel
+    # @param channel [Channel, String, Integer] The channel the webhook should use.
+    def channel=(channel)
+      update_webhook(channel_id: channel.resolve_id)
+    end
+
+    # Sets the webhook's name.
+    # @param name [String] The webhook's new name.
+    def name=(name)
+      update_webhook(name: name)
+    end
+
+    # Updates the webhook if you need to edit more than 1 attribute.
+    # @param data [Hash] the data to update.
+    # @option data [String, #read, nil] :avatar The new avatar, in base64-encoded JPG format, or nil to delete the avatar.
+    # @option data [Channel, String, Integer] :channel The channel the webhook should use.
+    # @option data [String] :name The webhook's new name.
+    # @option data [String] :reason The reason for the webhook changes.
+    def update(data)
+      # Only pass a value for avatar if the key is defined as sending nil will delete the
+      data[:avatar] = avatarise(data[:avatar]) if data.key?(:avatar)
+      data[:channel_id] = data[:channel]&.resolve_id
+      data.delete(:channel)
+      update_webhook(**data)
+    end
+
+    # Deletes the webhook.
+    # @param reason [String] The reason the webhook is being deleted.
+    def delete(reason = nil)
+      if token?
+        API::Webhook.token_delete_webhook(@token, @id, reason)
+      else
+        API::Webhook.delete_webhook(@bot.token, @id, reason)
+      end
+    end
+
+    # Execute a webhook.
+    # @param content [String] The content of the message. May be 2000 characters long at most.
+    # @param username [String] The username the webhook will display as. If this is not set, the default username set in the webhook's settings.
+    # @param avatar_url [String] The URL of an image file to be used as an avatar. If this is not set, the default avatar from the webhook's
+    # @param tts [true, false] Whether this message should use TTS or not. By default, it doesn't.
+    # @param file [File] File to be sent together with the message. Mutually exclusive with embeds; a webhook message can contain
+    #   either a file to be sent or embeds.
+    # @param embeds [Array<Webhooks::Embed, Hash>] Embeds to attach to this message.
+    # @param allowed_mentions [AllowedMentions, Hash] Mentions that are allowed to ping in the `content`.
+    # @param wait [true, false] Whether Discord should wait for the message to be successfully received by clients, or
+    #   whether it should return immediately after sending the message. If `true` a {Message} object will be returned.
+    # @yield [builder] Gives the builder to the block to add additional steps, or to do the entire building process.
+    # @yieldparam builder [Builder] The builder given as a parameter which is used as the initial step to start from.
+    # @example Execute the webhook with kwargs
+    #   client.execute(
+    #     content: 'Testing',
+    #     username: 'onyxcord',
+    #     embeds: [
+    #       { timestamp: Time.now.iso8601, title: 'testing', image: { url: 'https://i.imgur.com/PcMltU7.jpg' } }
+    #     ])
+    # @example Execute the webhook with an already existing builder
+    #   builder = OnyxCord::Webhooks::Builder.new # ...
+    #   client.execute(builder)
+    # @example Execute the webhook by building a new message
+    #   client.execute do |builder|
+    #     builder.content = 'Testing'
+    #     builder.username = 'onyxcord'
+    #     builder.add_embed do |embed|
+    #       embed.timestamp = Time.now
+    #       embed.title = 'Testing'
+    #       embed.image = OnyxCord::Webhooks::EmbedImage.new(url: 'https://i.imgur.com/PcMltU7.jpg')
+    #     end
+    #   end
+    # @return [Message, nil] If `wait` is `true`, a {Message} will be returned. Otherwise this method will return `nil`.
+    # @note This is only available to webhooks with publically exposed tokens. This excludes channel follow webhooks and webhooks retrieved
+    #   via the audit log.
+    def execute(content: nil, username: nil, avatar_url: nil, tts: nil, file: nil, embeds: nil, allowed_mentions: nil, wait: true, builder: nil, components: nil, flags: 0, has_components: false, components_v2: false)
+      raise OnyxCord::Errors::UnauthorizedWebhook unless @token
+
+      params = { content: content, username: username, avatar_url: avatar_url, tts: tts, file: file, embeds: embeds, allowed_mentions: allowed_mentions }
+
+      builder ||= Webhooks::Builder.new
+      view = Webhooks::View.new
+
+      yield(builder, view) if block_given?
+
+      data = builder.to_json_hash.merge(params.compact)
+      components ||= view
+      flags = OnyxCord::MessageComponents.apply_v2_flag(flags, components, force: has_components || components_v2)
+
+      resp = API::Webhook.token_execute_webhook(@token, @id, wait, data[:content], data[:username], data[:avatar_url], data[:tts], data[:file], data[:embeds], data[:allowed_mentions], flags, components.to_a)
+
+      Message.new(JSON.parse(resp), @bot) if wait
+    end
+
+    # Delete a message created by this webhook.
+    # @param message [Message, String, Integer] The ID of the message to delete.
+    def delete_message(message)
+      raise OnyxCord::Errors::UnauthorizedWebhook unless @token
+
+      API::Webhook.token_delete_message(@token, @id, message.resolve_id)
+    end
+
+    # Edit a message created by this webhook.
+    # @param message [Message, String, Integer] The ID of the message to edit.
+    # @param content [String] The content of the message. May be 2000 characters long at most.
+    # @param embeds [Array<Webhooks::Embed, Hash>] Embeds to be attached to the message.
+    # @param allowed_mentions [AllowedMentions, Hash] Mentions that are allowed to ping in the `content`.
+    # @param builder [Builder, nil] The builder to start out with, or nil if one should be created anew.
+    # @yield [builder] Gives the builder to the block to add additional steps, or to do the entire building process.
+    # @yieldparam builder [Webhooks::Builder] The builder given as a parameter which is used as the initial step to start from.
+    # @return [Message] The updated message.
+    # @param components [View, Array<Hash>] Interaction components to associate with this message.
+    # @note When editing `allowed_mentions`, it will update visually in the client but not alert the user with a notification.
+    def edit_message(message, content: nil, embeds: nil, allowed_mentions: nil, builder: nil, components: nil, flags: 0, has_components: false, components_v2: false)
+      raise OnyxCord::Errors::UnauthorizedWebhook unless @token
+
+      params = { content: content, embeds: embeds, allowed_mentions: allowed_mentions }.compact
+
+      builder ||= Webhooks::Builder.new
+      view ||= Webhooks::View.new
+
+      yield(builder, view) if block_given?
+
+      data = builder.to_json_hash.merge(params.compact)
+      components ||= view
+      flags = OnyxCord::MessageComponents.apply_v2_flag(flags, components, force: has_components || components_v2)
+
+      resp = API::Webhook.token_edit_message(@token, @id, message.resolve_id, data[:content], data[:embeds], data[:allowed_mentions], components.to_a, nil, flags)
+      Message.new(JSON.parse(resp), @bot)
+    end
+
+    # Utility function to get a webhook's avatar URL.
+    # @return [String] the URL to the avatar image
+    def avatar_url
+      return API::User.default_avatar(@id) unless @avatar
+
+      API::User.avatar_url(@id, @avatar)
+    end
+
+    # The `inspect` method is overwritten to give more useful output.
+    def inspect
+      "<Webhook name=#{@name} id=#{@id}>"
+    end
+
+    # Utility function to know if the webhook was requested through a webhook token, rather than auth.
+    # @return [true, false] whether the webhook was requested by token or not.
+    def token?
+      @owner.nil?
+    end
+
+    private
+
+    def avatarise(avatar)
+      avatar.respond_to?(:read) ? OnyxCord.encode64(avatar) : avatar
+    end
+
+    def update_internal(data)
+      @name = data['name']
+      @avatar_id = data['avatar']
+      @channel = @bot.channel(data['channel_id'])
+    end
+
+    def update_webhook(new_data)
+      reason = new_data.delete(:reason)
+      data = JSON.parse(if token?
+                          API::Webhook.token_update_webhook(@token, @id, new_data, reason)
+                        else
+                          API::Webhook.update_webhook(@bot.token, @id, new_data, reason)
+                        end)
+      # Only update cache if API call worked
+      update_internal(data) if data['name']
+    end
+  end
+end

data/lib/onyxcord/data.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'onyxcord/allowed_mentions'
+require 'onyxcord/permissions'
+require 'onyxcord/id_object'
+require 'onyxcord/colour_rgb'
+require 'onyxcord/errors'
+require 'onyxcord/api'
+require 'onyxcord/api/channel'
+require 'onyxcord/api/server'
+require 'onyxcord/api/invite'
+require 'onyxcord/api/user'
+require 'onyxcord/api/webhook'
+require 'onyxcord/webhooks/embeds'
+require 'onyxcord/webhooks/view'
+require 'onyxcord/paginator'
+require 'time'
+require 'base64'
+
+require 'onyxcord/data/activity'
+require 'onyxcord/data/application'
+require 'onyxcord/data/user'
+require 'onyxcord/data/voice_state'
+require 'onyxcord/data/voice_region'
+require 'onyxcord/data/member'
+require 'onyxcord/data/recipient'
+require 'onyxcord/data/profile'
+require 'onyxcord/data/role'
+require 'onyxcord/data/invite'
+require 'onyxcord/data/overwrite'
+require 'onyxcord/data/channel'
+require 'onyxcord/data/embed'
+require 'onyxcord/data/attachment'
+require 'onyxcord/data/message'
+require 'onyxcord/data/reaction'
+require 'onyxcord/data/emoji'
+require 'onyxcord/data/integration'
+require 'onyxcord/data/server'
+require 'onyxcord/data/webhook'
+require 'onyxcord/data/audit_logs'
+require 'onyxcord/data/interaction'
+require 'onyxcord/data/component'
+require 'onyxcord/data/avatar_decoration'
+require 'onyxcord/data/collectibles'
+require 'onyxcord/data/primary_server'
+require 'onyxcord/data/server_preview'
+require 'onyxcord/data/call'
+require 'onyxcord/data/snapshot'
+require 'onyxcord/data/role_subscription'
+require 'onyxcord/data/message_activity'
+require 'onyxcord/data/team'
+require 'onyxcord/data/install_params'
+require 'onyxcord/data/role_connection_data'
+require 'onyxcord/data/channel_tag'
+require 'onyxcord/data/timestamp'
+require 'onyxcord/data/scheduled_event'
+require 'onyxcord/data/poll'

data/lib/onyxcord/errors.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module OnyxCord
+  # Custom errors raised in various places
+  module Errors
+    # Raised when authentication data is invalid or incorrect.
+    class InvalidAuthenticationError < RuntimeError
+      # Default message for this exception
+      def message
+        'User login failed due to an invalid email or password!'
+      end
+    end
+
+    # Raised when a message is over the character limit
+    class MessageTooLong < RuntimeError; end
+
+    # Raised when the bot can't do something because its permissions on the server are insufficient
+    class NoPermission < RuntimeError; end
+
+    # Raised when the bot gets a HTTP 502 error, which is usually caused by Cloudflare.
+    class CloudflareError < RuntimeError; end
+
+    # Raised when using a webhook method without an associated token.
+    class UnauthorizedWebhook < RuntimeError; end
+
+    # Generic class for errors denoted by API error codes
+    class CodeError < RuntimeError
+      class << self
+        # @return [Integer] The error code represented by this error class.
+        attr_reader :code
+      end
+
+      # Create a new error with a particular message (the code should be defined by the class instance variable)
+      # @param message [String] the message to use
+      # @param errors [Hash] API errors
+      def initialize(message, errors = nil)
+        @message = message
+
+        @errors = errors ? flatten_errors(errors) : []
+      end
+
+      # @return [Integer] The error code represented by this error.
+      def code
+        self.class.code
+      end
+
+      # @return [String] A message including the message and flattened errors.
+      def full_message(*)
+        error_list = @errors.collect { |err| "\t- #{err}" }
+
+        "#{@message}\n#{error_list.join("\n")}"
+      end
+
+      # @return [String] This error's represented message
+      attr_reader :message
+
+      # @return [Hash] More precise errors
+      attr_reader :errors
+
+      private
+
+      # @!visibility hidden
+      # Flattens errors into a more easily read format.
+      # @example Flattening errors of a bad field
+      #   flatten_errors(data['errors'])
+      #   # => ["embed.fields[0].name: This field is required", "embed.fields[0].value: This field is required"]
+      def flatten_errors(err, prev_key = nil)
+        err.collect do |key, sub_err|
+          if prev_key
+            key = /\A\d+\Z/.match?(key) ? "#{prev_key}[#{key}]" : "#{prev_key}.#{key}"
+          end
+
+          if (errs = sub_err['_errors'])
+            "#{key}: #{errs.map { |e| e['message'] }.join(' ')}"
+          elsif sub_err['message'] || sub_err['code']
+            "#{"#{sub_err['code']}: " if sub_err['code']}#{err_msg}"
+          elsif sub_err.is_a? String
+            sub_err
+          else
+            flatten_errors(sub_err, key)
+          end
+        end.flatten
+      end
+    end
+
+    # Create a new code error class
+    # rubocop:disable Naming/MethodName
+    def self.Code(code)
+      classy = Class.new(CodeError)
+      classy.instance_variable_set(:@code, code)
+
+      @code_classes ||= {}
+      @code_classes[code] = classy
+
+      classy
+    end
+    # rubocop:enable Naming/MethodName
+
+    # @param code [Integer] The code to check
+    # @return [Class] the error class for the given code
+    def self.error_class_for(code)
+      @code_classes[code] || Code(code)
+    end
+
+    # Used when Discord doesn't provide a more specific code
+    UnknownError = Code(0)
+
+    # Unknown Account
+    UnknownAccount = Code(10_001)
+
+    # Unknown Application
+    UnknownApplication = Code(10_002)
+
+    # Unknown Channel
+    UnknownChannel = Code(10_003)
+
+    # Unknown Server
+    UnknownServer = Code(10_004)
+
+    # Unknown Integration
+    UnknownIntegration = Code(10_005)
+
+    # Unknown Invite
+    UnknownInvite = Code(10_006)
+
+    # Unknown Member
+    UnknownMember = Code(10_007)
+
+    # Unknown Message
+    UnknownMessage = Code(10_008)
+
+    # Unknown Overwrite
+    UnknownOverwrite = Code(10_009)
+
+    # Unknown Provider
+    UnknownProvider = Code(10_010)
+
+    # Unknown Role
+    UnknownRole = Code(10_011)
+
+    # Unknown Token
+    UnknownToken = Code(10_012)
+
+    # Unknown User
+    UnknownUser = Code(10_013)
+
+    # Unknown Emoji
+    UnknownEmoji = Code(10_014)
+
+    # Bots cannot use this endpoint
+    EndpointNotForBots = Code(20_001)
+
+    # Only bots can use this endpoint
+    EndpointOnlyForBots = Code(20_002)
+
+    # Maximum number of servers reached (100)
+    ServerLimitReached = Code(30_001)
+
+    # Maximum number of friends reached (1000)
+    FriendLimitReached = Code(30_002)
+
+    # Maximum number of pins reached (50)
+    PinLimitReached = Code(30_003)
+
+    # Maximum number of guild roles reached (250)
+    RoleLimitReached = Code(30_005)
+
+    # Too many reactions
+    ReactionLimitReached = Code(30_010)
+
+    # Maximum number of guild channels reached (500)
+    ChannelLimitReached = Code(30_013)
+
+    # Unauthorized
+    Unauthorized = Unauthorised = Code(40_001)
+
+    # Unable to bulk ban any users
+    UnableToBulkBanUsers = Code(500_000)
+
+    # Missing Access
+    MissingAccess = Code(50_001)
+
+    # Invalid Account Type
+    InvalidAccountType = Code(50_002)
+
+    # Cannot execute action on a DM channel
+    InvalidActionForDM = Code(50_003)
+
+    # Embed Disabled
+    EmbedDisabled = Code(50_004)
+
+    # Cannot edit a message authored by another user
+    MessageAuthoredByOtherUser = Code(50_005)
+
+    # Cannot send an empty message
+    MessageEmpty = Code(50_006)
+
+    # Cannot send messages to this user
+    NoMessagesToUser = Code(50_007)
+
+    # Cannot send messages in a voice channel
+    NoMessagesInVoiceChannel = Code(50_008)
+
+    # Channel verification level is too high
+    VerificationLevelTooHigh = Code(50_009)
+
+    # OAuth2 application does not have a bot
+    NoBotForApplication = Code(50_010)
+
+    # OAuth2 application limit reached
+    ApplicationLimitReached = Code(50_011)
+
+    # Invalid OAuth State
+    InvalidOAuthState = Code(50_012)
+
+    # Missing Permissions
+    MissingPermissions = Code(50_013)
+
+    # Invalid authentication token
+    InvalidAuthToken = Code(50_014)
+
+    # Note is too long
+    NoteTooLong = Code(50_015)
+
+    # Provided too few or too many messages to delete. Must provide at least 2 and fewer than 100 messages to delete.
+    InvalidBulkDeleteCount = Code(50_016)
+
+    # A message can only be pinned to the channel it was sent in
+    CannotPinInDifferentChannel = Code(50_019)
+
+    # Cannot execute action on a system message
+    InvalidActionForSystemMessage = Code(50_021)
+
+    # A message provided was too old to bulk delete
+    MessageTooOld = Code(50_034)
+
+    # Invalid Form Body
+    InvalidFormBody = Code(50_035)
+
+    # An invite was accepted to a guild the application's bot is not in
+    MissingBotMember = Code(50_036)
+
+    # Reaction Blocked
+    ReactionBlocked = Code(90_001)
+  end
+end