x 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 553e0e0e9a87126211bf62942b02cb2c7c8b6d9380ee8fd4336058038c9735b0
-  data.tar.gz: 34922d1e52a0c04de3c6fe090e854174d78d437c8e14b061a95ca4ab5e1a0438
+  metadata.gz: 4f4970075e9256b31a7f53ca6a3a06df7559631b9104c2069372b3797845cd77
+  data.tar.gz: a0e25d20e521f8a3408b9e04b8826d7f8959257ecf6748687a0d1b0292719f38
 SHA512:
-  metadata.gz: e28c53b17bb053c26326d46940eb539c4612d6f4a547b074e974c2b6ddee616bb37af6c2dd2d4d84b05a21aa2946306de074889b90bd411b2a268793e40d72a0
-  data.tar.gz: 79ab655009e07915cf71158bb2976301d1519093c753b6f8fc1d128781b4844e867551c3d430bb0226aa113d3c7342efdd401e08d4f3d920a7437dfa8c432ba6
+  metadata.gz: 7be87f0b82af146429afa88288f60d53d07185d2ed47f57d534c729758a3bfc426c4a57e11703665eedd19b9d994ce4e51bd4f08e3de84cdc49ca7a2de28eae6
+  data.tar.gz: 3e28cfc6ee5d244eff7671e0f724c0a07071d1872792d9fb742ee44bcf2fc2f1a797053dc0d2a415a51a625d85629115f71ad003bb3b9fcaf75049cde6b5d0d1

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## [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)
+[![RuboCop](https://github.com/sferik/x-ruby/actions/workflows/rubocop.yml/badge.svg)](https://github.com/sferik/x-ruby/actions/workflows/rubocop.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)
@@ -55,7 +55,7 @@ v1_client = X::Client.new(base_url: "https://api.twitter.com/1.1/", **x_credenti
 # Get your account settings
 v1_client.get("account/settings.json")
 
-# Initialize an X Ads API client
+# 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 +80,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,9 +149,9 @@ 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 [RuboCop rules](https://github.com/rubocop/rubocop). This can be verified with:
 
-       bundle exec rake standard
+       bundle exec rubocop
 
 2. 100% C0 code coverage. This can be verified with:
 
@@ -142,6 +159,7 @@ Pull requests will only be accepted if they meet all the following criteria:
 
 3. 100% mutation coverage. This can be verified with:
 
+       git remote add upstream https://github.com/sferik/x-ruby
        bundle exec rake mutant
 
 4. RBS type signatures (in `sig/x.rbs`). This can be verified with:

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/version.rb

@@ -1,5 +1,5 @@
 require "rubygems/version"
 
 module X
-  VERSION = Gem::Version.create("0.12.1")
+  VERSION = Gem::Version.create("0.13.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]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: x
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Erik Berlin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-28 00:00:00.000000000 Z
+date: 2023-12-04 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