x 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c40d2b65cf1479d65e6f434d6d9c98cb32ad7aa62b739fd1207b491b7e276e4d
-  data.tar.gz: 6dee4de59342deb6bbc8a5897f7a96e18ae6b7a856083ae84e1ee26580ce7482
+  metadata.gz: 56ad55c544f1c7774395d906e0d9d07b6dc2a6d20e37d7df0b3e5b9f7b7b2bb6
+  data.tar.gz: 1747e256413ee2aeae02d8ed0e351b6d411217b00e634a42aeec5299764d6fac
 SHA512:
-  metadata.gz: d64f01c2f011e53621214597fd1a9ac80e777ce22db2eb5d48c6b2f760743efa2fa3aa6848e6549b3fc25290c80456873262ddf92dbffaff2d134040cb87555f
-  data.tar.gz: 8fc7d2aca33c67534ac775cc97f6afce95ef035716c5799e3571fb7b3a0218fd5b4646b41d8c66f61e3bba1d58f22b6c56c67ca273199b99dd7c55829827215a
+  metadata.gz: c5b386cd7386457b148c555359e68c4f9cb72b598ff9eb0a75405f3af75599dca0d5fc1700b01653465b2e50e401b69e9f9e5e9dd126d6a56c46b6df96b5736c
+  data.tar.gz: 462957aeee740d46f4a83497e69bec852fa0a4d8a9e38aec6bf8ffcd8f432e862737fa34847995dce5a49c09a40d9a08607ace68a1314a32972292d881cbd1db

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+- Add accessors to X::Client (e61fa73)
+- Add configurable read timeout (41502b9)
+- Handle network-related errors (9ed1fb4)
+- Include response body in errors (a203e6a)
+
 ## [0.2.0] - 2023-08-02
 
 - Allow configuration of base URL (4bc0531)

data/README.md

@@ -15,22 +15,39 @@ If bundler is not being used to manage dependencies, install the gem by executin
 ## Usage
 
 ```ruby
-x_api_key             = "YOUR_X_API_KEY"
-x_api_key_secret      = "YOUR_X_API_KEY_SECRET"
-x_access_token        = "YOUR_X_ACCESS_TOKEN"
-x_access_token_secret = "YOUR_X_ACCESS_TOKEN_SECRET"
-
-x_client = X::Client.new(api_key:             x_api_key,
-                         api_key_secret:      x_api_key_secret,
-                         access_token:        x_access_token,
-                         access_token_secret: x_access_token_secret)
-
-begin
-  response = x_client.get("users/me")
-  puts JSON.pretty_generate(response)
-rescue X::Error => e
-  puts "Error: #{e.message}"
-end
+oauth_credentials = {
+  api_key:             "INSERT YOUR X API KEY HERE",
+  api_key_secret:      "INSERT YOUR X API KEY SECRET HERE",
+  access_token:        "INSERT YOUR X API ACCESS TOKEN HERE",
+  access_token_secret: "INSERT YOUR X API ACCESS TOKEN SECRET HERE",
+}
+
+# Initialize X API client with OAuth credentials
+x_client = X::Client.new(**oauth_credentials)
+
+# Request yourself
+x_client.get("users/me")
+# {"data"=>{"id"=>"7505382", "name"=>"Erik Berlin", "username"=>"sferik"}}
+
+# Post a tweet
+tweet = x_client.post("tweets", '{"text":"Hello, World! (from @gem)"}')
+# {"data"=>{"edit_history_tweet_ids"=>["1234567890123456789"], "id"=>"1234567890123456789", "text"=>"Hello, World! (from @gem)"}}
+
+# Delete a tweet
+x_client.delete("tweets/#{tweet["data"]["id"]}")
+# {"data"=>{"deleted"=>true}}
+
+# Initialize an API v1.1 client
+v1_client = X::Client.new(base_url: "https://api.twitter.com/1.1/", **oauth_credentials)
+
+# Request your account settings
+v1_client.get("account/settings.json")
+
+# Initialize an X Ads API client
+ads_client = X::Client.new(base_url: "https://ads-api.twitter.com/12/", **oauth_credentials)
+
+# Request your ad accounts
+ads_client.get("accounts")
 ```
 
 ## Development

data/lib/x/client.rb

@@ -1,142 +1,198 @@
+require "forwardable"
 require "json"
 require "net/http"
 require "oauth"
+require "uri"
+require_relative "version"
 
 module X
+  JSON_CONTENT_TYPE = "application/json; charset=utf-8".freeze
+
+  # Base error class
+  class Error < ::StandardError
+    attr_reader :object
+
+    def initialize(response = nil)
+      if response.is_a?(Net::HTTPResponse) && response.body && response["content-type"] == JSON_CONTENT_TYPE
+        @object = JSON.parse(response.body)
+      end
+      super
+    end
+  end
+
+  class NetworkError < Error; end
+  class ClientError < Error; end
+  class AuthenticationError < ClientError; end
+  class BadRequestError < ClientError; end
+  class ForbiddenError < ClientError; end
+  class NotFoundError < ClientError; end
+
+  # Rate limit error
+  class TooManyRequestsError < ClientError
+    def initialize(response = nil)
+      @response = response
+      super
+    end
+
+    def limit
+      @response && @response["x-rate-limit-limit"]&.to_i
+    end
+
+    def remaining
+      @response && @response["x-rate-limit-remaining"]&.to_i
+    end
+
+    def reset_at
+      reset = @response && @response["x-rate-limit-reset"]&.to_i
+      Time.at(reset.to_i).utc if reset
+    end
+
+    def reset_in
+      [(reset_at - Time.now).ceil, 0].max if reset_at
+    end
+    alias retry_after reset_in
+  end
+
+  class ServerError < Error; end
+  class ServiceUnavailableError < ServerError; end
+
   # HTTP client that handles authentication and requests
   class Client
+    extend Forwardable
+
+    attr_accessor :bearer_token, :user_agent, :read_timeout
+    attr_reader :base_url
+
+    def_delegator :@access_token, :secret, :access_token_secret
+    def_delegator :@access_token, :secret=, :access_token_secret=
+    def_delegator :@access_token, :token, :access_token
+    def_delegator :@access_token, :token=, :access_token=
+    def_delegator :@consumer, :key, :api_key
+    def_delegator :@consumer, :key=, :api_key=
+    def_delegator :@consumer, :secret, :api_key_secret
+    def_delegator :@consumer, :secret=, :api_key_secret=
+
     DEFAULT_BASE_URL = "https://api.twitter.com/2/".freeze
-    DEFAULT_USER_AGENT = "X-Client/#{VERSION} Ruby/#{RUBY_VERSION}".freeze
+    DEFAULT_USER_AGENT = "X-Client/#{X::Version} Ruby/#{RUBY_VERSION}".freeze
+    DEFAULT_READ_TIMEOUT = 60 # seconds
+    HTTP_METHODS = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      put: Net::HTTP::Put,
+      delete: Net::HTTP::Delete
+    }.freeze
 
     def initialize(bearer_token: nil, api_key: nil, api_key_secret: nil, access_token: nil, access_token_secret: nil,
-                   base_url: DEFAULT_BASE_URL, user_agent: DEFAULT_USER_AGENT)
-      @http_request = HttpRequest.new(bearer_token: bearer_token,
-                                      api_key: api_key,
-                                      api_key_secret: api_key_secret,
-                                      access_token: access_token,
-                                      access_token_secret: access_token_secret,
-                                      base_url: base_url,
-                                      user_agent: user_agent)
+                   base_url: DEFAULT_BASE_URL, user_agent: DEFAULT_USER_AGENT, read_timeout: DEFAULT_READ_TIMEOUT)
+      @base_url = URI(base_url)
+      @user_agent = user_agent
+      @read_timeout = read_timeout
+
+      validate_base_url!
+
+      if bearer_token.nil?
+        initialize_oauth(api_key, api_key_secret, access_token, access_token_secret)
+      else
+        @bearer_token = bearer_token
+      end
     end
 
     def get(endpoint)
-      handle_response { @http_request.get(endpoint) }
+      send_request(:get, endpoint)
     end
 
     def post(endpoint, body = nil)
-      handle_response { @http_request.post(endpoint, body) }
+      send_request(:post, endpoint, body)
     end
 
     def put(endpoint, body = nil)
-      handle_response { @http_request.put(endpoint, body) }
+      send_request(:put, endpoint, body)
     end
 
     def delete(endpoint)
-      handle_response { @http_request.delete(endpoint) }
+      send_request(:delete, endpoint)
     end
 
-    private
-
-    def handle_response
-      response = yield
-      ErrorHandler.new(response).handle
+    def base_url=(base_url)
+      @base_url = URI(base_url)
+      validate_base_url!
     end
 
-    # HTTP client requester
-    class HttpRequest
-      HTTP_METHODS = {
-        get: Net::HTTP::Get,
-        post: Net::HTTP::Post,
-        put: Net::HTTP::Put,
-        delete: Net::HTTP::Delete
-      }.freeze
-
-      def initialize(bearer_token: nil, api_key: nil, api_key_secret: nil, access_token: nil, access_token_secret: nil,
-                     base_url: nil, user_agent: nil)
-        @base_url = base_url
-        @use_bearer_token = !bearer_token.nil?
-        @user_agent = user_agent || Client::DEFAULT_USER_AGENT
+    private
 
-        if @use_bearer_token
-          @bearer_token = bearer_token
-        else
-          initialize_oauth(api_key, api_key_secret, access_token, access_token_secret)
-        end
+    def initialize_oauth(api_key, api_key_secret, access_token, access_token_secret)
+      unless api_key && api_key_secret && access_token && access_token_secret
+        raise ArgumentError, "Missing OAuth credentials"
       end
 
-      def get(endpoint)
-        send_request(:get, endpoint)
-      end
+      @consumer = OAuth::Consumer.new(api_key, api_key_secret, site: @base_url)
+      @access_token = OAuth::Token.new(access_token, access_token_secret)
+    end
 
-      def post(endpoint, body = nil)
-        send_request(:post, endpoint, body)
-      end
+    def send_request(http_method, endpoint, body = nil)
+      url = URI.join(@base_url, endpoint)
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = url.scheme == "https"
+      http.read_timeout = @read_timeout
 
-      def put(endpoint, body = nil)
-        send_request(:put, endpoint, body)
-      end
+      request = create_request(http_method, url, body)
+      add_headers(request)
 
-      def delete(endpoint)
-        send_request(:delete, endpoint)
-      end
+      handle_response(http.request(request))
+    rescue Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
+      raise X::NetworkError, "Network error: #{e.message}"
+    end
 
-      private
+    def create_request(http_method, url, body)
+      http_method_class = HTTP_METHODS[http_method]
 
-      def initialize_oauth(api_key, api_key_secret, access_token, access_token_secret)
-        unless api_key && api_key_secret && access_token && access_token_secret
-          raise ArgumentError, "Missing OAuth credentials."
-        end
-
-        @consumer = OAuth::Consumer.new(api_key, api_key_secret, site: @base_url)
-        @access_token = OAuth::Token.new(access_token, access_token_secret)
-      end
+      raise ArgumentError, "Unsupported HTTP method: #{http_method}" unless http_method_class
 
-      def send_request(http_method, endpoint, body = nil)
-        url = URI.parse(@base_url + endpoint)
-        http = Net::HTTP.new(url.host, url.port)
-        http.use_ssl = true
+      request = http_method_class.new(url)
+      request.body = body if body && http_method != :get
+      request
+    end
 
-        request = create_request(http_method, url, body)
-        add_authorization(request)
-        add_user_agent(request)
+    def add_headers(request)
+      add_authorization(request)
+      add_content_type(request)
+      add_user_agent(request)
+    end
 
-        http.request(request)
+    def add_authorization(request)
+      if @bearer_token.nil?
+        @consumer.sign!(request, @access_token)
+      else
+        request["Authorization"] = "Bearer #{@bearer_token}"
       end
+    end
 
-      def create_request(http_method, url, body)
-        http_method_class = HTTP_METHODS[http_method]
-
-        raise ArgumentError, "Unsupported HTTP method: #{http_method}" unless http_method_class
+    def add_content_type(request)
+      request["Content-Type"] = JSON_CONTENT_TYPE
+    end
 
-        request = http_method_class.new(url)
-        request.body = body if body && http_method != :get
-        request
-      end
+    def add_user_agent(request)
+      request["User-Agent"] = @user_agent if @user_agent
+    end
 
-      def add_authorization(request)
-        if @use_bearer_token
-          request["Authorization"] = "Bearer #{@bearer_token}"
-        else
-          @consumer.sign!(request, @access_token)
-        end
-      end
+    def validate_base_url!
+      raise ArgumentError, "Invalid base URL" unless @base_url.is_a?(URI::HTTPS) || @base_url.is_a?(URI::HTTP)
+    end
 
-      def add_user_agent(request)
-        request["User-Agent"] = @user_agent if @user_agent
-      end
+    def handle_response(response)
+      ResponseHandler.new(response).handle
     end
 
-    # HTTP client error handler
-    class ErrorHandler
-      HTTP_STATUS_HANDLERS = {
-        Net::HTTPOK => :handle_success_response,
-        Net::HTTPBadRequest => :handle_bad_request_response,
-        Net::HTTPForbidden => :handle_forbidden_response,
-        Net::HTTPUnauthorized => :handle_unauthorized_response,
-        Net::HTTPNotFound => :handle_not_found_response,
-        Net::HTTPTooManyRequests => :handle_too_many_requests_response,
-        Net::HTTPInternalServerError => :handle_server_error_response,
-        Net::HTTPServiceUnavailable => :handle_service_unavailable_response
+    # HTTP client response handler
+    class ResponseHandler
+      ERROR_CLASSES = {
+        Net::HTTPBadRequest => X::BadRequestError,
+        Net::HTTPUnauthorized => X::AuthenticationError,
+        Net::HTTPForbidden => X::ForbiddenError,
+        Net::HTTPNotFound => X::NotFoundError,
+        Net::HTTPTooManyRequests => X::TooManyRequestsError,
+        Net::HTTPInternalServerError => X::ServerError,
+        Net::HTTPServiceUnavailable => X::ServiceUnavailableError
       }.freeze
 
       def initialize(response)
@@ -144,50 +200,15 @@ module X
       end
 
       def handle
-        handler_method = HTTP_STATUS_HANDLERS[@response.class]
-        if handler_method
-          send(handler_method)
-        else
-          handle_unexpected_response
+        if @response.is_a?(Net::HTTPSuccess) && @response["content-type"] == JSON_CONTENT_TYPE
+          return JSON.parse(@response.body)
         end
-      end
 
-      private
-
-      def handle_success_response
-        JSON.parse(@response.body)
-      end
-
-      def handle_bad_request_response
-        raise X::BadRequestError, "Bad request: #{@response.code} #{@response.message}"
-      end
-
-      def handle_forbidden_response
-        raise X::ForbiddenError, "Forbidden: #{@response.code} #{@response.message}"
-      end
-
-      def handle_unauthorized_response
-        raise X::AuthenticationError, "Authentication failed. Please check your credentials."
-      end
-
-      def handle_not_found_response
-        raise X::NotFoundError, "Not found: #{@response.code} #{@response.message}"
-      end
-
-      def handle_too_many_requests_response
-        raise X::TooManyRequestsError, "Too many requests: #{@response.code} #{@response.message}"
-      end
-
-      def handle_server_error_response
-        raise X::ServerError, "Internal server error: #{@response.code} #{@response.message}"
-      end
-
-      def handle_service_unavailable_response
-        raise X::ServiceUnavailableError, "Service unavailable: #{@response.code} #{@response.message}"
-      end
+        error_class = ERROR_CLASSES[@response.class] || X::Error
+        error_message = "#{@response.code} #{@response.message}"
+        raise error_class, error_message if @response.body.nil? || @response.body.empty?
 
-      def handle_unexpected_response
-        raise X::Error, "Unexpected response: #{@response.code}"
+        raise error_class.new(@response), error_message
       end
     end
   end

data/lib/x/version.rb

@@ -1,3 +1,39 @@
 module X
-  VERSION = "0.2.0".freeze
+  # The version of this library
+  module Version
+    module_function
+
+    def major
+      0
+    end
+
+    def minor
+      3
+    end
+
+    def patch
+      0
+    end
+
+    def pre
+      nil
+    end
+
+    def to_h
+      {
+        major: major,
+        minor: minor,
+        patch: patch,
+        pre: pre
+      }
+    end
+
+    def to_a
+      [major, minor, patch, pre].compact
+    end
+
+    def to_s
+      to_a.join(".")
+    end
+  end
 end

data/lib/x.rb

@@ -1,3 +1 @@
-require_relative "x/version"
-require_relative "x/errors"
 require_relative "x/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: x
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Erik Berlin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-02 00:00:00.000000000 Z
+date: 2023-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth
@@ -39,7 +39,6 @@ files:
 - Rakefile
 - lib/x.rb
 - lib/x/client.rb
-- lib/x/errors.rb
 - lib/x/version.rb
 - sig/x.rbs
 homepage: https://github.com/sferik/x-ruby

data/lib/x/errors.rb

@@ -1,11 +0,0 @@
-module X
-  class Error < ::StandardError; end
-  class ClientError < Error; end
-  class AuthenticationError < ClientError; end
-  class BadRequestError < ClientError; end
-  class ForbiddenError < ClientError; end
-  class NotFoundError < ClientError; end
-  class TooManyRequestsError < ClientError; end
-  class ServerError < Error; end
-  class ServiceUnavailableError < ServerError; end
-end