x 0.17.0 → 0.18.0

data/lib/x/media_uploader.rb

@@ -1,27 +1,58 @@
 require "json"
 require "securerandom"
 require "tmpdir"
+require_relative "errors/invalid_media_type"
 require_relative "media_upload_validator"
 
 module X
+  # Uploads media files to the X API
+  # @api public
   module MediaUploader
     extend self
 
+    # Maximum number of retry attempts for failed uploads
     MAX_RETRIES = 3
+    # Number of bytes per megabyte
     BYTES_PER_MB = 1_048_576
+    # Media category constants
     DM_GIF, DM_IMAGE, DM_VIDEO, SUBTITLES, TWEET_GIF, TWEET_IMAGE, TWEET_VIDEO = MediaUploadValidator::MEDIA_CATEGORIES
-    DEFAULT_MIME_TYPE = "application/octet-stream".freeze
+    # Supported MIME types
     MIME_TYPES = %w[image/gif image/jpeg video/mp4 image/png application/x-subrip image/webp].freeze
+    # MIME type constants
     GIF_MIME_TYPE, JPEG_MIME_TYPE, MP4_MIME_TYPE, PNG_MIME_TYPE, SUBRIP_MIME_TYPE, WEBP_MIME_TYPE = MIME_TYPES
+    # Mapping of file extensions to MIME types
     MIME_TYPE_MAP = {"gif" => GIF_MIME_TYPE, "jpg" => JPEG_MIME_TYPE, "jpeg" => JPEG_MIME_TYPE, "mp4" => MP4_MIME_TYPE,
                      "png" => PNG_MIME_TYPE, "srt" => SUBRIP_MIME_TYPE, "webp" => WEBP_MIME_TYPE}.freeze
+    # Processing states that indicate completion
     PROCESSING_INFO_STATES = %w[failed succeeded].freeze
 
+    # Upload a file to the X API
+    #
+    # @api public
+    # @param client [Client] the X API client
+    # @param file_path [String] the path to the file to upload
+    # @param media_category [String] the media category
+    # @param boundary [String] the multipart boundary
+    # @return [Hash, nil] the upload response data
+    # @raise [RuntimeError] if the file does not exist
+    # @example Upload an image
+    #   MediaUploader.upload(client: client, file_path: "image.png", media_category: "tweet_image")
     def upload(client:, file_path:, media_category:, boundary: SecureRandom.hex)
       MediaUploadValidator.validate_file_path!(file_path:)
       upload_binary(client:, content: File.binread(file_path), media_category:, boundary:)
     end
 
+    # Upload binary content to the X API
+    #
+    # @api public
+    # @param client [Client] the X API client
+    # @param content [String] the binary content to upload
+    # @param media_category [String] the media category
+    # @param boundary [String] the multipart boundary
+    # @return [Hash, nil] the upload response data
+    # @raise [ArgumentError] if the media category is invalid
+    # @example Upload binary content
+    #   MediaUploader.upload_binary(client: client, content: data, media_category: "tweet_image")
     def upload_binary(client:, content:, media_category:, boundary: SecureRandom.hex)
       MediaUploadValidator.validate_media_category!(media_category:)
       upload_body = construct_upload_body(content:, media_category:, boundary:)
@@ -29,6 +60,20 @@ module X
       client.post("media/upload", upload_body, headers:)&.fetch("data")
     end
 
+    # Perform a chunked upload for large files
+    #
+    # @api public
+    # @param client [Client] the X API client
+    # @param file_path [String] the path to the file to upload
+    # @param media_category [String] the media category
+    # @param media_type [String] the MIME type of the media
+    # @param boundary [String] the multipart boundary
+    # @param chunk_size_mb [Integer] the size of each chunk in megabytes
+    # @return [Hash, nil] the upload response data
+    # @raise [RuntimeError] if the file does not exist
+    # @raise [ArgumentError] if the media category is invalid
+    # @example Upload a large video
+    #   MediaUploader.chunked_upload(client: client, file_path: "video.mp4", media_category: "tweet_video")
     def chunked_upload(client:, file_path:, media_category:, media_type: infer_media_type(file_path, media_category),
       boundary: SecureRandom.hex, chunk_size_mb: 1)
       MediaUploadValidator.validate_file_path!(file_path:)
@@ -39,6 +84,14 @@ module X
       client.post("media/upload/#{media["id"]}/finalize")&.fetch("data")
     end
 
+    # Wait for media processing to complete
+    #
+    # @api public
+    # @param client [Client] the X API client
+    # @param media [Hash] the media object with an id
+    # @return [Hash, nil] the processing status
+    # @example Wait for processing
+    #   MediaUploader.await_processing(client: client, media: media)
     def await_processing(client:, media:)
       loop do
         status = client.get("media/upload?command=STATUS&media_id=#{media["id"]}")&.fetch("data")
@@ -48,6 +101,15 @@ module X
       end
     end
 
+    # Wait for media processing and raise on failure
+    #
+    # @api public
+    # @param client [Client] the X API client
+    # @param media [Hash] the media object with an id
+    # @return [Hash, nil] the processing status
+    # @raise [RuntimeError] if media processing failed
+    # @example Wait for processing with error handling
+    #   MediaUploader.await_processing!(client: client, media: media)
     def await_processing!(client:, media:)
       status = await_processing(client:, media:)
       raise "Media processing failed" if status&.dig("processing_info", "state") == "failed"
@@ -55,17 +117,34 @@ module X
       status
     end
 
-    private
-
+    # Infer the media type from file path and category
+    #
+    # @api public
+    # @param file_path [String] the file path
+    # @param media_category [String] the media category
+    # @return [String] the inferred MIME type
+    # @raise [InvalidMediaType] if the MIME type cannot be determined
+    # @example MediaUploader.infer_media_type("image.png", "tweet_image") #=> "image/png"
     def infer_media_type(file_path, media_category)
       case media_category.downcase
       when TWEET_GIF, DM_GIF then GIF_MIME_TYPE
       when TWEET_VIDEO, DM_VIDEO then MP4_MIME_TYPE
       when SUBTITLES then SUBRIP_MIME_TYPE
-      else MIME_TYPE_MAP.fetch(File.extname(file_path).delete(".").downcase, DEFAULT_MIME_TYPE)
+      else
+        extension = File.extname(file_path).delete(".").downcase
+        MIME_TYPE_MAP.fetch(extension) do
+          raise InvalidMediaType, "unable to determine MIME type from file extension: #{file_path.inspect}"
+        end
       end
     end
 
+    private
+
+    # Split a file into chunks
+    # @api private
+    # @param file_path [String] the file path
+    # @param chunk_size [Integer] the chunk size in bytes
+    # @return [Array<String>] the paths to the chunk files
     def split(file_path, chunk_size)
       file_size = File.size(file_path)
       segment_count = (file_size.to_f / chunk_size).ceil
@@ -76,12 +155,26 @@ module X
       end
     end
 
+    # Initialize a chunked upload
+    # @api private
+    # @param client [Client] the X API client
+    # @param file_path [String] the file path
+    # @param media_type [String] the MIME type
+    # @param media_category [String] the media category
+    # @return [Hash, nil] the initialization response
     def init(client:, file_path:, media_type:, media_category:)
       total_bytes = File.size(file_path)
       data = {media_type:, media_category:, total_bytes:}.to_json
       client.post("media/upload/initialize", data)&.fetch("data")
     end
 
+    # Append chunks to a chunked upload
+    # @api private
+    # @param client [Client] the X API client
+    # @param file_paths [Array<String>] the chunk file paths
+    # @param media [Hash] the media object
+    # @param boundary [String] the multipart boundary
+    # @return [void]
     def append(client:, file_paths:, media:, boundary: SecureRandom.hex)
       threads = file_paths.map.with_index do |file_path, index|
         Thread.new do
@@ -93,6 +186,14 @@ module X
       threads.each(&:join)
     end
 
+    # Upload a single chunk with retry logic
+    # @api private
+    # @param client [Client] the X API client
+    # @param media_id [String] the media ID
+    # @param upload_body [String] the upload body
+    # @param file_path [String] the chunk file path
+    # @param headers [Hash] the request headers
+    # @return [void]
     def upload_chunk(client:, media_id:, upload_body:, file_path:, headers: {})
       client.post("media/upload/#{media_id}/append", upload_body, headers:)
     rescue NetworkError, ServerError
@@ -102,19 +203,30 @@ module X
       cleanup_file(file_path)
     end
 
+    # Clean up a temporary file
+    # @api private
+    # @param file_path [String] the file path
+    # @return [void]
     def cleanup_file(file_path)
       dirname = File.dirname(file_path)
       File.delete(file_path)
       Dir.delete(dirname) if Dir.empty?(dirname)
     end
 
+    # Construct the multipart upload body
+    # @api private
+    # @param content [String] the content to upload
+    # @param media_category [String, nil] the media category
+    # @param segment_index [Integer, nil] the segment index
+    # @param boundary [String] the multipart boundary
+    # @return [String] the upload body
     def construct_upload_body(content:, media_category: nil, segment_index: nil, boundary: SecureRandom.hex)
       body = ""
       body += "--#{boundary}\r\nContent-Disposition: form-data; name=\"segment_index\"\r\n\r\n#{segment_index}\r\n" if segment_index
       body += "--#{boundary}\r\nContent-Disposition: form-data; name=\"media_category\"\r\n\r\n#{media_category}\r\n" if media_category
       "#{body}--#{boundary}\r\n" \
         "Content-Disposition: form-data; name=\"media\"\r\n" \
-        "Content-Type: #{DEFAULT_MIME_TYPE}\r\n\r\n" \
+        "Content-Type: application/octet-stream\r\n\r\n" \
         "#{content}\r\n" \
         "--#{boundary}--\r\n"
     end

data/lib/x/oauth2_authenticator.rb

@@ -0,0 +1,169 @@
+require "base64"
+require "json"
+require "net/http"
+require "uri"
+require_relative "authenticator"
+require_relative "connection"
+
+module X
+  # Handles OAuth 2.0 authentication with token refresh capability
+  # @api public
+  class OAuth2Authenticator < Authenticator
+    # Path for the OAuth 2.0 token endpoint
+    TOKEN_PATH = "/2/oauth2/token".freeze
+    # Host for token refresh requests
+    TOKEN_HOST = "api.x.com".freeze
+    # Grant type for token refresh
+    REFRESH_GRANT_TYPE = "refresh_token".freeze
+    # Buffer time in seconds to account for clock skew and network latency
+    EXPIRATION_BUFFER = 30
+
+    # The OAuth 2.0 client ID
+    # @api public
+    # @return [String] the client ID
+    # @example Get the client ID
+    #   authenticator.client_id
+    attr_accessor :client_id
+    # The OAuth 2.0 client secret
+    # @api public
+    # @return [String] the client secret
+    # @example Get the client secret
+    #   authenticator.client_secret
+    attr_accessor :client_secret
+    # The OAuth 2.0 access token
+    # @api public
+    # @return [String] the access token
+    # @example Get the access token
+    #   authenticator.access_token
+    attr_accessor :access_token
+    # The OAuth 2.0 refresh token
+    # @api public
+    # @return [String] the refresh token
+    # @example Get the refresh token
+    #   authenticator.refresh_token
+    attr_accessor :refresh_token
+    # The expiration time of the access token
+    # @api public
+    # @return [Time, nil] the expiration time
+    # @example Get the expiration time
+    #   authenticator.expires_at
+    attr_accessor :expires_at
+
+    # The connection for making token requests
+    # @api public
+    # @return [Connection] the connection instance
+    # @example Get the connection
+    #   authenticator.connection
+    attr_accessor :connection
+
+    # Initialize a new OAuth 2.0 authenticator
+    #
+    # @api public
+    # @param client_id [String] the OAuth 2.0 client ID
+    # @param client_secret [String] the OAuth 2.0 client secret
+    # @param access_token [String] the OAuth 2.0 access token
+    # @param refresh_token [String] the OAuth 2.0 refresh token
+    # @param expires_at [Time, nil] the expiration time of the access token
+    # @param connection [Connection] the connection for making token requests
+    # @return [OAuth2Authenticator] a new authenticator instance
+    # @example Create an authenticator
+    #   authenticator = X::OAuth2Authenticator.new(
+    #     client_id: "id",
+    #     client_secret: "secret",
+    #     access_token: "token",
+    #     refresh_token: "refresh"
+    #   )
+    def initialize(client_id:, client_secret:, access_token:, refresh_token:, expires_at: nil,
+      connection: Connection.new)
+      @client_id = client_id
+      @client_secret = client_secret
+      @access_token = access_token
+      @refresh_token = refresh_token
+      @expires_at = expires_at
+      @connection = connection
+    end
+
+    # Generate the authentication header
+    #
+    # @api public
+    # @param _request [Net::HTTPRequest, nil] the HTTP request (unused)
+    # @return [Hash{String => String}] the authentication header
+    # @example Get the header
+    #   authenticator.header(request)
+    def header(_request)
+      {AUTHENTICATION_HEADER => "Bearer #{access_token}"}
+    end
+
+    # Check if the access token has expired or will expire soon
+    #
+    # @api public
+    # @return [Boolean] true if the token has expired or will expire within the buffer period
+    # @example Check expiration
+    #   authenticator.token_expired?
+    def token_expired?
+      return false if expires_at.nil?
+
+      Time.now >= expires_at - EXPIRATION_BUFFER
+    end
+
+    # Refresh the access token using the refresh token
+    #
+    # @api public
+    # @return [Hash{String => Object}] the token response
+    # @raise [Error] if token refresh fails
+    # @example Refresh the token
+    #   authenticator.refresh_token!
+    def refresh_token!
+      response = send_token_request
+      handle_token_response(response)
+    end
+
+    private
+
+    # Send the token refresh request
+    # @api private
+    # @return [Net::HTTPResponse] the HTTP response
+    def send_token_request
+      request = build_token_request
+      connection.perform(request: request)
+    end
+
+    # Build the token refresh request
+    # @api private
+    # @return [Net::HTTP::Post] the POST request
+    def build_token_request
+      uri = URI::HTTPS.build(host: TOKEN_HOST, path: TOKEN_PATH)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/x-www-form-urlencoded"
+      request["Authorization"] = "Basic #{Base64.strict_encode64("#{client_id}:#{client_secret}")}"
+      request.body = URI.encode_www_form(grant_type: REFRESH_GRANT_TYPE, refresh_token: refresh_token)
+      request
+    end
+
+    # Handle the token response
+    # @api private
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [Hash{String => Object}] the parsed response body
+    # @raise [Error] if the response indicates an error
+    def handle_token_response(response)
+      body = JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise Error, "Token refresh failed"
+    else
+      raise Error, body["error_description"] || body["error"] || "Token refresh failed" unless response.is_a?(Net::HTTPSuccess)
+
+      update_tokens(body)
+      body
+    end
+
+    # Update tokens from the response
+    # @api private
+    # @param token_response [Hash{String => Object}] the token response
+    # @return [void]
+    def update_tokens(token_response)
+      @access_token = token_response.fetch("access_token")
+      @refresh_token = token_response.fetch("refresh_token") if token_response.key?("refresh_token")
+      @expires_at = Time.now + token_response.fetch("expires_in") if token_response.key?("expires_in")
+    end
+  end
+end

data/lib/x/oauth_authenticator.rb

@@ -7,20 +7,73 @@ require "uri"
 require_relative "authenticator"
 
 module X
+  # Authenticator for OAuth 1.0a authentication
+  # @api public
   class OAuthAuthenticator < Authenticator
+    # OAuth version
     OAUTH_VERSION = "1.0".freeze
+    # OAuth signature method
     OAUTH_SIGNATURE_METHOD = "HMAC-SHA1".freeze
+    # OAuth signature algorithm
     OAUTH_SIGNATURE_ALGORITHM = "sha1".freeze
 
-    attr_accessor :api_key, :api_key_secret, :access_token, :access_token_secret
+    # The API key (consumer key)
+    # @api public
+    # @return [String] the API key (consumer key)
+    # @example Get or set the API key
+    #   authenticator.api_key = "key"
+    attr_accessor :api_key
 
-    def initialize(api_key:, api_key_secret:, access_token:, access_token_secret:) # rubocop:disable Lint/MissingSuper
+    # The API key secret (consumer secret)
+    # @api public
+    # @return [String] the API key secret (consumer secret)
+    # @example Get or set the API key secret
+    #   authenticator.api_key_secret = "secret"
+    attr_accessor :api_key_secret
+
+    # The access token
+    # @api public
+    # @return [String] the access token
+    # @example Get or set the access token
+    #   authenticator.access_token = "token"
+    attr_accessor :access_token
+
+    # The access token secret
+    # @api public
+    # @return [String] the access token secret
+    # @example Get or set the access token secret
+    #   authenticator.access_token_secret = "token_secret"
+    attr_accessor :access_token_secret
+
+    # Initialize a new OAuthAuthenticator
+    #
+    # @api public
+    # @param api_key [String] the API key (consumer key)
+    # @param api_key_secret [String] the API key secret (consumer secret)
+    # @param access_token [String] the access token
+    # @param access_token_secret [String] the access token secret
+    # @return [OAuthAuthenticator] a new instance
+    # @example Create an OAuth authenticator
+    #   authenticator = X::OAuthAuthenticator.new(
+    #     api_key: "key",
+    #     api_key_secret: "secret",
+    #     access_token: "token",
+    #     access_token_secret: "token_secret"
+    #   )
+    def initialize(api_key:, api_key_secret:, access_token:, access_token_secret:)
       @api_key = api_key
       @api_key_secret = api_key_secret
       @access_token = access_token
       @access_token_secret = access_token_secret
     end
 
+    # Generate the OAuth authentication header for a request
+    #
+    # @api public
+    # @param request [Net::HTTPRequest] the HTTP request
+    # @return [Hash{String => String}] the authentication header with OAuth signature
+    # @example Generate an OAuth authentication header
+    #   authenticator.header(request)
     def header(request)
       method, url, query_params = parse_request(request)
       {AUTHENTICATION_HEADER => build_oauth_header(method, url, query_params)}
@@ -28,20 +81,38 @@ module X
 
     private
 
+    # Parse the request to extract method, URL, and query parameters
+    # @api private
+    # @param request [Net::HTTPRequest] the HTTP request
+    # @return [Array<String, String, Hash>] the method, URL, and query parameters
     def parse_request(request)
       uri = request.uri
       query_params = parse_query_params(uri.query.to_s)
       [request.method, uri_without_query(uri), query_params]
     end
 
+    # Parse query parameters from a query string
+    # @api private
+    # @param query_string [String] the query string
+    # @return [Hash] the parsed query parameters
     def parse_query_params(query_string)
       URI.decode_www_form(query_string).to_h
     end
 
+    # Get the URI without query parameters
+    # @api private
+    # @param uri [URI] the URI
+    # @return [String] the URI without query parameters
     def uri_without_query(uri)
       "#{uri.scheme}://#{uri.host}#{uri.path}"
     end
 
+    # Build the OAuth header value
+    # @api private
+    # @param method [String] the HTTP method
+    # @param url [String] the request URL
+    # @param query_params [Hash] the query parameters
+    # @return [String] the OAuth header value
     def build_oauth_header(method, url, query_params)
       oauth_params = default_oauth_params
       all_params = query_params.merge(oauth_params)
@@ -49,6 +120,9 @@ module X
       format_oauth_header(oauth_params)
     end
 
+    # Get the default OAuth parameters
+    # @api private
+    # @return [Hash] the default OAuth parameters
     def default_oauth_params
       {
         "oauth_consumer_key" => api_key,
@@ -60,24 +134,47 @@ module X
       }
     end
 
+    # Generate the OAuth signature
+    # @api private
+    # @param method [String] the HTTP method
+    # @param url [String] the request URL
+    # @param params [Hash] the combined parameters
+    # @return [String] the OAuth signature
     def generate_signature(method, url, params)
       base_string = signature_base_string(method, url, params)
       hmac_signature(base_string)
     end
 
+    # Generate the HMAC signature
+    # @api private
+    # @param base_string [String] the signature base string
+    # @return [String] the Base64-encoded HMAC signature
     def hmac_signature(base_string)
       hmac = OpenSSL::HMAC.digest(OAUTH_SIGNATURE_ALGORITHM, signing_key, base_string)
       Base64.strict_encode64(hmac)
     end
 
+    # Build the signature base string
+    # @api private
+    # @param method [String] the HTTP method
+    # @param url [String] the request URL
+    # @param params [Hash] the combined parameters
+    # @return [String] the signature base string
     def signature_base_string(method, url, params)
       "#{method}&#{CGI.escapeURIComponent(url)}&#{CGI.escapeURIComponent(URI.encode_www_form(params.sort).gsub("+", "%20"))}"
     end
 
+    # Get the signing key
+    # @api private
+    # @return [String] the signing key
     def signing_key
       "#{api_key_secret}&#{access_token_secret}"
     end
 
+    # Format the OAuth header value
+    # @api private
+    # @param params [Hash] the OAuth parameters
+    # @return [String] the formatted OAuth header value
     def format_oauth_header(params)
       "OAuth #{params.sort.map { |k, v| "#{k}=\"#{CGI.escapeURIComponent(v)}\"" }.join(", ")}"
     end

data/lib/x/rate_limit.rb

@@ -1,33 +1,89 @@
 module X
+  # Represents rate limit information from an API response
+  # @api public
   class RateLimit
+    # Rate limit type identifier
     RATE_LIMIT_TYPE = "rate-limit".freeze
+    # App limit type identifier
     APP_LIMIT_TYPE = "app-limit-24hour".freeze
+    # User limit type identifier
     USER_LIMIT_TYPE = "user-limit-24hour".freeze
+    # All supported rate limit types
     TYPES = [RATE_LIMIT_TYPE, APP_LIMIT_TYPE, USER_LIMIT_TYPE].freeze
 
-    attr_accessor :type, :response
+    # The type of rate limit
+    # @api public
+    # @return [String] the type of rate limit
+    # @example Get or set the rate limit type
+    #   rate_limit.type = "rate-limit"
+    attr_accessor :type
 
+    # The HTTP response containing rate limit headers
+    # @api public
+    # @return [Net::HTTPResponse] the HTTP response containing rate limit headers
+    # @example Get or set the response
+    #   rate_limit.response = http_response
+    attr_accessor :response
+
+    # Initialize a new RateLimit
+    #
+    # @api public
+    # @param type [String] the type of rate limit
+    # @param response [Net::HTTPResponse] the HTTP response containing rate limit headers
+    # @return [RateLimit] a new instance
+    # @example Create a rate limit instance
+    #   rate_limit = X::RateLimit.new(type: "rate-limit", response: response)
     def initialize(type:, response:)
       @type = type
       @response = response
     end
 
+    # Get the rate limit maximum
+    #
+    # @api public
+    # @return [Integer] the maximum number of requests allowed
+    # @example Get the rate limit
+    #   rate_limit.limit
     def limit
       Integer(response.fetch("x-#{type}-limit"))
     end
 
+    # Get the remaining requests
+    #
+    # @api public
+    # @return [Integer] the number of requests remaining
+    # @example Get the remaining requests
+    #   rate_limit.remaining
     def remaining
       Integer(response.fetch("x-#{type}-remaining"))
     end
 
+    # Get the time when the rate limit resets
+    #
+    # @api public
+    # @return [Time] the time when the rate limit resets
+    # @example Get the reset time
+    #   rate_limit.reset_at
     def reset_at
       Time.at(Integer(response.fetch("x-#{type}-reset")))
     end
 
+    # Get the seconds until the rate limit resets
+    #
+    # @api public
+    # @return [Integer] the seconds until the rate limit resets
+    # @example Get the reset time in seconds
+    #   rate_limit.reset_in
     def reset_in
       [(reset_at - Time.now).ceil, 0].max
     end
 
+    # @!method retry_after
+    #   Alias for reset_in, returns the seconds until the rate limit resets
+    #   @api public
+    #   @return [Integer] the seconds until the rate limit resets
+    #   @example Get the retry after time
+    #     rate_limit.retry_after
     alias_method :retry_after, :reset_in
   end
 end