Add OAuth 2.0 authentication with token refresh support

Implement OAuth2Authenticator class that supports:
- Token storage (access_token, refresh_token, expires_at)
- Automatic token expiration checking via token_expired?
- Token refresh via refresh_token! method

Author: sferik

lib/x/client.rb

@@ -4,6 +4,7 @@
 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"
@@ -54,6 +55,9 @@ class Client
     # @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
@@ -69,7 +73,7 @@ class Client
     # @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,
@@ -79,7 +83,8 @@ def initialize(api_key: nil, api_key_secret: nil, access_token: nil, access_toke
       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:)
+      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
       @default_array_class = default_array_class

lib/x/client_credentials.rb

@@ -32,6 +32,24 @@ module ClientCredentials
     # @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
     #
@@ -93,24 +111,64 @@ def 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:)
+    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 || bearer_authenticator || @authenticator || Authenticator.new
+      @authenticator = oauth_authenticator || oauth2_authenticator || bearer_authenticator || @authenticator || Authenticator.new
     end
 
     # Build an OAuth 1.0a authenticator if credentials are available
@@ -122,6 +180,15 @@ def oauth_authenticator
       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

lib/x/oauth2_authenticator.rb

@@ -0,0 +1,166 @@
+require "base64"
+require "json"
+require "net/http"
+require "uri"
+require_relative "authenticator"
+
+module X
+  # Handles OAuth 2.0 authentication with token refresh capability
+  # @api public
+  class OAuth2Authenticator < Authenticator
+    # URL for the OAuth 2.0 token endpoint
+    TOKEN_URL = "https://api.x.com/2/oauth2/token".freeze
+    # Host for token refresh requests
+    TOKEN_HOST = "api.x.com".freeze
+    # Port for token refresh requests
+    TOKEN_PORT = 443
+    # Grant type for token refresh
+    REFRESH_GRANT_TYPE = "refresh_token".freeze
+
+    # 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
+
+    # 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
+    # @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) # rubocop:disable Lint/MissingSuper
+      @client_id = client_id
+      @client_secret = client_secret
+      @access_token = access_token
+      @refresh_token = refresh_token
+      @expires_at = expires_at
+    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
+    #
+    # @api public
+    # @return [Boolean] true if the token has expired
+    # @example Check expiration
+    #   authenticator.token_expired?
+    def token_expired?
+      return false if expires_at.nil?
+
+      Time.now >= expires_at
+    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
+      http = build_http_client
+      request = build_token_request
+      http.request(request)
+    end
+
+    # Build the HTTP client for token refresh
+    # @api private
+    # @return [Net::HTTP] the HTTP client
+    def build_http_client
+      http = Net::HTTP.new(TOKEN_HOST, TOKEN_PORT)
+      http.use_ssl = true
+      http
+    end
+
+    # Build the token refresh request
+    # @api private
+    # @return [Net::HTTP::Post] the POST request
+    def build_token_request
+      request = Net::HTTP::Post.new(TOKEN_URL)
+      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)
+      unless response.is_a?(Net::HTTPSuccess)
+        error_message = body["error_description"] || body["error"] || "Token refresh failed"
+        raise Error, error_message
+      end
+      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

sig/x.rbs

@@ -208,22 +208,53 @@ module X
     def json?: (Net::HTTPResponse response) -> bool
   end
 
+  class OAuth2Authenticator < Authenticator
+    TOKEN_URL: String
+    TOKEN_HOST: String
+    TOKEN_PORT: Integer
+    REFRESH_GRANT_TYPE: String
+
+    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?
+    def initialize: (client_id: String, client_secret: String, access_token: String, refresh_token: String, ?expires_at: Time?) -> 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_http_client: -> Net::HTTP
+    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?) -> void
-    def initialize_authenticator: -> (Authenticator | BearerTokenAuthenticator | OAuthAuthenticator)
+    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
 
@@ -234,7 +265,7 @@ module X
     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
@@ -243,7 +274,7 @@ module X
     attr_accessor base_url: String
     attr_accessor default_array_class: singleton(Array)
     attr_accessor default_object_class: singleton(Hash)
-    def initialize: (?api_key: String?, ?api_key_secret: String?, ?access_token: String?, ?access_token_secret: String?, ?bearer_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 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