discorb-lib/discorb

module Discorb
  type json =
    ::Hash[Symbol | String, json]
    | ::Array[json]
    | ::String
    | ::Symbol
    | ::Numeric
    | bool
    | nil

  #
  # A class to handle http requests.
  # @private
  class HTTP
    #
    # Initializes the http client.
    # @private
    #
    # @param [Discorb::Client] client The client.
    def initialize: (Discorb::Client client) -> void

    #
    # Execute a request.
    # @async
    #
    # @param [Discorb::Route] path The path to the resource.
    # @param [String, Hash] body The body of the request. Defaults to an empty string.
    # @param [String] audit_log_reason The audit log reason to send with the request.
    # @param [Hash] kwargs The keyword arguments.
    #
    # @return [Async::Task<Array(Net::HTTPResponse, Hash)>] The response and as JSON.
    # @return [Async::Task<Array(Net::HTTPResponse, nil)>] The response was 204.
    #
    # @raise [Discorb::HTTPError] The request was failed.
    def request: (
      Discorb::Route path,
      ?json | String body,
      ?audit_log_reason: String?,
      **String kwargs
    ) -> Async::Task[[Net::HTTPResponse, json]]

    #
    # Execute a multipart request.
    # @async
    #
    # @param [Discorb::Route] path The path to the resource.
    # @param [String, Hash] body The body of the request.
    # @param [Array<Discorb::Attachment>] files The files to upload.
    # @param [Hash] headers The headers to send with the request.
    # @param [String] audit_log_reason The audit log reason to send with the request.
    # @param [Hash] kwargs The keyword arguments.
    #
    # @return [Async::Task<Array(Net::HTTPResponse, Hash)>] The response and as JSON.
    # @return [Async::Task<Array(Net::HTTPResponse, nil)>] The response was 204.
    #
    # @raise [Discorb::HTTPError] The request was failed.
    def multipart_request: (
      Discorb::Route path,
      json | String body,
      ::Array[Discorb::Attachment]? files,
      ?audit_log_reason: String?,
      **untyped kwargs
    ) -> Async::Task[[Net::HTTPResponse, json]]

    %a{pure}
    def inspect: -> String

    private

    def handle_response: (
      Net::HTTPResponse resp,
      json data,
      Discorb::Route path,
      json | String body,
      ::Array[Discorb::Attachment]? files,
      String? audit_log_reason,
      untyped kwargs
    ) -> [Net::HTTPResponse, json]

    def get_headers: (
      ?String | json body,
      ?String? audit_log_reason
    ) -> ::Hash[String, String]

    def get_body: (nil | String | json body) -> String

    def get_path: (Discorb::Route path) -> String

    def get_response_data: (Net::HTTPResponse resp) -> json?

    def http: -> Net::HTTP

    def cdn_http: -> Net::HTTP

    def recr_utf8: [O] (O data) -> O
  end

  #
  # Represents an endpoint.
  # @private
  class Route
    def initialize: (untyped url, untyped key, untyped method) -> void

    %a{pure}
    def inspect: -> String

    def hash: -> untyped

    def identifier: -> untyped

    def major_param: -> untyped

    # Returns the value of attribute url.
    attr_reader url: untyped

    # Returns the value of attribute key.
    attr_reader key: untyped

    # Returns the value of attribute method.
    attr_reader method: untyped
  end

  #
  # Class to handle rate limiting.
  # @private
  class RatelimitHandler
    #
    # Initialize a rate limit handler.
    # @private
    #
    # @param [Discorb::Client] client The client.
    def initialize: (Discorb::Client client) -> void

    %a{pure}
    def inspect: -> String

    #
    # Wait for the rate limit to reset.
    #
    # @param [Discorb::Route] path The path.
    def wait: (Discorb::Route path) -> untyped

    #
    # Save the rate limit.
    #
    # @param [String] path The path.
    # @param [Net::HTTPResponse] resp The response.
    def save: (String path, Net::HTTPResponse resp) -> untyped
  end
end