disrb 0.1.2.2 → 0.1.3

data/lib/disrb.rb

@@ -5,24 +5,77 @@ require 'async'
 require 'async/http/endpoint'
 require 'async/websocket/client'
 require 'faraday'
-require 'disrb/guild'
-require 'disrb/logger'
-require 'disrb/user'
-require 'disrb/message'
+require_relative 'disrb/guild'
+require_relative 'disrb/logger'
+require_relative 'disrb/user'
+require_relative 'disrb/message'
+require_relative 'disrb/application_commands'
+
+# Contains functions related to Discord snowflakes.
+class Snowflake
+  # @!attribute [r] snowflake
+  #  @return [String] 64-bit binary representation of the snowflake as a string
+  # @!attribute [r] discord_epoch_timestamp
+  #  @return [String] binary representation of the discord epoch timestamp
+  #   (milliseconds since the first second of 2015).
+  # @!attribute [r] internal_worker_id
+  #  @return [String] Internal worker ID.
+  # @!attribute [r] internal_process_id
+  #  @return [String] Internal process ID.
+  # @!attribute [r] gen_id_on_process
+  #  @return [String] Nº of the ID generated on the process. This is incremented every time a new snowflake is generated
+  #   on the same process.
+  # @!attribute [r] unix_timestamp
+  #  @return [Integer] Unix timestamp of the snowflake in milliseconds.
+  # @!attribute [r] timestamp
+  #  @return [Time] Timestamp of the snowflake in UTC as a Time object.
+  attr_accessor(:snowflake, :discord_epoch_timestamp, :internal_worker_id, :internal_process_id, :gen_id_on_process,
+                :unix_timestamp, :timestamp)
+
+  # Creates a new Snowflake instance.
+  # @param snowflake [Integer] The snowflake to be used.
+  # @return [Snowflake] Snowflake instance.
+  def initialize(snowflake)
+    @snowflake = snowflake.to_s(2).rjust(64, '0')
+    @discord_epoch_timestamp = snowflake[0..41]
+    @internal_worker_id = snowflake[42..46]
+    @internal_process_id = snowflake[47..51]
+    @gen_id_on_process = snowflake[52..64]
+    @unix_timestamp = snowflake[0..41].to_i(2) + 1_420_070_400_000
+    @timestamp = Time.at((snowflake[0..41].to_i(2) + 1_420_070_400_000) / 1000).utc
+  end
+end
 
-# DiscordApi
-# The class that contains everything that interacts with the Discord API.
+# Class that contains functions that allow interacting with the Discord API.
+# @version 0.1.3
 class DiscordApi
-  attr_accessor(:base_url, :authorization_header, :application_id, :interaction_created, :interaction, :logger)
-
+  # @!attribute [r] base_url
+  #   @return [String] the base URL that is used to access the Discord API. ex: "https://discord.com/api/v10"
+  # @!attribute [r] authorization_header
+  #   @return [String] the authorization header that is used to authenticate requests to the Discord API.
+  # @!attribute [r] application_id
+  #   @return [Integer] the application ID of the bot that has been assigned to the provided authorization token.
+  attr_accessor(:base_url, :authorization_header, :application_id, :logger)
+
+  # Creates a new DiscordApi instance. (required to use most functions)
+  #
+  # @param authorization_token_type [String] The type of authorization token provided by Discord, 'Bot' or 'Bearer'.
+  # @param authorization_token [String] The value of the authorization token provided by Discord.
+  # @param verbosity_level [String, Integer, nil] The verbosity level of the logger.
+  # Set verbosity_level to:
+  # - 'all' or 5 to log all of the below plus debug messages
+  # - 'info', 4 or nil to log all of the below plus info messages [DEFAULT]
+  # - 'warning' or 3 to log all of the below plus warning messages
+  # - 'error' or 2 to log fatal errors and error messages
+  # - 'fatal_error' or 1 to log only fatal errors
+  # - 'none' or 0 for no logging
+  # @return [DiscordApi] DiscordApi instance.
   def initialize(authorization_token_type, authorization_token, verbosity_level = nil)
     @api_version = '10'
     @base_url = "https://discord.com/api/v#{@api_version}"
     @authorization_token_type = authorization_token_type
     @authorization_token = authorization_token
     @authorization_header = "#{authorization_token_type} #{authorization_token}"
-    @interaction_created = false
-    @interaction = {}
     if verbosity_level.nil?
       @verbosity_level = 4
     elsif verbosity_level.is_a?(String)
@@ -66,6 +119,12 @@ class DiscordApi
     end
   end
 
+  # Converts a hash into a valid query string.
+  # @example Convert a hash into a query string
+  #   DiscordApi.handle_query_strings({'key1' => 'value1', 'key2' => 'value2'}) #=> "?key1=value1&key2=value2"
+  # If the hash is empty, it returns an empty string.
+  # @param query_string_hash [Hash] The hash to convert into a query string.
+  # @return [String] The query string.
   def self.handle_query_strings(query_string_hash)
     query_string_array = []
     query_string_hash.each do |key, value|
@@ -81,272 +140,22 @@ class DiscordApi
     query_string_array.join
   end
 
-  def self.handle_snowflake(snowflake)
-    snowflake = snowflake.to_s(2).rjust(64, '0')
-    {
-      discord_epoch_timestamp: snowflake[0..41],
-      internal_worker_id: snowflake[42..46],
-      internal_process_id: snowflake[47..51],
-      gen_id_on_process: snowflake[52..64],
-      unix_timestamp: snowflake[0..41].to_i(2) + 1_420_070_400_000,
-      timestamp: Time.at((snowflake[0..41].to_i(2) + 1_420_070_400_000) / 1000).utc
-    }
-  end
-
-  def create_guild_application_command(guild_id, name, name_localizations: nil, description: nil,
-                                       description_localizations: nil, options: nil, default_member_permissions: nil,
-                                       default_permission: nil, type: nil, nsfw: nil)
-    output = {}
-    output[:name] = name
-    output[:name_localizations] = name_localizations unless name_localizations.nil?
-    output[:description] = description unless description.nil?
-    output[:description_localizations] = description_localizations unless description_localizations.nil?
-    output[:options] = options unless options.nil?
-    output[:default_permission] = default_permission unless default_permission.nil?
-    output[:type] = type unless type.nil?
-    output[:nsfw] = nsfw unless nsfw.nil?
-    output[:default_member_permissions] = default_member_permissions unless default_member_permissions.nil?
-    url = "#{@base_url}/applications/#{@application_id}/guilds/#{guild_id}/commands"
-    data = JSON.generate(output)
-    headers = { 'Authorization': @authorization_header, 'Content-Type': 'application/json' }
-    response = DiscordApi.post(url, data, headers)
-    return response if response.status == 201 || response.status == 200
-
-    @logger.error("Failed to create guild application command in guild with ID #{guild_id}. Response: #{response.body}")
-    response
-  end
-
-  def create_guild_application_commands(application_commands_array)
-    if application_commands_array.is_a?(Array)
-      application_commands_array.each do |parameter_array|
-        if parameter_array.is_a?(Array)
-          create_guild_application_command(*parameter_array)
-        else
-          @logger.error("Invalid parameter array: #{parameter_array}. Expected an array of parameters.")
-        end
-      end
-    else
-      @logger.error("Invalid application commands array: #{application_commands_array}. Expected an array of arrays.")
-    end
-  end
-
-  def create_global_application_command(name, name_localizations: nil, description: nil,
-                                        description_localizations: nil, options: nil,
-                                        default_member_permissions: nil, default_permission: nil,
-                                        integration_types: nil, contexts: nil, type: nil, nsfw: nil)
-    output = {}
-    output[:name] = name
-    output[:name_localizations] = name_localizations unless name_localizations.nil?
-    output[:description] = description unless description.nil?
-    output[:description_localizations] = description_localizations unless description_localizations.nil?
-    output[:options] = options unless options.nil?
-    output[:default_permission] = default_permission unless default_permission.nil?
-    output[:type] = type unless type.nil?
-    output[:nsfw] = nsfw unless nsfw.nil?
-    output[:default_member_permissions] = default_member_permissions unless default_member_permissions.nil?
-    output[:integration_types] = integration_types unless integration_types.nil?
-    output[:contexts] = contexts unless contexts.nil?
-    url = "#{@base_url}/applications/#{@application_id}/commands"
-    data = JSON.generate(output)
-    headers = { 'Authorization': @authorization_header, 'Content-Type': 'application/json' }
-    response = DiscordApi.post(url, data, headers)
-    return response if response.status == 201 || response.status == 200
-
-    @logger.error("Failed to create global application command. Response: #{response.body}")
-    response
-  end
-
-  def create_global_application_commands(application_commands_array)
-    if application_commands_array.is_a?(Array)
-      application_commands_array.each do |parameter_array|
-        if parameter_array.is_a?(Array)
-          create_global_application_command(*parameter_array)
-        else
-          @logger.error("Invalid parameter array: #{parameter_array}. Expected an array of parameters.")
-        end
-      end
-    else
-      @logger.error("Invalid application commands array: #{application_commands_array}. Expected an array of arrays.")
-    end
-  end
-
-  def edit_global_application_command(command_id, name: nil, name_localizations: nil, description: nil,
-                                      description_localizations: nil, options: nil, default_member_permissions: nil,
-                                      default_permission: nil, integration_types: nil, contexts: nil, nsfw: nil)
-    if args[1..].all?(&:nil?)
-      @logger.warn("No modifications provided for global application command with ID #{command_id}. Skipping.")
-      return nil
-    end
-    output = {}
-    output[:name] = name
-    output[:name_localizations] = name_localizations unless name_localizations.nil?
-    output[:description] = description unless description.nil?
-    output[:description_localizations] = description_localizations unless description_localizations.nil?
-    output[:options] = options unless options.nil?
-    output[:default_permission] = default_permission unless default_permission.nil?
-    output[:nsfw] = nsfw unless nsfw.nil?
-    output[:default_member_permissions] = default_member_permissions unless default_member_permissions.nil?
-    output[:integration_types] = integration_types unless integration_types.nil?
-    output[:contexts] = contexts unless contexts.nil?
-    url = "#{@base_url}/applications/#{@application_id}/commands/#{command_id}"
-    data = JSON.generate(output)
-    headers = { 'Authorization': @authorization_header, 'Content-Type': 'application/json' }
-    response = DiscordApi.patch(url, data, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to edit global application command with ID #{command_id}. Response: #{response.body}")
-    response
-  end
-
-  def edit_guild_application_command(guild_id, command_id, name: nil, name_localizations: nil, description: nil,
-                                     description_localizations: nil, options: nil, default_member_permissions: nil,
-                                     default_permission: nil, nsfw: nil)
-    if args[2..].all?(&:nil?)
-      @logger.warn("No modifications provided for guild application command with command ID #{command_id}. Skipping.")
-      return nil
-    end
-    output = {}
-    output[:name] = name
-    output[:name_localizations] = name_localizations unless name_localizations.nil?
-    output[:description] = description unless description.nil?
-    output[:description_localizations] = description_localizations unless description_localizations.nil?
-    output[:options] = options unless options.nil?
-    output[:default_permission] = default_permission unless default_permission.nil?
-    output[:nsfw] = nsfw unless nsfw.nil?
-    output[:default_member_permissions] = default_member_permissions unless default_member_permissions.nil?
-    url = "#{@base_url}/applications/#{@application_id}/guilds/#{guild_id}/commands/#{command_id}"
-    data = JSON.generate(output)
-    headers = { 'Authorization': @authorization_header, 'Content-Type': 'application/json' }
-    response = DiscordApi.patch(url, data, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to edit guild application command with ID #{command_id}. Response: #{response.body}")
-    response
-  end
-
-  def delete_global_application_command(command_id)
-    url = "#{@base_url}/applications/#{@application_id}/commands/#{command_id}"
-    headers = { 'Authorization': @authorization_header }
-    response = DiscordApi.delete(url, headers)
-    return response if response.status == 204
-
-    @logger.error("Failed to delete global application command with ID #{command_id}. Response: #{response.body}")
-    response
-  end
-
-  def delete_guild_application_command(guild_id, command_id)
-    url = "#{@base_url}/applications/#{@application_id}/guilds/#{guild_id}/commands/#{command_id}"
-    headers = { 'Authorization': @authorization_header }
-    response = DiscordApi.delete(url, headers)
-    return response if response.status == 204
-
-    @logger.error("Failed to delete guild application command with ID #{command_id} in guild with ID #{guild_id}. " \
-                  "Response: #{response.body}")
-  end
-
-  def get_guild_application_commands(guild_id, with_localizations: nil)
-    query_string_hash = {}
-    query_string_hash[:with_localizations] = with_localizations unless with_localizations.nil?
-    query_string = DiscordApi.handle_query_strings(query_string_hash)
-    url = "#{@base_url}/applications/#{@application_id}/guilds/#{guild_id}/commands#{query_string}"
-    headers = { 'Authorization': @authorization_header }
-    response = DiscordApi.get(url, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to get guild application commands for guild with ID #{guild_id}. Response: #{response.body}")
-    response
-  end
-
-  def get_global_application_commands(with_localizations: false)
-    query_string_hash = {}
-    query_string_hash[:with_localizations] = with_localizations unless with_localizations.nil?
-    query_string = DiscordApi.handle_query_strings(query_string_hash)
-    url = "#{@base_url}/applications/#{@application_id}/commands#{query_string}"
-    headers = { 'Authorization': @authorization_header }
-    response = DiscordApi.get(url, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to get global application commands. Response: #{response.body}")
-    response
-  end
-
-  def get_global_application_command(command_id)
-    url = "#{@base_url}/applications/#{@application_id}/commands/#{command_id}"
-    headers = { 'Authorization': @authorization_header }
-    response = DiscordApi.get(url, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to get global application command with ID #{command_id}. Response: #{response.body}")
-    response
-  end
-
-  def get_guild_application_command(guild_id, command_id)
-    url = "#{@base_url}/applications/#{@application_id}/guilds/#{guild_id}/commands/#{command_id}"
-    headers = { 'Authorization': @authorization_header }
-    response = DiscordApi.get(url, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to get guild application command with ID #{command_id}. Response: #{response.body}")
-    response
-  end
-
-  def bulk_overwrite_global_application_commands(commands)
-    url = "#{@base_url}/applications/#{@application_id}/commands"
-    data = JSON.generate(commands)
-    headers = { 'Authorization': @authorization_header, 'Content-Type': 'application/json' }
-    response = DiscordApi.put(url, data, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to bulk overwrite global application commands. Response: #{response.body}")
-    response
-  end
-
-  def bulk_overwrite_guild_application_commands(guild_id, commands)
-    url = "#{@base_url}/applications/#{@application_id}/guilds/#{guild_id}/commands"
-    data = JSON.generate(commands)
-    headers = { 'Authorization': @authorization_header, 'Content-Type': 'application/json' }
-    response = DiscordApi.put(url, data, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to bulk overwrite guild application commands in guild with ID #{guild_id}. " \
-                    "Response: #{response.body}")
-    response
-  end
-
-  def get_guild_application_command_permissions(guild_id)
-    url = "#{@base_url}/applications/#{@application_id}/guilds/#{guild_id}/commands/permissions"
-    headers = { 'Authorization': @authorization_header }
-    response = DiscordApi.get(url, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to get guild application command permissions for guild with ID #{guild_id}. " \
-                    "Response: #{response.body}")
-    response
-  end
-
-  def get_application_command_permissions(guild_id, command_id)
-    url = "#{@base_url}/applications/#{@application_id}/guilds/#{guild_id}/commands/#{command_id}/permissions"
-    headers = { 'Authorization': @authorization_header }
-    response = DiscordApi.get(url, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to get appliaction command permissions for command with ID #{command_id} in guild with ID " \
-                    "#{guild_id}. Response: #{response.body}")
-    response
-  end
-
-  def edit_application_command_permissions(guild_id, command_id, permissions)
-    url = "#{@base_url}/applications/#{@application_id}/guilds/#{guild_id}/commands/#{command_id}/permissions"
-    data = JSON.generate(permissions)
-    headers = { 'Authorization': @authorization_header, 'Content-Type': 'application/json' }
-    response = DiscordApi.put(url, data, headers)
-    return response if response.status == 200
-
-    @logger.error("Failed to edit application command permissions for command with ID #{command_id} in guild with ID " \
-                    "#{guild_id}. Response: #{response.body}")
-    response
-  end
-
+  # Connects to the Discord Gateway and identifies/resumes the session.
+  # This establishes a WebSocket connection, performs Identify/Resume flows, sends/receives heartbeats,
+  # and yields gateway events to the provided block.
+  # See https://discord.com/developers/docs/topics/gateway and
+  # https://discord.com/developers/docs/topics/gateway#identify and
+  # https://discord.com/developers/docs/topics/gateway#resume
+  # @param activities [Hash, Array, nil] Activity or list of activities to set in presence.
+  # @param os [String, nil] OS name reported to the Gateway. Host OS if nil.
+  # @param browser [String, nil] Browser/client name reported to the Gateway. "discord.rb" if nil.
+  # @param device [String, nil] Device name reported to the Gateway. "discord.rb" if nil
+  # @param intents [Integer, nil] Bitwise Gateway intents integer.
+  # @param presence_since [Integer, TrueClass, nil] Unix ms timestamp or true for since value in presence.
+  # @param presence_status [String, nil] Presence status (e.g., "online", "idle", "dnd").
+  # @param presence_afk [TrueClass, FalseClass, nil] Whether the client is AFK.
+  # @yield [event] Yields parsed Gateway events to the block if provided.
+  # @return [void]
   def connect_gateway(activities: nil, os: nil, browser: nil, device: nil, intents: nil, presence_since: nil,
                       presence_status: nil, presence_afk: nil, &block)
     if @authorization_token_type == 'Bearer'
@@ -426,6 +235,7 @@ class DiscordApi
     Async do |_task|
       rescue_connection, sequence, resume_gateway_url, session_id = nil
       loop do
+        recieved_ready = false
         url = if rescue_connection.nil?
                 response = DiscordApi.get("#{@base_url}/gateway")
                 if response.status == 200
@@ -439,9 +249,6 @@ class DiscordApi
               end
         endpoint = Async::HTTP::Endpoint.parse(url, alpn_protocols: Async::HTTP::Protocol::HTTP11.names)
         Async::WebSocket::Client.connect(endpoint) do |connection|
-          connection.write JSON.generate({ op: 1, d: nil })
-          connection.flush
-
           if rescue_connection.nil?
             identify = {}
             identify[:op] = 2
@@ -481,50 +288,72 @@ class DiscordApi
 
           loop do
             message = connection.read
+            next if message.nil?
+
+            @logger.debug("Raw gateway message: #{message.buffer}")
             message = JSON.parse(message, symbolize_names: true)
-            @logger.debug(message)
+            @logger.debug("JSON parsed gateway message: #{message}")
 
+            block.call(message)
             case message
             in { op: 10 }
               @logger.info('Received Hello')
               @heartbeat_interval = message[:d][:heartbeat_interval]
-            in { op:  1 }
+            in { op: 1 }
               @logger.info('Received Heartbeat Request')
               connection.write JSON.generate({ op: 1, d: nil })
               connection.flush
             in { op: 11 }
               @logger.info('Received Heartbeat ACK')
-            in { op: 0, t: 'INTERACTION_CREATE' }
-              @logger.info('An interaction was created')
-              sequence = message[:s]
-              block.call(message)
             in { op: 0, t: 'READY' }
               @logger.info('Recieved Ready')
               session_id = message[:d][:session_id]
               resume_gateway_url = message[:d][:resume_gateway_url]
               sequence = message[:s]
+              recieved_ready = true
             in { op: 0 }
               @logger.info('An event was dispatched')
               sequence = message[:s]
             in { op: 7 }
-              rescue_connection = { type: 'reconnect', session_id: session_id, resume_gateway_url: resume_gateway_url,
-                                    sequence: sequence }
-              @logger.warn('Received Reconnect. A rescue will be attempted....')
+              if recieved_ready
+                rescue_connection = { session_id: session_id, resume_gateway_url: resume_gateway_url,
+                                      sequence: sequence }
+                @logger.warn('Received Reconnect. A rescue will be attempted....')
+              else
+                @logger.warn('Received Reconnect. A rescue cannot be attempted.')
+              end
+            in { op: 9 }
+              if message[:d] && recieved_ready
+                rescue_connection = { session_id: session_id, resume_gateway_url: resume_gateway_url,
+                                      sequence: sequence }
+                @logger.warn('Recieved Invalid Session. A rescue will be attempted...')
+              else
+                @logger.warn('Recieved Invalid Session. A rescue cannot be attempted.')
+              end
             else
-              @logger.error('Unimplemented event type')
+              @logger.error("Unimplemented event type with opcode #{message[:op]}")
             end
           end
         end
       rescue Protocol::WebSocket::ClosedError
-        @logger.warn('WebSocket connection closed. Attempting rescue.')
-        if rescue_connection && rescue_connection[:type] == 'reconnect'
-          @logger.info('Rescue possible. Starting...')
-          next
+        @logger.warn('WebSocket connection closed. Attempting reconnect and rescue.')
+        if rescue_connection
+          @logger.info('Rescue possible. Reconnecting and rescuing...')
+        else
+          @logger.info('Rescue not possible. Reconnecting...')
         end
+        next
       end
     end
   end
 
+  # Creates a response to an interaction. Returns 204 No Content by default, or 200 OK with the created message
+  # if `with_response` is true and the response type expects it.
+  # See https://discord.com/developers/docs/interactions/receiving-and-responding#create-interaction-response
+  # @param interaction [Hash] The interaction payload received from the Gateway.
+  # @param response [Hash] The interaction response payload.
+  # @param with_response [TrueClass, FalseClass] Whether to request the created message in the response.
+  # @return [Faraday::Response] The response from the Discord API.
   def respond_interaction(interaction, response, with_response: false)
     query_string_hash = {}
     query_string_hash[:with_response] = with_response
@@ -539,123 +368,92 @@ class DiscordApi
     response
   end
 
-  def self.calculate_permissions_integer(permissions)
-    bitwise_permission_flags = {
-      create_instant_invite: 0x0000000000000001,
-      kick_members: 0x0000000000000002,
-      ban_members: 0x0000000000000004,
-      administrator: 0x0000000000000008,
-      manage_channels: 0x0000000000000010,
-      manage_guild: 0x0000000000000020,
-      add_reactions: 0x0000000000000040,
-      view_audit_log: 0x0000000000000080,
-      priority_speaker: 0x0000000000000100,
-      stream: 0x0000000000000200,
-      view_channel: 0x0000000000000400,
-      send_messages: 0x0000000000000800,
-      send_tts_messages: 0x0000000000001000,
-      manage_messages: 0x0000000000002000,
-      embed_links: 0x0000000000004000,
-      attach_files: 0x0000000000008000,
-      read_message_history: 0x0000000000010000,
-      mention_everyone: 0x0000000000020000,
-      use_external_emojis: 0x0000000000040000,
-      view_guild_insights: 0x0000000000080000,
-      connect: 0x0000000000100000,
-      speak: 0x0000000000200000,
-      mute_members: 0x0000000000400000,
-      deafen_members: 0x0000000000800000,
-      move_members: 0x0000000001000000,
-      use_vad: 0x0000000002000000,
-      change_nickname: 0x0000000004000000,
-      manage_nicknames: 0x0000000008000000,
-      manage_roles: 0x0000000010000000,
-      manage_webhooks: 0x0000000020000000,
-      manage_guild_expressions: 0x0000000040000000,
-      use_application_commands: 0x0000000080000000,
-      request_to_speak: 0x0000000100000000,
-      manage_events: 0x0000000200000000,
-      manage_threads: 0x0000000400000000,
-      create_public_threads: 0x0000000800000000,
-      create_private_threads: 0x0000001000000000,
-      use_external_stickers: 0x0000002000000000,
-      send_messages_in_threads: 0x0000004000000000,
-      use_embedded_activities: 0x0000008000000000,
-      moderate_members: 0x0000010000000000,
-      view_creator_monetization_analytics: 0x0000020000000000,
-      use_soundboard: 0x0000040000000000,
-      create_guild_expressions: 0x0000080000000000,
-      create_events: 0x0000100000000000,
-      use_external_sounds: 0x0000200000000000,
-      send_voice_messages: 0x0000400000000000,
-      send_polls: 0x0002000000000000,
-      use_external_apps: 0x0004000000000000
+  # Returns a hash of permission names and their corresponding bitwise values.
+  # See https://discord.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags
+  def self.bitwise_permission_flags
+    {
+      create_instant_invite: 1 << 0,
+      kick_members: 1 << 1,
+      ban_members: 1 << 2,
+      administrator: 1 << 3,
+      manage_channels: 1 << 4,
+      manage_guild: 1 << 5,
+      add_reactions: 1 << 6,
+      view_audit_log: 1 << 7,
+      priority_speaker: 1 << 8,
+      stream: 1 << 9,
+      view_channel: 1 << 10,
+      send_messages: 1 << 11,
+      send_tts_messages: 1 << 12,
+      manage_messages: 1 << 13,
+      embed_links: 1 << 14,
+      attach_files: 1 << 15,
+      read_message_history: 1 << 16,
+      mention_everyone: 1 << 17,
+      use_external_emojis: 1 << 18,
+      view_guild_insights: 1 << 19,
+      connect: 1 << 20,
+      speak: 1 << 21,
+      mute_members: 1 << 22,
+      deafen_members: 1 << 23,
+      move_members: 1 << 24,
+      use_vad: 1 << 25,
+      change_nickname: 1 << 26,
+      manage_nicknames: 1 << 27,
+      manage_roles: 1 << 28,
+      manage_webhooks: 1 << 29,
+      manage_guild_expressions: 1 << 30,
+      use_application_commands: 1 << 31,
+      request_to_speak: 1 << 32,
+      manage_events: 1 << 33,
+      manage_threads: 1 << 34,
+      create_public_threads: 1 << 35,
+      create_private_threads: 1 << 36,
+      use_external_stickers: 1 << 37,
+      send_messages_in_threads: 1 << 38,
+      use_embedded_activities: 1 << 39,
+      moderate_members: 1 << 40,
+      view_creator_monetization_analytics: 1 << 41,
+      use_soundboard: 1 << 42,
+      create_guild_expressions: 1 << 43,
+      create_events: 1 << 44,
+      use_external_sounds: 1 << 45,
+      send_voice_messages: 1 << 46,
+      send_polls: 1 << 49,
+      use_external_apps: 1 << 50,
+      pin_messages: 1 << 51
     }
+  end
+
+  # Calculates a permissions integer from an array of permission names.
+  # See https://discord.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags
+  # @param permissions [Array] Array of permission names as strings or symbols, case insensitive, use underscores
+  #   between spaces.
+  # @return [Integer] Bitwise OR of all permission flags.
+  def self.calculate_permissions_integer(permissions)
     permissions = permissions.map do |permission|
-      bitwise_permission_flags[permission.downcase.to_sym]
+      DiscordApi.bitwise_permission_flags[permission.downcase.to_sym]
     end
     permissions.reduce(0) { |acc, n| acc | n }
   end
 
+  # Reverses a permissions integer back into an array of permission names.
+  # See https://discord.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags
+  # @param permissions_integer [Integer] Bitwise permissions integer.
+  # @return [Array] Array of permission names present (as symbols) in the integer.
   def self.reverse_permissions_integer(permissions_integer)
-    bitwise_permission_flags = {
-      create_instant_invite: 0x0000000000000001,
-      kick_members: 0x0000000000000002,
-      ban_members: 0x0000000000000004,
-      administrator: 0x0000000000000008,
-      manage_channels: 0x0000000000000010,
-      manage_guild: 0x0000000000000020,
-      add_reactions: 0x0000000000000040,
-      view_audit_log: 0x0000000000000080,
-      priority_speaker: 0x0000000000000100,
-      stream: 0x0000000000000200,
-      view_channel: 0x0000000000000400,
-      send_messages: 0x0000000000000800,
-      send_tts_messages: 0x0000000000001000,
-      manage_messages: 0x0000000000002000,
-      embed_links: 0x0000000000004000,
-      attach_files: 0x0000000000008000,
-      read_message_history: 0x0000000000010000,
-      mention_everyone: 0x0000000000020000,
-      use_external_emojis: 0x0000000000040000,
-      view_guild_insights: 0x0000000000080000,
-      connect: 0x0000000000100000,
-      speak: 0x0000000000200000,
-      mute_members: 0x0000000000400000,
-      deafen_members: 0x0000000000800000,
-      move_members: 0x0000000001000000,
-      use_vad: 0x0000000002000000,
-      change_nickname: 0x0000000004000000,
-      manage_nicknames: 0x0000000008000000,
-      manage_roles: 0x0000000010000000,
-      manage_webhooks: 0x0000000020000000,
-      manage_guild_expressions: 0x0000000040000000,
-      use_application_commands: 0x0000000080000000,
-      request_to_speak: 0x0000000100000000,
-      manage_events: 0x0000000200000000,
-      manage_threads: 0x0000000400000000,
-      create_public_threads: 0x0000000800000000,
-      create_private_threads: 0x0000001000000000,
-      use_external_stickers: 0x0000002000000000,
-      send_messages_in_threads: 0x0000004000000000,
-      use_embedded_activities: 0x0000008000000000,
-      moderate_members: 0x0000010000000000,
-      view_creator_monetization_analytics: 0x0000020000000000,
-      use_soundboard: 0x0000040000000000,
-      create_guild_expressions: 0x0000080000000000,
-      create_events: 0x0000100000000000,
-      use_external_sounds: 0x0000200000000000,
-      send_voice_messages: 0x0000400000000000,
-      send_polls: 0x0002000000000000,
-      use_external_apps: 0x0004000000000000
-    }
     permissions = []
-    bitwise_permission_flags.each do |permission, value|
+    DiscordApi.bitwise_permission_flags.each do |permission, value|
       permissions << permission if (permissions_integer & value) != 0
     end
     permissions
   end
 
+  # Calculates a gateway intents integer from an array of intent names.
+  # See https://discord.com/developers/docs/topics/gateway#gateway-intents
+  # @param intents [Array] Array of gateway intent names as strings or symbols, case insensitive, use underscores
+  #   between spaces.
+  # @return [Integer] Bitwise OR of all intents flags.
   def self.calculate_gateway_intents(intents)
     bitwise_intent_flags = {
       guilds: 1 << 0,
@@ -682,6 +480,10 @@ class DiscordApi
     intents.reduce(0) { |acc, n| acc | n }
   end
 
+  # Performs an HTTP GET request using Faraday.
+  # @param url [String] Full URL including scheme and host; path may be included.
+  # @param headers [Hash, nil] Optional request headers.
+  # @return [Faraday::Response] The Faraday response object.
   def self.get(url, headers = nil)
     split_url = url.split(%r{(http[^/]+)(/.*)}).reject(&:empty?)
     @logger.error("Empty/invalid URL provided: #{url}. Cannot perform GET request.") if split_url.empty?
@@ -695,6 +497,10 @@ class DiscordApi
     end
   end
 
+  # Performs an HTTP DELETE request using Faraday.
+  # @param url [String] Full URL including scheme and host; path may be included.
+  # @param headers [Hash, nil] Optional request headers.
+  # @return [Faraday::Response] The Faraday response object.
   def self.delete(url, headers = nil)
     split_url = url.split(%r{(http[^/]+)(/.*)}).reject(&:empty?)
     @logger.error("Empty/invalid URL provided: #{url}. Cannot perform DELETE request.") if split_url.empty?
@@ -708,6 +514,11 @@ class DiscordApi
     end
   end
 
+  # Performs an HTTP POST request using Faraday.
+  # @param url [String] Full URL including scheme and host; path may be included.
+  # @param data [String] Serialized request body (e.g., JSON string).
+  # @param headers [Hash, nil] Optional request headers.
+  # @return [Faraday::Response] The Faraday response object.
   def self.post(url, data, headers = nil)
     split_url = url.split(%r{(http[^/]+)(/.*)}).reject(&:empty?)
     @logger.error("Empty/invalid URL provided: #{url}. Cannot perform POST request.") if split_url.empty?
@@ -721,6 +532,11 @@ class DiscordApi
     end
   end
 
+  # Performs an HTTP PATCH request using Faraday.
+  # @param url [String] Full URL including scheme and host; path may be included.
+  # @param data [String] Serialized request body (e.g., JSON string).
+  # @param headers [Hash, nil] Optional request headers.
+  # @return [Faraday::Response] The Faraday response object.
   def self.patch(url, data, headers = nil)
     split_url = url.split(%r{(http[^/]+)(/.*)}).reject(&:empty?)
     @logger.error("Empty/invalid URL provided: #{url}. Cannot perform PATCH request.") if split_url.empty?
@@ -734,6 +550,11 @@ class DiscordApi
     end
   end
 
+  # Performs an HTTP PUT request using Faraday.
+  # @param url [String] Full URL including scheme and host; path may be included.
+  # @param data [String] Serialized request body (e.g., JSON string).
+  # @param headers [Hash, nil] Optional request headers.
+  # @return [Faraday::Response] The Faraday response object.
   def self.put(url, data, headers = nil)
     split_url = url.split(%r{(http[^/]+)(/.*)}).reject(&:empty?)
     @logger.error("Empty/invalid URL provided: #{url}. Cannot perform PUT request.") if split_url.empty?