twitter 8.2.0 → 8.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59d807ebfc2128393a4ab392ac3a5ebd0d7f544a834f1ae08504cbe71bbde002
-  data.tar.gz: 9113658774b1b0d05cdba8f10a741d938a29c5a0b54ef35cf6db0d005a0dc3a8
+  metadata.gz: e3e51290f1c00a7cccecb877674612cb6738dc57f0875b39e0ceed19665741cd
+  data.tar.gz: edb56f6daf0b68b9e9825235cfd8ed11ac0a829b06a13126974495705874a54c
 SHA512:
-  metadata.gz: 0eeaff88905056ae36daf1ddc6ffe027c10163271587a81d1a09413e1c17abf51cf1e104d5239faf92654caac643ec069c278da3ee481339f2a7128cfbc91473
-  data.tar.gz: 8895aef36dbcf669fe49042a775634c3aef1bb3de499e158d1270b14f5463e46e82c952051883e00627c41aea55e7322f3349510f24b108a3d0cc5f47e7678e0
+  metadata.gz: ce9c4b4231288f4889726413ab97baab2905fc3e2d66dd50d3ac90fb6378019088b4c25d9cca4c62406fd91d2387020cdaaf604ec182c663be2cdfcc1c098739
+  data.tar.gz: af70e5b070b1c17f565057712c292a71449384b651803932b0fadba22fb4e76131f1e1b9a1d103bdaed0201ee300957dc83d7cb8850e514daa47a615040aa65d

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2025 Erik Berlin, John Nunemaker, Wynn Netherland, Steve Richert, Steve Agalloco
+Copyright (c) 2006-2026 Erik Berlin, John Nunemaker, Wynn Netherland, Steve Richert, Steve Agalloco
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,18 +1,23 @@
 # The Twitter Ruby Gem
 
-## 📣 This gem is no longer maintained
-The Twitter Ruby Gem is no longer maintained and will not support X (Twitter) API v2.
+[![Lint](https://github.com/sferik/twitter-ruby/actions/workflows/lint.yml/badge.svg)](https://github.com/sferik/twitter-ruby/actions/workflows/lint.yml)
+[![Test](https://github.com/sferik/twitter-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/sferik/twitter-ruby/actions/workflows/test.yml)
+[![Mutant](https://github.com/sferik/twitter-ruby/actions/workflows/mutant.yml/badge.svg)](https://github.com/sferik/twitter-ruby/actions/workflows/mutant.yml)
+[![Typecheck](https://github.com/sferik/twitter-ruby/actions/workflows/typecheck.yml/badge.svg)](https://github.com/sferik/twitter-ruby/actions/workflows/typecheck.yml)
+[![Yardstick](https://github.com/sferik/twitter-ruby/actions/workflows/yardstick.yml/badge.svg)](https://github.com/sferik/twitter-ruby/actions/workflows/yardstick.yml)
+[![Gem Version](https://badge.fury.io/rb/twitter.svg)][gem]
 
-## 🎉 Here’s the good news
-We recommend switching to the [X gem][x], which supports both API v1.1 and v2
-to make the transition easier. It’s a robust, modern libary that is designed to
-ensure you’ll be able to easily integrate any new changes X may roll out.
+The Twitter Ruby Gem provides a Ruby interface to the X (Twitter) API v1.1.
+
+For new projects, or if you need API v2 support, use the [X gem][x] as a more
+modern alternative. It supports both API v1.1 and API v2.
 
 [x]: https://sferik.github.io/x-ruby/
+[gem]: https://rubygems.org/gems/twitter
 
 ## 💖 Sponsoring
-The [X gem][x] is free to use, but with new API pricing tiers, it actually costs
-money to develop and maintain. By contributing to the project, you help us:
+Open source maintenance takes real time and effort. By sponsoring development,
+you help us:
 
 1. 🛠  Maintain the library: Keeping it up-to-date and secure.
 2. 🌈 Add new features: Enhancements that make your life easier.
@@ -32,13 +37,170 @@ Thanks for considering sponsorship. Together we can make the X gem even better!
 [sponsor]: https://github.com/sponsors/sferik
 
 ## Announcements
-You should [follow @gem][follow] on Twitter for announcements and updates about
+You should [follow @gem][follow] on X for announcements and updates about
 this library.
 
 [follow]: https://x.com/gem
 
+## Configuration
+Twitter API v1.1 requests require OAuth credentials, so you'll need to
+[register an app in the X developer portal][register] first.
+
+[register]: https://developer.x.com/en/portal/dashboard
+
+After creating an app, you'll have a consumer key/secret pair and an access
+token/secret pair. Configure these before making requests.
+
+You can pass configuration options as a block to `Twitter::REST::Client.new`.
+
+```ruby
+client = Twitter::REST::Client.new do |config|
+  config.consumer_key        = "YOUR_CONSUMER_KEY"
+  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
+  config.access_token        = "YOUR_ACCESS_TOKEN"
+  config.access_token_secret = "YOUR_ACCESS_SECRET"
+end
+```
+
+## Usage Examples
+After configuring a `client`, you can do the following things.
+
+**Tweet (as the authenticated user)**
+
+```ruby
+client.update("I'm tweeting with @gem!")
+```
+
+**Follow a user (by screen name or user ID)**
+
+```ruby
+client.follow("gem")
+client.follow(213747670)
+```
+
+**Fetch a user (by screen name or user ID)**
+
+```ruby
+client.user("gem")
+client.user(213747670)
+```
+
+**Fetch a cursored list of followers (by screen name, user ID, or the authenticated user)**
+
+```ruby
+client.followers("gem")
+client.followers(213747670)
+client.followers
+```
+
+**Fetch a cursored list of friends (by screen name, user ID, or the authenticated user)**
+
+```ruby
+client.friends("gem")
+client.friends(213747670)
+client.friends
+```
+
+**Fetch the timeline of Tweets by a user**
+
+```ruby
+client.user_timeline("gem")
+client.user_timeline(213747670)
+```
+
+**Fetch the home timeline**
+
+```ruby
+client.home_timeline
+```
+
+**Fetch the mentions timeline**
+
+```ruby
+client.mentions_timeline
+```
+
+**Fetch a Tweet by ID**
+
+```ruby
+client.status(27558893223)
+```
+
+**Search recent matching Tweets**
+
+```ruby
+client.search("to:justinbieber marry me", result_type: "recent").take(3).map do |tweet|
+  "#{tweet.user.screen_name}: #{tweet.text}"
+end
+```
+
+**Find a Japanese-language Tweet tagged #ruby (excluding retweets)**
+
+```ruby
+client.search("#ruby -rt", lang: "ja").first.text
+```
+
+For more usage examples, see the full [documentation][].
+
+[documentation]: https://rubydoc.info/gems/twitter
+
+## Streaming
+This gem includes streaming clients for legacy API v1.1 streaming endpoints.
+Endpoint availability and access requirements depend on your developer account.
+
+**Configuration works just like `Twitter::REST::Client`**
+
+```ruby
+client = Twitter::Streaming::Client.new do |config|
+  config.consumer_key        = "YOUR_CONSUMER_KEY"
+  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
+  config.access_token        = "YOUR_ACCESS_TOKEN"
+  config.access_token_secret = "YOUR_ACCESS_SECRET"
+end
+```
+
+**Stream a random sample of Tweets**
+
+```ruby
+client.sample do |object|
+  puts object.text if object.is_a?(Twitter::Tweet)
+end
+```
+
+**Stream mentions of coffee or tea**
+
+```ruby
+topics = ["coffee", "tea"]
+client.filter(track: topics.join(",")) do |object|
+  puts object.text if object.is_a?(Twitter::Tweet)
+end
+```
+
+**Stream Tweets, events, and direct messages for the authenticated user**
+
+```ruby
+client.user do |object|
+  case object
+  when Twitter::Tweet
+    puts "It's a tweet!"
+  when Twitter::DirectMessage
+    puts "It's a direct message!"
+  when Twitter::Streaming::StallWarning
+    warn "Falling behind!"
+  end
+end
+```
+
+An `object` may be one of the following:
+* `Twitter::Tweet`
+* `Twitter::DirectMessage`
+* `Twitter::Streaming::DeletedTweet`
+* `Twitter::Streaming::Event`
+* `Twitter::Streaming::FriendList`
+* `Twitter::Streaming::StallWarning`
+
 ## Copyright
-Copyright (c) 2006-2025 Erik Berlin, John Nunemaker, Wynn Netherland, Steve Richert, Steve Agalloco.
+Copyright (c) 2006-2026 Erik Berlin, John Nunemaker, Wynn Netherland, Steve Richert, Steve Agalloco.
 See [LICENSE][] for details.
 
 [license]: LICENSE.md

data/lib/twitter/arguments.rb

@@ -1,13 +1,26 @@
 module Twitter
+  # An Array subclass that extracts options from arguments
   class Arguments < Array
+    # The options hash extracted from the arguments
+    #
+    # @api public
+    # @example
+    #   args = Twitter::Arguments.new([:user1, :user2, {trim_user: true}])
+    #   args.options # => {trim_user: true}
     # @return [Hash]
     attr_reader :options
 
     # Initializes a new Arguments object
     #
+    # @api public
+    # @example
+    #   args = Twitter::Arguments.new([:user1, :user2, {trim_user: true}])
+    #   args # => [:user1, :user2]
+    #   args.options # => {trim_user: true}
+    # @param args [Array] An array of arguments, optionally ending with a Hash
     # @return [Twitter::Arguments]
     def initialize(args)
-      @options = args.last.is_a?(::Hash) ? args.pop : {}
+      @options = args.last.is_a?(Hash) ? args.pop : {} # : Hash[Symbol, untyped]
       super(args.flatten)
     end
   end

data/lib/twitter/base.rb

@@ -1,23 +1,46 @@
-require "addressable/uri"
+require "uri"
 require "forwardable"
 require "memoizable"
 require "twitter/null_object"
 require "twitter/utils"
 
 module Twitter
+  # Base class for Twitter objects
   class Base
     extend Forwardable
     include Memoizable
     include Twitter::Utils
+
+    # The raw attributes hash
+    #
+    # @api public
+    # @example
+    #   user.attrs # => {id: 123, name: "John"}
     # @return [Hash]
     attr_reader :attrs
-    alias to_h attrs
-    alias to_hash to_h
+
+    # @!method to_h
+    #   Converts the object to a hash
+    #   @api public
+    #   @example
+    #     user.to_h # => {id: 123, name: "John"}
+    #   @return [Hash]
+    alias_method :to_h, :attrs
+
+    # @!method to_hash
+    #   Converts the object to a hash
+    #   @api public
+    #   @example
+    #     user.to_hash # => {id: 123, name: "John"}
+    #   @return [Hash]
+    alias_method :to_hash, :to_h
 
     class << self
       # Define methods that retrieve the value from attributes
       #
+      # @api private
       # @param attrs [Array, Symbol]
+      # @return [void]
       def attr_reader(*attrs)
         attrs.each do |attr|
           define_attribute_method(attr)
@@ -25,6 +48,11 @@ module Twitter
         end
       end
 
+      # Define predicate methods for attributes
+      #
+      # @api private
+      # @param attrs [Array, Symbol]
+      # @return [void]
       def predicate_attr_reader(*attrs)
         attrs.each do |attr|
           define_predicate_method(attr)
@@ -33,9 +61,11 @@ module Twitter
 
       # Define object methods from attributes
       #
+      # @api private
       # @param klass [Symbol]
       # @param key1 [Symbol]
       # @param key2 [Symbol]
+      # @return [void]
       def object_attr_reader(klass, key1, key2 = nil)
         define_attribute_method(key1, klass, key2)
         define_predicate_method(key1)
@@ -43,7 +73,9 @@ module Twitter
 
       # Define URI methods from attributes
       #
+      # @api private
       # @param attrs [Array, Symbol]
+      # @return [void]
       def uri_attr_reader(*attrs)
         attrs.each do |uri_key|
           array = uri_key.to_s.split("_")
@@ -58,6 +90,9 @@ module Twitter
       end
 
       # Define display_uri attribute methods
+      #
+      # @api private
+      # @return [void]
       def display_uri_attr_reader
         define_attribute_method(:display_url)
         alias_method(:display_uri, :display_url)
@@ -67,26 +102,30 @@ module Twitter
 
       # Dynamically define a method for a URI
       #
+      # @api private
       # @param key1 [Symbol]
       # @param key2 [Symbol]
+      # @return [void]
       def define_uri_method(key1, key2)
         define_method(key1) do
-          Addressable::URI.parse(@attrs[key2].chomp("#")) unless @attrs[key2].nil?
+          URI.parse(@attrs[key2].chomp("#").gsub(/[^\x00-\x7F]/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join }) unless @attrs[key2].nil? # steep:ignore FallbackAny,NoMethod
         end
         memoize(key1)
       end
 
       # Dynamically define a method for an attribute
       #
+      # @api private
       # @param key1 [Symbol]
       # @param klass [Symbol]
       # @param key2 [Symbol]
+      # @return [void]
       def define_attribute_method(key1, klass = nil, key2 = nil)
         define_method(key1) do
-          if attr_falsey_or_empty?(key1)
+          if attr_falsey_or_empty?(key1) # steep:ignore NoMethod
             NullObject.new
           else
-            klass.nil? ? @attrs[key1] : Twitter.const_get(klass).new(attrs_for_object(key1, key2))
+            klass.nil? ? @attrs[key1] : Twitter.const_get(klass).new(attrs_for_object(key1, key2)) # steep:ignore NoMethod,FallbackAny
           end
         end
         memoize(key1)
@@ -94,11 +133,13 @@ module Twitter
 
       # Dynamically define a predicate method for an attribute
       #
+      # @api private
       # @param key1 [Symbol]
       # @param key2 [Symbol]
+      # @return [void]
       def define_predicate_method(key1, key2 = key1)
         define_method(:"#{key1}?") do
-          !attr_falsey_or_empty?(key2)
+          !attr_falsey_or_empty?(key2) # steep:ignore NoMethod
         end
         memoize(:"#{key1}?")
       end
@@ -106,28 +147,48 @@ module Twitter
 
     # Initializes a new object
     #
+    # @api public
+    # @example
+    #   Twitter::Base.new(id: 123, name: "John")
     # @param attrs [Hash]
     # @return [Twitter::Base]
-    def initialize(attrs = {})
+    def initialize(attrs = nil)
       @attrs = attrs || {}
     end
 
     # Fetches an attribute of an object using hash notation
     #
+    # @api public
+    # @deprecated Use attribute methods instead
+    # @example
+    #   user[:id] # => 123
     # @param method [String, Symbol] Message to send to the object
+    # @return [Object, nil]
     def [](method)
-      warn "#{Kernel.caller.first}: [DEPRECATION] #[#{method.inspect}] is deprecated. Use ##{method} to fetch the value."
-      send(method.to_sym)
+      location = caller_locations(1, 1)&.first
+      warn "#{location&.path}:#{location&.lineno}: [DEPRECATION] #[#{method.inspect}] is deprecated. Use ##{method} to fetch the value."
+      public_send(method.to_sym)
     rescue NoMethodError
       nil
     end
 
-  private
+    private
 
+    # Check if an attribute is falsey or empty
+    #
+    # @api private
+    # @param key [Symbol]
+    # @return [Boolean]
     def attr_falsey_or_empty?(key)
       !@attrs[key] || (@attrs[key].respond_to?(:empty?) && @attrs[key].empty?)
     end
 
+    # Get attributes for creating a nested object
+    #
+    # @api private
+    # @param key1 [Symbol]
+    # @param key2 [Symbol]
+    # @return [Hash]
     def attrs_for_object(key1, key2 = nil)
       if key2.nil?
         @attrs[key1]

data/lib/twitter/basic_user.rb

@@ -2,7 +2,13 @@ require "twitter/identity"
 require "twitter/utils"
 
 module Twitter
-  class BasicUser < Twitter::Identity
+  # Represents a basic Twitter user with minimal attributes
+  class BasicUser < Identity
+    # The user's screen name (handle)
+    #
+    # @api public
+    # @example
+    #   user.screen_name # => "sferik"
     # @return [String]
     attr_reader :screen_name
 

data/lib/twitter/client.rb

@@ -3,13 +3,79 @@ require "twitter/utils"
 require "twitter/version"
 
 module Twitter
+  # Base client class for Twitter API authentication
   class Client
     include Twitter::Utils
-    attr_accessor :access_token, :access_token_secret, :consumer_key, :consumer_secret, :proxy, :timeouts, :dev_environment
+
+    # The OAuth access token
+    #
+    # @api public
+    # @example
+    #   client.access_token # => "token"
+    # @return [String]
+    attr_accessor :access_token
+
+    # The OAuth access token secret
+    #
+    # @api public
+    # @example
+    #   client.access_token_secret # => "secret"
+    # @return [String]
+    attr_accessor :access_token_secret
+
+    # The OAuth consumer key
+    #
+    # @api public
+    # @example
+    #   client.consumer_key # => "key"
+    # @return [String]
+    attr_accessor :consumer_key
+
+    # The OAuth consumer secret
+    #
+    # @api public
+    # @example
+    #   client.consumer_secret # => "secret"
+    # @return [String]
+    attr_accessor :consumer_secret
+
+    # The proxy server URI
+    #
+    # @api public
+    # @example
+    #   client.proxy # => "http://proxy.example.com:8080"
+    # @return [String]
+    attr_accessor :proxy
+
+    # The HTTP request timeouts
+    #
+    # @api public
+    # @example
+    #   client.timeouts # => {connect: 5, read: 10}
+    # @return [Hash]
+    attr_accessor :timeouts
+
+    # The development environment name for Premium API endpoints
+    #
+    # @api public
+    # @example
+    #   client.dev_environment # => "dev"
+    # @return [String]
+    attr_accessor :dev_environment
+
+    # The user agent string sent with requests
+    #
+    # @api public
+    # @example
+    #   client.user_agent = "MyApp/1.0"
+    # @return [String]
     attr_writer :user_agent
 
     # Initializes a new Client object
     #
+    # @api public
+    # @example
+    #   client = Twitter::Client.new(consumer_key: "key")
     # @param options [Hash]
     # @return [Twitter::Client]
     def initialize(options = {})
@@ -19,33 +85,58 @@ module Twitter
       yield(self) if block_given?
     end
 
+    # Check if user token credentials are present
+    #
+    # @api public
+    # @example
+    #   client.user_token? # => true
     # @return [Boolean]
     def user_token?
       !(blank_string?(access_token) || blank_string?(access_token_secret))
     end
 
+    # The user agent string sent with requests
+    #
+    # @api public
+    # @example
+    #   client.user_agent # => "TwitterRubyGem/8.2.0"
     # @return [String]
     def user_agent
       @user_agent ||= "TwitterRubyGem/#{Twitter::Version}"
     end
 
+    # The OAuth credentials hash
+    #
+    # @api public
+    # @example
+    #   client.credentials # => {consumer_key: "key", ...}
     # @return [Hash]
     def credentials
       {
         consumer_key:,
         consumer_secret:,
         token: access_token,
-        token_secret: access_token_secret,
+        token_secret: access_token_secret
       }
     end
 
+    # Check if all credentials are present
+    #
+    # @api public
+    # @example
+    #   client.credentials? # => true
     # @return [Boolean]
     def credentials?
       credentials.values.none? { |v| blank_string?(v) }
     end
 
-  private
+    private
 
+    # Check if string is blank or nil
+    #
+    # @api private
+    # @param string [String]
+    # @return [Boolean]
     def blank_string?(string)
       string.respond_to?(:empty?) ? string.empty? : !string
     end

data/lib/twitter/creatable.rb

@@ -2,14 +2,18 @@ require "time"
 require "memoizable"
 
 module Twitter
+  # Provides created_at functionality for Twitter objects
   module Creatable
     include Memoizable
 
     # Time when the object was created on Twitter
     #
+    # @api public
+    # @example
+    #   tweet.created_at # => 2025-01-15 12:00:00 UTC
     # @return [Time]
     def created_at
-      time = @attrs[:created_at]
+      time = @attrs[:created_at] # steep:ignore FallbackAny
       return if time.nil?
 
       time = Time.parse(time) unless time.is_a?(Time)
@@ -17,9 +21,14 @@ module Twitter
     end
     memoize :created_at
 
+    # Check if the created_at attribute is present
+    #
+    # @api public
+    # @example
+    #   tweet.created? # => true
     # @return [Boolean]
     def created?
-      !!@attrs[:created_at]
+      !!@attrs[:created_at] # steep:ignore FallbackAny
     end
     memoize :created?
   end