x 0.17.0 → 0.18.0

data/lib/x/client_credentials.rb

@@ -0,0 +1,208 @@
+module X
+  # Mixin for client authentication credentials
+  # @api private
+  module ClientCredentials
+    # The API key for OAuth 1.0a authentication
+    # @api public
+    # @return [String, nil] the API key for OAuth 1.0a authentication
+    # @example Get the API key
+    #   client.api_key
+    attr_reader :api_key
+
+    # The API key secret for OAuth 1.0a authentication
+    # @api public
+    # @return [String, nil] the API key secret for OAuth 1.0a authentication
+    # @example Get the API key secret
+    #   client.api_key_secret
+    attr_reader :api_key_secret
+
+    # The access token for OAuth authentication
+    # @api public
+    # @return [String, nil] the access token for OAuth authentication
+    # @example Get the access token
+    #   client.access_token
+    attr_reader :access_token
+
+    # The access token secret for OAuth 1.0a authentication
+    # @api public
+    # @return [String, nil] the access token secret for OAuth 1.0a authentication
+    # @example Get the access token secret
+    #   client.access_token_secret
+    attr_reader :access_token_secret
+
+    # The bearer token for authentication
+    # @api public
+    # @return [String, nil] the bearer token for authentication
+    # @example Get the bearer token
+    #   client.bearer_token
+    attr_reader :bearer_token
+
+    # The OAuth 2.0 client ID
+    # @api public
+    # @return [String, nil] the OAuth 2.0 client ID
+    # @example Get the client ID
+    #   client.client_id
+    attr_reader :client_id
+
+    # The OAuth 2.0 client secret
+    # @api public
+    # @return [String, nil] the OAuth 2.0 client secret
+    # @example Get the client secret
+    #   client.client_secret
+    attr_reader :client_secret
+
+    # The OAuth 2.0 refresh token
+    # @api public
+    # @return [String, nil] the OAuth 2.0 refresh token
+    # @example Get the refresh token
+    #   client.refresh_token
+    attr_reader :refresh_token
+
+    # Set the API key for OAuth 1.0a authentication
+    #
+    # @api public
+    # @param api_key [String] the API key for OAuth 1.0a authentication
+    # @return [void]
+    # @example Set the API key
+    #   client.api_key = "new_key"
+    def api_key=(api_key)
+      @api_key = api_key
+      initialize_authenticator
+    end
+
+    # Set the API key secret for OAuth 1.0a authentication
+    #
+    # @api public
+    # @param api_key_secret [String] the API key secret for OAuth 1.0a authentication
+    # @return [void]
+    # @example Set the API key secret
+    #   client.api_key_secret = "new_secret"
+    def api_key_secret=(api_key_secret)
+      @api_key_secret = api_key_secret
+      initialize_authenticator
+    end
+
+    # Set the access token for OAuth authentication
+    #
+    # @api public
+    # @param access_token [String] the access token for OAuth authentication
+    # @return [void]
+    # @example Set the access token
+    #   client.access_token = "new_token"
+    def access_token=(access_token)
+      @access_token = access_token
+      initialize_authenticator
+    end
+
+    # Set the access token secret for OAuth 1.0a authentication
+    #
+    # @api public
+    # @param access_token_secret [String] the access token secret for OAuth 1.0a authentication
+    # @return [void]
+    # @example Set the access token secret
+    #   client.access_token_secret = "new_secret"
+    def access_token_secret=(access_token_secret)
+      @access_token_secret = access_token_secret
+      initialize_authenticator
+    end
+
+    # Set the bearer token for authentication
+    #
+    # @api public
+    # @param bearer_token [String] the bearer token for authentication
+    # @return [void]
+    # @example Set the bearer token
+    #   client.bearer_token = "new_token"
+    def bearer_token=(bearer_token)
+      @bearer_token = bearer_token
+      initialize_authenticator
+    end
+
+    # Set the OAuth 2.0 client ID
+    #
+    # @api public
+    # @param client_id [String] the OAuth 2.0 client ID
+    # @return [void]
+    # @example Set the client ID
+    #   client.client_id = "new_id"
+    def client_id=(client_id)
+      @client_id = client_id
+      initialize_authenticator
+    end
+
+    # Set the OAuth 2.0 client secret
+    #
+    # @api public
+    # @param client_secret [String] the OAuth 2.0 client secret
+    # @return [void]
+    # @example Set the client secret
+    #   client.client_secret = "new_secret"
+    def client_secret=(client_secret)
+      @client_secret = client_secret
+      initialize_authenticator
+    end
+
+    # Set the OAuth 2.0 refresh token
+    #
+    # @api public
+    # @param refresh_token [String] the OAuth 2.0 refresh token
+    # @return [void]
+    # @example Set the refresh token
+    #   client.refresh_token = "new_token"
+    def refresh_token=(refresh_token)
+      @refresh_token = refresh_token
+      initialize_authenticator
+    end
+
+    private
+
+    # Initialize credential instance variables
+    # @api private
+    # @return [void]
+    def initialize_credentials(api_key:, api_key_secret:, access_token:, access_token_secret:, bearer_token:,
+      client_id:, client_secret:, refresh_token:)
+      @api_key = api_key
+      @api_key_secret = api_key_secret
+      @access_token = access_token
+      @access_token_secret = access_token_secret
+      @bearer_token = bearer_token
+      @client_id = client_id
+      @client_secret = client_secret
+      @refresh_token = refresh_token
+    end
+
+    # Initialize the appropriate authenticator based on available credentials
+    # @api private
+    # @return [Authenticator] the initialized authenticator
+    def initialize_authenticator
+      @authenticator = oauth_authenticator || oauth2_authenticator || bearer_authenticator || @authenticator || Authenticator.new
+    end
+
+    # Build an OAuth 1.0a authenticator if credentials are available
+    # @api private
+    # @return [OAuthAuthenticator, nil] the OAuth authenticator or nil
+    def oauth_authenticator
+      return unless api_key && api_key_secret && access_token && access_token_secret
+
+      OAuthAuthenticator.new(api_key:, api_key_secret:, access_token:, access_token_secret:)
+    end
+
+    # Build an OAuth 2.0 authenticator if credentials are available
+    # @api private
+    # @return [OAuth2Authenticator, nil] the OAuth 2.0 authenticator or nil
+    def oauth2_authenticator
+      return unless client_id && client_secret && access_token && refresh_token
+
+      OAuth2Authenticator.new(client_id:, client_secret:, access_token:, refresh_token:)
+    end
+
+    # Build a bearer token authenticator if credentials are available
+    # @api private
+    # @return [BearerTokenAuthenticator, nil] the bearer token authenticator or nil
+    def bearer_authenticator
+      return unless bearer_token
+
+      BearerTokenAuthenticator.new(bearer_token:)
+    end
+  end
+end

data/lib/x/connection.rb

@@ -5,15 +5,24 @@ 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
+    # Default debug output destination
     DEFAULT_DEBUG_OUTPUT = File.open(IO::NULL, "w")
+    # Network errors that should be wrapped in NetworkError
     NETWORK_ERRORS = [
       Errno::ECONNREFUSED,
       Errno::ECONNRESET,
@@ -22,14 +31,66 @@ module X
       OpenSSL::SSL::SSLError
     ].freeze
 
-    attr_accessor :open_timeout, :read_timeout, :write_timeout, :debug_output
-    attr_reader :proxy_url, :proxy_uri
+    # 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: DEFAULT_DEBUG_OUTPUT, proxy_url: nil)
       @open_timeout = open_timeout
@@ -39,6 +100,14 @@ module X
       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
@@ -49,6 +118,14 @@ module X
       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)
@@ -59,6 +136,11 @@ module X
 
     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)
@@ -68,6 +150,10 @@ module X
       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

data/lib/x/errors/bad_gateway.rb

@@ -1,5 +1,6 @@
 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,5 +1,6 @@
 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,5 +1,6 @@
 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,5 +1,6 @@
 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,3 +1,4 @@
 module X
+  # Base error class for all X API errors
   class Error < StandardError; end
 end

data/lib/x/errors/forbidden.rb

@@ -1,5 +1,6 @@
 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,5 +1,6 @@
 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,5 +1,6 @@
 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

@@ -2,17 +2,46 @@ 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}
 
-    attr_reader :response, :code
+    # 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)
@@ -21,19 +50,33 @@ module X
       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.key?("title") && response_object.key?("detail")
+      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")
-      elsif response_object["errors"].instance_of?(Array)
-        response_object.fetch("errors").map { |error| error.fetch("message") }.join(", ")
       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

data/lib/x/errors/internal_server_error.rb

@@ -1,5 +1,6 @@
 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

@@ -0,0 +1,6 @@
+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,5 +1,6 @@
 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,5 +1,6 @@
 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,5 +1,6 @@
 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,5 +1,6 @@
 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,5 +1,6 @@
 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,5 +1,6 @@
 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,5 +1,6 @@
 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

@@ -2,25 +2,57 @@ 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,5 +1,6 @@
 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,5 +1,6 @@
 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,13 +1,32 @@
 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)