x 0.12.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 553e0e0e9a87126211bf62942b02cb2c7c8b6d9380ee8fd4336058038c9735b0
-  data.tar.gz: 34922d1e52a0c04de3c6fe090e854174d78d437c8e14b061a95ca4ab5e1a0438
+  metadata.gz: e7f8185b86c61142faad23edbd1563f5a10263d7f47114d5f31a83e93af805dd
+  data.tar.gz: 8df083a42c16683e27d4face3445e3a835663f11600751024a519c3a658ed0ed
 SHA512:
-  metadata.gz: e28c53b17bb053c26326d46940eb539c4612d6f4a547b074e974c2b6ddee616bb37af6c2dd2d4d84b05a21aa2946306de074889b90bd411b2a268793e40d72a0
-  data.tar.gz: 79ab655009e07915cf71158bb2976301d1519093c753b6f8fc1d128781b4844e867551c3d430bb0226aa113d3c7342efdd401e08d4f3d920a7437dfa8c432ba6
+  metadata.gz: 17dda35c335587d569dc1d41c8fe3ca2221e8e1d3b1742a443559c7d558b149e92229d7d767e64bf4a12982f4a3b4d2afb002d9d34db819216e1934eaf48391f
+  data.tar.gz: 990d9afb8e30cb0c998765525b47c4bf44779f96f4fbd006903fc9b3fe655d0f50df8aa197c77d9ad05250ded0fc086bb768d4662d539490ab81804d2e86b5f0

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.14.0] - 2023-12-08
+* Allow passing custom objects per-request (768889f)
+
+## [0.13.0] - 2023-12-04
+* Introduce X::RateLimit, which is returned with X::TooManyRequests errors (196caec)
+
 ## [0.12.1] - 2023-11-28
 * Ensure split chunks are written as binary (c6e257f)
 * Require tmpdir in X::MediaUploader (9e7c7f1)

data/README.md

@@ -1,7 +1,7 @@
-![Tests](https://github.com/sferik/x-ruby/actions/workflows/test.yml/badge.svg)
-![Linter](https://github.com/sferik/x-ruby/actions/workflows/lint.yml/badge.svg)
-![Mutant](https://github.com/sferik/x-ruby/actions/workflows/mutant.yml/badge.svg)
-![Typer Checker](https://github.com/sferik/x-ruby/actions/workflows/type_check.yml/badge.svg)
+[![Tests](https://github.com/sferik/x-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/sferik/x-ruby/actions/workflows/test.yml)
+[![Linter](https://github.com/sferik/x-ruby/actions/workflows/lint.yml/badge.svg)](https://github.com/sferik/x-ruby/actions/workflows/lint.yml)
+[![Mutant](https://github.com/sferik/x-ruby/actions/workflows/mutant.yml/badge.svg)](https://github.com/sferik/x-ruby/actions/workflows/mutant.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)
 [![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)
@@ -52,10 +52,17 @@ x_client.delete("tweets/#{post["data"]["id"]}")
 # Initialize an API v1.1 client
 v1_client = X::Client.new(base_url: "https://api.twitter.com/1.1/", **x_credentials)
 
-# Get your account settings
-v1_client.get("account/settings.json")
+# Define a custom response object
+Language = Struct.new(:code, :name, :local_name, :status, :debug)
 
-# Initialize an X Ads API client
+# Parse a response with custom array and object classes
+languages = v1_client.get("help/languages.json", object_class: Language, array_class: Set)
+# #<Set: {#<struct Language code="ur", name="Urdu", local_name="اردو", status="beta", debug=false>, …
+
+# Access data with dots instead of brackets
+languages.first.local_name
+
+# Initialize an Ads API client
 ads_client = X::Client.new(base_url: "https://ads-api.twitter.com/12/", **x_credentials)
 
 # Get your ad accounts
@@ -80,6 +87,23 @@ The tests for the previous version of this library executed in about 2 seconds.
 
 This code is not littered with comments that are intended to generate documentation. Rather, this code is intended to be simple enough to serve as its own documentation. If you want to understand how something works, don’t read the documentation—it might be wrong—read the code. The code is always right.
 
+## 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:
+
+* OAuth 1.0 Revision A
+* OAuth 2.0 Bearer Token
+* Thread safety
+* HTTP redirect following
+* HTTP proxy support
+* HTTP logging
+* HTTP timeout configuration
+* HTTP error handling
+* Rate limit handling
+* Parsing JSON into custom response objects (e.g. OpenStruct)
+* Configurable base URLs for accessing different APIs/versions
+* Parallel uploading of large media files in chunks
+
 ## Sponsorship
 
 The X gem is free to use, but with X API pricing tiers, it actually costs money to develop and maintain. By contributing to the project, you help us:
@@ -132,19 +156,23 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/sferik
 
 Pull requests will only be accepted if they meet all the following criteria:
 
-1. Code must conform to [Standard Ruby](https://github.com/standardrb/standard). This can be verified with:
+1. Code must conform to [Standard Ruby](https://github.com/standardrb/standard#readme). This can be verified with:
 
        bundle exec rake standard
 
-2. 100% C0 code coverage. This can be verified with:
+2. Code must conform to the [RuboCop rules](https://github.com/rubocop/rubocop#readme). This can be verified with:
+
+       bundle exec rake rubocop
+
+3. 100% C0 code coverage. This can be verified with:
 
        bundle exec rake test
 
-3. 100% mutation coverage. This can be verified with:
+4. 100% mutation coverage. This can be verified with:
 
        bundle exec rake mutant
 
-4. RBS type signatures (in `sig/x.rbs`). This can be verified with:
+5. RBS type signatures (in `sig/x.rbs`). This can be verified with:
 
        bundle exec rake steep
 

data/lib/x/client.rb

@@ -11,16 +11,16 @@ module X
     extend Forwardable
 
     DEFAULT_BASE_URL = "https://api.twitter.com/2/".freeze
+    DEFAULT_ARRAY_CLASS = Array
+    DEFAULT_OBJECT_CLASS = Hash
 
-    attr_accessor :base_url
+    attr_accessor :base_url, :default_array_class, :default_object_class
     attr_reader :api_key, :api_key_secret, :access_token, :access_token_secret, :bearer_token
 
     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=
-    def_delegators :@response_parser, :array_class, :object_class
-    def_delegators :@response_parser, :array_class=, :object_class=
 
     def initialize(api_key: nil, api_key_secret: nil, access_token: nil, access_token_secret: nil,
       bearer_token: nil,
@@ -30,36 +30,38 @@ module X
       write_timeout: Connection::DEFAULT_WRITE_TIMEOUT,
       debug_output: Connection::DEFAULT_DEBUG_OUTPUT,
       proxy_url: nil,
-      array_class: nil,
-      object_class: nil,
+      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 = bearer_token
+      initialize_oauth(api_key, api_key_secret, access_token, access_token_secret, bearer_token)
       initialize_authenticator
       @base_url = base_url
+      initialize_default_classes(default_array_class, default_object_class)
       @connection = Connection.new(open_timeout: open_timeout, read_timeout: read_timeout,
         write_timeout: write_timeout, debug_output: debug_output, proxy_url: proxy_url)
       @request_builder = RequestBuilder.new
       @redirect_handler = RedirectHandler.new(connection: @connection, request_builder: @request_builder,
         max_redirects: max_redirects)
-      @response_parser = ResponseParser.new(array_class: array_class, object_class: object_class)
+      @response_parser = ResponseParser.new
     end
 
-    def get(endpoint, headers: {})
-      execute_request(:get, endpoint, headers: headers)
+    def get(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class)
+      execute_request(:get, endpoint, headers: headers, array_class: array_class, object_class: object_class)
     end
 
-    def post(endpoint, body = nil, headers: {})
-      execute_request(:post, endpoint, body: body, headers: headers)
+    def post(endpoint, body = nil, headers: {}, array_class: default_array_class, object_class: default_object_class)
+      execute_request(:post, endpoint, body: body, headers: headers, array_class: array_class,
+        object_class: object_class)
     end
 
-    def put(endpoint, body = nil, headers: {})
-      execute_request(:put, endpoint, body: body, headers: headers)
+    def put(endpoint, body = nil, headers: {}, array_class: default_array_class, object_class: default_object_class)
+      execute_request(:put, endpoint, body: body, headers: headers, array_class: array_class,
+        object_class: object_class)
     end
 
-    def delete(endpoint, headers: {})
-      execute_request(:delete, endpoint, headers: headers)
+    def delete(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class)
+      execute_request(:delete, endpoint, headers: headers, array_class: array_class, object_class: object_class)
     end
 
     def api_key=(api_key)
@@ -89,11 +91,17 @@ module X
 
     private
 
-    def initialize_oauth(api_key, api_key_secret, access_token, access_token_secret)
+    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
@@ -109,14 +117,14 @@ module X
       end
     end
 
-    def execute_request(http_method, endpoint, headers:, body: nil)
+    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: http_method, uri: uri, body: body, headers: headers,
         authenticator: @authenticator)
       response = @connection.perform(request: request)
       response = @redirect_handler.handle(response: response, request: request, base_url: base_url,
         authenticator: @authenticator)
-      @response_parser.parse(response: response)
+      @response_parser.parse(response: response, array_class: array_class, object_class: object_class)
     end
   end
 end

data/lib/x/errors/too_many_requests.rb

@@ -1,17 +1,20 @@
 require_relative "client_error"
+require_relative "../rate_limit"
 
 module X
   class TooManyRequests < ClientError
-    def limit
-      response["x-rate-limit-limit"].to_i
+    def rate_limit
+      rate_limits.max_by(&:reset_at)
     end
 
-    def remaining
-      response["x-rate-limit-remaining"].to_i
+    def rate_limits
+      @rate_limits ||= RateLimit::TYPES.filter_map do |type|
+        RateLimit.new(type: type, response: response) if response["x-#{type}-remaining"].eql?("0")
+      end
     end
 
     def reset_at
-      Time.at(response["x-rate-limit-reset"].to_i)
+      rate_limit&.reset_at || Time.at(0)
     end
 
     def reset_in

data/lib/x/rate_limit.rb

@@ -0,0 +1,33 @@
+module X
+  class RateLimit
+    RATE_LIMIT_TYPE = "rate-limit".freeze
+    APP_LIMIT_TYPE = "app-limit-24hour".freeze
+    USER_LIMIT_TYPE = "user-limit-24hour".freeze
+    TYPES = [RATE_LIMIT_TYPE, APP_LIMIT_TYPE, USER_LIMIT_TYPE].freeze
+
+    attr_accessor :type, :response
+
+    def initialize(type:, response:)
+      @type = type
+      @response = response
+    end
+
+    def limit
+      Integer(response.fetch("x-#{type}-limit"))
+    end
+
+    def remaining
+      Integer(response.fetch("x-#{type}-remaining"))
+    end
+
+    def reset_at
+      Time.at(Integer(response.fetch("x-#{type}-reset")))
+    end
+
+    def reset_in
+      [(reset_at - Time.now).ceil, 0].max
+    end
+
+    alias_method :retry_after, :reset_in
+  end
+end

data/lib/x/response_parser.rb

@@ -36,14 +36,7 @@ module X
     }.freeze
     JSON_CONTENT_TYPE_REGEXP = %r{application/json}
 
-    attr_accessor :array_class, :object_class
-
-    def initialize(array_class: nil, object_class: nil)
-      @array_class = array_class
-      @object_class = object_class
-    end
-
-    def parse(response:)
+    def parse(response:, array_class: nil, object_class: nil)
       raise error(response) unless response.is_a?(Net::HTTPSuccess)
 
       return unless json?(response)

data/lib/x/version.rb

@@ -1,5 +1,5 @@
 require "rubygems/version"
 
 module X
-  VERSION = Gem::Version.create("0.12.1")
+  VERSION = Gem::Version.create("0.14.0")
 end

data/sig/x.rbs

@@ -102,10 +102,10 @@ module X
   end
 
   class TooManyRequests < ClientError
-    @response: Net::HTTPResponse
+    @rate_limits: Array[RateLimit]
 
-    def limit: -> Integer
-    def remaining: -> Integer
+    def rate_limit: -> RateLimit?
+    def rate_limits: -> Array[RateLimit]
     def reset_at: -> Time
     def reset_in: -> Integer?
   end
@@ -147,6 +147,21 @@ module X
     def configure_http_client: (Net::HTTP http_client) -> Net::HTTP
   end
 
+  class RateLimit
+    RATE_LIMIT_TYPE: String
+    APP_LIMIT_TYPE: String
+    USER_LIMIT_TYPE: String
+    TYPES: [String, String, String]
+
+    attr_accessor type: String
+    attr_accessor response: Net::HTTPResponse
+    def initialize: (type: String, response: Net::HTTPResponse) -> void
+    def limit: -> Integer
+    def remaining: -> Integer
+    def reset_at: -> Time
+    def reset_in: -> Integer?
+  end
+
   class RequestBuilder
     HTTP_METHODS: Hash[Symbol, (singleton(Net::HTTP::Get) | singleton(Net::HTTP::Post) | singleton(Net::HTTP::Put) | singleton(Net::HTTP::Delete))]
     DEFAULT_HEADERS: Hash[String, String]
@@ -178,15 +193,10 @@ module X
   end
 
   class ResponseParser
-    DEFAULT_ARRAY_CLASS: Class
-    DEFAULT_OBJECT_CLASS: Class
     ERROR_MAP: Hash[Integer, singleton(Unauthorized) | singleton(BadRequest) | singleton(Forbidden) | singleton(InternalServerError) | singleton(NotFound) | singleton(PayloadTooLarge) | singleton(ServiceUnavailable) | singleton(TooManyRequests)]
     JSON_CONTENT_TYPE_REGEXP: Regexp
 
-    attr_accessor array_class: Class
-    attr_accessor object_class: Class
-    def initialize: (?array_class: Class, ?object_class: Class) -> void
-    def parse: (response: Net::HTTPResponse) -> untyped
+    def parse: (response: Net::HTTPResponse, ?array_class: Class?, ?object_class: Class?) -> untyped
 
     private
     def error: (Net::HTTPResponse response) -> (Unauthorized | BadRequest | Forbidden | InternalServerError | NotFound | PayloadTooLarge | ServiceUnavailable | TooManyRequests)
@@ -196,6 +206,8 @@ module X
 
   class Client
     DEFAULT_BASE_URL: String
+    DEFAULT_ARRAY_CLASS: Class
+    DEFAULT_OBJECT_CLASS: Class
 
     extend Forwardable
     @authenticator: Authenticator
@@ -215,8 +227,8 @@ module X
     attr_accessor write_timeout: Float | Integer
     attr_accessor proxy_url: String
     attr_accessor debug_output: IO
-    attr_accessor array_class: Class
-    attr_accessor object_class: Class
+    attr_accessor default_array_class: Class
+    attr_accessor default_object_class: Class
     attr_accessor max_redirects: Integer
     attr_accessor authenticator: Authenticator
     attr_accessor connection: Connection
@@ -224,16 +236,17 @@ module X
     attr_accessor redirect_handler: RedirectHandler
     attr_accessor response_parser: ResponseParser
 
-    def initialize: (?api_key: String?, ?api_key_secret: String?, ?access_token: String?, ?access_token_secret: String?, ?bearer_token: String?, ?base_url: String, ?open_timeout: Float | Integer, ?read_timeout: Float | Integer, ?write_timeout: Float | Integer, ?proxy_url: URI::Generic? | String?, ?debug_output: IO, ?array_class: Class, ?object_class: Class, ?max_redirects: Integer) -> void
-    def get: (String endpoint, ?headers: Hash[String, String]) -> untyped
-    def post: (String endpoint, ?String? body, ?headers: Hash[String, String]) -> untyped
-    def put: (String endpoint, ?String? body, ?headers: Hash[String, String]) -> untyped
-    def delete: (String endpoint, ?headers: Hash[String, String]) -> untyped
+    def initialize: (?api_key: String?, ?api_key_secret: String?, ?access_token: String?, ?access_token_secret: String?, ?bearer_token: String?, ?base_url: String, ?open_timeout: Float | Integer, ?read_timeout: Float | Integer, ?write_timeout: Float | Integer, ?proxy_url: URI::Generic? | String?, ?debug_output: IO, ?default_array_class: Class, ?default_object_class: Class, ?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
+    def delete: (String endpoint, ?headers: Hash[String, String], ?array_class: Class, ?object_class: Class) -> untyped
 
     private
-    def initialize_oauth: (String? api_key, String? api_key_secret, String? access_token, String? access_token_secret) -> void
+    def initialize_oauth: (String? api_key, String? api_key_secret, String? access_token, String? access_token_secret, String? bearer_token) -> void
+    def initialize_default_classes: (Class? default_array_class, Class? default_object_class) -> void
     def initialize_authenticator: -> Authenticator
-    def execute_request: (Symbol http_method, String endpoint, headers: Hash[String, String], ?body: String?) -> untyped
+    def execute_request: (Symbol http_method, String endpoint, ?body: String?, ?headers: Hash[String, String], ?array_class: Class?, ?object_class: Class?) -> untyped
   end
 
   module MediaUploader

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: x
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.14.0
 platform: ruby
 authors:
 - Erik Berlin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-28 00:00:00.000000000 Z
+date: 2023-12-08 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -50,6 +50,7 @@ files:
 - lib/x/errors/unprocessable_entity.rb
 - lib/x/media_uploader.rb
 - lib/x/oauth_authenticator.rb
+- lib/x/rate_limit.rb
 - lib/x/redirect_handler.rb
 - lib/x/request_builder.rb
 - lib/x/response_parser.rb