x 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4df136d018c47058c7524faada6292a1464b34f2f0e98f2a76e8491630b28d1c
-  data.tar.gz: f7101280a194f40bef57a82e9670cd6ddf409e80b7563072384b8f8c7687cb63
+  metadata.gz: 017d3f20bd339939e92fd91d8e1034ded6b3165c31734eb6b7b092e17cafb15a
+  data.tar.gz: 8d4bf8295848cba641b9bc9ab6583eee426dcaed0eccfbedcfa982aa82423808
 SHA512:
-  metadata.gz: 24599b2cb2604a711a1a810cb21b0631ce26519dcee977e12bf494fdde1be55c08bf4e2716b6c281918010847e8c1bd72cd236a44f0343ece70a66f4a908ab1f
-  data.tar.gz: 84cdf631377ed38f0400a0f82d6dc42609839eeb4ba81d77526017af8541365152adb4f3e73f2722ae2645a494cf697976c1ae85039c9bd2b82edb1efe97136f
+  metadata.gz: '0597ac0dcb4633c682c237e24d701e8972ff5f7390feab5fa16d320654ecbdbe97ec356ebc6aaa11861d54267fe7ea14f89b43b5290c58202a0a65318940a268'
+  data.tar.gz: f48b37b5042dd349bd822f1d8c2c4e27574e48494e1e8610f265e95eb608b33adee081b57c9b7f5234e7e799c6820aebc77e4f931e99feb80a3e2d77ffb8e523

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.18.0] - 2026-01-06
+* Add OAuth 2.0 authentication with token refresh support (d4c03cb)
+* Add AccountUploader for profile image and banner uploads (7833dd2)
+* Raise InvalidMediaType error for unsupported file extensions (2b6eacc)
+* Prioritize errors array over title/detail in error messages (75279b9)
+
 ## [0.17.0] - 2025-12-02
 * Add MediaUploader.upload_binary method (9f2f108)
 * Don't forward filename during media upload (492214d)

data/README.md

@@ -2,7 +2,7 @@
 [![mutation tests](https://github.com/sferik/x-ruby/actions/workflows/mutant.yml/badge.svg)](https://github.com/sferik/x-ruby/actions/workflows/mutant.yml)
 [![linter](https://github.com/sferik/x-ruby/actions/workflows/lint.yml/badge.svg)](https://github.com/sferik/x-ruby/actions/workflows/lint.yml)
 [![typer checker](https://github.com/sferik/x-ruby/actions/workflows/steep.yml/badge.svg)](https://github.com/sferik/x-ruby/actions/workflows/steep.yml)
-[![maintainability](https://api.codeclimate.com/v1/badges/40bbddf2c9170742ca9e/maintainability)](https://codeclimate.com/github/sferik/x-ruby/maintainability)
+[![maintainability](https://qlty.sh/gh/sferik/projects/x-ruby/maintainability.svg)](https://qlty.sh/gh/sferik/projects/x-ruby)
 [![gem version](https://badge.fury.io/rb/x.svg)](https://rubygems.org/gems/x)
 
 # A [Ruby](https://www.ruby-lang.org) interface to the [X API](https://developer.x.com)
@@ -75,7 +75,7 @@ See other common usage [examples](https://github.com/sferik/x-ruby/tree/main/exa
 
 ## History and Philosophy
 
-This library is a rewrite of the [Twitter Ruby library](https://github.com/sferik/twitter). Over 16 years of development, that library ballooned to over 3,000 lines of code (plus 7,500 lines of tests), not counting dependencies. This library is about 500 lines of code (plus 1000 test lines) and has no runtime dependencies. That doesn’t mean new features won’t be added over time, but the benefits of more code must be weighed against the benefits of less:
+This library is a rewrite of the [Twitter Ruby library](https://github.com/sferik/twitter). Over 16 years of development, that library ballooned to over 3,000 lines of code (plus 7,500 lines of tests), not counting dependencies. This library is about 750 lines of code (plus 1335 test lines) and has no runtime dependencies. That doesn’t mean new features won’t be added over time, but the benefits of more code must be weighed against the benefits of less:
 
 * Less code is easier to maintain.
 * Less code means fewer bugs.
@@ -91,10 +91,10 @@ This code is not littered with comments that are intended to generate documentat
 
 ## Features
 
-If this entire library is implemented in just 500 lines of code, why should you use it at all vs. writing your own library that suits your needs? If you feel inspired to do that, don’t let me discourage you, but this library has some advanced features that may not be apparent without diving into the code:
+If this entire library is implemented in just 750 lines of code, why should you use it at all vs. writing your own library that suits your needs? If you feel inspired to do that, don’t let me discourage you, but this library has some advanced features that may not be apparent without diving into the code:
 
 * OAuth 1.0 Revision A
-* OAuth 2.0 Bearer Token
+* OAuth 2.0
 * Thread safety
 * HTTP redirect following
 * HTTP proxy support

data/lib/x/account_uploader.rb

@@ -0,0 +1,168 @@
+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,7 +1,19 @@
+# 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

data/lib/x/bearer_token_authenticator.rb

@@ -1,13 +1,34 @@
 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
 
-    def initialize(bearer_token:) # rubocop:disable Lint/MissingSuper
+    # 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

data/lib/x/client.rb

@@ -1,29 +1,88 @@
 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"
 
 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
 
-    attr_accessor :base_url, :default_array_class, :default_object_class
-    attr_reader :api_key, :api_key_secret, :access_token, :access_token_secret, :bearer_token
+    # 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,
+      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,
@@ -33,89 +92,68 @@ module X
       default_array_class: DEFAULT_ARRAY_CLASS,
       default_object_class: DEFAULT_OBJECT_CLASS,
       max_redirects: RedirectHandler::DEFAULT_MAX_REDIRECTS)
-      initialize_oauth(api_key, api_key_secret, access_token, access_token_secret, bearer_token)
+      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)
+      @default_array_class = default_array_class
+      @default_object_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
     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
 
-    def api_key=(api_key)
-      @api_key = api_key
-      initialize_authenticator
-    end
-
-    def api_key_secret=(api_key_secret)
-      @api_key_secret = api_key_secret
-      initialize_authenticator
-    end
-
-    def access_token=(access_token)
-      @access_token = access_token
-      initialize_authenticator
-    end
-
-    def access_token_secret=(access_token_secret)
-      @access_token_secret = access_token_secret
-      initialize_authenticator
-    end
-
-    def bearer_token=(bearer_token)
-      @bearer_token = bearer_token
-      initialize_authenticator
-    end
-
     private
 
-    def initialize_oauth(api_key, api_key_secret, access_token, access_token_secret, bearer_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
-    end
-
-    def initialize_default_classes(default_array_class, default_object_class)
-      @default_array_class = default_array_class
-      @default_object_class = default_object_class
-    end
-
-    def initialize_authenticator
-      @authenticator = if api_key && api_key_secret && access_token && access_token_secret
-        OAuthAuthenticator.new(api_key:, api_key_secret:, access_token:, access_token_secret:)
-      elsif bearer_token
-        BearerTokenAuthenticator.new(bearer_token:)
-      elsif @authenticator.nil?
-        Authenticator.new
-      else
-        @authenticator
-      end
-    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: @authenticator)
+      request = @request_builder.build(http_method:, uri:, body:, headers:, authenticator:)
       response = @connection.perform(request:)
-      response = @redirect_handler.handle(response:, request:, base_url:, authenticator: @authenticator)
+      response = @redirect_handler.handle(response:, request:, base_url:, authenticator:)
       @response_parser.parse(response:, array_class:, object_class:)
     end
   end