lib_discord 0.1.0.pre2 → 0.1.0

data/lib/lib_discord/client.rb

@@ -1,40 +1,111 @@
 # frozen_string_literal: true
 
 require "dry-container"
-require "forwardable"
 require "logger"
 
-require "lib_discord/resources"
+require "lib_discord/application"
+require "lib_discord/application_command"
+require "lib_discord/application_role_connection_metadata"
+require "lib_discord/audit_log"
+require "lib_discord/auto_moderation"
+require "lib_discord/channel"
+require "lib_discord/emoji"
+require "lib_discord/errors"
+require "lib_discord/guild"
+require "lib_discord/guild_scheduled_event"
+require "lib_discord/guild_template"
+require "lib_discord/interaction"
+require "lib_discord/invite"
+require "lib_discord/poll"
+require "lib_discord/stage_instance"
+require "lib_discord/sticker"
 require "lib_discord/types"
 require "lib_discord/urls"
+require "lib_discord/user"
 require "lib_discord/version"
+require "lib_discord/voice"
+require "lib_discord/webhook"
 
 module LibDiscord
+  ##
+  # This class is the entry point in utilizing +lib_discord+ to access
+  # Discord's API. Initialize a client and cache it for as long as you need to
+  # make requests to Discord.
+  #
+  #   require "lib_discord"
+  #   client = LibDiscord::Client.new("Bot my.amazing.token")
   class Client
-    extend Forwardable
-
-    def initialize(auth_header:, base_url: nil, user_agent: nil, logger: nil)
-      auth_header = Types::Strict::String[auth_header]
-      base_url = Types::Strict::String[base_url || "https://discord.com/api/v10"]
-      user_agent = Types::Strict::String[user_agent || "LibDiscord (#{LibDiscord.project_url}, #{LibDiscord.version})"]
+    ##
+    # Initialize a +LibDiscord::Client+ for making requests to Discord's
+    # RESTful web API.
+    #
+    # @param auth_header [#to_s] Authorization header to be used in
+    #   communication with Discord. In the format +Bot <token>+ or +Bearer
+    #   <token>+.
+    # @param base_url [#to_s] Base URL to use in requests to Discord.
+    # @param user_agent [#to_s] User-Agent header to use in requests to
+    #   Discord.
+    # @param logger [Logger] Logger to use for output messages. If not
+    #   provided, a basic INFO-level +$stdout+ logger is created for internal use
+    #   ( +l = Logger.new($stdout); l.level = :info+ )
+    #
+    # @return [self]
+    #
+    # @raise [ConstraintError] if parameters for +auth_header+,
+    #   +base_url+, or +user_agent+ do not respond to #to_s.
+    # @raise [ConstraintError] if the parameter for +logger+ is not
+    #   an instance of Logger, or an instance that inherits from Logger.
+    #
+    # @example hook in your own logger and app-specific user-agent
+    #   client = LibDiscord::Client.new(
+    #     "Bot my.token",
+    #     user_agent: "MyApp (https://example.myapp.com, 1.2.3)",
+    #     logger: my_logger
+    #   )
+    # @example I don't want any messages going to +stdout+.
+    #   client = LibDiscord::Client.new(
+    #     "Bot my.token",
+    #     logger: Logger.new("/dev/null")
+    #   )
+    #
+    # @see https://discord.com/developers/docs/reference#authentication Discord
+    #   documentation "Authentication"
+    # @see https://discord.com/developers/docs/reference#user-agent Discord
+    #   documentation "User Agent"
+    def initialize(
+      auth_header,
+      base_url: "https://discord.com/api/v10",
+      user_agent: "LibDiscord (#{LibDiscord::PROJECT_URL}, #{LibDiscord.version})",
+      logger: nil
+    )
+      auth_header = Types::Coercible::String[auth_header]
+      base_url = Types::Coercible::String[base_url]
+      user_agent = Types::Coercible::String[user_agent]
 
       unless logger
         logger = Logger.new($stdout)
         logger.level = :info
       end
 
+      logger = Types::Logger[logger]
+
       @container = Dry::Container.new
 
       @container.register("application") do
         Application.new(auth_header, base_url, user_agent, logger)
       end
 
-      @container.register("application.command") do
+      @container.register("application_command") do
         ApplicationCommand.new(auth_header, base_url, user_agent, logger)
       end
 
-      @container.register("application.role_connection_metadata") do
-        ApplicationRoleConnectionMetadata.new(auth_header, base_url, user_agent, logger)
+      @container.register("application_role_connection_metadata") do
+        ApplicationRoleConnectionMetadata.new(
+          auth_header,
+          base_url,
+          user_agent,
+          logger
+        )
       end
 
       @container.register("audit_log") do
@@ -57,11 +128,11 @@ module LibDiscord
         Guild.new(auth_header, base_url, user_agent, logger)
       end
 
-      @container.register("guild.scheduled_event") do
+      @container.register("guild_scheduled_event") do
         GuildScheduledEvent.new(auth_header, base_url, user_agent, logger)
       end
 
-      @container.register("guild.template") do
+      @container.register("guild_template") do
         GuildTemplate.new(auth_header, base_url, user_agent, logger)
       end
 
@@ -73,6 +144,10 @@ module LibDiscord
         Invite.new(auth_header, base_url, user_agent, logger)
       end
 
+      @container.register("poll") do
+        Poll.new(auth_header, base_url, user_agent, logger)
+      end
+
       @container.register("stage_instance") do
         StageInstance.new(auth_header, base_url, user_agent, logger)
       end
@@ -92,8 +167,43 @@ module LibDiscord
       @container.register("webhook") do
         Webhook.new(auth_header, base_url, user_agent, logger)
       end
+    rescue Dry::Types::ConstraintError => e
+      raise ConstraintError.new(e.message)
+    end
+
+    ##
+    # Get a Resource for making Discord API requests.
+    #
+    # @param resource [String] Resource key. see {#keys} for available values.
+    #
+    # @return Resource
+    #
+    # @raise [KeyError] if no resource exists for a given key
+    #
+    # @example
+    #   client["application"]
+    #   # => #<LibDiscord::Application: ... >
+    # @example
+    #   client["not.a.valid.key"]
+    #   # => key not found "not.a.valid.key" (LibDiscord::KeyError)
+    def [](resource)
+      @container[resource]
+    rescue Dry::Container::KeyError => e
+      raise KeyError.new(e.message)
     end
 
-    def_delegators :@container, :[], :keys
+    ##
+    # Get available Resource keys.
+    #
+    # @return [Array<String>] a list of resources available
+    #
+    # @example
+    #   client.keys
+    #   # =>
+    #   # ["application",
+    #   #  "guild",
+    #   #  "channel",
+    #   #  ...]
+    def keys = @container.keys
   end
 end

data/lib/lib_discord/emoji.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "lib_discord/resource"
+
+module LibDiscord
+  ##
+  # Emoji Resource
+  #
+  # Do not instantiate an {Emoji} directly. Instead request one from an
+  # instance of {Client}.
+  #
+  #   client = LibDiscord::Client.new("Bot auth.token")
+  #   e = client["emoji"]
+  #
+  # @see https://discord.com/developers/docs/resources/emoji Discord
+  #   documentation "Emoji Resource"
+  class Emoji < Resource
+    ##
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/resources/emoji#list-guild-emojis
+    #   Discord documentation "List Guild Emojis"
+    def list_guild_emojis(guild_id:)
+      send_request(:get, "/guilds/#{guild_id}/emojis")
+    end
+
+    ##
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param emoji_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/resources/emoji#get-guild-emoji
+    #   Discord documentation "Get Guild Emoji"
+    def get_guild_emoji(guild_id:, emoji_id:)
+      send_request(:get, "/guilds/#{guild_id}/emojis/#{emoji_id}")
+    end
+
+    ##
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash] JSON serializable payload
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/resources/emoji#create-guild-emoji
+    #   Discord documentation "Create Guild Emoji"
+    def create_guild_emoji(guild_id:, json:)
+      send_request(:post, "/guilds/#{guild_id}/emojis", json:)
+    end
+
+    ##
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param emoji_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash] JSON serializable payload
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/resources/emoji#modify-guild-emoji
+    #   Discord documentation "Modify Guild Emoji"
+    def modify_guild_emoji(guild_id:, emoji_id:, json:)
+      send_request(:patch, "/guilds/#{guild_id}/emojis/#{emoji_id}", json:)
+    end
+
+    ##
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param emoji_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/resources/emoji#delete-guild-emoji
+    #   Discord documentation "Delete Guild Emoji"
+    def delete_guild_emoji(guild_id:, emoji_id:)
+      send_request(:delete, "/guilds/#{guild_id}/emojis/#{emoji_id}")
+    end
+  end
+end

data/lib/lib_discord/errors.rb

@@ -1,7 +1,31 @@
 # frozen_string_literal: true
 
+require "dry-container"
+require "dry/types"
 require "http"
 
 module LibDiscord
+  ##
+  # Constraint Error
+  #
+  # This error is thrown when a type-check against LibDiscord's type
+  # constraints fails.
+  class ConstraintError < Dry::Types::ConstraintError; end
+
+  ##
+  # Key Error
+  #
+  # This error is thrown when a {Client} instance has no object mapped to the
+  # key used.
+  #
+  # @see Client#[]
+  # @see Client#keys
+  class KeyError < Dry::Container::KeyError; end
+
+  ##
+  # This error is thrown when an HTTP request made to Discord times out.
+  #
+  # @see https://github.com/httprb/http/wiki/Errors-and-Exceptions HTTP.rb
+  #   "Errors and Exceptions"
   class TimeoutError < HTTP::TimeoutError; end
 end