x 0.19.0 → 1.0.0

data/lib/x/account_uploader.rb

@@ -1,168 +0,0 @@
-require "base64"
-require "securerandom"
-require_relative "errors/invalid_media_type"
-
-module X
-  # Uploads profile images and banners to the X API v1.1
-  # @api public
-  module AccountUploader
-    extend self
-
-    # Base URL for X API v1.1 account endpoints
-    V1_BASE_URL = "https://api.x.com/1.1/".freeze
-    # Supported image extensions for profile uploads
-    SUPPORTED_EXTENSIONS = %w[gif jpg jpeg png].freeze
-    # Mapping of file extensions to MIME types
-    MIME_TYPE_MAP = {"gif" => "image/gif", "jpg" => "image/jpeg", "jpeg" => "image/jpeg", "png" => "image/png"}.freeze
-
-    # Update the authenticating user's profile image
-    #
-    # @api public
-    # @param client [Client] the X API client
-    # @param file_path [String] the path to the image file
-    # @param boundary [String] the multipart boundary
-    # @return [Hash, nil] the updated user object
-    # @raise [RuntimeError] if the file does not exist
-    # @raise [InvalidMediaType] if the file type is not supported
-    # @example Update profile image from a file
-    #   AccountUploader.update_profile_image(client: client, file_path: "avatar.png")
-    def update_profile_image(client:, file_path:, boundary: SecureRandom.hex)
-      validate_file!(file_path)
-      upload_profile_image_binary(client:, content: File.binread(file_path), boundary:)
-    end
-
-    # Update the authenticating user's profile image from binary content
-    #
-    # @api public
-    # @param client [Client] the X API client
-    # @param content [String] the binary image content
-    # @param boundary [String] the multipart boundary
-    # @return [Hash, nil] the updated user object
-    # @example Update profile image from binary content
-    #   AccountUploader.upload_profile_image_binary(client: client, content: image_data)
-    def upload_profile_image_binary(client:, content:, boundary: SecureRandom.hex)
-      body = construct_multipart_body(field_name: "image", content:, boundary:)
-      headers = {"Content-Type" => "multipart/form-data; boundary=#{boundary}"}
-      v1_client(client).post("account/update_profile_image.json", body, headers:)
-    end
-
-    # Update the authenticating user's profile banner
-    #
-    # @api public
-    # @param client [Client] the X API client
-    # @param file_path [String] the path to the image file
-    # @param width [Integer, nil] the width of the banner
-    # @param height [Integer, nil] the height of the banner
-    # @param offset_left [Integer, nil] the left offset of the banner
-    # @param offset_top [Integer, nil] the top offset of the banner
-    # @param boundary [String] the multipart boundary
-    # @return [Hash, nil] nil on success (204 No Content)
-    # @raise [RuntimeError] if the file does not exist
-    # @raise [InvalidMediaType] if the file type is not supported
-    # @example Update profile banner from a file
-    #   AccountUploader.update_profile_banner(client: client, file_path: "banner.png")
-    # @example Update profile banner with dimensions
-    #   AccountUploader.update_profile_banner(client: client, file_path: "banner.png", width: 1500, height: 500)
-    def update_profile_banner(client:, file_path:, width: nil, height: nil, offset_left: nil, offset_top: nil,
-      boundary: SecureRandom.hex)
-      validate_file!(file_path)
-      upload_profile_banner_binary(client:, content: File.binread(file_path), width:, height:, offset_left:,
-        offset_top:, boundary:)
-    end
-
-    # Update the authenticating user's profile banner from binary content
-    #
-    # @api public
-    # @param client [Client] the X API client
-    # @param content [String] the binary image content
-    # @param width [Integer, nil] the width of the banner
-    # @param height [Integer, nil] the height of the banner
-    # @param offset_left [Integer, nil] the left offset of the banner
-    # @param offset_top [Integer, nil] the top offset of the banner
-    # @param boundary [String] the multipart boundary
-    # @return [Hash, nil] nil on success (204 No Content)
-    # @example Update profile banner from binary content
-    #   AccountUploader.upload_profile_banner_binary(client: client, content: image_data)
-    def upload_profile_banner_binary(client:, content:, width: nil, height: nil, offset_left: nil, offset_top: nil,
-      boundary: SecureRandom.hex)
-      body = construct_banner_body(content:, width:, height:, offset_left:, offset_top:, boundary:)
-      headers = {"Content-Type" => "multipart/form-data; boundary=#{boundary}"}
-      v1_client(client).post("account/update_profile_banner.json", body, headers:)
-    end
-
-    private
-
-    # Create a v1.1 API client from an existing client
-    # @api private
-    # @param client [Client] the original client
-    # @return [Client] a client configured for v1.1 API
-    def v1_client(client)
-      Client.new(
-        api_key: client.api_key,
-        api_key_secret: client.api_key_secret,
-        access_token: client.access_token,
-        access_token_secret: client.access_token_secret,
-        base_url: V1_BASE_URL
-      )
-    end
-
-    # Validate that the file exists and has a supported extension
-    # @api private
-    # @param file_path [String] the file path
-    # @return [nil]
-    # @raise [RuntimeError] if the file does not exist
-    # @raise [InvalidMediaType] if the file type is not supported
-    def validate_file!(file_path)
-      raise "File not found: #{file_path}" unless File.exist?(file_path)
-
-      extension = File.extname(file_path).delete(".").downcase
-      return if SUPPORTED_EXTENSIONS.include?(extension)
-
-      raise InvalidMediaType, "Unsupported file type: #{extension}. Supported types: #{SUPPORTED_EXTENSIONS.join(", ")}"
-    end
-
-    # Construct multipart body for profile image upload
-    # @api private
-    # @param field_name [String] the form field name
-    # @param content [String] the binary content
-    # @param boundary [String] the multipart boundary
-    # @return [String] the multipart body
-    def construct_multipart_body(field_name:, content:, boundary:)
-      "--#{boundary}\r\n" \
-        "Content-Disposition: form-data; name=\"#{field_name}\"\r\n" \
-        "Content-Type: application/octet-stream\r\n\r\n" \
-        "#{content}\r\n" \
-        "--#{boundary}--\r\n"
-    end
-
-    # Construct multipart body for profile banner upload with optional dimensions
-    # @api private
-    # @param content [String] the binary content
-    # @param width [Integer, nil] the width
-    # @param height [Integer, nil] the height
-    # @param offset_left [Integer, nil] the left offset
-    # @param offset_top [Integer, nil] the top offset
-    # @param boundary [String] the multipart boundary
-    # @return [String] the multipart body
-    def construct_banner_body(content:, width:, height:, offset_left:, offset_top:, boundary:)
-      body = ""
-      body += multipart_field("width", width, boundary) if width
-      body += multipart_field("height", height, boundary) if height
-      body += multipart_field("offset_left", offset_left, boundary) if offset_left
-      body += multipart_field("offset_top", offset_top, boundary) if offset_top
-      body + construct_multipart_body(field_name: "banner", content:, boundary:)
-    end
-
-    # Create a multipart form field
-    # @api private
-    # @param name [String] the field name
-    # @param value [Object] the field value
-    # @param boundary [String] the multipart boundary
-    # @return [String] the multipart field
-    def multipart_field(name, value, boundary)
-      "--#{boundary}\r\n" \
-        "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n" \
-        "#{value}\r\n"
-    end
-  end
-end

data/lib/x/authenticator.rb

@@ -1,21 +0,0 @@
-# A Ruby client for the X API
-module X
-  # Base class for authentication
-  # @api public
-  class Authenticator
-    # The HTTP header name for authentication
-    AUTHENTICATION_HEADER = "Authorization".freeze
-
-    # Generate the authentication header for a request
-    #
-    # @api public
-    # @param _request [Net::HTTPRequest] the HTTP request
-    # @return [Hash{String => String}] the authentication header
-    # @example Generate an empty authentication header
-    #   authenticator = X::Authenticator.new
-    #   authenticator.header(request)
-    def header(_request)
-      {AUTHENTICATION_HEADER => ""}
-    end
-  end
-end

data/lib/x/bearer_token_authenticator.rb

@@ -1,36 +0,0 @@
-require_relative "authenticator"
-
-module X
-  # Authenticator for Bearer token authentication
-  # @api public
-  class BearerTokenAuthenticator < Authenticator
-    # The bearer token for authentication
-    # @api public
-    # @return [String] the bearer token
-    # @example Get the bearer token
-    #   authenticator.bearer_token
-    attr_accessor :bearer_token
-
-    # Initialize a new BearerTokenAuthenticator
-    #
-    # @api public
-    # @param bearer_token [String] the bearer token for authentication
-    # @return [BearerTokenAuthenticator] a new instance
-    # @example Create a new bearer token authenticator
-    #   authenticator = X::BearerTokenAuthenticator.new(bearer_token: "token")
-    def initialize(bearer_token:)
-      @bearer_token = bearer_token
-    end
-
-    # Generate the authentication header for a request
-    #
-    # @api public
-    # @param _request [Net::HTTPRequest] the HTTP request
-    # @return [Hash{String => String}] the authentication header with bearer token
-    # @example Generate a bearer authentication header
-    #   authenticator.header(request)
-    def header(_request)
-      {AUTHENTICATION_HEADER => "Bearer #{bearer_token}"}
-    end
-  end
-end

data/lib/x/client.rb

@@ -1,191 +0,0 @@
-require "forwardable"
-require_relative "authenticator"
-require_relative "bearer_token_authenticator"
-require_relative "client_credentials"
-require_relative "connection"
-require_relative "oauth_authenticator"
-require_relative "oauth2_authenticator"
-require_relative "redirect_handler"
-require_relative "request_builder"
-require_relative "response_parser"
-require_relative "stream_parser"
-
-module X
-  # A client for interacting with the X API
-  # @api public
-  class Client
-    extend Forwardable
-    include ClientCredentials
-
-    # Default base URL for the X API
-    DEFAULT_BASE_URL = "https://api.twitter.com/2/".freeze
-    # Default class for parsing JSON arrays
-    DEFAULT_ARRAY_CLASS = Array
-    # Default class for parsing JSON objects
-    DEFAULT_OBJECT_CLASS = Hash
-
-    # The base URL for API requests
-    # @api public
-    # @return [String] the base URL for API requests
-    # @example Get or set the base URL
-    #   client.base_url = "https://api.twitter.com/1.1/"
-    attr_accessor :base_url
-
-    # The default class for parsing JSON arrays
-    # @api public
-    # @return [Class] the default class for parsing JSON arrays
-    # @example Get or set the default array class
-    #   client.default_array_class = Set
-    attr_accessor :default_array_class
-
-    # The default class for parsing JSON objects
-    # @api public
-    # @return [Class] the default class for parsing JSON objects
-    # @example Get or set the default object class
-    #   client.default_object_class = OpenStruct
-    attr_accessor :default_object_class
-
-    # The authenticator for API requests
-    # @api public
-    # @return [Authenticator] the authenticator instance
-    # @example Check if the OAuth 2.0 token has expired
-    #   client.authenticator.token_expired?
-    attr_reader :authenticator
-
-    def_delegators :@connection, :open_timeout, :read_timeout, :write_timeout, :proxy_url, :debug_output
-    def_delegators :@connection, :open_timeout=, :read_timeout=, :write_timeout=, :proxy_url=, :debug_output=
-    def_delegators :@redirect_handler, :max_redirects
-    def_delegators :@redirect_handler, :max_redirects=
-
-    # Initialize a new X API client
-    #
-    # @api public
-    # @param api_key [String, nil] the API key for OAuth 1.0a authentication
-    # @param api_key_secret [String, nil] the API key secret for OAuth 1.0a authentication
-    # @param access_token [String, nil] the access token for OAuth authentication
-    # @param access_token_secret [String, nil] the access token secret for OAuth 1.0a authentication
-    # @param bearer_token [String, nil] the bearer token for authentication
-    # @param client_id [String, nil] the OAuth 2.0 client ID
-    # @param client_secret [String, nil] the OAuth 2.0 client secret
-    # @param refresh_token [String, nil] the OAuth 2.0 refresh token
-    # @param base_url [String] the base URL for API requests
-    # @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
-    # @param default_array_class [Class] the default class for parsing JSON arrays
-    # @param default_object_class [Class] the default class for parsing JSON objects
-    # @param max_redirects [Integer] the maximum number of redirects to follow
-    # @return [Client] a new client instance
-    # @example Create a client with bearer token authentication
-    #   client = X::Client.new(bearer_token: "your_bearer_token")
-    # @example Create a client with OAuth 1.0a authentication
-    #   client = X::Client.new(api_key: "key", api_key_secret: "secret", access_token: "token", access_token_secret: "token_secret")
-    def initialize(api_key: nil, api_key_secret: nil, access_token: nil, access_token_secret: nil,
-      bearer_token: nil, client_id: nil, client_secret: nil, refresh_token: nil,
-      base_url: DEFAULT_BASE_URL,
-      open_timeout: Connection::DEFAULT_OPEN_TIMEOUT,
-      read_timeout: Connection::DEFAULT_READ_TIMEOUT,
-      write_timeout: Connection::DEFAULT_WRITE_TIMEOUT,
-      debug_output: nil,
-      proxy_url: nil,
-      default_array_class: DEFAULT_ARRAY_CLASS,
-      default_object_class: DEFAULT_OBJECT_CLASS,
-      max_redirects: RedirectHandler::DEFAULT_MAX_REDIRECTS)
-      initialize_credentials(api_key:, api_key_secret:, access_token:, access_token_secret:, bearer_token:,
-        client_id:, client_secret:, refresh_token:)
-      initialize_authenticator
-      @base_url = base_url
-      initialize_default_classes(default_array_class:, default_object_class:)
-      @connection = Connection.new(open_timeout:, read_timeout:, write_timeout:, debug_output:, proxy_url:)
-      @request_builder = RequestBuilder.new
-      @redirect_handler = RedirectHandler.new(connection: @connection, request_builder: @request_builder, max_redirects:)
-      @response_parser = ResponseParser.new
-      @stream_parser = StreamParser.new
-    end
-
-    # Perform a GET request to the X API
-    #
-    # @api public
-    # @return [Hash, Array, nil] the parsed response body
-    # @example Get a user by username
-    #   client.get("users/by/username/sferik")
-    def get(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class)
-      execute_request(:get, endpoint, headers:, array_class:, object_class:)
-    end
-
-    # Perform a POST request to the X API
-    #
-    # @api public
-    # @return [Hash, Array, nil] the parsed response body
-    # @example Create a tweet
-    #   client.post("tweets", '{"text": "Hello, World!"}')
-    def post(endpoint, body = nil, headers: {}, array_class: default_array_class, object_class: default_object_class)
-      execute_request(:post, endpoint, body:, headers:, array_class:, object_class:)
-    end
-
-    # Perform a PUT request to the X API
-    #
-    # @api public
-    # @return [Hash, Array, nil] the parsed response body
-    # @example Update a resource
-    #   client.put("some/endpoint", '{"key": "value"}')
-    def put(endpoint, body = nil, headers: {}, array_class: default_array_class, object_class: default_object_class)
-      execute_request(:put, endpoint, body:, headers:, array_class:, object_class:)
-    end
-
-    # Perform a DELETE request to the X API
-    #
-    # @api public
-    # @return [Hash, Array, nil] the parsed response body
-    # @example Delete a tweet
-    #   client.delete("tweets/1234567890")
-    def delete(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class)
-      execute_request(:delete, endpoint, headers:, array_class:, object_class:)
-    end
-
-    # Stream data from the X API
-    #
-    # @api public
-    # @param endpoint [String] the streaming API endpoint
-    # @param headers [Hash] additional headers for the request
-    # @param array_class [Class] the class for parsing JSON arrays
-    # @param object_class [Class] 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 Stream filtered tweets
-    #   client.stream("tweets/search/stream") { |tweet| puts tweet }
-    def stream(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class, &block)
-      uri = URI.join(base_url, endpoint)
-      request = @request_builder.build(http_method: :get, uri:, headers:, authenticator:)
-      @connection.perform_stream(request:) do |response|
-        @stream_parser.process(response:, response_parser: @response_parser, array_class:, object_class:, &block)
-      end
-    end
-
-    private
-
-    # Initialize default JSON parsing classes
-    # @api private
-    # @param default_array_class [Class] the default class for parsing JSON arrays
-    # @param default_object_class [Class] the default class for parsing JSON objects
-    # @return [void]
-    def initialize_default_classes(default_array_class:, default_object_class:)
-      @default_array_class = default_array_class
-      @default_object_class = default_object_class
-    end
-
-    # Execute an HTTP request to the X API
-    # @api private
-    # @return [Hash, Array, nil] the parsed response body
-    def execute_request(http_method, endpoint, body: nil, headers: {}, array_class: default_array_class, object_class: default_object_class)
-      uri = URI.join(base_url, endpoint)
-      request = @request_builder.build(http_method:, uri:, body:, headers:, authenticator:)
-      response = @connection.perform(request:)
-      response = @redirect_handler.handle(response:, request:, base_url:, authenticator:)
-      @response_parser.parse(response:, array_class:, object_class:)
-    end
-  end
-end

data/lib/x/client_credentials.rb

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