x 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c6252a6765246fe6ca0820e5ce96f9e66d9611e91b2d59753730fad6b87f67e
-  data.tar.gz: 7a7dc55ece60d848cde08c151e887a1cc86808408a864c05934c4be906b2021a
+  metadata.gz: 4f4970075e9256b31a7f53ca6a3a06df7559631b9104c2069372b3797845cd77
+  data.tar.gz: a0e25d20e521f8a3408b9e04b8826d7f8959257ecf6748687a0d1b0292719f38
 SHA512:
-  metadata.gz: 4216ad5a466dd1a714a638a45d9c0996f40c16247f7fc6eb0ff756d301c3cd63aac5ca95fd421940634e3661db5cb41e19300b73f8ef01056c14e21ad89edea1
-  data.tar.gz: a27036e7dd594f9b13b5cd66267c57b63679352ea3eeeaada13adbba838c6cdad5d8f841fe35b808950fc610808c219679e72334091b3d8de1dca5899ba386b5
+  metadata.gz: 7be87f0b82af146429afa88288f60d53d07185d2ed47f57d534c729758a3bfc426c4a57e11703665eedd19b9d994ce4e51bd4f08e3de84cdc49ca7a2de28eae6
+  data.tar.gz: 3e28cfc6ee5d244eff7671e0f724c0a07071d1872792d9fb742ee44bcf2fc2f1a797053dc0d2a415a51a625d85629115f71ad003bb3b9fcaf75049cde6b5d0d1

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [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)
+
 ## [0.12.0] - 2023-11-02
 * Ensure Authenticator is passed to RedirectHandler (fc8557b)
 * Add AUTHENTICATION_HEADER to X::Authenticator base class (85a2818)

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)
@@ -41,24 +41,24 @@ x_client = X::Client.new(**x_credentials)
 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)"}')
+# Post
+post = x_client.post("tweets", '{"text":"Hello, World! (from @gem)"}')
 # {"data"=>{"edit_history_tweet_ids"=>["1234567890123456789"], "id"=>"1234567890123456789", "text"=>"Hello, World! (from @gem)"}}
 
-# Delete the tweet you just posted
-x_client.delete("tweets/#{tweet["data"]["id"]}")
+# Delete the post
+x_client.delete("tweets/#{post["data"]["id"]}")
 # {"data"=>{"deleted"=>true}}
 
 # Initialize an API v1.1 client
 v1_client = X::Client.new(base_url: "https://api.twitter.com/1.1/", **x_credentials)
 
-# Request your account settings
+# 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)
 
-# Request your ad accounts
+# Get your ad accounts
 ads_client.get("accounts")
 ```
 
@@ -66,7 +66,7 @@ See other common usage [examples](https://github.com/sferik/x-ruby/tree/main/exa
 
 ## History and Philosophy
 
-This library is a rewrite of the [Twitter Ruby library](https://github.com/sferik/twitter). Over 16 years of development, that library ballooned to over 3,000 lines of code (plus 7,500 lines of tests). At the time of writing, this library is about 300 lines of code (plus 200 test lines) and I’d like to keep it that way. That doesn’t mean new features won’t be added over time, but the benefits of more code must be weighted against the benefits of less:
+This library is a rewrite of the [Twitter Ruby library](https://github.com/sferik/twitter). Over 16 years of development, that library ballooned to over 3,000 lines of code (plus 7,500 lines of tests), not counting dependencies. This library is about 500 lines of code (plus 1000 test lines) and has no runtime dependencies. That doesn’t mean new features won’t be added over time, but the benefits of more code must be weighed against the benefits of less:
 
 * Less code is easier to maintain.
 * Less code means fewer bugs.
@@ -76,12 +76,27 @@ In the immortal words of [Ezra Zygmuntowicz](https://github.com/ezmobius) and hi
 
 > No code is faster than no code.
 
-The fastest code is the code that is never executed because it doesn’t exist. That principle should apply not just to this library itself but to third-party dependencies. At present, this library has no runtime dependencies and I’d like to keep it that way.
-
-The tests for the previous version of this library executed in about 2 seconds. That sounds pretty fast until you see that tests for this library run in 2 hundredths of a second. This means you can automatically run the tests any time you write a file and receive immediate feedback. For such of workflows, 2 seconds feels painfully slow.
+The tests for the previous version of this library executed in about 2 seconds. That sounds pretty fast until you see that tests for this library run in one-twentieth of a second. This means you can automatically run the tests any time you write a file and receive immediate feedback. For such of workflows, 2 seconds feels painfully slow.
 
 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:
@@ -103,6 +118,8 @@ Many thanks to our sponsors (listed in order of when they sponsored this project
 <a href="https://betterstack.com"><img src="https://raw.githubusercontent.com/sferik/x-ruby/main/sponsor_logos/better_stack.svg" alt="Better Stack" width="200" align="middle"></a>
 <img src="https://raw.githubusercontent.com/sferik/x-ruby/main/sponsor_logos/spacer.png" width="20" align="middle">
 <a href="https://sentry.io"><img src="https://raw.githubusercontent.com/sferik/x-ruby/main/sponsor_logos/sentry.svg" alt="Sentry" width="200" align="middle"></a>
+<img src="https://raw.githubusercontent.com/sferik/x-ruby/main/sponsor_logos/spacer.png" width="20" align="middle">
+<a href="https://ifttt.com"><img src="https://raw.githubusercontent.com/sferik/x-ruby/main/sponsor_logos/ifttt.svg" alt="IFTTT" width="200" align="middle"></a>
 
 ## Development
 
@@ -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/authenticator.rb

@@ -1,5 +1,4 @@
 module X
-  # Base Authenticator class
   class Authenticator
     AUTHENTICATION_HEADER = "Authorization".freeze
 

data/lib/x/bearer_token_authenticator.rb

@@ -1,7 +1,6 @@
 require_relative "authenticator"
 
 module X
-  # Handles bearer token authentication
   class BearerTokenAuthenticator < Authenticator
     attr_accessor :bearer_token
 

data/lib/x/cgi.rb

@@ -1,7 +1,6 @@
 require "cgi"
 
 module X
-  # Namespaced CGI class
   class CGI
     # TODO: Replace CGI.escape with CGI.escapeURIComponent when support for Ruby 3.1 is dropped
     def self.escape(value)

data/lib/x/client.rb

@@ -7,7 +7,6 @@ require_relative "request_builder"
 require_relative "response_parser"
 
 module X
-  # Main public interface
   class Client
     extend Forwardable
 

data/lib/x/connection.rb

@@ -5,7 +5,6 @@ require "uri"
 require_relative "errors/network_error"
 
 module X
-  # Sends HTTP requests
   class Connection
     extend Forwardable
 

data/lib/x/errors/http_error.rb

@@ -2,7 +2,6 @@ require "json"
 require_relative "error"
 
 module X
-  # Base HTTP error class
   class HTTPError < Error
     JSON_CONTENT_TYPE_REGEXP = %r{application/(problem\+|)json}
 

data/lib/x/errors/too_many_requests.rb

@@ -1,18 +1,20 @@
 require_relative "client_error"
+require_relative "../rate_limit"
 
 module X
-  # Rate limit error class
   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/media_uploader.rb

@@ -1,7 +1,7 @@
 require "securerandom"
+require "tmpdir"
 
 module X
-  # Helper module for uploading images and videos
   module MediaUploader
     extend self
 
@@ -72,7 +72,7 @@ module X
         File.open(file_path, "rb") do |f|
           while (chunk = f.read(chunk_size))
             file_paths << "#{Dir.mktmpdir}/x#{format("%03d", file_number += 1)}".tap do |path|
-              File.write(path, chunk)
+              File.binwrite(path, chunk)
             end
           end
         end

data/lib/x/oauth_authenticator.rb

@@ -7,7 +7,6 @@ require_relative "authenticator"
 require_relative "cgi"
 
 module X
-  # Handles OAuth authentication
   class OAuthAuthenticator < Authenticator
     OAUTH_VERSION = "1.0".freeze
     OAUTH_SIGNATURE_METHOD = "HMAC-SHA1".freeze

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

@@ -6,7 +6,6 @@ require_relative "errors/too_many_redirects"
 require_relative "request_builder"
 
 module X
-  # Handles HTTP redirects
   class RedirectHandler
     DEFAULT_MAX_REDIRECTS = 10
 

data/lib/x/request_builder.rb

@@ -5,7 +5,6 @@ require_relative "cgi"
 require_relative "version"
 
 module X
-  # Creates HTTP requests
   class RequestBuilder
     DEFAULT_HEADERS = {
       "Content-Type" => "application/json; charset=utf-8",

data/lib/x/response_parser.rb

@@ -17,7 +17,6 @@ require_relative "errors/unauthorized"
 require_relative "errors/unprocessable_entity"
 
 module X
-  # Process HTTP responses
   class ResponseParser
     ERROR_MAP = {
       400 => BadRequest,

data/lib/x/version.rb

@@ -1,5 +1,5 @@
 require "rubygems/version"
 
 module X
-  VERSION = Gem::Version.create("0.12.0")
+  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]
@@ -279,7 +294,3 @@ module X
     def self.escape_params: (Hash[String, String] | Array[[String, String]] params) -> String
   end
 end
-
-class Dir
-  def self.mktmpdir: (?String? prefix_suffix) -> String
-end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: x
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Erik Berlin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-02 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
@@ -81,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.21
+rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
 summary: A Ruby interface to the X API.