twitter 8.2.0 → 8.3.0

data/lib/twitter/cursor.rb

@@ -3,23 +3,47 @@ require "twitter/rest/request"
 require "twitter/utils"
 
 module Twitter
+  # Represents a cursor for paginating through Twitter API responses
   class Cursor
-    include Twitter::Enumerable
-    include Twitter::Utils
+    include Enumerable
+    include Utils
+
+    # The raw response attributes
+    #
+    # @api public
+    # @example
+    #   cursor.attrs # => {users: [...], next_cursor: 123}
     # @return [Hash]
     attr_reader :attrs
-    alias to_h attrs
-    alias to_hash to_h
+
+    # @!method to_h
+    #   Returns the attributes as a hash
+    #   @api public
+    #   @example
+    #     cursor.to_h # => {users: [...], next_cursor: 123}
+    #   @return [Hash]
+    alias_method :to_h, :attrs
+
+    # @!method to_hash
+    #   Returns the attributes as a hash
+    #   @api public
+    #   @example
+    #     cursor.to_hash # => {users: [...], next_cursor: 123}
+    #   @return [Hash]
+    alias_method :to_hash, :to_h
 
     # Initializes a new Cursor
     #
+    # @api public
+    # @example
+    #   cursor = Twitter::Cursor.new(:users, Twitter::User, request)
     # @param key [String, Symbol] The key to fetch the data from the response
     # @param klass [Class] The class to instantiate objects in the response
     # @param request [Twitter::REST::Request]
     # @param limit [Integer] After reaching the limit, we stop fetching next page
     # @return [Twitter::Cursor]
     def initialize(key, klass, request, limit = nil)
-      @key = key.to_sym
+      @key = key
       @klass = klass
       @client = request.client
       @request_method = request.verb
@@ -30,14 +54,25 @@ module Twitter
       self.attrs = request.perform
     end
 
-  private
+    private
 
+    # The next cursor value for pagination
+    #
+    # @api private
     # @return [Integer]
     def next_cursor
       @attrs[:next_cursor]
     end
-    alias next next_cursor
 
+    # @!method next
+    #   The next cursor value for pagination
+    #   @api private
+    #   @return [Integer]
+    alias_method :next, :next_cursor
+
+    # Check if this is the last page of results
+    #
+    # @api private
     # @return [Boolean]
     def last?
       return false if next_cursor.is_a?(String)
@@ -46,25 +81,37 @@ module Twitter
       next_cursor.zero?
     end
 
+    # Check if the limit has been reached
+    #
+    # @api private
     # @return [Boolean]
     def reached_limit?
-      @limit && @limit <= attrs[@key].count
+      limit = @limit
+      return false if limit.nil?
+
+      limit <= attrs[@key].count
     end
 
+    # Fetch the next page of results
+    #
+    # @api private
     # @return [Hash]
     def fetch_next_page
-      response = Twitter::REST::Request.new(@client, @request_method, @path, @options.merge(cursor: next_cursor)).perform
+      response = REST::Request.new(@client, @request_method, @path, @options.merge(cursor: next_cursor)).perform
       self.attrs = response
     end
 
+    # Set the attributes and populate the collection
+    #
+    # @api private
     # @param attrs [Hash]
     # @return [Hash]
     def attrs=(attrs)
       @attrs = attrs
+      klass = @klass
       @attrs.fetch(@key, []).each do |element|
-        @collection << (@klass ? @klass.new(element) : element)
+        @collection << (klass ? klass.new(element) : element) # steep:ignore UnexpectedPositionalArgument
       end
-      @attrs
     end
   end
 end

data/lib/twitter/direct_message.rb

@@ -3,13 +3,41 @@ require "twitter/entities"
 require "twitter/identity"
 
 module Twitter
-  class DirectMessage < Twitter::Identity
-    include Twitter::Creatable
-    include Twitter::Entities
+  # Represents a Twitter direct message
+  class DirectMessage < Identity
+    include Creatable
+    include Entities
+
+    # The text content of the direct message
+    #
+    # @api public
+    # @example
+    #   direct_message.text
     # @return [String]
     attr_reader :text
+
+    # The ID of the user who sent this direct message
+    #
+    # @api public
+    # @example
+    #   direct_message.sender_id
+    # @return [Integer]
+
+    # The ID of the user who received this direct message
+    #
+    # @api public
+    # @example
+    #   direct_message.recipient_id
+    # @return [Integer]
     attr_reader :sender_id, :recipient_id
-    alias full_text text
+
+    # @!method full_text
+    #   The full text content of the direct message
+    #   @api public
+    #   @example
+    #     direct_message.full_text
+    #   @return [String]
+    alias_method :full_text, :text
     object_attr_reader :User, :recipient
     object_attr_reader :User, :sender
   end

data/lib/twitter/direct_message_event.rb

@@ -3,37 +3,61 @@ require "twitter/entities"
 require "twitter/identity"
 
 module Twitter
-  class DirectMessageEvent < Twitter::Identity
-    include Twitter::Creatable
-    include Twitter::Entities
+  # Represents a Twitter direct message event
+  class DirectMessageEvent < Identity
+    include Creatable
+    include Entities
 
+    # The timestamp when the event was created
+    #
+    # @api public
+    # @example
+    #   event.created_timestamp
+    # @return [String]
     attr_reader :created_timestamp
 
     object_attr_reader :DirectMessage, :direct_message
 
+    # Initializes a new DirectMessageEvent
+    #
+    # @api public
+    # @example
+    #   Twitter::DirectMessageEvent.new(attrs)
+    # @param attrs [Hash] The attributes hash from the API response
+    # @return [Twitter::DirectMessageEvent]
     def initialize(attrs)
       attrs = read_from_response(attrs)
       text = attrs.dig(:message_create, :message_data, :text)
       urls = attrs.dig(:message_create, :message_data, :entities, :urls)
 
-      text.gsub!(urls[0][:url], urls[0][:expanded_url]) if urls.any?
+      text = text.gsub(urls[0][:url], urls[0][:expanded_url]) if urls.any?
 
       attrs[:direct_message] = build_direct_message(attrs, text)
       super
     end
 
-  private
+    private
 
-    # @return [Hash] Normalized hash of attrs
+    # Normalizes the response attributes
+    #
+    # @api private
+    # @param attrs [Hash] The raw attributes hash
+    # @return [Hash]
     def read_from_response(attrs)
       attrs[:event].nil? ? attrs : attrs[:event]
     end
 
+    # Builds the direct message hash from event attributes
+    #
+    # @api private
+    # @param attrs [Hash] The event attributes
+    # @param text [String] The message text
+    # @return [Hash]
     def build_direct_message(attrs, text)
-      recipient_id = attrs[:message_create][:target][:recipient_id].to_i
-      sender_id = attrs[:message_create][:sender_id].to_i
-      {id: attrs[:id].to_i,
-       created_at: Time.at(attrs[:created_timestamp].to_i / 1000.0),
+      recipient_id = Integer(attrs.fetch(:message_create).fetch(:target).fetch(:recipient_id))
+      sender_id = Integer(attrs.fetch(:message_create).fetch(:sender_id))
+      {id: Integer(attrs.fetch(:id)),
+       created_at: Time.at(Integer(attrs.fetch(:created_timestamp)) / 1000.0),
        sender: {id: sender_id},
        sender_id:,
        recipient: {id: recipient_id},

data/lib/twitter/direct_messages/welcome_message.rb

@@ -3,15 +3,36 @@ require "twitter/entities"
 require "twitter/identity"
 
 module Twitter
+  # Namespace for direct message related classes
   module DirectMessages
+    # Represents a Twitter welcome message for direct messages
     class WelcomeMessage < Twitter::Identity
       include Twitter::Creatable
       include Twitter::Entities
+
+      # The text content of the welcome message
+      #
+      # @api public
+      # @example
+      #   welcome_message.text
       # @return [String]
       attr_reader :text
+
+      # The name of the welcome message
+      #
+      # @api public
+      # @example
+      #   welcome_message.name
       # @return [String]
       attr_reader :name
-      alias full_text text
+
+      # @!method full_text
+      #   The full text content of the welcome message
+      #   @api public
+      #   @example
+      #     welcome_message.full_text
+      #   @return [String]
+      alias_method :full_text, :text
     end
   end
 end

data/lib/twitter/direct_messages/welcome_message_rule.rb

@@ -3,8 +3,15 @@ require "twitter/identity"
 
 module Twitter
   module DirectMessages
+    # Represents a Twitter welcome message rule
     class WelcomeMessageRule < Twitter::Identity
       include Twitter::Creatable
+
+      # The ID of the associated welcome message
+      #
+      # @api public
+      # @example
+      #   rule.welcome_message_id
       # @return [Integer]
       attr_reader :welcome_message_id
     end

data/lib/twitter/direct_messages/welcome_message_rule_wrapper.rb

@@ -3,11 +3,25 @@ require "twitter/identity"
 
 module Twitter
   module DirectMessages
+    # Wraps a Twitter welcome message rule response
     class WelcomeMessageRuleWrapper < Twitter::Identity
+      # The timestamp when the rule was created
+      #
+      # @api public
+      # @example
+      #   wrapper.created_timestamp
+      # @return [String]
       attr_reader :created_timestamp
 
       object_attr_reader "DirectMessages::WelcomeMessageRule", :welcome_message_rule
 
+      # Initializes a new WelcomeMessageRuleWrapper
+      #
+      # @api public
+      # @example
+      #   Twitter::DirectMessages::WelcomeMessageRuleWrapper.new(attrs)
+      # @param attrs [Hash] The attributes hash from the API response
+      # @return [Twitter::DirectMessages::WelcomeMessageRuleWrapper]
       def initialize(attrs)
         attrs = read_from_response(attrs)
 
@@ -15,20 +29,29 @@ module Twitter
         super
       end
 
-    private
+      private
 
-      # @return [Hash] Normalized hash of attrs
+      # Normalizes the response attributes
+      #
+      # @api private
+      # @param attrs [Hash] The raw attributes hash
+      # @return [Hash]
       def read_from_response(attrs)
         return attrs[:welcome_message_rule] unless attrs[:welcome_message_rule].nil?
 
         attrs
       end
 
+      # Builds the welcome message rule hash from attributes
+      #
+      # @api private
+      # @param attrs [Hash] The wrapper attributes
+      # @return [Hash]
       def build_welcome_message_rule(attrs)
         {
           id: attrs[:id].to_i,
           created_at: Time.at(attrs[:created_timestamp].to_i / 1000.0),
-          welcome_message_id: attrs[:welcome_message_id].to_i,
+          welcome_message_id: attrs[:welcome_message_id].to_i
         }
       end
     end

data/lib/twitter/direct_messages/welcome_message_wrapper.rb

@@ -3,38 +3,63 @@ require "twitter/identity"
 
 module Twitter
   module DirectMessages
+    # Wraps a Twitter welcome message response
     class WelcomeMessageWrapper < Twitter::Identity
+      # The timestamp when the message was created
+      #
+      # @api public
+      # @example
+      #   wrapper.created_timestamp
+      # @return [String]
       attr_reader :created_timestamp
 
       object_attr_reader "DirectMessages::WelcomeMessage", :welcome_message
 
+      # Initializes a new WelcomeMessageWrapper
+      #
+      # @api public
+      # @example
+      #   Twitter::DirectMessages::WelcomeMessageWrapper.new(attrs)
+      # @param attrs [Hash] The attributes hash from the API response
+      # @return [Twitter::DirectMessages::WelcomeMessageWrapper]
       def initialize(attrs)
         attrs = read_from_response(attrs)
-        text = attrs.dig(:message_data, :text)
-        urls = attrs.dig(:message_data, :entities, :urls)
+        message_data = attrs.fetch(:message_data)
+        text = message_data.fetch(:text)
+        urls = message_data.fetch(:entities).fetch(:urls)
 
-        text.gsub!(urls[0][:url], urls[0][:expanded_url]) if urls.any?
+        text = text.gsub(urls.fetch(0).fetch(:url), urls.fetch(0).fetch(:expanded_url)) if urls.any?
 
-        attrs[:welcome_message] = build_welcome_message(attrs, text)
+        attrs[:welcome_message] = build_welcome_message(attrs, text, message_data)
         super
       end
 
-    private
+      private
 
-      # @return [Hash] Normalized hash of attrs
+      # Normalizes the response attributes
+      #
+      # @api private
+      # @param attrs [Hash] The raw attributes hash
+      # @return [Hash]
       def read_from_response(attrs)
-        return attrs[:welcome_message] unless attrs[:welcome_message].nil?
+        return attrs.fetch(:welcome_message) unless attrs[:welcome_message].nil?
 
         attrs
       end
 
-      def build_welcome_message(attrs, text)
+      # Builds the welcome message hash from attributes
+      #
+      # @api private
+      # @param attrs [Hash] The wrapper attributes
+      # @param text [String] The message text
+      # @return [Hash]
+      def build_welcome_message(attrs, text, message_data)
         {
-          id: attrs[:id].to_i,
-          created_at: Time.at(attrs[:created_timestamp].to_i / 1000.0),
+          id: Integer(attrs.fetch(:id)),
+          created_at: Time.at(Integer(attrs.fetch(:created_timestamp)) / 1000.0),
           text:,
           name: attrs[:name],
-          entities: attrs.dig(:message_data, :entities),
+          entities: message_data.fetch(:entities)
         }
       end
     end

data/lib/twitter/entities.rb

@@ -6,29 +6,50 @@ require "twitter/entity/user_mention"
 require "twitter/media_factory"
 
 module Twitter
+  # Provides methods for accessing entities in tweets
   module Entities
     include Memoizable
 
+    # Returns true if the object has any entities
+    #
+    # @api public
+    # @example
+    #   tweet.entities?
     # @return [Boolean]
     def entities?
-      !@attrs[:entities].nil? && @attrs[:entities].any? { |_, array| array.any? }
+      !@attrs[:entities].nil? && @attrs[:entities].any? { |_, array| array.any? } # steep:ignore FallbackAny
     end
     memoize :entities?
 
+    # Returns an array of hashtags in the object
+    #
+    # @api public
     # @note Must include entities in your request for this method to work
+    # @example
+    #   tweet.hashtags
     # @return [Array<Twitter::Entity::Hashtag>]
     def hashtags
       entities(Entity::Hashtag, :hashtags)
     end
     memoize :hashtags
 
+    # Returns true if the object has any hashtags
+    #
+    # @api public
+    # @example
+    #   tweet.hashtags?
     # @return [Boolean]
     def hashtags?
       hashtags.any?
     end
     memoize :hashtags?
 
+    # Returns an array of media in the object
+    #
+    # @api public
     # @note Must include entities in your request for this method to work
+    # @example
+    #   tweet.media
     # @return [Array<Twitter::Media>]
     def media
       extended_entities = entities(MediaFactory, :media, :extended_entities)
@@ -36,59 +57,114 @@ module Twitter
     end
     memoize :media
 
+    # Returns true if the object has any media
+    #
+    # @api public
+    # @example
+    #   tweet.media?
     # @return [Boolean]
     def media?
       media.any?
     end
     memoize :media?
 
+    # Returns an array of symbols in the object
+    #
+    # @api public
     # @note Must include entities in your request for this method to work
+    # @example
+    #   tweet.symbols
     # @return [Array<Twitter::Entity::Symbol>]
     def symbols
       entities(Entity::Symbol, :symbols)
     end
     memoize :symbols
 
+    # Returns true if the object has any symbols
+    #
+    # @api public
+    # @example
+    #   tweet.symbols?
     # @return [Boolean]
     def symbols?
       symbols.any?
     end
     memoize :symbols?
 
+    # Returns an array of URIs in the object
+    #
+    # @api public
     # @note Must include entities in your request for this method to work
+    # @example
+    #   tweet.uris
     # @return [Array<Twitter::Entity::URI>]
     def uris
       entities(Entity::URI, :urls)
     end
     memoize :uris
-    alias urls uris
 
+    # @!method urls
+    #   Returns an array of URLs in the object
+    #   @api public
+    #   @example
+    #     tweet.urls
+    #   @return [Array<Twitter::Entity::URI>]
+    alias_method :urls, :uris
+
+    # Returns true if the object has any URIs
+    #
+    # @api public
+    # @example
+    #   tweet.uris?
     # @return [Boolean]
     def uris?
       uris.any?
     end
-    alias urls? uris?
 
+    # @!method urls?
+    #   Returns true if the object has any URLs
+    #   @api public
+    #   @example
+    #     tweet.urls?
+    #   @return [Boolean]
+    alias_method :urls?, :uris?
+
+    # Returns an array of user mentions in the object
+    #
+    # @api public
     # @note Must include entities in your request for this method to work
+    # @example
+    #   tweet.user_mentions
     # @return [Array<Twitter::Entity::UserMention>]
     def user_mentions
       entities(Entity::UserMention, :user_mentions)
     end
     memoize :user_mentions
 
+    # Returns true if the object has any user mentions
+    #
+    # @api public
+    # @example
+    #   tweet.user_mentions?
     # @return [Boolean]
     def user_mentions?
       user_mentions.any?
     end
     memoize :user_mentions?
 
-  private
+    private
 
-    # @param klass [Class]
-    # @param key2 [Symbol]
-    # @param key1 [Symbol]
+    # Extracts entities of a given type from the attributes
+    #
+    # @api private
+    # @param klass [Class] The class to instantiate for each entity
+    # @param key2 [Symbol] The key within the entities hash
+    # @param key1 [Symbol] The top-level key containing entities
+    # @return [Array]
     def entities(klass, key2, key1 = :entities)
-      @attrs.fetch(key1.to_sym, {}).fetch(key2.to_sym, []).collect do |entity|
+      empty_hash = {} # : Hash[Symbol, untyped]
+      empty_array = [] # : Array[untyped]
+      @attrs.fetch(key1.to_sym, empty_hash).fetch(key2.to_sym, empty_array).collect do |entity| # steep:ignore FallbackAny
         klass.new(entity)
       end
     end

data/lib/twitter/entity/hashtag.rb

@@ -2,7 +2,13 @@ require "twitter/entity"
 
 module Twitter
   class Entity
-    class Hashtag < Twitter::Entity
+    # Represents a Twitter hashtag entity
+    class Hashtag < Entity
+      # The text of the hashtag without the hash symbol
+      #
+      # @api public
+      # @example
+      #   hashtag.text
       # @return [String]
       attr_reader :text
     end

data/lib/twitter/entity/symbol.rb

@@ -2,7 +2,13 @@ require "twitter/entity"
 
 module Twitter
   class Entity
-    class Symbol < Twitter::Entity
+    # Represents a Twitter cashtag symbol entity
+    class Symbol < Entity
+      # The text of the cashtag without the dollar sign
+      #
+      # @api public
+      # @example
+      #   symbol.text
       # @return [String]
       attr_reader :text
     end

data/lib/twitter/entity/uri.rb

@@ -2,7 +2,8 @@ require "twitter/entity"
 
 module Twitter
   class Entity
-    class URI < Twitter::Entity
+    # Represents a URI entity in a tweet
+    class URI < Entity
       display_uri_attr_reader
       uri_attr_reader :expanded_uri, :uri
     end

data/lib/twitter/entity/user_mention.rb

@@ -2,9 +2,28 @@ require "twitter/entity"
 
 module Twitter
   class Entity
-    class UserMention < Twitter::Entity
+    # Represents a Twitter user mention entity
+    class UserMention < Entity
+      # The ID of the mentioned user
+      #
+      # @api public
+      # @example
+      #   user_mention.id
       # @return [Integer]
       attr_reader :id
+
+      # The display name of the mentioned user
+      #
+      # @api public
+      # @example
+      #   user_mention.name
+      # @return [String]
+
+      # The screen name of the mentioned user
+      #
+      # @api public
+      # @example
+      #   user_mention.screen_name
       # @return [String]
       attr_reader :name, :screen_name
     end

data/lib/twitter/entity.rb

@@ -1,7 +1,13 @@
 require "twitter/base"
 
 module Twitter
-  class Entity < Twitter::Base
+  # Represents a Twitter entity with position information
+  class Entity < Base
+    # The indices of this entity in the text
+    #
+    # @api public
+    # @example
+    #   entity.indices
     # @return [Array<Integer>]
     attr_reader :indices
   end