x-twitter-scraper 0.4.2 → 0.4.4

data/lib/x_twitter_scraper/models/x/tweet_search_params.rb

@@ -14,52 +14,322 @@ module XTwitterScraper
         #   @return [String]
         required :q, String
 
+        # @!attribute advanced_query
+        #   Raw advanced search query appended as-is.
+        #
+        #   @return [String, nil]
+        optional :advanced_query, String
+
+        # @!attribute any_words
+        #   Words or quoted phrases where any one can match. Separate with spaces, commas,
+        #   or lines.
+        #
+        #   @return [String, nil]
+        optional :any_words, String
+
+        # @!attribute bounding_box
+        #   Geo bounding box, e.g. -74.1 40.6 -73.9 40.8.
+        #
+        #   @return [String, nil]
+        optional :bounding_box, String
+
+        # @!attribute cashtags
+        #   Cashtags separated by spaces, commas, or lines.
+        #
+        #   @return [String, nil]
+        optional :cashtags, String
+
+        # @!attribute conversation_id
+        #   Conversation ID filter.
+        #
+        #   @return [String, nil]
+        optional :conversation_id, String
+
         # @!attribute cursor
         #   Pagination cursor from previous response
         #
         #   @return [String, nil]
         optional :cursor, String
 
+        # @!attribute exact_phrase
+        #   Exact phrase to match.
+        #
+        #   @return [String, nil]
+        optional :exact_phrase, String
+
+        # @!attribute exclude_words
+        #   Words or quoted phrases to exclude. Separate with spaces, commas, or lines.
+        #
+        #   @return [String, nil]
+        optional :exclude_words, String
+
+        # @!attribute from_user
+        #   Filter by author username.
+        #
+        #   @return [String, nil]
+        optional :from_user, String
+
+        # @!attribute hashtags
+        #   Hashtags separated by spaces, commas, or lines.
+        #
+        #   @return [String, nil]
+        optional :hashtags, String
+
+        # @!attribute in_reply_to_tweet_id
+        #   Only replies to this tweet ID.
+        #
+        #   @return [String, nil]
+        optional :in_reply_to_tweet_id, String
+
+        # @!attribute language
+        #   Language code filter, e.g. en or tr.
+        #
+        #   @return [String, nil]
+        optional :language, String
+
         # @!attribute limit
         #   Max tweets to return (server paginates internally). Omit for single page (~20).
+        #   This is an upper bound for paid authenticated calls: remaining credits can
+        #   reduce the returned page size, and zero affordable results returns 402
+        #   insufficient_credits.
         #
         #   @return [Integer, nil]
         optional :limit, Integer
 
+        # @!attribute list_id
+        #   Search within a list ID.
+        #
+        #   @return [String, nil]
+        optional :list_id, String
+
+        # @!attribute media_type
+        #   Filter by media type.
+        #
+        #   @return [Symbol, XTwitterScraper::Models::X::TweetSearchParams::MediaType, nil]
+        optional :media_type, enum: -> { XTwitterScraper::X::TweetSearchParams::MediaType }
+
+        # @!attribute mentioning
+        #   Filter tweets mentioning a username.
+        #
+        #   @return [String, nil]
+        optional :mentioning, String
+
+        # @!attribute min_faves
+        #   Minimum likes threshold.
+        #
+        #   @return [Integer, nil]
+        optional :min_faves, Integer
+
+        # @!attribute min_quotes
+        #   Minimum quote count threshold.
+        #
+        #   @return [Integer, nil]
+        optional :min_quotes, Integer
+
+        # @!attribute min_replies
+        #   Minimum replies threshold.
+        #
+        #   @return [Integer, nil]
+        optional :min_replies, Integer
+
+        # @!attribute min_retweets
+        #   Minimum retweets threshold.
+        #
+        #   @return [Integer, nil]
+        optional :min_retweets, Integer
+
+        # @!attribute place
+        #   Search within a place ID.
+        #
+        #   @return [String, nil]
+        optional :place, String
+
+        # @!attribute place_country
+        #   Search within a country code.
+        #
+        #   @return [String, nil]
+        optional :place_country, String
+
+        # @!attribute point_radius
+        #   Geo point radius, e.g. -73.99 40.73 25mi.
+        #
+        #   @return [String, nil]
+        optional :point_radius, String
+
         # @!attribute query_type
-        #   Sort order — Latest (chronological) or Top (engagement-ranked)
+        #   Sort order - Latest (chronological) or Top (engagement-ranked)
         #
         #   @return [Symbol, XTwitterScraper::Models::X::TweetSearchParams::QueryType, nil]
         optional :query_type, enum: -> { XTwitterScraper::X::TweetSearchParams::QueryType }
 
+        # @!attribute quotes
+        #   Quote mode.
+        #
+        #   @return [Symbol, XTwitterScraper::Models::X::TweetSearchParams::Quotes, nil]
+        optional :quotes, enum: -> { XTwitterScraper::X::TweetSearchParams::Quotes }
+
+        # @!attribute quotes_of_tweet_id
+        #   Only quotes of this tweet ID.
+        #
+        #   @return [String, nil]
+        optional :quotes_of_tweet_id, String
+
+        # @!attribute replies
+        #   Reply mode.
+        #
+        #   @return [Symbol, XTwitterScraper::Models::X::TweetSearchParams::Replies, nil]
+        optional :replies, enum: -> { XTwitterScraper::X::TweetSearchParams::Replies }
+
+        # @!attribute retweets
+        #   Retweet mode.
+        #
+        #   @return [Symbol, XTwitterScraper::Models::X::TweetSearchParams::Retweets, nil]
+        optional :retweets, enum: -> { XTwitterScraper::X::TweetSearchParams::Retweets }
+
+        # @!attribute retweets_of_tweet_id
+        #   Only retweets of this tweet ID.
+        #
+        #   @return [String, nil]
+        optional :retweets_of_tweet_id, String
+
+        # @!attribute since_date
+        #   Start date in YYYY-MM-DD format.
+        #
+        #   @return [Date, nil]
+        optional :since_date, Date
+
         # @!attribute since_time
-        #   ISO 8601 timestamp — only return tweets after this time
+        #   ISO 8601 timestamp - only return tweets after this time
         #
         #   @return [String, nil]
         optional :since_time, String
 
+        # @!attribute to_user
+        #   Filter replies sent to a username.
+        #
+        #   @return [String, nil]
+        optional :to_user, String
+
+        # @!attribute until_date
+        #   End date in YYYY-MM-DD format.
+        #
+        #   @return [Date, nil]
+        optional :until_date, Date
+
         # @!attribute until_time
-        #   ISO 8601 timestamp — only return tweets before this time
+        #   ISO 8601 timestamp - only return tweets before this time
         #
         #   @return [String, nil]
         optional :until_time, String
 
-        # @!method initialize(q:, cursor: nil, limit: nil, query_type: nil, since_time: nil, until_time: nil, request_options: {})
+        # @!attribute url
+        #   URL substring or domain filter.
+        #
+        #   @return [String, nil]
+        optional :url, String
+
+        # @!attribute verified_only
+        #   Only return tweets from verified authors.
+        #
+        #   @return [Boolean, nil]
+        optional :verified_only, XTwitterScraper::Internal::Type::Boolean
+
+        # @!method initialize(q:, advanced_query: nil, any_words: nil, bounding_box: nil, cashtags: nil, conversation_id: nil, cursor: nil, exact_phrase: nil, exclude_words: nil, from_user: nil, hashtags: nil, in_reply_to_tweet_id: nil, language: nil, limit: nil, list_id: nil, media_type: nil, mentioning: nil, min_faves: nil, min_quotes: nil, min_replies: nil, min_retweets: nil, place: nil, place_country: nil, point_radius: nil, query_type: nil, quotes: nil, quotes_of_tweet_id: nil, replies: nil, retweets: nil, retweets_of_tweet_id: nil, since_date: nil, since_time: nil, to_user: nil, until_date: nil, until_time: nil, url: nil, verified_only: nil, request_options: {})
+        #   Some parameter documentations has been truncated, see
+        #   {XTwitterScraper::Models::X::TweetSearchParams} for more details.
+        #
         #   @param q [String] Search query (keywords,
         #
+        #   @param advanced_query [String] Raw advanced search query appended as-is.
+        #
+        #   @param any_words [String] Words or quoted phrases where any one can match. Separate with spaces, commas, o
+        #
+        #   @param bounding_box [String] Geo bounding box, e.g. -74.1 40.6 -73.9 40.8.
+        #
+        #   @param cashtags [String] Cashtags separated by spaces, commas, or lines.
+        #
+        #   @param conversation_id [String] Conversation ID filter.
+        #
         #   @param cursor [String] Pagination cursor from previous response
         #
+        #   @param exact_phrase [String] Exact phrase to match.
+        #
+        #   @param exclude_words [String] Words or quoted phrases to exclude. Separate with spaces, commas, or lines.
+        #
+        #   @param from_user [String] Filter by author username.
+        #
+        #   @param hashtags [String] Hashtags separated by spaces, commas, or lines.
+        #
+        #   @param in_reply_to_tweet_id [String] Only replies to this tweet ID.
+        #
+        #   @param language [String] Language code filter, e.g. en or tr.
+        #
         #   @param limit [Integer] Max tweets to return (server paginates internally). Omit for single page (~20).
         #
-        #   @param query_type [Symbol, XTwitterScraper::Models::X::TweetSearchParams::QueryType] Sort order — Latest (chronological) or Top (engagement-ranked)
+        #   @param list_id [String] Search within a list ID.
+        #
+        #   @param media_type [Symbol, XTwitterScraper::Models::X::TweetSearchParams::MediaType] Filter by media type.
+        #
+        #   @param mentioning [String] Filter tweets mentioning a username.
+        #
+        #   @param min_faves [Integer] Minimum likes threshold.
+        #
+        #   @param min_quotes [Integer] Minimum quote count threshold.
+        #
+        #   @param min_replies [Integer] Minimum replies threshold.
+        #
+        #   @param min_retweets [Integer] Minimum retweets threshold.
+        #
+        #   @param place [String] Search within a place ID.
+        #
+        #   @param place_country [String] Search within a country code.
+        #
+        #   @param point_radius [String] Geo point radius, e.g. -73.99 40.73 25mi.
+        #
+        #   @param query_type [Symbol, XTwitterScraper::Models::X::TweetSearchParams::QueryType] Sort order - Latest (chronological) or Top (engagement-ranked)
+        #
+        #   @param quotes [Symbol, XTwitterScraper::Models::X::TweetSearchParams::Quotes] Quote mode.
+        #
+        #   @param quotes_of_tweet_id [String] Only quotes of this tweet ID.
         #
-        #   @param since_time [String] ISO 8601 timestamp — only return tweets after this time
+        #   @param replies [Symbol, XTwitterScraper::Models::X::TweetSearchParams::Replies] Reply mode.
         #
-        #   @param until_time [String] ISO 8601 timestamp — only return tweets before this time
+        #   @param retweets [Symbol, XTwitterScraper::Models::X::TweetSearchParams::Retweets] Retweet mode.
+        #
+        #   @param retweets_of_tweet_id [String] Only retweets of this tweet ID.
+        #
+        #   @param since_date [Date] Start date in YYYY-MM-DD format.
+        #
+        #   @param since_time [String] ISO 8601 timestamp - only return tweets after this time
+        #
+        #   @param to_user [String] Filter replies sent to a username.
+        #
+        #   @param until_date [Date] End date in YYYY-MM-DD format.
+        #
+        #   @param until_time [String] ISO 8601 timestamp - only return tweets before this time
+        #
+        #   @param url [String] URL substring or domain filter.
+        #
+        #   @param verified_only [Boolean] Only return tweets from verified authors.
         #
         #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
 
-        # Sort order — Latest (chronological) or Top (engagement-ranked)
+        # Filter by media type.
+        module MediaType
+          extend XTwitterScraper::Internal::Type::Enum
+
+          IMAGES = :images
+          VIDEOS = :videos
+          GIFS = :gifs
+          MEDIA = :media
+          LINKS = :links
+          NONE = :none
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
+        # Sort order - Latest (chronological) or Top (engagement-ranked)
         module QueryType
           extend XTwitterScraper::Internal::Type::Enum
 
@@ -69,6 +339,42 @@ module XTwitterScraper
           # @!method self.values
           #   @return [Array<Symbol>]
         end
+
+        # Quote mode.
+        module Quotes
+          extend XTwitterScraper::Internal::Type::Enum
+
+          INCLUDE = :include
+          EXCLUDE = :exclude
+          ONLY = :only
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
+        # Reply mode.
+        module Replies
+          extend XTwitterScraper::Internal::Type::Enum
+
+          INCLUDE = :include
+          EXCLUDE = :exclude
+          ONLY = :only
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
+        # Retweet mode.
+        module Retweets
+          extend XTwitterScraper::Internal::Type::Enum
+
+          INCLUDE = :include
+          EXCLUDE = :exclude
+          ONLY = :only
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
       end
     end
   end

data/lib/x_twitter_scraper/models/x/user_remove_follower_params.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    module X
+      # @see XTwitterScraper::Resources::X::Users#remove_follower
+      class UserRemoveFollowerParams < XTwitterScraper::Internal::Type::BaseModel
+        extend XTwitterScraper::Internal::Type::RequestParameters::Converter
+        include XTwitterScraper::Internal::Type::RequestParameters
+
+        # @!attribute id
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute account
+        #   X account identifier (@username or account ID)
+        #
+        #   @return [String]
+        required :account, String
+
+        # @!method initialize(id:, account:, request_options: {})
+        #   @param id [String]
+        #
+        #   @param account [String] X account identifier (@username or account ID)
+        #
+        #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/models/x/user_remove_follower_response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    module X
+      # @see XTwitterScraper::Resources::X::Users#remove_follower
+      class UserRemoveFollowerResponse < XTwitterScraper::Internal::Type::BaseModel
+        # @!attribute success
+        #
+        #   @return [Boolean, true]
+        required :success, const: true
+
+        # @!method initialize(success: true)
+        #   @param success [Boolean, true]
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/models/x/user_retrieve_batch_params.rb

@@ -9,13 +9,17 @@ module XTwitterScraper
         include XTwitterScraper::Internal::Type::RequestParameters
 
         # @!attribute ids
-        #   Comma-separated user IDs (max 100)
+        #   Comma-separated numeric user IDs (1-100 values). Duplicate IDs are ignored while
+        #   preserving first-seen order.
         #
         #   @return [String]
         required :ids, String
 
         # @!method initialize(ids:, request_options: {})
-        #   @param ids [String] Comma-separated user IDs (max 100)
+        #   Some parameter documentations has been truncated, see
+        #   {XTwitterScraper::Models::X::UserRetrieveBatchParams} for more details.
+        #
+        #   @param ids [String] Comma-separated numeric user IDs (1-100 values). Duplicate IDs are ignored while
         #
         #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
       end

data/lib/x_twitter_scraper/models/x/user_retrieve_batch_response.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    module X
+      # @see XTwitterScraper::Resources::X::Users#retrieve_batch
+      class UserRetrieveBatchResponse < XTwitterScraper::Internal::Type::BaseModel
+        # @!attribute has_next_page
+        #   Batch lookups never paginate.
+        #
+        #   @return [Boolean, false]
+        required :has_next_page, const: false
+
+        # @!attribute next_cursor
+        #   Empty because batch lookups never paginate.
+        #
+        #   @return [String]
+        required :next_cursor, String
+
+        # @!attribute processed_count
+        #   Number of requested IDs included in the lookup.
+        #
+        #   @return [Integer]
+        required :processed_count, Integer
+
+        # @!attribute requested_count
+        #   Number of unique IDs requested.
+        #
+        #   @return [Integer]
+        required :requested_count, Integer
+
+        # @!attribute returned_count
+        #   Number of user profiles returned and charged.
+        #
+        #   @return [Integer]
+        required :returned_count, Integer
+
+        # @!attribute unavailable_ids
+        #   Processed IDs with no returned profile, in first-seen request order.
+        #
+        #   @return [Array<String>]
+        required :unavailable_ids, XTwitterScraper::Internal::Type::ArrayOf[String]
+
+        # @!attribute unprocessed_ids
+        #   Requested IDs skipped because available credits limited processing. Retry these
+        #   IDs after adding credits.
+        #
+        #   @return [Array<String>]
+        required :unprocessed_ids, XTwitterScraper::Internal::Type::ArrayOf[String]
+
+        # @!attribute users
+        #
+        #   @return [Array<XTwitterScraper::Models::UserProfile>]
+        required :users, -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::UserProfile] }
+
+        # @!method initialize(next_cursor:, processed_count:, requested_count:, returned_count:, unavailable_ids:, unprocessed_ids:, users:, has_next_page: false)
+        #   Some parameter documentations has been truncated, see
+        #   {XTwitterScraper::Models::X::UserRetrieveBatchResponse} for more details.
+        #
+        #   Batch user lookup results. Duplicate requested IDs are ignored while preserving
+        #   first-seen order. unavailable_ids identifies processed IDs with no returned
+        #   profile. unprocessed_ids identifies IDs skipped when available credits limit
+        #   processing.
+        #
+        #   @param next_cursor [String] Empty because batch lookups never paginate.
+        #
+        #   @param processed_count [Integer] Number of requested IDs included in the lookup.
+        #
+        #   @param requested_count [Integer] Number of unique IDs requested.
+        #
+        #   @param returned_count [Integer] Number of user profiles returned and charged.
+        #
+        #   @param unavailable_ids [Array<String>] Processed IDs with no returned profile, in first-seen request order.
+        #
+        #   @param unprocessed_ids [Array<String>] Requested IDs skipped because available credits limited processing. Retry these
+        #
+        #   @param users [Array<XTwitterScraper::Models::UserProfile>]
+        #
+        #   @param has_next_page [Boolean, false] Batch lookups never paginate.
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/models/x/user_retrieve_followers_params.rb

@@ -13,24 +13,46 @@ module XTwitterScraper
         #   @return [String]
         required :id, String
 
+        # @!attribute after
+        #   Legacy cursor alias. Prefer cursor.
+        #
+        #   @return [String, nil]
+        optional :after, String
+
         # @!attribute cursor
         #   Pagination cursor for followers list
         #
         #   @return [String, nil]
         optional :cursor, String
 
+        # @!attribute limit
+        #   Legacy integer page size alias for following lists. Prefer pageSize.
+        #
+        #   @return [Integer, nil]
+        optional :limit, Integer
+
         # @!attribute page_size
-        #   Items per page (20-200, default 200)
+        #   Maximum user profiles requested from this page (20-200, default 200). The
+        #   response can contain fewer profiles because the source returned fewer or
+        #   remaining credits cover fewer results. Keep requesting next_cursor while
+        #   has_next_page is true. The deprecated limit and count aliases remain accepted.
         #
         #   @return [Integer, nil]
         optional :page_size, Integer
 
-        # @!method initialize(id:, cursor: nil, page_size: nil, request_options: {})
+        # @!method initialize(id:, after: nil, cursor: nil, limit: nil, page_size: nil, request_options: {})
+        #   Some parameter documentations has been truncated, see
+        #   {XTwitterScraper::Models::X::UserRetrieveFollowersParams} for more details.
+        #
         #   @param id [String]
         #
+        #   @param after [String] Legacy cursor alias. Prefer cursor.
+        #
         #   @param cursor [String] Pagination cursor for followers list
         #
-        #   @param page_size [Integer] Items per page (20-200, default 200)
+        #   @param limit [Integer] Legacy integer page size alias for following lists. Prefer pageSize.
+        #
+        #   @param page_size [Integer] Maximum user profiles requested from this page (20-200, default 200). The respon
         #
         #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
       end

data/lib/x_twitter_scraper/models/x/user_retrieve_followers_you_know_params.rb

@@ -19,11 +19,26 @@ module XTwitterScraper
         #   @return [String, nil]
         optional :cursor, String
 
-        # @!method initialize(id:, cursor: nil, request_options: {})
+        # @!attribute page_size
+        #   Maximum user profiles requested from this page (20-200, default 200). The
+        #   response can contain fewer profiles because the source returned fewer or
+        #   remaining credits cover fewer results. Keep requesting next_cursor while
+        #   has_next_page is true. The deprecated limit and count aliases remain accepted.
+        #
+        #   @return [Integer, nil]
+        optional :page_size, Integer
+
+        # @!method initialize(id:, cursor: nil, page_size: nil, request_options: {})
+        #   Some parameter documentations has been truncated, see
+        #   {XTwitterScraper::Models::X::UserRetrieveFollowersYouKnowParams} for more
+        #   details.
+        #
         #   @param id [String]
         #
         #   @param cursor [String] Pagination cursor for followers-you-know
         #
+        #   @param page_size [Integer] Maximum user profiles requested from this page (20-200, default 200). The respon
+        #
         #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
       end
     end

data/lib/x_twitter_scraper/models/x/user_retrieve_following_params.rb

@@ -13,24 +13,46 @@ module XTwitterScraper
         #   @return [String]
         required :id, String
 
+        # @!attribute after
+        #   Legacy cursor alias. Prefer cursor.
+        #
+        #   @return [String, nil]
+        optional :after, String
+
         # @!attribute cursor
         #   Pagination cursor for following list
         #
         #   @return [String, nil]
         optional :cursor, String
 
+        # @!attribute limit
+        #   Legacy page size alias. Prefer pageSize.
+        #
+        #   @return [Integer, nil]
+        optional :limit, Integer
+
         # @!attribute page_size
-        #   Results per page (20-200, default 200)
+        #   Maximum user profiles requested from this page (20-200, default 200). The
+        #   response can contain fewer profiles because the source returned fewer or
+        #   remaining credits cover fewer results. Keep requesting next_cursor while
+        #   has_next_page is true. The deprecated limit and count aliases remain accepted.
         #
         #   @return [Integer, nil]
         optional :page_size, Integer
 
-        # @!method initialize(id:, cursor: nil, page_size: nil, request_options: {})
+        # @!method initialize(id:, after: nil, cursor: nil, limit: nil, page_size: nil, request_options: {})
+        #   Some parameter documentations has been truncated, see
+        #   {XTwitterScraper::Models::X::UserRetrieveFollowingParams} for more details.
+        #
         #   @param id [String]
         #
+        #   @param after [String] Legacy cursor alias. Prefer cursor.
+        #
         #   @param cursor [String] Pagination cursor for following list
         #
-        #   @param page_size [Integer] Results per page (20-200, default 200)
+        #   @param limit [Integer] Legacy page size alias. Prefer pageSize.
+        #
+        #   @param page_size [Integer] Maximum user profiles requested from this page (20-200, default 200). The respon
         #
         #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
       end