twitter 8.2.0 → 8.3.0

data/lib/twitter/enumerable.rb

@@ -1,32 +1,49 @@
 module Twitter
+  # Provides iteration support for collections
   module Enumerable
     include ::Enumerable
 
+    # Iterates over the collection
+    #
+    # @api public
+    # @example
+    #   cursor.each { |item| puts item }
+    # @param start [Integer] The starting index
+    # @yield [Object] Each item in the collection
     # @return [Enumerator]
     def each(start = 0, &block)
       return to_enum(:each, start) unless block
 
-      Array(@collection[start..]).each(&block)
+      Array(@collection[start..]).each(&block) # steep:ignore FallbackAny
       unless finished?
-        start = [@collection.size, start].max
+        start = [@collection.size, start].max # steep:ignore FallbackAny
         fetch_next_page
         each(start, &block)
       end
       self
     end
 
-  private
+    private
 
+    # Returns true if this is the last page
+    #
+    # @api private
     # @return [Boolean]
     def last?
       true
     end
 
+    # Returns true if the limit has been reached
+    #
+    # @api private
     # @return [Boolean]
     def reached_limit?
       false
     end
 
+    # Returns true if iteration is finished
+    #
+    # @api private
     # @return [Boolean]
     def finished?
       last? || reached_limit?

data/lib/twitter/error.rb

@@ -3,77 +3,107 @@ require "twitter/rate_limit"
 module Twitter
   # Custom error class for rescuing from all Twitter errors
   class Error < StandardError
+    # The error code from Twitter
+    #
+    # @api public
+    # @example
+    #   error.code
     # @return [Integer]
     attr_reader :code
+
+    # The rate limit information from the response
+    #
+    # @api public
+    # @example
+    #   error.rate_limit
     # @return [Twitter::RateLimit]
     attr_reader :rate_limit
 
     # Raised when Twitter returns a 4xx HTTP status code
-    ClientError = Class.new(self)
+    ClientError = Class.new(self) # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 400
-    BadRequest = Class.new(ClientError)
+    class BadRequest < ClientError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 401
-    Unauthorized = Class.new(ClientError)
+    class Unauthorized < ClientError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 403
-    Forbidden = Class.new(ClientError)
+    class Forbidden < ClientError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 413
-    RequestEntityTooLarge = Class.new(ClientError)
+    class RequestEntityTooLarge < ClientError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when a Tweet has already been favorited
-    AlreadyFavorited = Class.new(Forbidden)
+    class AlreadyFavorited < Forbidden
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when a Tweet has already been retweeted
-    AlreadyRetweeted = Class.new(Forbidden)
+    class AlreadyRetweeted < Forbidden
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when a Tweet has already been posted
-    DuplicateStatus = Class.new(Forbidden)
+    class DuplicateStatus < Forbidden
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 404
-    NotFound = Class.new(ClientError)
+    class NotFound < ClientError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 406
-    NotAcceptable = Class.new(ClientError)
+    class NotAcceptable < ClientError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 422
-    UnprocessableEntity = Class.new(ClientError)
+    class UnprocessableEntity < ClientError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 429
-    TooManyRequests = Class.new(ClientError)
+    class TooManyRequests < ClientError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns a 5xx HTTP status code
-    ServerError = Class.new(self)
+    ServerError = Class.new(self) # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 500
-    InternalServerError = Class.new(ServerError)
+    class InternalServerError < ServerError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 502
-    BadGateway = Class.new(ServerError)
+    class BadGateway < ServerError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 503
-    ServiceUnavailable = Class.new(ServerError)
+    class ServiceUnavailable < ServerError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns the HTTP status code 504
-    GatewayTimeout = Class.new(ServerError)
+    class GatewayTimeout < ServerError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns a media related error
-    MediaError = Class.new(self)
+    MediaError = Class.new(self) # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns an InvalidMedia error
-    InvalidMedia = Class.new(MediaError)
+    class InvalidMedia < MediaError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns a media InternalError error
-    MediaInternalError = Class.new(MediaError)
+    class MediaInternalError < MediaError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when Twitter returns an UnsupportedMedia error
-    UnsupportedMedia = Class.new(MediaError)
+    class UnsupportedMedia < MediaError
+    end # steep:ignore IncompatibleAssignment
 
     # Raised when an operation subject to timeout takes too long
-    TimeoutError = Class.new(self)
+    TimeoutError = Class.new(self) # steep:ignore IncompatibleAssignment
 
+    # Maps HTTP status codes to error classes
     ERRORS = {
       400 => Twitter::Error::BadRequest,
       401 => Twitter::Error::Unauthorized,
@@ -87,9 +117,10 @@ module Twitter
       500 => Twitter::Error::InternalServerError,
       502 => Twitter::Error::BadGateway,
       503 => Twitter::Error::ServiceUnavailable,
-      504 => Twitter::Error::GatewayTimeout,
+      504 => Twitter::Error::GatewayTimeout
     }.freeze
 
+    # Maps forbidden message patterns to error classes
     FORBIDDEN_MESSAGES = proc do |message|
       case message
       when /(?=.*status).*duplicate/i
@@ -106,57 +137,89 @@ module Twitter
       end
     end
 
+    # Maps media error names to error classes
     MEDIA_ERRORS = {
       "InternalError" => Twitter::Error::MediaInternalError,
       "InvalidMedia" => Twitter::Error::InvalidMedia,
-      "UnsupportedMedia" => Twitter::Error::UnsupportedMedia,
+      "UnsupportedMedia" => Twitter::Error::UnsupportedMedia
     }.freeze
 
-    # If error code is missing see https://developer.twitter.com/en/docs/basics/response-codes
+    # Twitter API error codes
+    # @see https://developer.twitter.com/en/docs/basics/response-codes
     module Code
-      AUTHENTICATION_PROBLEM       =  32
-      RESOURCE_NOT_FOUND           =  34
-      SUSPENDED_ACCOUNT            =  64
-      DEPRECATED_CALL              =  68
-      RATE_LIMIT_EXCEEDED          =  88
-      INVALID_OR_EXPIRED_TOKEN     =  89
-      SSL_REQUIRED                 =  92
-      UNABLE_TO_VERIFY_CREDENTIALS =  99
-      OVER_CAPACITY                = 130
-      INTERNAL_ERROR               = 131
+      # Authentication problem error code
+      AUTHENTICATION_PROBLEM = 32
+      # Resource not found error code
+      RESOURCE_NOT_FOUND = 34
+      # Suspended account error code
+      SUSPENDED_ACCOUNT = 64
+      # Deprecated call error code
+      DEPRECATED_CALL = 68
+      # Rate limit exceeded error code
+      RATE_LIMIT_EXCEEDED = 88
+      # Invalid or expired token error code
+      INVALID_OR_EXPIRED_TOKEN = 89
+      # SSL required error code
+      SSL_REQUIRED = 92
+      # Unable to verify credentials error code
+      UNABLE_TO_VERIFY_CREDENTIALS = 99
+      # Over capacity error code
+      OVER_CAPACITY = 130
+      # Internal error code
+      INTERNAL_ERROR = 131
+      # OAuth timestamp out of range error code
       OAUTH_TIMESTAMP_OUT_OF_RANGE = 135
-      ALREADY_FAVORITED            = 139
-      FOLLOW_ALREADY_REQUESTED     = 160
-      FOLLOW_LIMIT_EXCEEDED        = 161
-      PROTECTED_STATUS             = 179
-      OVER_UPDATE_LIMIT            = 185
-      DUPLICATE_STATUS             = 187
-      BAD_AUTHENTICATION_DATA      = 215
-      SPAM                         = 226
-      LOGIN_VERIFICATION_NEEDED    = 231
-      ENDPOINT_RETIRED             = 251
-      CANNOT_WRITE                 = 261
-      CANNOT_MUTE                  = 271
-      CANNOT_UNMUTE                = 272
+      # Already favorited error code
+      ALREADY_FAVORITED = 139
+      # Follow already requested error code
+      FOLLOW_ALREADY_REQUESTED = 160
+      # Follow limit exceeded error code
+      FOLLOW_LIMIT_EXCEEDED = 161
+      # Protected status error code
+      PROTECTED_STATUS = 179
+      # Over update limit error code
+      OVER_UPDATE_LIMIT = 185
+      # Duplicate status error code
+      DUPLICATE_STATUS = 187
+      # Bad authentication data error code
+      BAD_AUTHENTICATION_DATA = 215
+      # Spam error code
+      SPAM = 226
+      # Login verification needed error code
+      LOGIN_VERIFICATION_NEEDED = 231
+      # Endpoint retired error code
+      ENDPOINT_RETIRED = 251
+      # Cannot write error code
+      CANNOT_WRITE = 261
+      # Cannot mute error code
+      CANNOT_MUTE = 271
+      # Cannot unmute error code
+      CANNOT_UNMUTE = 272
     end
 
     class << self
       include Twitter::Utils
 
-      # Create a new error from an HTTP response
+      # Creates a new error from an HTTP response
       #
-      # @param body [String]
-      # @param headers [Hash]
+      # @api public
+      # @example
+      #   Twitter::Error.from_response(body, headers)
+      # @param body [String] The response body
+      # @param headers [Hash] The response headers
       # @return [Twitter::Error]
       def from_response(body, headers)
         message, code = parse_error(body)
         new(message, headers, code)
       end
 
-      # Create a new error from a media error hash
+      # Creates a new error from a media error hash
       #
-      # @param error [Hash]
-      # @param headers [Hash]
+      # @api public
+      # @example
+      #   Twitter::Error.from_processing_response(error, headers)
+      # @param error [Hash] The error hash from the response
+      # @param headers [Hash] The response headers
       # @return [Twitter::MediaError]
       def from_processing_response(error, headers)
         klass = MEDIA_ERRORS[error[:name]] || self
@@ -165,37 +228,50 @@ module Twitter
         klass.new(message, headers, code)
       end
 
-    private
+      private
 
+      # Parses an error from the response body
+      #
+      # @api private
+      # @param body [Hash, nil] The response body
+      # @return [Array]
       def parse_error(body)
         if body.nil? || body.empty?
           ["", nil]
         elsif body[:error]
-          [body[:error], nil]
+          [body.fetch(:error), nil]
         elsif body[:errors]
           extract_message_from_errors(body)
         end
       end
 
+      # Extracts error message from errors array
+      #
+      # @api private
+      # @param body [Hash] The response body with errors
+      # @return [Array]
       def extract_message_from_errors(body)
         first = Array(body[:errors]).first
         if first.is_a?(Hash)
           [first[:message].chomp, first[:code]]
         else
-          [first.chomp, nil]
+          [first.chomp, nil] # steep:ignore NoMethod
         end
       end
     end
 
     # Initializes a new Error object
     #
-    # @param message [Exception, String]
-    # @param rate_limit [Hash]
-    # @param code [Integer]
+    # @api public
+    # @example
+    #   Twitter::Error.new("Something went wrong", {}, 123)
+    # @param message [Exception, String] The error message
+    # @param rate_limit [Hash] The rate limit headers
+    # @param code [Integer] The error code
     # @return [Twitter::Error]
     def initialize(message = "", rate_limit = {}, code = nil)
       super(message)
-      @rate_limit = Twitter::RateLimit.new(rate_limit)
+      @rate_limit = RateLimit.new(rate_limit)
       @code = code
     end
   end

data/lib/twitter/factory.rb

@@ -1,12 +1,16 @@
 module Twitter
+  # Factory for creating Twitter objects based on type
   class Factory
     class << self
-      # Construct a new object
+      # Constructs a new object based on type
       #
-      # @param method [Symbol]
-      # @param klass [Class]
-      # @param attrs [Hash]
-      # @raise [IndexError] Error raised when supplied argument is missing a key.
+      # @api public
+      # @example
+      #   Twitter::Factory.new(:type, Twitter::Geo, attrs)
+      # @param method [Symbol] The key to look up the type
+      # @param klass [Class] The base class for the type
+      # @param attrs [Hash] The attributes hash
+      # @raise [IndexError] Error raised when argument is missing a key
       # @return [Twitter::Base]
       def new(method, klass, attrs = {})
         type = attrs.fetch(method.to_sym)

data/lib/twitter/geo/point.rb

@@ -2,19 +2,51 @@ require "twitter/geo"
 
 module Twitter
   class Geo
+    # Represents a geographic point with latitude and longitude
     class Point < Twitter::Geo
-      # @return [Integer]
+      # Returns the latitude of this point
+      #
+      # @api public
+      # @example
+      #   point.latitude
+      # @return [Float]
       def latitude
         coordinates[0]
       end
-      alias lat latitude
 
-      # @return [Integer]
+      # @!method lat
+      #   Returns the latitude of this point
+      #   @api public
+      #   @example
+      #     point.lat
+      #   @return [Float]
+      alias_method :lat, :latitude
+
+      # Returns the longitude of this point
+      #
+      # @api public
+      # @example
+      #   point.longitude
+      # @return [Float]
       def longitude
         coordinates[1]
       end
-      alias long longitude
-      alias lng longitude
+
+      # @!method long
+      #   Returns the longitude of this point
+      #   @api public
+      #   @example
+      #     point.long
+      #   @return [Float]
+      alias_method :long, :longitude
+
+      # @!method lng
+      #   Returns the longitude of this point
+      #   @api public
+      #   @example
+      #     point.lng
+      #   @return [Float]
+      alias_method :lng, :longitude
     end
   end
 end

data/lib/twitter/geo/polygon.rb

@@ -2,6 +2,7 @@ require "twitter/geo"
 
 module Twitter
   class Geo
+    # Represents a polygon geographic area
     class Polygon < Twitter::Geo
     end
   end

data/lib/twitter/geo.rb

@@ -2,10 +2,24 @@ require "equalizer"
 require "twitter/base"
 
 module Twitter
-  class Geo < Twitter::Base
+  # Represents geographic information
+  class Geo < Base
     include Equalizer.new(:coordinates)
+
+    # The coordinates of this geographic location
+    #
+    # @api public
+    # @example
+    #   geo.coordinates
     # @return [Array<Float>]
     attr_reader :coordinates
-    alias coords coordinates
+
+    # @!method coords
+    #   The coordinates of this geographic location
+    #   @api public
+    #   @example
+    #     geo.coords
+    #   @return [Array<Float>]
+    alias_method :coords, :coordinates
   end
 end

data/lib/twitter/geo_factory.rb

@@ -3,12 +3,16 @@ require "twitter/geo/point"
 require "twitter/geo/polygon"
 
 module Twitter
+  # Factory for creating geo objects based on type
   class GeoFactory < Twitter::Factory
     class << self
-      # Construct a new geo object
+      # Constructs a new geo object
       #
-      # @param attrs [Hash]
-      # @raise [IndexError] Error raised when supplied argument is missing a :type key.
+      # @api public
+      # @example
+      #   Twitter::GeoFactory.new(type: "Point", coordinates: [1.0, 2.0])
+      # @param attrs [Hash] The attributes hash with a :type key
+      # @raise [IndexError] Error raised when argument is missing a :type key
       # @return [Twitter::Geo]
       def new(attrs = {})
         super(:type, Geo, attrs)

data/lib/twitter/geo_results.rb

@@ -2,25 +2,56 @@ require "twitter/enumerable"
 require "twitter/utils"
 
 module Twitter
+  # Represents a collection of geo search results
   class GeoResults
-    include Twitter::Enumerable
-    include Twitter::Utils
+    include Enumerable
+    include Utils
+
+    # The raw attributes hash
+    #
+    # @api public
+    # @example
+    #   results.attrs
     # @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
+    #     results.to_h
+    #   @return [Hash]
+    alias_method :to_h, :attrs
+
+    # @!method to_hash
+    #   Returns the attributes as a hash
+    #   @api public
+    #   @example
+    #     results.to_hash
+    #   @return [Hash]
+    alias_method :to_hash, :to_h
 
     # Initializes a new GeoResults object
     #
-    # @param attrs [Hash]
+    # @api public
+    # @example
+    #   Twitter::GeoResults.new(result: {places: []})
+    # @param attrs [Hash] The attributes hash from the API response
     # @return [Twitter::GeoResults]
-    def initialize(attrs = {})
-      @attrs = attrs
-      @collection = @attrs[:result].fetch(:places, []).collect do |place|
+    def initialize(attrs = nil)
+      @attrs = attrs || {}
+      empty_hash = {} # : Hash[Symbol, untyped]
+      empty_array = [] # : Array[untyped]
+      @collection = @attrs.fetch(:result, empty_hash).fetch(:places, empty_array).collect do |place| # steep:ignore ArgumentTypeMismatch
         Place.new(place)
       end
     end
 
+    # Returns the token for pagination
+    #
+    # @api public
+    # @example
+    #   results.token
     # @return [String]
     def token
       @attrs[:token]

data/lib/twitter/headers.rb

@@ -1,30 +1,59 @@
-require "addressable/uri"
+require "uri"
 require "base64"
 require "simple_oauth"
 
 module Twitter
+  # Builds HTTP headers for Twitter API requests
   class Headers
+    # Initializes a new Headers object
+    #
+    # @api public
+    # @example
+    #   Twitter::Headers.new(client, :get, "https://api.twitter.com")
+    # @param client [Twitter::Client] The client making the request
+    # @param request_method [Symbol] The HTTP request method
+    # @param url [String] The request URL
+    # @param options [Hash] Additional options
+    # @return [Twitter::Headers]
     def initialize(client, request_method, url, options = {})
       @client = client
-      @request_method = request_method.to_sym
-      @uri = Addressable::URI.parse(url)
+      @request_method = request_method
+      @uri = URI.parse(url)
       @bearer_token_request = options.delete(:bearer_token_request)
       @options = options
     end
 
+    # Check if this is a bearer token request
+    #
+    # @api public
+    # @example
+    #   headers.bearer_token_request? # => false
+    # @return [Boolean]
     def bearer_token_request?
       !!@bearer_token_request
     end
 
+    # Generate OAuth authentication header
+    #
+    # @api public
+    # @example
+    #   headers.oauth_auth_header # => #<SimpleOAuth::Header>
+    # @return [SimpleOAuth::Header]
     def oauth_auth_header
-      SimpleOAuth::Header.new(@request_method, @uri, @options, @client.credentials.merge(ignore_extra_keys: true))
+      SimpleOAuth::Header.new(@request_method, @uri.to_s, @options, @client.credentials.merge(ignore_extra_keys: true))
     end
 
+    # Build the request headers hash
+    #
+    # @api public
+    # @example
+    #   headers.request_headers # => {user_agent: "...", authorization: "..."}
+    # @return [Hash]
     def request_headers
-      headers = {}
+      headers = {} # : Hash[Symbol, String]
       headers[:user_agent] = @client.user_agent
       if bearer_token_request?
-        headers[:accept]        = "*/*"
+        headers[:accept] = "*/*"
         headers[:authorization] = bearer_token_credentials_auth_header
       else
         headers[:authorization] = auth_header
@@ -32,8 +61,12 @@ module Twitter
       headers
     end
 
-  private
+    private
 
+    # Generate the appropriate auth header based on credentials
+    #
+    # @api private
+    # @return [String]
     def auth_header
       if @client.user_token?
         oauth_auth_header.to_s
@@ -43,6 +76,9 @@ module Twitter
       end
     end
 
+    # Generate a bearer auth header
+    #
+    # @api private
     # @return [String]
     def bearer_auth_header
       "Bearer #{@client.bearer_token}"
@@ -50,6 +86,7 @@ module Twitter
 
     # Generates authentication header for a bearer token request
     #
+    # @api private
     # @return [String]
     def bearer_token_credentials_auth_header
       "Basic #{Base64.strict_encode64("#{@client.consumer_key}:#{@client.consumer_secret}")}"