lib_discord 0.1.0.pre2 → 0.1.0

data/lib/lib_discord/poll.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "lib_discord/resource"
+
+module LibDiscord
+  ##
+  # Poll Resource
+  #
+  # Do not instantiate a {Poll} directly. Instead request one from an instance
+  # of {Client}.
+  #
+  #   client = LibDiscord::Client.new("Bot auth.token")
+  #   p = client["poll"]
+  #
+  # To create a poll, use {Channel#create_message}.
+  #
+  # @see https://discord.com/developers/docs/resources/poll Discord
+  #   documentation "Poll Resource"
+  class Poll < Resource
+    ##
+    # @param channel_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param message_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param answer_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param params [Hash] optional HTTP query parameters
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +params+ cannot be coerced into a valid query
+    #   parameters string
+    #
+    # @see https://discord.com/developers/docs/resources/poll#get-answer-voters
+    #   Discord documentation "Get Answer Voters"
+    def get_answer_voters(channel_id:, message_id:, answer_id:, params: {})
+      send_request(:get, "/channels/#{channel_id}/polls/#{message_id}/answers/#{answer_id}", params:)
+    end
+
+    ##
+    # @param channel_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param message_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/poll#end-poll Discord
+    #   documentation "End Poll"
+    def end_poll(channel_id:, message_id:)
+      send_request(:post, "/channels/#{channel_id}/polls/#{message_id}/expire")
+    end
+  end
+end

data/lib/lib_discord/resource.rb

@@ -8,56 +8,126 @@ require "lib_discord/response"
 require "lib_discord/types"
 
 module LibDiscord
+  ##
+  # @abstract Do not interact with or instantiate a Resource class. It is the
+  #   parent class for discreet Discord resources.
   class Resource
+    ##
+    # Initialize a Resource subclass.
+    #
+    # @param auth_header [String] Authorization header
+    # @param base_url [String] Base URL to be prepended on all request
+    #   endpoints.
+    # @param user_agent [String] User-Agent header
+    # @param logger [Logger] Logger to use for output messages
+    #
+    # @raise [Dry::Types::ConstraintError] if +auth_header+, +base_url+, or
+    #   +user_agent+ are not of type String.
+    # @raise [Dry::Types::ConstraintError] if the parameter for +logger+ is not
+    #   an instance of Logger, or an instance that inherits from Logger.
+    #
+    # @api private
     def initialize(auth_header, base_url, user_agent, logger)
       @auth_header = Types::Strict::String[auth_header]
       @base_url = Types::Strict::String[base_url]
 
       @default_headers = {user_agent: Types::Strict::String[user_agent]}
-      @logger = logger
+      @logger = Types::Logger[logger]
     end
 
     private
 
-    def clientjson = client(content_type: "application/json")
+    ##
+    # Retrieve an HTTP client, with logger attached.
+    #
+    # @api private
+    def client
+      HTTP.use(logging: {logger: @logger})
+    end
 
-    def client(**additional_headers)
+    ##
+    # Retrieve an HTTP client, with logger, authorization, and any given
+    # additional headers attached.
+    #
+    # @param additional_headers zero or more keyword arguments to attach to the
+    #   HTTP client as HTTP request headers.
+    #
+    # @return [HTTP::Client] client used to make a request
+    #
+    # @api private
+    def client_with_headers(**additional_headers)
       headers = @default_headers.merge(
-        Types::Resource::ClientHeaders[additional_headers]
+        Types::ResourceClientHeaders[additional_headers]
       )
-      HTTP.use(logging: {logger: @logger}).auth(@auth_header).headers(**headers)
+      client.auth(@auth_header).headers(**headers)
     end
 
+    ##
+    # Retrieve an HTTP client, all necessary headers and loggers attached, with
+    # its content-type set as +application/json+.
+    #
+    # @return [HTTP::Client] client used to make a request
+    #
+    # @api private
+    def clientjson = client_with_headers(content_type: "application/json")
+
+    ##
+    # Concatenate a request path with the base URL.
+    #
+    # @param path [String] request path to append to +@base_url+.
+    #
+    # @raise [Dry::Types::ConstraintError] if +path+ is not of type String.
+    #
+    # @return [String] concatenated request URL
+    #
+    # @api private
     def request_url(path)
       @base_url + Types::Strict::String[path]
     end
 
+    ##
+    # Make an HTTP request.
+    #
+    # @param verb [Symbol] HTTP action (+:get+, +:post+, +:put+, +:patch+,
+    #   +:delete+)
+    # @param relative_path [String] request path, relative to the base URL
+    # @param http_client [HTTP::Client] client to use for making the request
+    # @param kwargs one or more keyword arguments that get passed to the HTTP
+    #   client
+    #
+    # @raise [Dry::Types::ConstraintError] if +verb+ is not of type Symbol
+    # @raise [Dry::Types::ConstraintError] if +kwargs+ are not of type
+    #   Hash<Symbol, String>
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @return [Response]
+    #
+    # @api private
     def send_request(verb, relative_path, http_client: clientjson, **kwargs)
-      # TODO: account for any reasonable errors that HTTP may throw
       discord_response = http_client.send(
         Types::Strict::Symbol[verb],
         request_url(relative_path),
-        **Types::Resource::HttpKwargs[kwargs]
+        **Types::ResourceHttpKwargs[kwargs]
       )
 
-      resp = Response.new(
-        code: discord_response.code,
-        headers: discord_response.headers.to_h,
-        body_raw: discord_response.to_s
-      )
-
-      begin
-        resp.body_parsed = discord_response.parse
+      body_parsed = begin
+        discord_response.parse
       rescue HTTP::Error
-        # we'll get here if HTTP doesn't have a parser for the response's mime
-        # type. we simply want to try to parse it, and skip over it if it
-        # fails.
+        @logger.add(
+          Logger::DEBUG,
+          "Could not parse HTTP response body with content-type #{discord_response.headers["Content-Type"]}.",
+          "lib_discord"
+        )
 
-        msg = "Could not parse HTTP response body with content-type #{resp.headers["Content-Type"]}."
-        @logger.add(Logger::DEBUG, msg, "lib_discord")
+        nil
       end
 
-      resp
+      Response.new(
+        code: discord_response.code,
+        headers: discord_response.headers.to_h,
+        body_raw: discord_response.to_s,
+        body_parsed:
+      )
     rescue HTTP::TimeoutError => e
       raise TimeoutError.new(e.message)
     end

data/lib/lib_discord/response.rb

@@ -1,11 +1,43 @@
 # frozen_string_literal: true
 
+require "dry-struct"
+require "lib_discord/types"
+
 module LibDiscord
-  Response = Struct.new(
-    :code,
-    :headers,
-    :body_raw,
-    :body_parsed,
-    keyword_init: true
-  )
+  ##
+  # Response
+  #
+  # {Response} represents an HTTP response from Discord.
+  #
+  # @see https://dry-rb.org/gems/dry-struct dry-struct
+  class Response < Dry::Struct
+    ##
+    # Returns the HTTP response status code.
+    #
+    # @return [Integer]
+    attribute :code, Types::Strict::Integer
+
+    ##
+    # Returns the HTTP response headers.
+    #
+    # @return [Hash{String=>(String, Array(String))}]
+    attribute :headers, Types::ResponseHeaders
+
+    ##
+    # Returns the raw HTTP response body.
+    #
+    # @return [String]
+    attribute :body_raw, Types::Strict::String
+
+    ##
+    # Returns the deserialized HTTP response body, usually parsed from JSON.
+    # The exact structure and content-type differs per Discord API endpoint.
+    # Consult a given endpoint's Discord documentation for details.
+    #
+    # @note If we receive a content-type that we cannot parse/deserialize,
+    #   +body_parsed+ will be nil.
+    #
+    # @return [Hash, Array, nil]
+    attribute :body_parsed, Types::ResponseBody.optional
+  end
 end

data/lib/lib_discord/stage_instance.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "lib_discord/resource"
+
+module LibDiscord
+  ##
+  # Stage Instance Resource
+  #
+  # Do not instantiate a {StageInstance} directly. Instead request one from an
+  # instance of {Client}.
+  #
+  #   client = LibDiscord::Client.new("Bot auth.token")
+  #   s = client["stage_instance"]
+  #
+  # @see https://discord.com/developers/docs/resources/stage-instance Discord
+  #   documentation "Stage Instance Resource"
+  class StageInstance < Resource
+    ##
+    # @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/stage-instance#create-stage-instance
+    #   Discord documentation "Create Stage Instance"
+    def create_stage_instance(json:)
+      send_request(:post, "/stage-instances", json:)
+    end
+
+    ##
+    # @param channel_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/stage-instance#get-stage-instance
+    #   Discord documentation "Get Stage Instance"
+    def get_stage_instance(channel_id:)
+      send_request(:get, "/stage-instances/#{channel_id}")
+    end
+
+    ##
+    # @param channel_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/stage-instance#modify-stage-instance
+    #   Discord documentation "Modify Stage Instance"
+    def modify_stage_instance(channel_id:, json:)
+      send_request(:patch, "/stage-instances/#{channel_id}", json:)
+    end
+
+    ##
+    # @param channel_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/stage-instance#delete-stage-instance
+    #   Discord documentation "Delete Stage Instance"
+    def delete_stage_instance(channel_id:)
+      send_request(:delete, "/stage-instances/#{channel_id}")
+    end
+  end
+end

data/lib/lib_discord/sticker.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "lib_discord/resource"
+
+module LibDiscord
+  ##
+  # Sticker Resource
+  #
+  # Do not instantiate a {Sticker} directly. Instead request one from an
+  # instance of {Client}.
+  #
+  #   client = LibDiscord::Client.new("Bot auth.token")
+  #   s = client["sticker"]
+  #
+  # @see https://discord.com/developers/docs/resources/sticker Discord
+  #   documentation "Sticker Resource"
+  class Sticker < Resource
+    ##
+    # @param sticker_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/sticker#get-sticker
+    #   Discord documentation "Get Sticker"
+    def get_sticker(sticker_id:)
+      send_request(:get, "/stickers/#{sticker_id}")
+    end
+
+    ##
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/resources/sticker#list-sticker-packs
+    #   Discord documentation "List Sticker Packs"
+    def list_sticker_packs
+      send_request(:get, "/sticker-packs")
+    end
+
+    ##
+    # @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/sticker#list-guild-stickers
+    #   Discord documentation "List Guild Stickers"
+    def list_guild_stickers(guild_id:)
+      send_request(:get, "/guilds/#{guild_id}/stickers")
+    end
+
+    ##
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param sticker_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/sticker#get-guild-sticker
+    #   Discord documentation "Get Guild Sticker"
+    def get_guild_sticker(guild_id:, sticker_id:)
+      send_request(:get, "/guilds/#{guild_id}/stickers/#{sticker_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/sticker#create-guild-sticker
+    #   Discord documentation "Create Guild Sticker"
+    def create_guild_sticker(guild_id:, json:)
+      send_request(:post, "/guilds/#{guild_id}/stickers", json:)
+    end
+
+    ##
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param sticker_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/sticker#modify-guild-sticker
+    #   Discord documentation "Modify Guild Sticker"
+    def modify_guild_sticker(guild_id:, sticker_id:, json:)
+      send_request(:patch, "/guilds/#{guild_id}/stickers/#{sticker_id}", json:)
+    end
+
+    ##
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param sticker_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/sticker#delete-guild-sticker
+    #   Discord documentation "Delete Guild Sticker"
+    def delete_guild_sticker(guild_id:, sticker_id:)
+      send_request(:delete, "/guilds/#{guild_id}/stickers/#{sticker_id}")
+    end
+  end
+end

data/lib/lib_discord/types.rb

@@ -1,21 +1,45 @@
 # frozen_string_literal: true
 
 require "dry/types"
+require "logger"
 
 module LibDiscord
+  ##
+  # {LibDiscord}-specific type definitions
+  #
+  # @see https://dry-rb.org/gems/dry-types dry-types
+  #
+  # @api private
   module Types
-    include Dry::Types()
+    include Dry.Types()
 
-    module Resource
-      HttpKwargs = Types::Hash.schema(
-        params?: Types::Params::Hash,
-        json?: Types::JSON::Hash
-      )
+    ##
+    # Check for instance of, or decendant of Logger.
+    Logger = Types.Instance(::Logger)
 
-      ClientHeaders = Types::Hash.map(
-        Types::Strict::Symbol,
-        Types::Strict::String
-      )
-    end
+    ##
+    # Check Discord response headers.
+    ResponseHeaders = Types::Hash.map(
+      Types::Strict::String,
+      Types::Strict::String | Types::Strict::Array.of(Types::Strict::String)
+    )
+
+    ##
+    # Check Discord response body is JSON-ish.
+    ResponseBody = Types::JSON::Hash | Types::JSON::Array
+
+    ##
+    # Check +params+ and +json+ kwargs before using them in a request.
+    ResourceHttpKwargs = Types::Hash.schema(
+      params?: Types::Params::Hash,
+      json?: Types::JSON::Hash
+    )
+
+    ##
+    # Check +additional_headers+ before handing them to HTTP.
+    ResourceClientHeaders = Types::Hash.map(
+      Types::Strict::Symbol | Types::Strict::String,
+      Types::Strict::String
+    )
   end
 end

data/lib/lib_discord/urls.rb

@@ -1,19 +1,27 @@
 # frozen_string_literal: true
 
 module LibDiscord
-  def self.project_url
-    "https://sr.ht/~komidore64/lib_discord"
-  end
+  ##
+  # Project URL
+  #
+  # @api private
+  PROJECT_URL = "https://sr.ht/~komidore64/lib_discord"
 
-  def self.source_url
-    "https://git.sr.ht/~komidore64/lib_discord"
-  end
+  ##
+  # Source code URL
+  #
+  # @api private
+  SOURCE_URL = "https://git.sr.ht/~komidore64/lib_discord"
 
-  def self.bug_tracker_url
-    "https://todo.sr.ht/~komidore64/lib_discord"
-  end
+  ##
+  # Bug tracker URL
+  #
+  # @api private
+  BUG_TRACKER_URL = "https://todo.sr.ht/~komidore64/lib_discord"
 
-  def self.mailing_list_url
-    "https://sr.ht/~komidore64/lib_discord/lists"
-  end
+  ##
+  # Mailing list URLs
+  #
+  # @api private
+  MAILING_LIST_URL = "https://sr.ht/~komidore64/lib_discord/lists"
 end