x 0.17.0 → 0.19.0

data/lib/x/redirect_handler.rb

@@ -6,12 +6,42 @@ require_relative "errors/too_many_redirects"
 require_relative "request_builder"
 
 module X
+  # Handles HTTP redirects for API requests
+  # @api public
   class RedirectHandler
+    # Default maximum number of redirects to follow
     DEFAULT_MAX_REDIRECTS = 10
 
+    # The maximum number of redirects to follow
+    # @api public
+    # @return [Integer] the maximum number of redirects to follow
+    # @example Get or set the maximum redirects
+    #   handler.max_redirects = 5
     attr_accessor :max_redirects
-    attr_reader :connection, :request_builder
 
+    # The connection for making requests
+    # @api public
+    # @return [Connection] the connection for making requests
+    # @example Get the connection
+    #   handler.connection
+    attr_reader :connection
+
+    # The request builder for creating requests
+    # @api public
+    # @return [RequestBuilder] the request builder for creating requests
+    # @example Get the request builder
+    #   handler.request_builder
+    attr_reader :request_builder
+
+    # Initialize a new RedirectHandler
+    #
+    # @api public
+    # @param connection [Connection] the connection for making requests
+    # @param request_builder [RequestBuilder] the request builder for creating requests
+    # @param max_redirects [Integer] the maximum number of redirects to follow
+    # @return [RedirectHandler] a new instance
+    # @example Create a redirect handler
+    #   handler = X::RedirectHandler.new(connection: conn, request_builder: builder)
     def initialize(connection: Connection.new, request_builder: RequestBuilder.new,
       max_redirects: DEFAULT_MAX_REDIRECTS)
       @connection = connection
@@ -19,6 +49,18 @@ module X
       @max_redirects = max_redirects
     end
 
+    # Handle redirects for an HTTP response
+    #
+    # @api public
+    # @param response [Net::HTTPResponse] the HTTP response to handle
+    # @param request [Net::HTTPRequest] the original HTTP request
+    # @param base_url [String] the base URL for the request
+    # @param authenticator [Authenticator] the authenticator for requests
+    # @param redirect_count [Integer] the current redirect count
+    # @return [Net::HTTPResponse] the final HTTP response after following redirects
+    # @raise [TooManyRedirects] if the maximum number of redirects is exceeded
+    # @example Handle a response
+    #   response = handler.handle(response: resp, request: req, base_url: url)
     def handle(response:, request:, base_url:, authenticator: Authenticator.new, redirect_count: 0)
       if response.is_a?(Net::HTTPRedirection)
         raise TooManyRedirects, "Too many redirects" if redirect_count > max_redirects
@@ -36,12 +78,24 @@ module X
 
     private
 
+    # Build a new URI from the redirect response
+    # @api private
+    # @param response [Net::HTTPResponse] the redirect response
+    # @param base_url [String] the base URL
+    # @return [URI] the new URI
     def build_new_uri(response, base_url)
       location = response.fetch("location")
       # If location is relative, it will join with the original base URL, otherwise it will overwrite it
       URI.join(base_url, location)
     end
 
+    # Build a new request for the redirect
+    # @api private
+    # @param request [Net::HTTPRequest] the original request
+    # @param uri [URI] the new URI
+    # @param response_code [Integer] the HTTP response code
+    # @param authenticator [Authenticator] the authenticator
+    # @return [Net::HTTPRequest] the new request
     def build_request(request, uri, response_code, authenticator)
       http_method = :get
       if [307, 308].include?(response_code)

data/lib/x/request_builder.rb

@@ -4,11 +4,15 @@ require_relative "authenticator"
 require_relative "version"
 
 module X
+  # Builds HTTP requests for the X API
+  # @api public
   class RequestBuilder
+    # Default headers for API requests
     DEFAULT_HEADERS = {
       "Content-Type" => "application/json; charset=utf-8",
       "User-Agent" => "X-Client/#{VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
     }.freeze
+    # Mapping of HTTP method symbols to Net::HTTP classes
     HTTP_METHODS = {
       get: Net::HTTP::Get,
       post: Net::HTTP::Post,
@@ -16,6 +20,18 @@ module X
       delete: Net::HTTP::Delete
     }.freeze
 
+    # Build an HTTP request
+    #
+    # @api public
+    # @param http_method [Symbol] the HTTP method (:get, :post, :put, :delete)
+    # @param uri [URI] the request URI
+    # @param body [String, nil] the request body
+    # @param headers [Hash] additional headers for the request
+    # @param authenticator [Authenticator] the authenticator for the request
+    # @return [Net::HTTPRequest] the built HTTP request
+    # @raise [ArgumentError] if the HTTP method is not supported
+    # @example Build a GET request
+    #   builder.build(http_method: :get, uri: URI("https://api.x.com/2/users/me"))
     def build(http_method:, uri:, body: nil, headers: {}, authenticator: Authenticator.new)
       request = create_request(http_method:, uri:, body:)
       add_headers(request:, headers:)
@@ -25,6 +41,12 @@ module X
 
     private
 
+    # Create an HTTP request
+    # @api private
+    # @param http_method [Symbol] the HTTP method
+    # @param uri [URI] the request URI
+    # @param body [String, nil] the request body
+    # @return [Net::HTTPRequest] the created request
     def create_request(http_method:, uri:, body:)
       http_method_class = HTTP_METHODS[http_method]
 
@@ -36,18 +58,32 @@ module X
       request
     end
 
+    # Add authentication to a request
+    # @api private
+    # @param request [Net::HTTPRequest] the request
+    # @param authenticator [Authenticator] the authenticator
+    # @return [void]
     def add_authentication(request:, authenticator:)
       authenticator.header(request).each do |key, value|
         request[key] = value
       end
     end
 
+    # Add headers to a request
+    # @api private
+    # @param request [Net::HTTPRequest] the request
+    # @param headers [Hash] additional headers
+    # @return [void]
     def add_headers(request:, headers:)
       DEFAULT_HEADERS.merge(headers).each do |key, value|
         request[key] = value
       end
     end
 
+    # Escape query parameters in a URI
+    # @api private
+    # @param uri [URI] the URI
+    # @return [URI] the URI with escaped query parameters
     def escape_query_params(uri)
       URI(uri).tap do |u|
         u.query = URI.encode_www_form(URI.decode_www_form(u.query)).gsub("%2C", ",") if u.query

data/lib/x/response_parser.rb

@@ -17,7 +17,10 @@ require_relative "errors/unauthorized"
 require_relative "errors/unprocessable_entity"
 
 module X
+  # Parses HTTP responses from the X API
+  # @api public
   class ResponseParser
+    # Mapping of HTTP status codes to error classes
     ERROR_MAP = {
       400 => BadRequest,
       401 => Unauthorized,
@@ -35,6 +38,16 @@ module X
       504 => GatewayTimeout
     }.freeze
 
+    # Parse an HTTP response
+    #
+    # @api public
+    # @param response [Net::HTTPResponse] the HTTP response to parse
+    # @param array_class [Class, nil] the class for parsing JSON arrays
+    # @param object_class [Class, nil] the class for parsing JSON objects
+    # @return [Hash, Array, nil] the parsed response body
+    # @raise [HTTPError] if the response is not successful
+    # @example Parse a response
+    #   parser.parse(response: response)
     def parse(response:, array_class: nil, object_class: nil)
       raise error(response) unless response.is_a?(Net::HTTPSuccess)
 
@@ -49,10 +62,18 @@ module X
 
     private
 
+    # Create an error from a response
+    # @api private
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [HTTPError] the error
     def error(response)
       error_class(response).new(response:)
     end
 
+    # Get the error class for a response
+    # @api private
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [Class] the error class
     def error_class(response)
       ERROR_MAP[Integer(response.code)] || HTTPError
     end

data/lib/x/stream_parser.rb

@@ -0,0 +1,75 @@
+require "json"
+require "net/http"
+require_relative "response_parser"
+
+module X
+  # Handles streaming responses from the X API
+  # @api public
+  class StreamParser
+    # Line delimiter for streaming responses
+    LINE_DELIMITER = "\r\n".freeze
+
+    # Process a streaming response and yield parsed JSON objects
+    #
+    # @api public
+    # @param response [Net::HTTPResponse] the HTTP response to stream
+    # @param response_parser [ResponseParser] the response parser for error handling
+    # @param array_class [Class, nil] the class for parsing JSON arrays
+    # @param object_class [Class, nil] the class for parsing JSON objects
+    # @yield [Hash, Array] each parsed JSON object from the stream
+    # @return [void]
+    # @raise [HTTPError] if the response is not successful
+    # @example Process a streaming response
+    #   handler.process(response: response, response_parser: parser) { |json| puts json }
+    def process(response:, response_parser:, array_class: nil, object_class: nil, &block)
+      response_parser.parse(response:) unless response.is_a?(Net::HTTPSuccess)
+
+      buffer = +""
+      response.read_body do |chunk|
+        buffer << chunk
+        process_buffer(buffer:, array_class:, object_class:, &block)
+      end
+      process_remaining(buffer:, array_class:, object_class:, &block)
+    end
+
+    private
+
+    # Process complete lines from the buffer
+    # @api private
+    # @param buffer [String] the accumulated data buffer
+    # @param array_class [Class, nil] the class for parsing JSON arrays
+    # @param object_class [Class, nil] the class for parsing JSON objects
+    # @yield [Hash, Array] each parsed JSON object
+    # @return [void]
+    def process_buffer(buffer:, array_class:, object_class:, &)
+      while (line_end = buffer.index(LINE_DELIMITER))
+        line = buffer.slice!(0, line_end) # : String
+        buffer.delete_prefix!(LINE_DELIMITER)
+        yield_json(line:, array_class:, object_class:, &) unless line.empty?
+      end
+    end
+
+    # Process any remaining data after the stream ends
+    # @api private
+    # @param buffer [String] the remaining data buffer
+    # @param array_class [Class, nil] the class for parsing JSON arrays
+    # @param object_class [Class, nil] the class for parsing JSON objects
+    # @yield [Hash, Array] the parsed JSON object
+    # @return [void]
+    def process_remaining(buffer:, array_class:, object_class:, &)
+      buffer.strip!
+      yield_json(line: buffer, array_class:, object_class:, &) unless buffer.empty?
+    end
+
+    # Parse a line as JSON and yield the result
+    # @api private
+    # @param line [String] the JSON line to parse
+    # @param array_class [Class, nil] the class for parsing JSON arrays
+    # @param object_class [Class, nil] the class for parsing JSON objects
+    # @yield [Hash, Array] the parsed JSON object
+    # @return [void]
+    def yield_json(line:, array_class:, object_class:)
+      yield JSON.parse(line, array_class:, object_class:)
+    end
+  end
+end

data/lib/x/version.rb

@@ -1,5 +1,6 @@
 require "rubygems/version"
 
 module X
-  VERSION = Gem::Version.create("0.17.0")
+  # The current version of the X gem
+  VERSION = Gem::Version.create("0.19.0")
 end

data/sig/x.rbs

@@ -101,6 +101,9 @@ module X
   class TooManyRedirects < Error
   end
 
+  class InvalidMediaType < Error
+  end
+
   class TooManyRequests < ClientError
     @rate_limits: Array[RateLimit]
 
@@ -122,7 +125,7 @@ module X
     DEFAULT_OPEN_TIMEOUT: Integer
     DEFAULT_READ_TIMEOUT: Integer
     DEFAULT_WRITE_TIMEOUT: Integer
-    DEFAULT_DEBUG_OUTPUT: IO
+
     NETWORK_ERRORS: Array[(singleton(Errno::ECONNREFUSED) | singleton(Errno::ECONNRESET) | singleton(Net::OpenTimeout) | singleton(Net::ReadTimeout) | singleton(OpenSSL::SSL::SSLError))]
 
     @proxy_url: URI::Generic | String
@@ -143,6 +146,7 @@ module X
     def initialize: (?open_timeout: Float | Integer, ?read_timeout: Float | Integer, ?write_timeout: Float | Integer, ?proxy_url: URI::Generic? | String?, ?debug_output: IO) -> void
     def proxy_url=: (URI::Generic | String proxy_url) -> void
     def perform: (request: Net::HTTPRequest) -> Net::HTTPResponse
+    def perform_stream: (request: Net::HTTPRequest) { (Net::HTTPResponse) -> void } -> void
 
     private
     def build_http_client: (?String host, ?Integer port) -> Net::HTTP
@@ -205,40 +209,94 @@ module X
     def json?: (Net::HTTPResponse response) -> bool
   end
 
+  class StreamParser
+    LINE_DELIMITER: String
+
+    def process: (response: Net::HTTPResponse, response_parser: ResponseParser, ?array_class: Class?, ?object_class: Class?) { (untyped) -> void } -> void
+
+    private
+    def process_buffer: (buffer: String, array_class: Class?, object_class: Class?) { (untyped) -> void } -> void
+    def process_remaining: (buffer: String, array_class: Class?, object_class: Class?) { (untyped) -> void } -> void
+    def yield_json: (line: String, array_class: Class?, object_class: Class?) { (untyped) -> void } -> void
+  end
+
+  class OAuth2Authenticator < Authenticator
+    TOKEN_PATH: String
+    TOKEN_HOST: String
+    REFRESH_GRANT_TYPE: String
+    EXPIRATION_BUFFER: Integer
+
+    attr_accessor client_id: String
+    attr_accessor client_secret: String
+    attr_accessor access_token: String
+    attr_accessor refresh_token: String
+    attr_accessor expires_at: Time?
+    attr_accessor connection: Connection
+    def initialize: (client_id: String, client_secret: String, access_token: String, refresh_token: String, ?expires_at: Time?, ?connection: Connection) -> void
+    def header: (Net::HTTPRequest? request) -> Hash[String, String]
+    def token_expired?: -> bool
+    def refresh_token!: -> Hash[String, untyped]
+
+    private
+    def send_token_request: -> Net::HTTPResponse
+    def build_token_request: -> Net::HTTP::Post
+    def handle_token_response: (Net::HTTPResponse response) -> Hash[String, untyped]
+    def update_tokens: (Hash[String, untyped] token_response) -> void
+  end
+
+  module ClientCredentials
+    attr_reader api_key: String?
+    attr_reader api_key_secret: String?
+    attr_reader access_token: String?
+    attr_reader access_token_secret: String?
+    attr_reader bearer_token: String?
+    attr_reader client_id: String?
+    attr_reader client_secret: String?
+    attr_reader refresh_token: String?
+    def api_key=: (String api_key) -> void
+    def api_key_secret=: (String api_key_secret) -> void
+    def access_token=: (String access_token) -> void
+    def access_token_secret=: (String access_token_secret) -> void
+    def bearer_token=: (String bearer_token) -> void
+    def client_id=: (String client_id) -> void
+    def client_secret=: (String client_secret) -> void
+    def refresh_token=: (String refresh_token) -> void
+
+    private
+    def initialize_credentials: (api_key: String?, api_key_secret: String?, access_token: String?, access_token_secret: String?, bearer_token: String?, client_id: String?, client_secret: String?, refresh_token: String?) -> void
+    def initialize_authenticator: -> (Authenticator | BearerTokenAuthenticator | OAuthAuthenticator | OAuth2Authenticator)
+    def oauth_authenticator: -> OAuthAuthenticator?
+    def oauth2_authenticator: -> OAuth2Authenticator?
+    def bearer_authenticator: -> BearerTokenAuthenticator?
+  end
+
   class Client
+    include ClientCredentials
+
     DEFAULT_BASE_URL: String
     DEFAULT_ARRAY_CLASS: singleton(Array)
     DEFAULT_OBJECT_CLASS: singleton(Hash)
     extend Forwardable
-    @authenticator: Authenticator | BearerTokenAuthenticator | OAuthAuthenticator
+    @authenticator: Authenticator | BearerTokenAuthenticator | OAuthAuthenticator | OAuth2Authenticator
     @connection: Connection
     @request_builder: RequestBuilder
     @redirect_handler: RedirectHandler
     @response_parser: ResponseParser
+    @stream_parser: StreamParser
 
     attr_accessor base_url: String
     attr_accessor default_array_class: singleton(Array)
     attr_accessor default_object_class: singleton(Hash)
-    attr_reader api_key: String?
-    attr_reader api_key_secret: String?
-    attr_reader access_token: String?
-    attr_reader access_token_secret: String?
-    attr_reader bearer_token: String?
-    def initialize: (?api_key: nil, ?api_key_secret: nil, ?access_token: nil, ?access_token_secret: nil, ?bearer_token: nil, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer, ?debug_output: untyped, ?proxy_url: nil, ?default_array_class: singleton(Array), ?default_object_class: singleton(Hash), ?max_redirects: Integer) -> void
+    attr_reader authenticator: Authenticator | BearerTokenAuthenticator | OAuthAuthenticator | OAuth2Authenticator
+    def initialize: (?api_key: String?, ?api_key_secret: String?, ?access_token: String?, ?access_token_secret: String?, ?bearer_token: String?, ?client_id: String?, ?client_secret: String?, ?refresh_token: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer, ?debug_output: untyped, ?proxy_url: String?, ?default_array_class: singleton(Array), ?default_object_class: singleton(Hash), ?max_redirects: Integer) -> void
     def get: (String endpoint, ?headers: Hash[String, String], ?array_class: Class, ?object_class: Class) -> untyped
     def post: (String endpoint, ?String? body, ?headers: Hash[String, String], ?array_class: Class, ?object_class: Class) -> untyped
     def put: (String endpoint, ?String? body, ?headers: Hash[String, String], ?array_class: Class, ?object_class: Class) -> untyped
     def delete: (String endpoint, ?headers: Hash[String, String], ?array_class: Class, ?object_class: Class) -> untyped
-    def api_key=: (String api_key) -> void
-    def api_key_secret=: (String api_key_secret) -> void
-    def access_token=: (String access_token) -> void
-    def access_token_secret=: (String access_token_secret) -> void
-    def bearer_token=: (String bearer_token) -> void
+    def stream: (String endpoint, ?headers: Hash[String, String], ?array_class: Class, ?object_class: Class) { (untyped) -> void } -> void
 
     private
-    def initialize_oauth: (String? api_key, String? api_key_secret, String? access_token, String? access_token_secret, String? bearer_token) -> void
-    def initialize_default_classes: (singleton(Array) default_array_class, singleton(Hash) default_object_class) -> singleton(Hash)
-    def initialize_authenticator: -> (Authenticator | BearerTokenAuthenticator | OAuthAuthenticator)
+    def initialize_default_classes: (default_array_class: singleton(Array), default_object_class: singleton(Hash)) -> void
     def execute_request: (:delete | :get | :post | :put http_method, String endpoint, ?body: String?, ?headers: Hash[String, String], ?array_class: Class, ?object_class: Class) -> nil
   end
 
@@ -252,7 +310,6 @@ module X
     TWEET_GIF: String
     TWEET_IMAGE: String
     TWEET_VIDEO: String
-    DEFAULT_MIME_TYPE: String
     MIME_TYPES: Array[String]
     GIF_MIME_TYPE: String
     JPEG_MIME_TYPE: String
@@ -269,9 +326,9 @@ module X
     def chunked_upload: (client: Client, file_path: String, media_category: String, ?media_type: String, ?boundary: String, ?chunk_size_mb: Integer) -> untyped
     def await_processing: (client: Client, media: untyped) -> untyped
     def await_processing!: (client: Client, media: untyped) -> untyped
+    def infer_media_type: (String file_path, String media_category) -> String
 
     private
-    def infer_media_type: (String file_path, String media_category) -> String
     def split: (String file_path, Integer chunk_size) -> Array[String]
     def init: (client: Client, file_path: String, media_type: String, media_category: String) -> untyped
     def append: (client: Client, file_paths: Array[String], media: untyped, ?boundary: String) -> Array[String]
@@ -288,4 +345,23 @@ module X
     def validate_file_path!: (file_path: String) -> nil
     def validate_media_category!: (media_category: String) -> nil
   end
+
+  module AccountUploader
+    V1_BASE_URL: String
+    SUPPORTED_EXTENSIONS: Array[String]
+    MIME_TYPE_MAP: Hash[String, String]
+    extend AccountUploader
+
+    def update_profile_image: (client: Client, file_path: String, ?boundary: String) -> untyped
+    def upload_profile_image_binary: (client: Client, content: String, ?boundary: String) -> untyped
+    def update_profile_banner: (client: Client, file_path: String, ?width: Integer?, ?height: Integer?, ?offset_left: Integer?, ?offset_top: Integer?, ?boundary: String) -> untyped
+    def upload_profile_banner_binary: (client: Client, content: String, ?width: Integer?, ?height: Integer?, ?offset_left: Integer?, ?offset_top: Integer?, ?boundary: String) -> untyped
+
+    private
+    def v1_client: (Client client) -> Client
+    def validate_file!: (String file_path) -> nil
+    def construct_multipart_body: (field_name: String, content: String, boundary: String) -> String
+    def construct_banner_body: (content: String, width: Integer?, height: Integer?, offset_left: Integer?, offset_top: Integer?, boundary: String) -> String
+    def multipart_field: (String name, untyped value, String boundary) -> String
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: x
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Erik Berlin
@@ -35,9 +35,11 @@ files:
 - bin/console
 - bin/setup
 - lib/x.rb
+- lib/x/account_uploader.rb
 - lib/x/authenticator.rb
 - lib/x/bearer_token_authenticator.rb
 - lib/x/client.rb
+- lib/x/client_credentials.rb
 - lib/x/connection.rb
 - lib/x/errors/bad_gateway.rb
 - lib/x/errors/bad_request.rb
@@ -49,6 +51,7 @@ files:
 - lib/x/errors/gone.rb
 - lib/x/errors/http_error.rb
 - lib/x/errors/internal_server_error.rb
+- lib/x/errors/invalid_media_type.rb
 - lib/x/errors/network_error.rb
 - lib/x/errors/not_acceptable.rb
 - lib/x/errors/not_found.rb
@@ -61,11 +64,13 @@ files:
 - lib/x/errors/unprocessable_entity.rb
 - lib/x/media_upload_validator.rb
 - lib/x/media_uploader.rb
+- lib/x/oauth2_authenticator.rb
 - lib/x/oauth_authenticator.rb
 - lib/x/rate_limit.rb
 - lib/x/redirect_handler.rb
 - lib/x/request_builder.rb
 - lib/x/response_parser.rb
+- lib/x/stream_parser.rb
 - lib/x/version.rb
 - sig/x.rbs
 homepage: https://sferik.github.io/x-ruby
@@ -94,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.7
 specification_version: 4
 summary: A Ruby interface to the X API.
 test_files: []