x-twitter-scraper 0.4.2 → 0.4.4

data/lib/x_twitter_scraper/resources/x/media.rb

@@ -3,16 +3,20 @@
 module XTwitterScraper
   module Resources
     class X
-      # Media upload & download
+      # Media upload and download
       class Media
-        # Download tweet media
+        # Download images and videos from tweets
         #
-        # @overload download(tweet_ids: nil, tweet_input: nil, request_options: {})
+        # @overload download(tweet_id: nil, tweet_ids: nil, tweet_input: nil, tweet_url: nil, request_options: {})
         #
-        # @param tweet_ids [Array<String>] Array of tweet URLs or IDs (bulk, max 50)
+        # @param tweet_id [String] Numeric tweet ID alias for tweetInput
+        #
+        # @param tweet_ids [Array<String>] Array of tweet URLs or IDs (bulk, max 50 string items)
         #
         # @param tweet_input [String] Tweet URL or ID (single tweet)
         #
+        # @param tweet_url [String] Tweet URL alias for tweetInput
+        #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [XTwitterScraper::Models::X::MediaDownloadResponse]
@@ -31,13 +35,11 @@ module XTwitterScraper
 
         # Upload media
         #
-        # @overload upload(account:, file:, is_long_video: nil, request_options: {})
-        #
-        # @param account [String] X account (@username or ID) uploading media
+        # @overload upload(account:, url:, request_options: {})
         #
-        # @param file [Pathname, StringIO, IO, String, XTwitterScraper::FilePart] Media file to upload
+        # @param account [String] X account (@username or ID) uploading media from URL
         #
-        # @param is_long_video [Boolean]
+        # @param url [String] HTTPS URL to download and upload as media
         #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #

data/lib/x_twitter_scraper/resources/x/profile.rb

@@ -37,11 +37,11 @@ module XTwitterScraper
 
         # Update profile avatar
         #
-        # @overload update_avatar(account:, file:, request_options: {})
+        # @overload update_avatar(account:, url:, request_options: {})
         #
-        # @param account [String] X account (@username or ID) for avatar update
+        # @param account [String] X account (@username or ID) receiving avatar from URL
         #
-        # @param file [Pathname, StringIO, IO, String, XTwitterScraper::FilePart] Avatar image (max 716KB)
+        # @param url [String] HTTPS URL to the avatar image to download
         #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -62,11 +62,11 @@ module XTwitterScraper
 
         # Update profile banner
         #
-        # @overload update_banner(account:, file:, request_options: {})
+        # @overload update_banner(account:, url:, request_options: {})
         #
-        # @param account [String] X account (@username or ID) for banner update
+        # @param account [String] X account (@username or ID) receiving banner from URL
         #
-        # @param file [Pathname, StringIO, IO, String, XTwitterScraper::FilePart] Banner image (max 2MB)
+        # @param url [String] HTTPS URL to the banner image to download
         #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #

data/lib/x_twitter_scraper/resources/x/tweets.rb

@@ -12,24 +12,27 @@ module XTwitterScraper
         # @return [XTwitterScraper::Resources::X::Tweets::Retweet]
         attr_reader :retweet
 
+        # Some parameter documentations has been truncated, see
+        # {XTwitterScraper::Models::X::TweetCreateParams} for more details.
+        #
         # Create tweet
         #
-        # @overload create(account:, text:, attachment_url: nil, community_id: nil, is_note_tweet: nil, media_ids: nil, reply_to_tweet_id: nil, request_options: {})
+        # @overload create(account:, attachment_url: nil, community_id: nil, is_note_tweet: nil, media: nil, reply_to_tweet_id: nil, text: nil, request_options: {})
         #
         # @param account [String] X account (@username or account ID)
         #
-        # @param text [String]
-        #
         # @param attachment_url [String]
         #
         # @param community_id [String]
         #
         # @param is_note_tweet [Boolean]
         #
-        # @param media_ids [Array<String>]
+        # @param media [Array<String>] Array of public media URLs to attach. Supports up to 4 images or exactly 1 MP4 v
         #
         # @param reply_to_tweet_id [String]
         #
+        # @param text [String] Tweet text (optional when media is provided)
+        #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [XTwitterScraper::Models::X::TweetCreateResponse]
@@ -46,11 +49,11 @@ module XTwitterScraper
           )
         end
 
-        # Look up tweet
+        # Get tweet with full text, author, metrics and media
         #
         # @overload retrieve(id, request_options: {})
         #
-        # @param id [String] Tweet ID
+        # @param id [String] Numeric tweet ID, 15-20 digits
         #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -113,14 +116,19 @@ module XTwitterScraper
           )
         end
 
-        # Get users who liked a tweet
+        # Some parameter documentations has been truncated, see
+        # {XTwitterScraper::Models::X::TweetGetFavoritersParams} for more details.
+        #
+        # List users who liked a tweet
         #
-        # @overload get_favoriters(id, cursor: nil, request_options: {})
+        # @overload get_favoriters(id, cursor: nil, page_size: nil, request_options: {})
         #
         # @param id [String] Tweet ID to get favoriters
         #
         # @param cursor [String] Pagination cursor for favoriters
         #
+        # @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}, nil]
         #
         # @return [XTwitterScraper::Models::PaginatedUsers]
@@ -132,26 +140,81 @@ module XTwitterScraper
           @client.request(
             method: :get,
             path: ["x/tweets/%1$s/favoriters", id],
-            query: query,
+            query: query.transform_keys(page_size: "pageSize"),
             model: XTwitterScraper::PaginatedUsers,
             options: options
           )
         end
 
-        # Get quote tweets of a tweet
+        # Some parameter documentations has been truncated, see
+        # {XTwitterScraper::Models::X::TweetGetQuotesParams} for more details.
+        #
+        # List quote tweets of a tweet
         #
-        # @overload get_quotes(id, cursor: nil, include_replies: nil, since_time: nil, until_time: nil, request_options: {})
+        # @overload get_quotes(id, any_words: nil, cashtags: nil, conversation_id: nil, cursor: nil, exact_phrase: nil, exclude_words: nil, from_user: nil, hashtags: nil, include_replies: nil, in_reply_to_tweet_id: nil, language: nil, media_type: nil, mentioning: nil, min_faves: nil, min_quotes: nil, min_replies: nil, min_retweets: nil, page_size: 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: {})
         #
-        # @param id [String] Tweet ID to get quotes
+        # @param id [String] Numeric tweet ID to get quotes, 15-20 digits
+        #
+        # @param any_words [String] Words or quoted phrases where any one can match. Separate with spaces, commas, o
+        #
+        # @param cashtags [String] Cashtags separated by spaces, commas, or lines.
+        #
+        # @param conversation_id [String] Conversation ID filter.
         #
         # @param cursor [String] Pagination cursor for quote tweets
         #
+        # @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 include_replies [Boolean] Include reply quotes (default false)
         #
+        # @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 media_type [Symbol, XTwitterScraper::Models::X::TweetGetQuotesParams::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 page_size [Integer] Maximum items requested from this page (1-100, default 20). The response can con
+        #
+        # @param quotes [Symbol, XTwitterScraper::Models::X::TweetGetQuotesParams::Quotes] Quote mode.
+        #
+        # @param quotes_of_tweet_id [String] Only quotes of this tweet ID.
+        #
+        # @param replies [Symbol, XTwitterScraper::Models::X::TweetGetQuotesParams::Replies] Reply mode.
+        #
+        # @param retweets [Symbol, XTwitterScraper::Models::X::TweetGetQuotesParams::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] Unix timestamp - return quotes posted 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] Unix timestamp - return quotes posted 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}, nil]
         #
         # @return [XTwitterScraper::Models::PaginatedTweets]
@@ -164,27 +227,100 @@ module XTwitterScraper
             method: :get,
             path: ["x/tweets/%1$s/quotes", id],
             query: query.transform_keys(
+              any_words: "anyWords",
+              conversation_id: "conversationId",
+              exact_phrase: "exactPhrase",
+              exclude_words: "excludeWords",
+              from_user: "fromUser",
               include_replies: "includeReplies",
+              in_reply_to_tweet_id: "inReplyToTweetId",
+              media_type: "mediaType",
+              min_faves: "minFaves",
+              min_quotes: "minQuotes",
+              min_replies: "minReplies",
+              min_retweets: "minRetweets",
+              page_size: "pageSize",
+              quotes_of_tweet_id: "quotesOfTweetId",
+              retweets_of_tweet_id: "retweetsOfTweetId",
+              since_date: "sinceDate",
               since_time: "sinceTime",
-              until_time: "untilTime"
+              to_user: "toUser",
+              until_date: "untilDate",
+              until_time: "untilTime",
+              verified_only: "verifiedOnly"
             ),
             model: XTwitterScraper::PaginatedTweets,
             options: options
           )
         end
 
-        # Get replies to a tweet
+        # Some parameter documentations has been truncated, see
+        # {XTwitterScraper::Models::X::TweetGetRepliesParams} for more details.
         #
-        # @overload get_replies(id, cursor: nil, since_time: nil, until_time: nil, request_options: {})
+        # List replies to a tweet
+        #
+        # @overload get_replies(id, any_words: 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, media_type: nil, mentioning: nil, min_faves: nil, min_quotes: nil, min_replies: nil, min_retweets: nil, page_size: 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: {})
         #
         # @param id [String] Tweet ID to get replies
         #
+        # @param any_words [String] Words or quoted phrases where any one can match. Separate with spaces, commas, o
+        #
+        # @param cashtags [String] Cashtags separated by spaces, commas, or lines.
+        #
+        # @param conversation_id [String] Conversation ID filter.
+        #
         # @param cursor [String] Pagination cursor for tweet replies
         #
+        # @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 media_type [Symbol, XTwitterScraper::Models::X::TweetGetRepliesParams::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 page_size [Integer] Maximum items requested from this page (1-100, default 20). The response can con
+        #
+        # @param quotes [Symbol, XTwitterScraper::Models::X::TweetGetRepliesParams::Quotes] Quote mode.
+        #
+        # @param quotes_of_tweet_id [String] Only quotes of this tweet ID.
+        #
+        # @param replies [Symbol, XTwitterScraper::Models::X::TweetGetRepliesParams::Replies] Reply mode.
+        #
+        # @param retweets [Symbol, XTwitterScraper::Models::X::TweetGetRepliesParams::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] Unix timestamp - return replies posted 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] Unix timestamp - return replies posted 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}, nil]
         #
         # @return [XTwitterScraper::Models::PaginatedTweets]
@@ -196,20 +332,46 @@ module XTwitterScraper
           @client.request(
             method: :get,
             path: ["x/tweets/%1$s/replies", id],
-            query: query.transform_keys(since_time: "sinceTime", until_time: "untilTime"),
+            query: query.transform_keys(
+              any_words: "anyWords",
+              conversation_id: "conversationId",
+              exact_phrase: "exactPhrase",
+              exclude_words: "excludeWords",
+              from_user: "fromUser",
+              in_reply_to_tweet_id: "inReplyToTweetId",
+              media_type: "mediaType",
+              min_faves: "minFaves",
+              min_quotes: "minQuotes",
+              min_replies: "minReplies",
+              min_retweets: "minRetweets",
+              page_size: "pageSize",
+              quotes_of_tweet_id: "quotesOfTweetId",
+              retweets_of_tweet_id: "retweetsOfTweetId",
+              since_date: "sinceDate",
+              since_time: "sinceTime",
+              to_user: "toUser",
+              until_date: "untilDate",
+              until_time: "untilTime",
+              verified_only: "verifiedOnly"
+            ),
             model: XTwitterScraper::PaginatedTweets,
             options: options
           )
         end
 
-        # Get users who retweeted a tweet
+        # Some parameter documentations has been truncated, see
+        # {XTwitterScraper::Models::X::TweetGetRetweetersParams} for more details.
+        #
+        # List users who retweeted a tweet
         #
-        # @overload get_retweeters(id, cursor: nil, request_options: {})
+        # @overload get_retweeters(id, cursor: nil, page_size: nil, request_options: {})
         #
         # @param id [String] Tweet ID to get retweeters
         #
         # @param cursor [String] Pagination cursor for retweeters
         #
+        # @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}, nil]
         #
         # @return [XTwitterScraper::Models::PaginatedUsers]
@@ -221,20 +383,25 @@ module XTwitterScraper
           @client.request(
             method: :get,
             path: ["x/tweets/%1$s/retweeters", id],
-            query: query,
+            query: query.transform_keys(page_size: "pageSize"),
             model: XTwitterScraper::PaginatedUsers,
             options: options
           )
         end
 
-        # Get thread context for a tweet
+        # Some parameter documentations has been truncated, see
+        # {XTwitterScraper::Models::X::TweetGetThreadParams} for more details.
+        #
+        # Get full conversation thread for a tweet
         #
-        # @overload get_thread(id, cursor: nil, request_options: {})
+        # @overload get_thread(id, cursor: nil, page_size: nil, request_options: {})
         #
         # @param id [String] Tweet ID to get thread context
         #
         # @param cursor [String] Pagination cursor for thread tweets
         #
+        # @param page_size [Integer] Maximum items requested from this page (1-100, default 20). The response can con
+        #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [XTwitterScraper::Models::PaginatedTweets]
@@ -246,27 +413,92 @@ module XTwitterScraper
           @client.request(
             method: :get,
             path: ["x/tweets/%1$s/thread", id],
-            query: query,
+            query: query.transform_keys(page_size: "pageSize"),
             model: XTwitterScraper::PaginatedTweets,
             options: options
           )
         end
 
-        # Search tweets
+        # Some parameter documentations has been truncated, see
+        # {XTwitterScraper::Models::X::TweetSearchParams} for more details.
+        #
+        # Search tweets by query, Tweet ID, X status URL, or account date window
         #
-        # @overload search(q:, cursor: nil, limit: nil, query_type: nil, since_time: nil, until_time: nil, request_options: {})
+        # @overload search(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: {})
         #
         # @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 replies [Symbol, XTwitterScraper::Models::X::TweetSearchParams::Replies] Reply mode.
+        #
+        # @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 since_time [String] ISO 8601 timestamp — only return tweets after this time
+        # @param url [String] URL substring or domain filter.
         #
-        # @param until_time [String] ISO 8601 timestamp — only return tweets before this time
+        # @param verified_only [Boolean] Only return tweets from verified authors.
         #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -280,9 +512,31 @@ module XTwitterScraper
             method: :get,
             path: "x/tweets/search",
             query: query.transform_keys(
+              advanced_query: "advancedQuery",
+              any_words: "anyWords",
+              bounding_box: "boundingBox",
+              conversation_id: "conversationId",
+              exact_phrase: "exactPhrase",
+              exclude_words: "excludeWords",
+              from_user: "fromUser",
+              in_reply_to_tweet_id: "inReplyToTweetId",
+              list_id: "listId",
+              media_type: "mediaType",
+              min_faves: "minFaves",
+              min_quotes: "minQuotes",
+              min_replies: "minReplies",
+              min_retweets: "minRetweets",
+              place_country: "placeCountry",
+              point_radius: "pointRadius",
               query_type: "queryType",
+              quotes_of_tweet_id: "quotesOfTweetId",
+              retweets_of_tweet_id: "retweetsOfTweetId",
+              since_date: "sinceDate",
               since_time: "sinceTime",
-              until_time: "untilTime"
+              to_user: "toUser",
+              until_date: "untilDate",
+              until_time: "untilTime",
+              verified_only: "verifiedOnly"
             ),
             model: XTwitterScraper::PaginatedTweets,
             options: options