x 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 017d3f20bd339939e92fd91d8e1034ded6b3165c31734eb6b7b092e17cafb15a
-  data.tar.gz: 8d4bf8295848cba641b9bc9ab6583eee426dcaed0eccfbedcfa982aa82423808
+  metadata.gz: 5aaa181ca277a20cc6ddb1ec8d4219535357611891da51642471f54c032a2b47
+  data.tar.gz: 43f3949ff58bb6e3248adad99324f25f6709ad507fc96bb75ff47eba832bddba
 SHA512:
-  metadata.gz: '0597ac0dcb4633c682c237e24d701e8972ff5f7390feab5fa16d320654ecbdbe97ec356ebc6aaa11861d54267fe7ea14f89b43b5290c58202a0a65318940a268'
-  data.tar.gz: f48b37b5042dd349bd822f1d8c2c4e27574e48494e1e8610f265e95eb608b33adee081b57c9b7f5234e7e799c6820aebc77e4f931e99feb80a3e2d77ffb8e523
+  metadata.gz: 612f01c108c9c219363f2910fe393795881151b008c6dc452210ead69c02d1421141061575e8d92f5108fbdc18a3949bc6c3330c9c73444495ed37b4df587e03
+  data.tar.gz: 1a5759aa9862066f735632e0ff63defeb6827bd63657013b88dd33d97792ca177f95859784f08ac32f0f31249ee6a26bdfab582218aee1abd79fcac71281b067

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## [0.19.0] - 2026-03-01
+* Add streaming support for filtered stream and volume stream endpoints
+
 ## [0.18.0] - 2026-01-06
 * Add OAuth 2.0 authentication with token refresh support (d4c03cb)
 * Add AccountUploader for profile image and banner uploads (7833dd2)

data/README.md

@@ -71,11 +71,23 @@ ads_client = X::Client.new(base_url: "https://ads-api.twitter.com/12/", **x_cred
 ads_client.get("accounts")
 ```
 
+### Streaming
+
+```ruby
+# Set up rules for filtered stream
+x_client.post("tweets/search/stream/rules", '{"add": [{"value": "ruby"}]}')
+
+# Stream matching posts in real time
+x_client.stream("tweets/search/stream") do |tweet|
+  puts tweet["data"]["text"]
+end
+```
+
 See other common usage [examples](https://github.com/sferik/x-ruby/tree/main/examples).
 
 ## 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), not counting dependencies. This library is about 750 lines of code (plus 1335 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:
+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 less than 1,000 lines of code (plus 2,000 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.
@@ -91,7 +103,7 @@ This code is not littered with comments that are intended to generate documentat
 
 ## Features
 
-If this entire library is implemented in just 750 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:
+If this entire library is implemented in under 1,000 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
@@ -102,6 +114,7 @@ If this entire library is implemented in just 750 lines of code, why should you
 * HTTP timeout configuration
 * HTTP error handling
 * Rate limit handling
+* Streaming (filtered stream, volume stream)
 * 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

data/lib/x/client.rb

@@ -8,6 +8,7 @@ require_relative "oauth2_authenticator"
 require_relative "redirect_handler"
 require_relative "request_builder"
 require_relative "response_parser"
+require_relative "stream_parser"
 
 module X
   # A client for interacting with the X API
@@ -87,7 +88,7 @@ module X
       open_timeout: Connection::DEFAULT_OPEN_TIMEOUT,
       read_timeout: Connection::DEFAULT_READ_TIMEOUT,
       write_timeout: Connection::DEFAULT_WRITE_TIMEOUT,
-      debug_output: Connection::DEFAULT_DEBUG_OUTPUT,
+      debug_output: nil,
       proxy_url: nil,
       default_array_class: DEFAULT_ARRAY_CLASS,
       default_object_class: DEFAULT_OBJECT_CLASS,
@@ -96,12 +97,12 @@ module X
         client_id:, client_secret:, refresh_token:)
       initialize_authenticator
       @base_url = base_url
-      @default_array_class = default_array_class
-      @default_object_class = default_object_class
+      initialize_default_classes(default_array_class:, default_object_class:)
       @connection = Connection.new(open_timeout:, read_timeout:, write_timeout:, debug_output:, proxy_url:)
       @request_builder = RequestBuilder.new
       @redirect_handler = RedirectHandler.new(connection: @connection, request_builder: @request_builder, max_redirects:)
       @response_parser = ResponseParser.new
+      @stream_parser = StreamParser.new
     end
 
     # Perform a GET request to the X API
@@ -144,8 +145,38 @@ module X
       execute_request(:delete, endpoint, headers:, array_class:, object_class:)
     end
 
+    # Stream data from the X API
+    #
+    # @api public
+    # @param endpoint [String] the streaming API endpoint
+    # @param headers [Hash] additional headers for the request
+    # @param array_class [Class] the class for parsing JSON arrays
+    # @param object_class [Class] the class for parsing JSON objects
+    # @yield [Hash, Array] each parsed JSON object from the stream
+    # @return [void]
+    # @raise [HTTPError] if the response is not successful
+    # @example Stream filtered tweets
+    #   client.stream("tweets/search/stream") { |tweet| puts tweet }
+    def stream(endpoint, headers: {}, array_class: default_array_class, object_class: default_object_class, &block)
+      uri = URI.join(base_url, endpoint)
+      request = @request_builder.build(http_method: :get, uri:, headers:, authenticator:)
+      @connection.perform_stream(request:) do |response|
+        @stream_parser.process(response:, response_parser: @response_parser, array_class:, object_class:, &block)
+      end
+    end
+
     private
 
+    # Initialize default JSON parsing classes
+    # @api private
+    # @param default_array_class [Class] the default class for parsing JSON arrays
+    # @param default_object_class [Class] the default class for parsing JSON objects
+    # @return [void]
+    def initialize_default_classes(default_array_class:, default_object_class:)
+      @default_array_class = default_array_class
+      @default_object_class = default_object_class
+    end
+
     # Execute an HTTP request to the X API
     # @api private
     # @return [Hash, Array, nil] the parsed response body

data/lib/x/connection.rb

@@ -20,8 +20,6 @@ module X
     DEFAULT_READ_TIMEOUT = 60 # seconds
     # Default timeout for writing requests in seconds
     DEFAULT_WRITE_TIMEOUT = 60 # seconds
-    # Default debug output destination
-    DEFAULT_DEBUG_OUTPUT = File.open(IO::NULL, "w")
     # Network errors that should be wrapped in NetworkError
     NETWORK_ERRORS = [
       Errno::ECONNREFUSED,
@@ -92,7 +90,7 @@ module X
     # @example Create a connection with custom timeouts
     #   connection = X::Connection.new(open_timeout: 30, read_timeout: 30)
     def initialize(open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
-      write_timeout: DEFAULT_WRITE_TIMEOUT, debug_output: DEFAULT_DEBUG_OUTPUT, proxy_url: nil)
+      write_timeout: DEFAULT_WRITE_TIMEOUT, debug_output: nil, proxy_url: nil)
       @open_timeout = open_timeout
       @read_timeout = read_timeout
       @write_timeout = write_timeout
@@ -118,6 +116,25 @@ module X
       raise NetworkError, "Network error: #{e}"
     end
 
+    # Perform a streaming HTTP request
+    #
+    # @api public
+    # @param request [Net::HTTPRequest] the HTTP request to perform
+    # @yield [Net::HTTPResponse] the HTTP response for streaming
+    # @return [void]
+    # @raise [NetworkError] if a network error occurs
+    # @example Perform a streaming request
+    #   connection.perform_stream(request: request) { |response| response.read_body { |chunk| } }
+    def perform_stream(request:, &)
+      host = request.uri.host || DEFAULT_HOST
+      port = request.uri.port || DEFAULT_PORT
+      http_client = build_http_client(host, port)
+      http_client.use_ssl = request.uri.scheme.eql?("https")
+      http_client.request(request, &)
+    rescue *NETWORK_ERRORS => e
+      raise NetworkError, "Network error: #{e}"
+    end
+
     # Set the proxy URL for requests
     #
     # @api public

data/lib/x/stream_parser.rb

@@ -0,0 +1,75 @@
+require "json"
+require "net/http"
+require_relative "response_parser"
+
+module X
+  # Handles streaming responses from the X API
+  # @api public
+  class StreamParser
+    # Line delimiter for streaming responses
+    LINE_DELIMITER = "\r\n".freeze
+
+    # Process a streaming response and yield parsed JSON objects
+    #
+    # @api public
+    # @param response [Net::HTTPResponse] the HTTP response to stream
+    # @param response_parser [ResponseParser] the response parser for error handling
+    # @param array_class [Class, nil] the class for parsing JSON arrays
+    # @param object_class [Class, nil] the class for parsing JSON objects
+    # @yield [Hash, Array] each parsed JSON object from the stream
+    # @return [void]
+    # @raise [HTTPError] if the response is not successful
+    # @example Process a streaming response
+    #   handler.process(response: response, response_parser: parser) { |json| puts json }
+    def process(response:, response_parser:, array_class: nil, object_class: nil, &block)
+      response_parser.parse(response:) unless response.is_a?(Net::HTTPSuccess)
+
+      buffer = +""
+      response.read_body do |chunk|
+        buffer << chunk
+        process_buffer(buffer:, array_class:, object_class:, &block)
+      end
+      process_remaining(buffer:, array_class:, object_class:, &block)
+    end
+
+    private
+
+    # Process complete lines from the buffer
+    # @api private
+    # @param buffer [String] the accumulated data buffer
+    # @param array_class [Class, nil] the class for parsing JSON arrays
+    # @param object_class [Class, nil] the class for parsing JSON objects
+    # @yield [Hash, Array] each parsed JSON object
+    # @return [void]
+    def process_buffer(buffer:, array_class:, object_class:, &)
+      while (line_end = buffer.index(LINE_DELIMITER))
+        line = buffer.slice!(0, line_end) # : String
+        buffer.delete_prefix!(LINE_DELIMITER)
+        yield_json(line:, array_class:, object_class:, &) unless line.empty?
+      end
+    end
+
+    # Process any remaining data after the stream ends
+    # @api private
+    # @param buffer [String] the remaining data buffer
+    # @param array_class [Class, nil] the class for parsing JSON arrays
+    # @param object_class [Class, nil] the class for parsing JSON objects
+    # @yield [Hash, Array] the parsed JSON object
+    # @return [void]
+    def process_remaining(buffer:, array_class:, object_class:, &)
+      buffer.strip!
+      yield_json(line: buffer, array_class:, object_class:, &) unless buffer.empty?
+    end
+
+    # Parse a line as JSON and yield the result
+    # @api private
+    # @param line [String] the JSON line to parse
+    # @param array_class [Class, nil] the class for parsing JSON arrays
+    # @param object_class [Class, nil] the class for parsing JSON objects
+    # @yield [Hash, Array] the parsed JSON object
+    # @return [void]
+    def yield_json(line:, array_class:, object_class:)
+      yield JSON.parse(line, array_class:, object_class:)
+    end
+  end
+end

data/lib/x/version.rb

@@ -2,5 +2,5 @@ require "rubygems/version"
 
 module X
   # The current version of the X gem
-  VERSION = Gem::Version.create("0.18.0")
+  VERSION = Gem::Version.create("0.19.0")
 end

data/sig/x.rbs

@@ -125,7 +125,7 @@ module X
     DEFAULT_OPEN_TIMEOUT: Integer
     DEFAULT_READ_TIMEOUT: Integer
     DEFAULT_WRITE_TIMEOUT: Integer
-    DEFAULT_DEBUG_OUTPUT: IO
+
     NETWORK_ERRORS: Array[(singleton(Errno::ECONNREFUSED) | singleton(Errno::ECONNRESET) | singleton(Net::OpenTimeout) | singleton(Net::ReadTimeout) | singleton(OpenSSL::SSL::SSLError))]
 
     @proxy_url: URI::Generic | String
@@ -146,6 +146,7 @@ module X
     def initialize: (?open_timeout: Float | Integer, ?read_timeout: Float | Integer, ?write_timeout: Float | Integer, ?proxy_url: URI::Generic? | String?, ?debug_output: IO) -> void
     def proxy_url=: (URI::Generic | String proxy_url) -> void
     def perform: (request: Net::HTTPRequest) -> Net::HTTPResponse
+    def perform_stream: (request: Net::HTTPRequest) { (Net::HTTPResponse) -> void } -> void
 
     private
     def build_http_client: (?String host, ?Integer port) -> Net::HTTP
@@ -208,6 +209,17 @@ module X
     def json?: (Net::HTTPResponse response) -> bool
   end
 
+  class StreamParser
+    LINE_DELIMITER: String
+
+    def process: (response: Net::HTTPResponse, response_parser: ResponseParser, ?array_class: Class?, ?object_class: Class?) { (untyped) -> void } -> void
+
+    private
+    def process_buffer: (buffer: String, array_class: Class?, object_class: Class?) { (untyped) -> void } -> void
+    def process_remaining: (buffer: String, array_class: Class?, object_class: Class?) { (untyped) -> void } -> void
+    def yield_json: (line: String, array_class: Class?, object_class: Class?) { (untyped) -> void } -> void
+  end
+
   class OAuth2Authenticator < Authenticator
     TOKEN_PATH: String
     TOKEN_HOST: String
@@ -270,6 +282,7 @@ module X
     @request_builder: RequestBuilder
     @redirect_handler: RedirectHandler
     @response_parser: ResponseParser
+    @stream_parser: StreamParser
 
     attr_accessor base_url: String
     attr_accessor default_array_class: singleton(Array)
@@ -280,8 +293,10 @@ module X
     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
+    def stream: (String endpoint, ?headers: Hash[String, String], ?array_class: Class, ?object_class: Class) { (untyped) -> void } -> void
 
     private
+    def initialize_default_classes: (default_array_class: singleton(Array), default_object_class: singleton(Hash)) -> void
     def execute_request: (:delete | :get | :post | :put http_method, String endpoint, ?body: String?, ?headers: Hash[String, String], ?array_class: Class, ?object_class: Class) -> nil
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: x
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Erik Berlin
@@ -70,6 +70,7 @@ files:
 - lib/x/redirect_handler.rb
 - lib/x/request_builder.rb
 - lib/x/response_parser.rb
+- lib/x/stream_parser.rb
 - lib/x/version.rb
 - sig/x.rbs
 homepage: https://sferik.github.io/x-ruby
@@ -98,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.7
 specification_version: 4
 summary: A Ruby interface to the X API.
 test_files: []