twitter 8.2.0 → 8.3.0

data/lib/twitter/premium_search_results.rb

@@ -5,17 +5,42 @@ require "twitter/utils"
 require "uri"
 
 module Twitter
+  # Represents premium search results from Twitter
   class PremiumSearchResults
-    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
 
-    # Initializes a new SearchResults object
+    # @!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 PremiumSearchResults object
     #
-    # @param request [Twitter::REST::Request]
+    # @api public
+    # @example
+    #   Twitter::PremiumSearchResults.new(request)
+    # @param request [Twitter::REST::Request] The request object
+    # @param request_config [Hash] Configuration options
     # @return [Twitter::PremiumSearchResults]
     def initialize(request, request_config = {})
       @client = request.client
@@ -27,41 +52,85 @@ module Twitter
       self.attrs = request.perform
     end
 
-  private
+    private
 
+    # Returns true if this is the last page of results
+    #
+    # @api private
     # @return [Boolean]
     def last?
       !next_page?
     end
 
+    # Returns true if there is a next page
+    #
+    # @api private
     # @return [Boolean]
     def next_page?
-      !!@attrs[:next]
+      !next_page_token.nil?
     end
 
-    # Returns a Hash of query parameters for the next result in the search
+    # Returns query parameters for the next page
     #
-    # @note Returned Hash can be merged into the previous search options list to easily access the next page.
-    # @return [Hash] The parameters needed to fetch the next page.
+    # @api private
+    # @note Returned Hash can be merged into previous search options
+    # @return [Hash]
     def next_page
-      {next: @attrs[:next]} if next_page?
+      return if next_page_token.nil?
+
+      {next: next_page_token}
     end
 
+    # Fetches the next page of results
+    #
+    # @api private
     # @return [Hash]
     def fetch_next_page
-      request = @client.premium_search(@options[:query], (@options.reject { |k| k == :query } || {}).merge(next_page), @request_config)
+      request = @client.premium_search(search_query, next_page_options, @request_config) # steep:ignore ArgumentTypeMismatch
 
       self.attrs = request.attrs
     end
 
-    # @param attrs [Hash]
+    # Sets the attributes and populates the collection
+    #
+    # @api private
+    # @param attrs [Hash] The attributes hash
     # @return [Hash]
     def attrs=(attrs)
-      @attrs = attrs
-      @attrs.fetch(:results, []).collect do |tweet|
-        @collection << Tweet.new(tweet)
+      attrs.tap do |value|
+        @attrs = value
+        @collection.concat(value.fetch(:results, []).map { |tweet| Tweet.new(tweet) })
       end
-      @attrs
+    end
+
+    # Returns the token used to fetch the next results page
+    #
+    # @api private
+    # @example
+    #   results.send(:next_page_token)
+    # @return [String, nil]
+    def next_page_token
+      @attrs[:next]
+    end
+
+    # Returns the original search query for this result set
+    #
+    # @api private
+    # @example
+    #   results.send(:search_query)
+    # @return [String, nil]
+    def search_query
+      @options[:query]
+    end
+
+    # Returns request options for fetching the next page
+    #
+    # @api private
+    # @example
+    #   results.send(:next_page_options)
+    # @return [Hash]
+    def next_page_options
+      @options.dup.tap { |options| options.delete(:query) }.merge(next_page || {})
     end
   end
 end

data/lib/twitter/profile.rb

@@ -1,65 +1,92 @@
-require "addressable/uri"
+require "uri"
 require "cgi"
 require "memoizable"
 
 module Twitter
+  # Provides profile image and banner URL methods
   module Profile
+    # Regular expression for profile image suffix
     PROFILE_IMAGE_SUFFIX_REGEX = /_normal(\.gif|\.jpe?g|\.png)$/i
-    PREDICATE_URI_METHOD_REGEX = /_uri\?$/
     include Memoizable
 
-    class << self
-    private
-
-      def alias_predicate_uri_methods(method)
-        %w[_url? _uri_https? _url_https?].each do |replacement|
-          alias_method_sub(method, PREDICATE_URI_METHOD_REGEX, replacement)
-        end
-      end
-
-      def alias_method_sub(method, pattern, replacement)
-        alias_method(method.to_s.sub(pattern, replacement).to_sym, method)
-      end
-    end
-
-    # Return the URL to the user's profile banner image
+    # Returns the URL to the user's profile banner image
     #
-    # @param size [String, Symbol] The size of the image. Must be one of: 'mobile', 'mobile_retina', 'web', 'web_retina', 'ipad', or 'ipad_retina'
-    # @return [Addressable::URI]
+    # @api public
+    # @example
+    #   user.profile_banner_uri(:web)
+    # @param size [String, Symbol] The size of the image
+    # @return [URI::Generic]
     def profile_banner_uri(size = :web)
-      parse_uri(insecure_uri([@attrs[:profile_banner_url], size].join("/"))) unless @attrs[:profile_banner_url].nil?
+      parse_uri(insecure_uri([@attrs[:profile_banner_url], size].join("/"))) unless @attrs[:profile_banner_url].nil? # steep:ignore FallbackAny
     end
-    alias profile_banner_url profile_banner_uri
 
-    # Return the secure URL to the user's profile banner image
+    # @!method profile_banner_url
+    #   Returns the URL to the user's profile banner image
+    #   @api public
+    #   @example
+    #     user.profile_banner_url(:web)
+    #   @return [URI::Generic]
+    alias_method :profile_banner_url, :profile_banner_uri
+
+    # Returns the secure URL to the user's profile banner image
     #
-    # @param size [String, Symbol] The size of the image. Must be one of: 'mobile', 'mobile_retina', 'web', 'web_retina', 'ipad', or 'ipad_retina'
-    # @return [Addressable::URI]
+    # @api public
+    # @example
+    #   user.profile_banner_uri_https(:web)
+    # @param size [String, Symbol] The size of the image
+    # @return [URI::Generic]
     def profile_banner_uri_https(size = :web)
-      parse_uri([@attrs[:profile_banner_url], size].join("/")) unless @attrs[:profile_banner_url].nil?
+      parse_uri([@attrs[:profile_banner_url], size].join("/")) unless @attrs[:profile_banner_url].nil? # steep:ignore FallbackAny
     end
-    alias profile_banner_url_https profile_banner_uri_https
 
+    # @!method profile_banner_url_https
+    #   Returns the secure URL to the user's profile banner image
+    #   @api public
+    #   @example
+    #     user.profile_banner_url_https(:web)
+    #   @return [URI::Generic]
+    alias_method :profile_banner_url_https, :profile_banner_uri_https
+
+    # Returns true if the user has a profile banner
+    #
+    # @api public
+    # @example
+    #   user.profile_banner_uri?
     # @return [Boolean]
     def profile_banner_uri?
-      !!@attrs[:profile_banner_url]
+      !!@attrs[:profile_banner_url] # steep:ignore FallbackAny
     end
     memoize :profile_banner_uri?
-    alias_predicate_uri_methods :profile_banner_uri?
+    alias_method :profile_banner_url?, :profile_banner_uri?
+    alias_method :profile_banner_uri_https?, :profile_banner_uri?
+    alias_method :profile_banner_url_https?, :profile_banner_uri?
 
-    # Return the URL to the user's profile image
+    # Returns the URL to the user's profile image
     #
-    # @param size [String, Symbol] The size of the image. Must be one of: 'mini', 'normal', 'bigger' or 'original'
-    # @return [Addressable::URI]
+    # @api public
+    # @example
+    #   user.profile_image_uri(:normal)
+    # @param size [String, Symbol] The size of the image
+    # @return [URI::Generic]
     def profile_image_uri(size = :normal)
-      parse_uri(insecure_uri(profile_image_uri_https(size))) unless @attrs[:profile_image_url_https].nil?
+      parse_uri(insecure_uri(profile_image_uri_https(size))) unless @attrs[:profile_image_url_https].nil? # steep:ignore FallbackAny
     end
-    alias profile_image_url profile_image_uri
 
-    # Return the secure URL to the user's profile image
+    # @!method profile_image_url
+    #   Returns the URL to the user's profile image
+    #   @api public
+    #   @example
+    #     user.profile_image_url(:normal)
+    #   @return [URI::Generic]
+    alias_method :profile_image_url, :profile_image_uri
+
+    # Returns the secure URL to the user's profile image
     #
-    # @param size [String, Symbol] The size of the image. Must be one of: 'mini', 'normal', 'bigger' or 'original'
-    # @return [Addressable::URI]
+    # @api public
+    # @example
+    #   user.profile_image_uri_https(:normal)
+    # @param size [String, Symbol] The size of the image
+    # @return [URI::Generic]
     def profile_image_uri_https(size = :normal)
       # The profile image URL comes in looking like like this:
       # https://a0.twimg.com/profile_images/1759857427/image1326743606_normal.png
@@ -67,29 +94,58 @@ module Twitter
       # https://a0.twimg.com/profile_images/1759857427/image1326743606.png
       # https://a0.twimg.com/profile_images/1759857427/image1326743606_mini.png
       # https://a0.twimg.com/profile_images/1759857427/image1326743606_bigger.png
-      parse_uri(@attrs[:profile_image_url_https].sub(PROFILE_IMAGE_SUFFIX_REGEX, profile_image_suffix(size))) unless @attrs[:profile_image_url_https].nil?
+      parse_uri(@attrs[:profile_image_url_https].sub(PROFILE_IMAGE_SUFFIX_REGEX, profile_image_suffix(size))) unless @attrs[:profile_image_url_https].nil? # steep:ignore FallbackAny
     end
-    alias profile_image_url_https profile_image_uri_https
 
+    # @!method profile_image_url_https
+    #   Returns the secure URL to the user's profile image
+    #   @api public
+    #   @example
+    #     user.profile_image_url_https(:normal)
+    #   @return [URI::Generic]
+    alias_method :profile_image_url_https, :profile_image_uri_https
+
+    # Returns true if the user has a profile image
+    #
+    # @api public
+    # @example
+    #   user.profile_image_uri?
     # @return [Boolean]
     def profile_image_uri?
-      !!@attrs[:profile_image_url_https]
+      !!@attrs[:profile_image_url_https] # steep:ignore FallbackAny
     end
     memoize :profile_image_uri?
-    alias_predicate_uri_methods :profile_image_uri?
+    alias_method :profile_image_url?, :profile_image_uri?
+    alias_method :profile_image_uri_https?, :profile_image_uri?
+    alias_method :profile_image_url_https?, :profile_image_uri?
 
-  private
+    private
 
+    # Parses a URI string
+    #
+    # @api private
+    # @param uri [String] The URI string
+    # @return [URI::Generic]
     def parse_uri(uri)
-      Addressable::URI.parse(uri)
+      URI.parse(uri.gsub(/[^\x00-\x7F]/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join })
     end
 
+    # Converts a URI to insecure (http) version
+    #
+    # @api private
+    # @param uri [Object] The URI to convert
+    # @return [String]
     def insecure_uri(uri)
-      uri.to_s.sub(/^https/i, "http")
+      uri.to_s.sub(/\Ahttps/i, "http")
     end
 
+    # Returns the suffix for profile image URLs
+    #
+    # @api private
+    # @param size [Symbol] The size
+    # @return [String]
     def profile_image_suffix(size)
-      size.to_sym == :original ? '\\1' : "_#{size}\\1"
+      (size.to_sym == :original) ? '\\1' : "_#{size}\\1"
     end
   end
 end

data/lib/twitter/profile_banner.rb

@@ -2,14 +2,19 @@ require "memoizable"
 require "twitter/base"
 
 module Twitter
-  class ProfileBanner < Twitter::Base
+  # Represents a user's profile banner
+  class ProfileBanner < Base
     include Memoizable
 
-    # Returns an array of photo sizes
+    # Returns a hash of banner sizes
     #
-    # @return [Array<Twitter::Size>]
+    # @api public
+    # @example
+    #   profile_banner.sizes
+    # @return [Hash{Symbol => Twitter::Size}]
     def sizes
-      @attrs.fetch(:sizes, []).each_with_object({}) do |(key, value), object|
+      result = {} # : Hash[Symbol, Size]
+      @attrs.fetch(:sizes, []).each_with_object(result) do |(key, value), object|
         object[key] = Size.new(value)
       end
     end

data/lib/twitter/rate_limit.rb

@@ -1,9 +1,15 @@
 require "memoizable"
 
 module Twitter
-  class RateLimit < Twitter::Base
+  # Represents rate limit information from Twitter API responses
+  class RateLimit < Base
     include Memoizable
 
+    # Returns the rate limit ceiling for this request
+    #
+    # @api public
+    # @example
+    #   rate_limit.limit
     # @return [Integer]
     def limit
       limit = @attrs["x-rate-limit-limit"]
@@ -11,6 +17,11 @@ module Twitter
     end
     memoize :limit
 
+    # Returns the number of requests remaining
+    #
+    # @api public
+    # @example
+    #   rate_limit.remaining
     # @return [Integer]
     def remaining
       remaining = @attrs["x-rate-limit-remaining"]
@@ -18,6 +29,11 @@ module Twitter
     end
     memoize :remaining
 
+    # Returns the time when the rate limit resets
+    #
+    # @api public
+    # @example
+    #   rate_limit.reset_at
     # @return [Time]
     def reset_at
       reset = @attrs["x-rate-limit-reset"]
@@ -25,10 +41,23 @@ module Twitter
     end
     memoize :reset_at
 
+    # Returns the number of seconds until the rate limit resets
+    #
+    # @api public
+    # @example
+    #   rate_limit.reset_in
     # @return [Integer]
     def reset_in
-      [(reset_at - Time.now).ceil, 0].max if reset_at
+      time = reset_at
+      [(time - Time.now).ceil, 0].max if time
     end
-    alias retry_after reset_in
+
+    # @!method retry_after
+    #   Returns the number of seconds until the rate limit resets
+    #   @api public
+    #   @example
+    #     rate_limit.retry_after
+    #   @return [Integer]
+    alias_method :retry_after, :reset_in
   end
 end

data/lib/twitter/relationship.rb

@@ -1,17 +1,20 @@
 require "twitter/base"
 
 module Twitter
-  class Relationship < Twitter::Base
+  # Represents a relationship between two Twitter users
+  class Relationship < Base
     object_attr_reader :SourceUser, :source
     object_attr_reader :TargetUser, :target
 
-    # Initializes a new object
+    # Initializes a new Relationship object
     #
-    # @param attrs [Hash]
+    # @api public
+    # @example
+    #   Twitter::Relationship.new(relationship: {source: {}, target: {}})
+    # @param attrs [Hash] The attributes hash
     # @return [Twitter::Relationship]
     def initialize(attrs = {})
-      super
-      @attrs = attrs[:relationship]
+      super(attrs[:relationship]) # steep:ignore NoMethod
     end
   end
 end

data/lib/twitter/rest/account_activity.rb

@@ -4,93 +4,122 @@ require "twitter/utils"
 
 module Twitter
   module REST
+    # Methods for interacting with the Account Activity API
     module AccountActivity
       include Twitter::REST::Utils
       include Twitter::Utils
 
-      # Registers a webhook URL for all event types. The URL will be validated via CRC request before saving. In case the validation failed, returns comprehensive error message to the requester.
+      # Registers a webhook URL for all event types
+      #
+      # @api public
       # @see https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference
       # @see https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/aaa-premium#post-account-activity-all-env-name-webhooks
       # @note Create a webhook
       # @rate_limited Yes
       # @authentication Requires user context - all consumer and access tokens
-      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.create_webhook("production", "https://example.com/webhook")
+      # @param env_name [String] Environment Name
+      # @param url [String] Encoded URL for the callback endpoint
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid
       # @return [Hash]
-      # @param env_name [String] Environment Name.
-      # @param url [String] Encoded URL for the callback endpoint.
       def create_webhook(env_name, url)
         perform_request(:json_post, "/1.1/account_activity/all/#{env_name}/webhooks.json?url=#{url}")
       end
 
-      # Returns all environments, webhook URLs and their statuses for the authenticating app. Currently, only one webhook URL can be registered to each environment.
+      # Returns all environments and webhook URLs for the app
+      #
+      # @api public
       # @see https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/aaa-premium#get-account-activity-all-webhooks
       # @note List webhooks
       # @rate_limited Yes
       # @authentication Requires user context - all consumer and access tokens
-      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list_webhooks("production")
+      # @param env_name [String] Environment Name
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid
       # @return [Hash]
-      # @param env_name [String] Environment Name.
       def list_webhooks(env_name)
         perform_request(:get, "/1.1/account_activity/all/#{env_name}/webhooks.json")
       end
 
-      # Removes the webhook from the provided application's all activities configuration. The webhook ID can be accessed by making a call to GET /1.1/account_activity/all/webhooks.
+      # Removes the webhook from the application's configuration
+      #
+      # @api public
       # @see https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/aaa-premium#delete-account-activity-all-env-name-webhooks-webhook-id
       # @note Delete a webhook
       # @authentication Requires user context - all consumer and access tokens
-      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.delete_webhook("production", "12345")
+      # @param env_name [String] Environment Name
+      # @param webhook_id [String] Webhook ID
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid
       # @return [nil]
-      # @param env_name [String] Environment Name.
-      # @param webhook_id [String] Webhook ID.
       def delete_webhook(env_name, webhook_id)
         perform_request(:delete, "/1.1/account_activity/all/#{env_name}/webhooks/#{webhook_id}.json")
       end
 
-      # Triggers the challenge response check (CRC) for the given enviroments webhook for all activites. If the check is successful, returns 204 and reenables the webhook by setting its status to valid.
+      # Triggers the challenge response check (CRC) for a webhook
+      #
+      # @api public
       # @see https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/aaa-premium#put-account-activity-all-env-name-webhooks-webhook-id
       # @note Trigger CRC check to a webhook
       # @rate_limited Yes
       # @authentication Requires user context - all consumer and access tokens
-      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.trigger_crc_check("production", "12345")
+      # @param env_name [String] Environment Name
+      # @param webhook_id [String] Webhook ID
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid
       # @return [nil]
-      # @param env_name [String] Environment Name.
-      # @param webhook_id [String] Webhook ID.
       def trigger_crc_check(env_name, webhook_id)
         perform_request(:json_put, "/1.1/account_activity/all/#{env_name}/webhooks/#{webhook_id}.json")
       end
 
-      # Subscribes the provided application to all events for the provided environment for all message types. After activation, all events for the requesting user will be sent to the application's webhook via POST request.
+      # Subscribes the application to all events for the environment
+      #
+      # @api public
       # @see https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/aaa-premium#post-account-activity-all-env-name-subscriptions
-      # @note Subscribe the user(whose credentials are provided) to the app so that the webhook can receive all types of events from user
+      # @note Subscribe the user to receive webhook events
       # @rate_limited Yes
       # @authentication Requires user context - all consumer and access tokens
-      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
-      # @return [nil]
+      # @example
+      #   client.create_subscription("production")
       # @param env_name [String] Environment Name
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid
+      # @return [nil]
       def create_subscription(env_name)
         perform_request(:json_post, "/1.1/account_activity/all/#{env_name}/subscriptions.json")
       end
 
-      # Provides a way to determine if a webhook configuration is subscribed to the provided user's events. If the provided user context has an active subscription with provided application, returns 204 OK.
+      # Checks if the user is subscribed to the webhook
+      #
+      # @api public
       # @see https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/aaa-premium#get-account-activity-all-env-name-subscriptions
       # @note Check if the user is subscribed to the given app
       # @rate_limited Yes
       # @authentication Requires user context - all consumer and access tokens
-      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
-      # @return [nil]
+      # @example
+      #   client.check_subscription("production")
       # @param env_name [String] Environment Name
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid
+      # @return [nil]
       def check_subscription(env_name)
         perform_request(:get, "/1.1/account_activity/all/#{env_name}/subscriptions.json")
       end
 
-      # Deactivates subscription(s) for the provided user context and application for all activities. After deactivation, all events for the requesting user will no longer be sent to the webhook URL.
+      # Deactivates subscription for the user and application
+      #
+      # @api public
       # @see https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/aaa-premium#delete-account-activity-all-env-name-subscriptions
-      # @note Deactivate a subscription, Users events will not be sent to the app
+      # @note Deactivate a subscription
       # @rate_limited Yes
       # @authentication Requires user context - all consumer and access tokens
-      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
-      # @return [nil]
+      # @example
+      #   client.deactivate_subscription("production")
       # @param env_name [String] Environment Name
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid
+      # @return [nil]
       def deactivate_subscription(env_name)
         perform_request(:delete, "/1.1/account_activity/all/#{env_name}/subscriptions.json")
       end

data/lib/twitter/rest/api.rb

@@ -19,7 +19,9 @@ require "twitter/rest/undocumented"
 require "twitter/rest/users"
 
 module Twitter
+  # REST API modules for Twitter
   module REST
+    # Combined Twitter REST API methods
     # @note All methods have been separated into modules and follow the same grouping used in {http://dev.twitter.com/doc the Twitter API Documentation}.
     # @see https://dev.twitter.com/overview/general/things-every-developer-should-know
     module API

data/lib/twitter/rest/client.rb

@@ -5,15 +5,33 @@ require "twitter/rest/utils"
 
 module Twitter
   module REST
+    # REST API client for Twitter
     class Client < Twitter::Client
       include Twitter::REST::API
+
+      # The bearer token for application-only authentication
+      #
+      # @api public
+      # @example
+      #   client.bearer_token = "AAAA..."
+      # @return [String]
       attr_accessor :bearer_token
 
+      # Returns true if a bearer token is set
+      #
+      # @api public
+      # @example
+      #   client.bearer_token?
       # @return [Boolean]
       def bearer_token?
         !!bearer_token
       end
 
+      # Returns true if credentials are configured
+      #
+      # @api public
+      # @example
+      #   client.credentials?
       # @return [Boolean]
       def credentials?
         super || bearer_token?