x 0.19.0 → 1.0.0

data/lib/x/connection.rb

@@ -1,183 +0,0 @@
-require "forwardable"
-require "net/http"
-require "openssl"
-require "uri"
-require_relative "errors/network_error"
-
-module X
-  # Manages HTTP connections to the X API
-  # @api public
-  class Connection
-    extend Forwardable
-
-    # Default host for the X API
-    DEFAULT_HOST = "api.twitter.com".freeze
-    # Default port for HTTPS connections
-    DEFAULT_PORT = 443
-    # Default timeout for opening connections in seconds
-    DEFAULT_OPEN_TIMEOUT = 60 # seconds
-    # Default timeout for reading responses in seconds
-    DEFAULT_READ_TIMEOUT = 60 # seconds
-    # Default timeout for writing requests in seconds
-    DEFAULT_WRITE_TIMEOUT = 60 # seconds
-    # Network errors that should be wrapped in NetworkError
-    NETWORK_ERRORS = [
-      Errno::ECONNREFUSED,
-      Errno::ECONNRESET,
-      Net::OpenTimeout,
-      Net::ReadTimeout,
-      OpenSSL::SSL::SSLError
-    ].freeze
-
-    # The timeout for opening connections in seconds
-    # @api public
-    # @return [Integer] the timeout for opening connections in seconds
-    # @example Get or set the open timeout
-    #   connection.open_timeout = 30
-    attr_accessor :open_timeout
-
-    # The timeout for reading responses in seconds
-    # @api public
-    # @return [Integer] the timeout for reading responses in seconds
-    # @example Get or set the read timeout
-    #   connection.read_timeout = 30
-    attr_accessor :read_timeout
-
-    # The timeout for writing requests in seconds
-    # @api public
-    # @return [Integer] the timeout for writing requests in seconds
-    # @example Get or set the write timeout
-    #   connection.write_timeout = 30
-    attr_accessor :write_timeout
-
-    # The IO object for debug output
-    # @api public
-    # @return [IO] the IO object for debug output
-    # @example Get or set the debug output
-    #   connection.debug_output = $stderr
-    attr_accessor :debug_output
-
-    # The proxy URL for requests
-    # @api public
-    # @return [String, nil] the proxy URL for requests
-    # @example Get the proxy URL
-    #   connection.proxy_url
-    attr_reader :proxy_url
-
-    # The parsed proxy URI
-    # @api public
-    # @return [URI, nil] the parsed proxy URI
-    # @example Get the proxy URI
-    #   connection.proxy_uri
-    attr_reader :proxy_uri
-
-    def_delegator :proxy_uri, :host, :proxy_host
-    def_delegator :proxy_uri, :port, :proxy_port
-    def_delegator :proxy_uri, :user, :proxy_user
-    def_delegator :proxy_uri, :password, :proxy_pass
-
-    # Initialize a new connection
-    #
-    # @api public
-    # @param open_timeout [Integer] the timeout for opening connections in seconds
-    # @param read_timeout [Integer] the timeout for reading responses in seconds
-    # @param write_timeout [Integer] the timeout for writing requests in seconds
-    # @param debug_output [IO] the IO object for debug output
-    # @param proxy_url [String, nil] the proxy URL for requests
-    # @return [Connection] a new connection instance
-    # @example Create a connection with default settings
-    #   connection = X::Connection.new
-    # @example Create a connection with custom timeouts
-    #   connection = X::Connection.new(open_timeout: 30, read_timeout: 30)
-    def initialize(open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
-      write_timeout: DEFAULT_WRITE_TIMEOUT, debug_output: nil, proxy_url: nil)
-      @open_timeout = open_timeout
-      @read_timeout = read_timeout
-      @write_timeout = write_timeout
-      @debug_output = debug_output
-      self.proxy_url = proxy_url unless proxy_url.nil?
-    end
-
-    # Perform an HTTP request
-    #
-    # @api public
-    # @param request [Net::HTTPRequest] the HTTP request to perform
-    # @return [Net::HTTPResponse] the HTTP response
-    # @raise [NetworkError] if a network error occurs
-    # @example Perform a request
-    #   response = connection.perform(request: request)
-    def perform(request:)
-      host = request.uri.host || DEFAULT_HOST
-      port = request.uri.port || DEFAULT_PORT
-      http_client = build_http_client(host, port)
-      http_client.use_ssl = request.uri.scheme.eql?("https")
-      http_client.request(request)
-    rescue *NETWORK_ERRORS => e
-      raise NetworkError, "Network error: #{e}"
-    end
-
-    # Perform a streaming HTTP request
-    #
-    # @api public
-    # @param request [Net::HTTPRequest] the HTTP request to perform
-    # @yield [Net::HTTPResponse] the HTTP response for streaming
-    # @return [void]
-    # @raise [NetworkError] if a network error occurs
-    # @example Perform a streaming request
-    #   connection.perform_stream(request: request) { |response| response.read_body { |chunk| } }
-    def perform_stream(request:, &)
-      host = request.uri.host || DEFAULT_HOST
-      port = request.uri.port || DEFAULT_PORT
-      http_client = build_http_client(host, port)
-      http_client.use_ssl = request.uri.scheme.eql?("https")
-      http_client.request(request, &)
-    rescue *NETWORK_ERRORS => e
-      raise NetworkError, "Network error: #{e}"
-    end
-
-    # Set the proxy URL for requests
-    #
-    # @api public
-    # @param proxy_url [String] the proxy URL
-    # @return [void]
-    # @raise [ArgumentError] if the proxy URL is invalid
-    # @example Set the proxy URL
-    #   connection.proxy_url = "http://proxy.example.com:8080"
-    def proxy_url=(proxy_url)
-      @proxy_url = proxy_url
-      proxy_uri = URI(proxy_url)
-      raise ArgumentError, "Invalid proxy URL: #{proxy_uri}" unless proxy_uri.is_a?(URI::HTTP)
-
-      @proxy_uri = proxy_uri
-    end
-
-    private
-
-    # Build an HTTP client for the given host and port
-    # @api private
-    # @param host [String] the host to connect to
-    # @param port [Integer] the port to connect to
-    # @return [Net::HTTP] the HTTP client
-    def build_http_client(host = DEFAULT_HOST, port = DEFAULT_PORT)
-      http_client = if proxy_uri
-        Net::HTTP.new(host, port, proxy_host, proxy_port, proxy_user, proxy_pass)
-      else
-        Net::HTTP.new(host, port)
-      end
-      configure_http_client(http_client)
-    end
-
-    # Configure an HTTP client with timeout settings
-    # @api private
-    # @param http_client [Net::HTTP] the HTTP client to configure
-    # @return [Net::HTTP] the configured HTTP client
-    def configure_http_client(http_client)
-      http_client.tap do |c|
-        c.open_timeout = open_timeout
-        c.read_timeout = read_timeout
-        c.write_timeout = write_timeout
-        c.set_debug_output(debug_output)
-      end
-    end
-  end
-end

data/lib/x/errors/bad_gateway.rb

@@ -1,6 +0,0 @@
-require_relative "server_error"
-
-module X
-  # Error raised for HTTP 502 Bad Gateway responses
-  class BadGateway < ServerError; end
-end

data/lib/x/errors/bad_request.rb

@@ -1,6 +0,0 @@
-require_relative "client_error"
-
-module X
-  # Error raised for HTTP 400 Bad Request responses
-  class BadRequest < ClientError; end
-end

data/lib/x/errors/client_error.rb

@@ -1,6 +0,0 @@
-require_relative "http_error"
-
-module X
-  # Base class for client errors (4xx HTTP status codes)
-  class ClientError < HTTPError; end
-end

data/lib/x/errors/connection_exception.rb

@@ -1,6 +0,0 @@
-require_relative "client_error"
-
-module X
-  # Error raised for HTTP 409 Conflict responses
-  class ConnectionException < ClientError; end
-end

data/lib/x/errors/error.rb

@@ -1,4 +0,0 @@
-module X
-  # Base error class for all X API errors
-  class Error < StandardError; end
-end

data/lib/x/errors/forbidden.rb

@@ -1,6 +0,0 @@
-require_relative "client_error"
-
-module X
-  # Error raised for HTTP 403 Forbidden responses
-  class Forbidden < ClientError; end
-end

data/lib/x/errors/gateway_timeout.rb

@@ -1,6 +0,0 @@
-require_relative "server_error"
-
-module X
-  # Error raised for HTTP 504 Gateway Timeout responses
-  class GatewayTimeout < ServerError; end
-end

data/lib/x/errors/gone.rb

@@ -1,6 +0,0 @@
-require_relative "client_error"
-
-module X
-  # Error raised for HTTP 410 Gone responses
-  class Gone < ClientError; end
-end

data/lib/x/errors/http_error.rb

@@ -1,84 +0,0 @@
-require "json"
-require_relative "error"
-
-module X
-  # Base class for HTTP errors from the X API
-  # @api public
-  class HTTPError < Error
-    # Regular expression to match JSON content types
-    JSON_CONTENT_TYPE_REGEXP = %r{application/(problem\+|)json}
-
-    # The HTTP response
-    # @api public
-    # @return [Net::HTTPResponse] the HTTP response
-    # @example Get the response
-    #   error.response
-    attr_reader :response
-
-    # The HTTP status code
-    # @api public
-    # @return [String] the HTTP status code
-    # @example Get the status code
-    #   error.code
-    attr_reader :code
-
-    # Initialize a new HTTPError
-    #
-    # @api public
-    # @param response [Net::HTTPResponse] the HTTP response
-    # @return [HTTPError] a new instance
-    # @example Create an HTTP error
-    #   error = X::HTTPError.new(response: response)
-    def initialize(response:)
-      super(error_message(response))
-      @response = response
-      @code = response.code
-    end
-
-    # Get the error message from the response
-    #
-    # @api public
-    # @param response [Net::HTTPResponse] the HTTP response
-    # @return [String] the error message
-    # @example Get the error message
-    #   error.error_message(response)
-    def error_message(response)
-      if json?(response)
-        message_from_json_response(response)
-      else
-        response.message
-      end
-    end
-
-    # Extract error message from a JSON response
-    #
-    # @api public
-    # @param response [Net::HTTPResponse] the HTTP response
-    # @return [String] the error message
-    # @example Get error message from JSON
-    #   error.message_from_json_response(response)
-    def message_from_json_response(response)
-      response_object = JSON.parse(response.body)
-      if response_object["errors"].instance_of?(Array)
-        response_object.fetch("errors").map { |error| error.fetch("message") }.join(", ")
-      elsif response_object.key?("title") && response_object.key?("detail")
-        "#{response_object.fetch("title")}: #{response_object.fetch("detail")}"
-      elsif response_object.key?("error")
-        response_object.fetch("error")
-      else
-        response.message
-      end
-    end
-
-    # Check if the response contains JSON
-    #
-    # @api public
-    # @param response [Net::HTTPResponse] the HTTP response
-    # @return [Boolean] true if the response is JSON
-    # @example Check if response is JSON
-    #   error.json?(response)
-    def json?(response)
-      JSON_CONTENT_TYPE_REGEXP === response["content-type"]
-    end
-  end
-end

data/lib/x/errors/internal_server_error.rb

@@ -1,6 +0,0 @@
-require_relative "server_error"
-
-module X
-  # Error raised for HTTP 500 Internal Server Error responses
-  class InternalServerError < ServerError; end
-end

data/lib/x/errors/invalid_media_type.rb

@@ -1,6 +0,0 @@
-require_relative "error"
-
-module X
-  # Error raised when a file's MIME type cannot be determined or is unsupported
-  class InvalidMediaType < Error; end
-end

data/lib/x/errors/network_error.rb

@@ -1,6 +0,0 @@
-require_relative "error"
-
-module X
-  # Error raised when a network error occurs
-  class NetworkError < Error; end
-end

data/lib/x/errors/not_acceptable.rb

@@ -1,6 +0,0 @@
-require_relative "client_error"
-
-module X
-  # Error raised for HTTP 406 Not Acceptable responses
-  class NotAcceptable < ClientError; end
-end

data/lib/x/errors/not_found.rb

@@ -1,6 +0,0 @@
-require_relative "client_error"
-
-module X
-  # Error raised for HTTP 404 Not Found responses
-  class NotFound < ClientError; end
-end

data/lib/x/errors/payload_too_large.rb

@@ -1,6 +0,0 @@
-require_relative "client_error"
-
-module X
-  # Error raised for HTTP 413 Payload Too Large responses
-  class PayloadTooLarge < ClientError; end
-end

data/lib/x/errors/server_error.rb

@@ -1,6 +0,0 @@
-require_relative "http_error"
-
-module X
-  # Base class for server errors (5xx HTTP status codes)
-  class ServerError < HTTPError; end
-end

data/lib/x/errors/service_unavailable.rb

@@ -1,6 +0,0 @@
-require_relative "server_error"
-
-module X
-  # Error raised for HTTP 503 Service Unavailable responses
-  class ServiceUnavailable < ServerError; end
-end

data/lib/x/errors/too_many_redirects.rb

@@ -1,6 +0,0 @@
-require_relative "error"
-
-module X
-  # Error raised when too many redirects are encountered
-  class TooManyRedirects < Error; end
-end

data/lib/x/errors/too_many_requests.rb

@@ -1,58 +0,0 @@
-require_relative "client_error"
-require_relative "../rate_limit"
-
-module X
-  # Error raised when rate limit is exceeded (HTTP 429)
-  # @api public
-  class TooManyRequests < ClientError
-    # Get the most restrictive rate limit
-    #
-    # @api public
-    # @return [RateLimit, nil] the rate limit with the latest reset time
-    # @example Get the rate limit
-    #   error.rate_limit
-    def rate_limit
-      rate_limits.max_by(&:reset_at)
-    end
-
-    # Get all rate limits from the response
-    #
-    # @api public
-    # @return [Array<RateLimit>] the rate limits that are exhausted
-    # @example Get all rate limits
-    #   error.rate_limits
-    def rate_limits
-      @rate_limits ||= RateLimit::TYPES.filter_map do |type|
-        RateLimit.new(type:, response:) if response["x-#{type}-remaining"].eql?("0")
-      end
-    end
-
-    # Get the time when the rate limit resets
-    #
-    # @api public
-    # @return [Time] the reset time
-    # @example Get the reset time
-    #   error.reset_at
-    def reset_at
-      rate_limit&.reset_at || Time.at(0)
-    end
-
-    # Get the seconds until the rate limit resets
-    #
-    # @api public
-    # @return [Integer] the seconds until reset
-    # @example Get the time until reset
-    #   error.reset_in
-    def reset_in
-      [(reset_at - Time.now).ceil, 0].max
-    end
-
-    # @!method retry_after
-    #   Alias for reset_in, returns the seconds to wait before retrying
-    #   @api public
-    #   @return [Integer] the seconds to wait before retrying
-    #   @example Get the retry delay
-    #     error.retry_after
-    alias_method :retry_after, :reset_in
-  end
-end

data/lib/x/errors/unauthorized.rb

@@ -1,6 +0,0 @@
-require_relative "client_error"
-
-module X
-  # Error raised for HTTP 401 Unauthorized responses
-  class Unauthorized < ClientError; end
-end

data/lib/x/errors/unprocessable_entity.rb

@@ -1,6 +0,0 @@
-require_relative "client_error"
-
-module X
-  # Error raised for HTTP 422 Unprocessable Entity responses
-  class UnprocessableEntity < ClientError; end
-end

data/lib/x/media_upload_validator.rb

@@ -1,36 +0,0 @@
-module X
-  # Validates media upload parameters
-  # @api public
-  module MediaUploadValidator
-    module_function
-
-    # Valid media category values
-    MEDIA_CATEGORIES = %w[dm_gif dm_image dm_video subtitles tweet_gif tweet_image tweet_video].freeze
-
-    # Validate that a file path exists
-    #
-    # @api private
-    # @param file_path [String] the file path to validate
-    # @return [void]
-    # @raise [RuntimeError] if the file does not exist
-    # @example Validate a file path
-    #   MediaUploadValidator.validate_file_path!(file_path: "image.png")
-    def validate_file_path!(file_path:)
-      raise "File not found: #{file_path}" unless File.exist?(file_path)
-    end
-
-    # Validate that a media category is valid
-    #
-    # @api private
-    # @param media_category [String] the media category to validate
-    # @return [void]
-    # @raise [ArgumentError] if the media category is invalid
-    # @example Validate a media category
-    #   MediaUploadValidator.validate_media_category!(media_category: "tweet_image")
-    def validate_media_category!(media_category:)
-      return if MEDIA_CATEGORIES.include?(media_category.downcase)
-
-      raise ArgumentError, "Invalid media_category: #{media_category}. Valid values: #{MEDIA_CATEGORIES.join(", ")}"
-    end
-  end
-end