x 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 480eb23ebeb098bcc5c2d4924279d2d4608f8cf2a8e5eb7897edf45cc0311bc4
-  data.tar.gz: c97f4694a91b3d3ad9f60d55001d48080329254d28db75aff74d646264fe38f2
+  metadata.gz: 56ad55c544f1c7774395d906e0d9d07b6dc2a6d20e37d7df0b3e5b9f7b7b2bb6
+  data.tar.gz: 1747e256413ee2aeae02d8ed0e351b6d411217b00e634a42aeec5299764d6fac
 SHA512:
-  metadata.gz: 86adf1889c2e820353c4455a08c443480682d4827addd074a7e1fe3e60937e70b638118d31802c8cc57d457865c917d2f1a83d739448659519f42c9cbede74ed
-  data.tar.gz: 714dcea3deff757a2d15548ed1fdbb17749ca5b901e9463a5b3a223120b05974ab792d1c3230406dc07984358a6d9e7c4d781402aa025fa5e257d967ee5ecbcf
+  metadata.gz: c5b386cd7386457b148c555359e68c4f9cb72b598ff9eb0a75405f3af75599dca0d5fc1700b01653465b2e50e401b69e9f9e5e9dd126d6a56c46b6df96b5736c
+  data.tar.gz: 462957aeee740d46f4a83497e69bec852fa0a4d8a9e38aec6bf8ffcd8f432e862737fa34847995dce5a49c09a40d9a08607ace68a1314a32972292d881cbd1db

data/.rubocop.yml

@@ -15,8 +15,8 @@ Style/StringLiteralsInInterpolation:
   Enabled: true
   EnforcedStyle: double_quotes
 
-Layout/LineLength:
-  Max: 120
-
 Style/FrozenStringLiteralComment:
   Enabled: false
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [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)
+- Improve error handling (14dc0cd)
+
 ## [0.1.0] - 2023-08-02
 
 - Initial release

data/Gemfile

@@ -9,4 +9,5 @@ gem "rubocop", ">= 1.21"
 gem "rubocop-minitest", ">= 0.31"
 gem "rubocop-performance", ">= 1.18"
 gem "rubocop-rake", ">= 0.6"
+gem "simplecov", ">= 0.22"
 gem "webmock", ">= 3.18.1"

data/README.md

@@ -15,19 +15,39 @@ If bundler is not being used to manage dependencies, install the gem by executin
 ## Usage
 
 ```ruby
-api_key = "YOUR_X_API_KEY"
-api_key_secret = "YOUR_X_API_KEY_SECRET"
-access_token = "YOUR_X_ACCESS_TOKEN"
-access_token_secret = "YOUR_X_ACCESS_TOKEN_SECRET"
-
-x_client = X::Client.new(api_key: api_key, api_key_secret: api_key_secret, access_token: access_token, access_token_secret: access_token_secret)
-
-begin
-  response = x_client.get("users/me")
-  puts JSON.pretty_generate(response)
-rescue StandardError => 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,11 +1,80 @@
-require "oauth"
+require "forwardable"
 require "json"
 require "net/http"
+require "oauth"
+require "uri"
+require_relative "version"
 
 module X
-  # Main client that handles HTTP authentication and requests
+  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
-    BASE_URL = "https://api.twitter.com/2/".freeze
+    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/#{X::Version} Ruby/#{RUBY_VERSION}".freeze
+    DEFAULT_READ_TIMEOUT = 60 # seconds
     HTTP_METHODS = {
       get: Net::HTTP::Get,
       post: Net::HTTP::Post,
@@ -13,52 +82,65 @@ module X
       delete: Net::HTTP::Delete
     }.freeze
 
-    def initialize(bearer_token: nil, api_key: nil, api_key_secret: nil, access_token: nil, access_token_secret: nil)
-      @use_bearer_token = !bearer_token.nil?
+    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, read_timeout: DEFAULT_READ_TIMEOUT)
+      @base_url = URI(base_url)
+      @user_agent = user_agent
+      @read_timeout = read_timeout
 
-      if @use_bearer_token
-        @bearer_token = bearer_token
-      else
-        unless api_key && api_key_secret && access_token && access_token_secret
-          raise ArgumentError, "Missing OAuth credentials."
-        end
+      validate_base_url!
 
-        @consumer = OAuth::Consumer.new(api_key, api_key_secret, site: BASE_URL)
-        @access_token = OAuth::Token.new(access_token, access_token_secret)
+      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)
-      response = send_request(:get, endpoint)
-      handle_response(response)
+      send_request(:get, endpoint)
     end
 
     def post(endpoint, body = nil)
-      response = send_request(:post, endpoint, body)
-      handle_response(response)
+      send_request(:post, endpoint, body)
     end
 
     def put(endpoint, body = nil)
-      response = send_request(:put, endpoint, body)
-      handle_response(response)
+      send_request(:put, endpoint, body)
     end
 
     def delete(endpoint)
-      response = send_request(:delete, endpoint)
-      handle_response(response)
+      send_request(:delete, endpoint)
+    end
+
+    def base_url=(base_url)
+      @base_url = URI(base_url)
+      validate_base_url!
     end
 
     private
 
+    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
+
     def send_request(http_method, endpoint, body = nil)
-      url = URI.parse(BASE_URL + endpoint)
+      url = URI.join(@base_url, endpoint)
       http = Net::HTTP.new(url.host, url.port)
-      http.use_ssl = true
+      http.use_ssl = url.scheme == "https"
+      http.read_timeout = @read_timeout
 
       request = create_request(http_method, url, body)
-      add_authorization(request)
+      add_headers(request)
 
-      http.request(request)
+      handle_response(http.request(request))
+    rescue Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
+      raise X::NetworkError, "Network error: #{e.message}"
     end
 
     def create_request(http_method, url, body)
@@ -71,24 +153,62 @@ module X
       request
     end
 
+    def add_headers(request)
+      add_authorization(request)
+      add_content_type(request)
+      add_user_agent(request)
+    end
+
     def add_authorization(request)
-      if @use_bearer_token
-        request["Authorization"] = "Bearer #{@bearer_token}"
-      else
+      if @bearer_token.nil?
         @consumer.sign!(request, @access_token)
+      else
+        request["Authorization"] = "Bearer #{@bearer_token}"
       end
     end
 
+    def add_content_type(request)
+      request["Content-Type"] = JSON_CONTENT_TYPE
+    end
+
+    def add_user_agent(request)
+      request["User-Agent"] = @user_agent if @user_agent
+    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 handle_response(response)
-      case response
-      when Net::HTTPSuccess
-        JSON.parse(response.body)
-      when Net::HTTPUnauthorized
-        raise X::AuthenticationError, "Authentication failed. Please check your credentials."
-      when Net::HTTPServerError
-        raise X::ServerError, "An internal server error occurred."
-      else
-        raise X::Error, "Unexpected response: #{response.code} #{response.message}"
+      ResponseHandler.new(response).handle
+    end
+
+    # 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)
+        @response = response
+      end
+
+      def handle
+        if @response.is_a?(Net::HTTPSuccess) && @response["content-type"] == JSON_CONTENT_TYPE
+          return JSON.parse(@response.body)
+        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?
+
+        raise error_class.new(@response), error_message
       end
     end
   end

data/lib/x/version.rb

@@ -1,3 +1,39 @@
 module X
-  VERSION = "0.1.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/client"
-require_relative "x/error"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: x
 version: !ruby/object:Gem::Version
-  version: 0.1.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/error.rb
 - lib/x/version.rb
 - sig/x.rbs
 homepage: https://github.com/sferik/x-ruby

data/lib/x/error.rb

@@ -1,5 +0,0 @@
-module X
-  class Error < StandardError; end
-  class AuthenticationError < Error; end
-  class ServerError < Error; end
-end