x-twitter-scraper 0.4.5 → 0.5.2

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

@@ -6,13 +6,18 @@ module XTwitterScraper
       class Tweets
         # X write actions (tweets, likes, follows, DMs)
         class Like
+          # Some parameter documentations has been truncated, see
+          # {XTwitterScraper::Models::X::Tweets::LikeCreateParams} for more details.
+          #
           # Like tweet
           #
-          # @overload create(id, account:, request_options: {})
+          # @overload create(id, account:, idempotency_key:, request_options: {})
+          #
+          # @param id [String] Path param: Tweet ID to like
           #
-          # @param id [String] Tweet ID to like
+          # @param account [String] Body param: X account identifier (@username or account ID)
           #
-          # @param account [String] X account identifier (@username or account ID)
+          # @param idempotency_key [String] Header param: Generate one unique value for each intended write. Reuse it only w
           #
           # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
           #
@@ -21,22 +26,29 @@ module XTwitterScraper
           # @see XTwitterScraper::Models::X::Tweets::LikeCreateParams
           def create(id, params)
             parsed, options = XTwitterScraper::X::Tweets::LikeCreateParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key"}
             @client.request(
               method: :post,
               path: ["x/tweets/%1$s/like", id],
-              body: parsed,
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
               model: XTwitterScraper::Models::X::Tweets::LikeCreateResponse,
               options: options
             )
           end
 
+          # Some parameter documentations has been truncated, see
+          # {XTwitterScraper::Models::X::Tweets::LikeDeleteParams} for more details.
+          #
           # Unlike tweet
           #
-          # @overload delete(id, account:, request_options: {})
+          # @overload delete(id, account:, idempotency_key:, request_options: {})
+          #
+          # @param id [String] Path param: Tweet ID to unlike
           #
-          # @param id [String] Tweet ID to unlike
+          # @param account [String] Body param: X account identifier (@username or account ID)
           #
-          # @param account [String] X account identifier (@username or account ID)
+          # @param idempotency_key [String] Header param: Generate one unique value for each intended write. Reuse it only w
           #
           # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
           #
@@ -45,10 +57,12 @@ module XTwitterScraper
           # @see XTwitterScraper::Models::X::Tweets::LikeDeleteParams
           def delete(id, params)
             parsed, options = XTwitterScraper::X::Tweets::LikeDeleteParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key"}
             @client.request(
               method: :delete,
               path: ["x/tweets/%1$s/like", id],
-              body: parsed,
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
               model: XTwitterScraper::Models::X::Tweets::LikeDeleteResponse,
               options: options
             )

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

@@ -6,13 +6,18 @@ module XTwitterScraper
       class Tweets
         # X write actions (tweets, likes, follows, DMs)
         class Retweet
+          # Some parameter documentations has been truncated, see
+          # {XTwitterScraper::Models::X::Tweets::RetweetCreateParams} for more details.
+          #
           # Retweet
           #
-          # @overload create(id, account:, request_options: {})
+          # @overload create(id, account:, idempotency_key:, request_options: {})
+          #
+          # @param id [String] Path param: Tweet ID to retweet
           #
-          # @param id [String] Tweet ID to retweet
+          # @param account [String] Body param: X account identifier (@username or account ID)
           #
-          # @param account [String] X account identifier (@username or account ID)
+          # @param idempotency_key [String] Header param: Generate one unique value for each intended write. Reuse it only w
           #
           # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
           #
@@ -21,22 +26,29 @@ module XTwitterScraper
           # @see XTwitterScraper::Models::X::Tweets::RetweetCreateParams
           def create(id, params)
             parsed, options = XTwitterScraper::X::Tweets::RetweetCreateParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key"}
             @client.request(
               method: :post,
               path: ["x/tweets/%1$s/retweet", id],
-              body: parsed,
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
               model: XTwitterScraper::Models::X::Tweets::RetweetCreateResponse,
               options: options
             )
           end
 
+          # Some parameter documentations has been truncated, see
+          # {XTwitterScraper::Models::X::Tweets::RetweetDeleteParams} for more details.
+          #
           # Unretweet
           #
-          # @overload delete(id, account:, request_options: {})
+          # @overload delete(id, account:, idempotency_key:, request_options: {})
+          #
+          # @param id [String] Path param: Tweet ID to unretweet
           #
-          # @param id [String] Tweet ID to unretweet
+          # @param account [String] Body param: X account identifier (@username or account ID)
           #
-          # @param account [String] X account identifier (@username or account ID)
+          # @param idempotency_key [String] Header param: Generate one unique value for each intended write. Reuse it only w
           #
           # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
           #
@@ -45,10 +57,12 @@ module XTwitterScraper
           # @see XTwitterScraper::Models::X::Tweets::RetweetDeleteParams
           def delete(id, params)
             parsed, options = XTwitterScraper::X::Tweets::RetweetDeleteParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key"}
             @client.request(
               method: :delete,
               path: ["x/tweets/%1$s/retweet", id],
-              body: parsed,
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
               model: XTwitterScraper::Models::X::Tweets::RetweetDeleteResponse,
               options: options
             )

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

@@ -17,21 +17,21 @@ module XTwitterScraper
         #
         # Create tweet
         #
-        # @overload create(account:, attachment_url: nil, community_id: nil, is_note_tweet: nil, media: nil, reply_to_tweet_id: nil, text: nil, request_options: {})
+        # @overload create(account:, idempotency_key:, 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 account [String] Body param: X account (@username or account ID)
         #
-        # @param attachment_url [String]
+        # @param idempotency_key [String] Header param: Generate one unique value for each intended write. Reuse it only w
         #
-        # @param community_id [String]
+        # @param community_id [String] Body param
         #
-        # @param is_note_tweet [Boolean]
+        # @param is_note_tweet [Boolean] Body param
         #
-        # @param media [Array<String>] Array of public media URLs to attach. Supports up to 4 images or exactly 1 MP4 v
+        # @param media [Array<String>] Body param: Array of public media URLs to attach. Supports up to 4 images or exa
         #
-        # @param reply_to_tweet_id [String]
+        # @param reply_to_tweet_id [String] Body param
         #
-        # @param text [String] Tweet text (optional when media is provided)
+        # @param text [String] Body param: Tweet text (optional when media is provided)
         #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -40,16 +40,18 @@ module XTwitterScraper
         # @see XTwitterScraper::Models::X::TweetCreateParams
         def create(params)
           parsed, options = XTwitterScraper::X::TweetCreateParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key"}
           @client.request(
             method: :post,
             path: "x/tweets",
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: XTwitterScraper::Models::X::TweetCreateResponse,
             options: options
           )
         end
 
-        # Get tweet with full text, author, metrics and media
+        # Get tweet with full text, author, metrics & media
         #
         # @overload retrieve(id, request_options: {})
         #
@@ -92,13 +94,18 @@ module XTwitterScraper
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {XTwitterScraper::Models::X::TweetDeleteParams} for more details.
+        #
         # Delete tweet
         #
-        # @overload delete(id, account:, request_options: {})
+        # @overload delete(id, account:, idempotency_key:, request_options: {})
+        #
+        # @param id [String] Path param: Tweet ID to delete
         #
-        # @param id [String] Tweet ID to delete
+        # @param account [String] Body param: X account identifier (@username or account ID)
         #
-        # @param account [String] X account identifier (@username or account ID)
+        # @param idempotency_key [String] Header param: Generate one unique value for each intended write. Reuse it only w
         #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -107,10 +114,12 @@ module XTwitterScraper
         # @see XTwitterScraper::Models::X::TweetDeleteParams
         def delete(id, params)
           parsed, options = XTwitterScraper::X::TweetDeleteParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key"}
           @client.request(
             method: :delete,
             path: ["x/tweets/%1$s", id],
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: XTwitterScraper::Models::X::TweetDeleteResponse,
             options: options
           )
@@ -119,7 +128,9 @@ module XTwitterScraper
         # Some parameter documentations has been truncated, see
         # {XTwitterScraper::Models::X::TweetGetFavoritersParams} for more details.
         #
-        # List users who liked a tweet
+        # Returns liker profiles that X makes visible for the post. X can withhold liker
+        # identities even when the post reports likes. In that case this endpoint returns
+        # 424 `favoriters_unavailable` instead of a misleading empty success.
         #
         # @overload get_favoriters(id, cursor: nil, page_size: nil, request_options: {})
         #
@@ -257,7 +268,11 @@ module XTwitterScraper
         # Some parameter documentations has been truncated, see
         # {XTwitterScraper::Models::X::TweetGetRepliesParams} for more details.
         #
-        # List replies to a tweet
+        # Returns visible replies. For an unfiltered first page, Xquik compares a terminal
+        # page with the post's reported reply count. If the page is visibly incomplete,
+        # the endpoint returns 424 `replies_incomplete` instead of presenting partial
+        # coverage as complete. Use tweet search with a `conversation_id:{id}` query as
+        # the broader fallback.
         #
         # @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: {})
         #

data/lib/x_twitter_scraper/resources/x/users/follow.rb

@@ -6,13 +6,18 @@ module XTwitterScraper
       class Users
         # X write actions (tweets, likes, follows, DMs)
         class Follow
+          # Some parameter documentations has been truncated, see
+          # {XTwitterScraper::Models::X::Users::FollowCreateParams} for more details.
+          #
           # Follow user
           #
-          # @overload create(id, account:, request_options: {})
+          # @overload create(id, account:, idempotency_key:, request_options: {})
+          #
+          # @param id [String] Path param: User ID to follow
           #
-          # @param id [String] User ID to follow
+          # @param account [String] Body param: X account identifier (@username or account ID)
           #
-          # @param account [String] X account identifier (@username or account ID)
+          # @param idempotency_key [String] Header param: Generate one unique value for each intended write. Reuse it only w
           #
           # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
           #
@@ -21,22 +26,29 @@ module XTwitterScraper
           # @see XTwitterScraper::Models::X::Users::FollowCreateParams
           def create(id, params)
             parsed, options = XTwitterScraper::X::Users::FollowCreateParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key"}
             @client.request(
               method: :post,
               path: ["x/users/%1$s/follow", id],
-              body: parsed,
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
               model: XTwitterScraper::Models::X::Users::FollowCreateResponse,
               options: options
             )
           end
 
+          # Some parameter documentations has been truncated, see
+          # {XTwitterScraper::Models::X::Users::FollowDeleteAllParams} for more details.
+          #
           # Unfollow user
           #
-          # @overload delete_all(id, account:, request_options: {})
+          # @overload delete_all(id, account:, idempotency_key:, request_options: {})
+          #
+          # @param id [String] Path param: User ID to unfollow
           #
-          # @param id [String] User ID to unfollow
+          # @param account [String] Body param: X account identifier (@username or account ID)
           #
-          # @param account [String] X account identifier (@username or account ID)
+          # @param idempotency_key [String] Header param: Generate one unique value for each intended write. Reuse it only w
           #
           # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
           #
@@ -45,10 +57,12 @@ module XTwitterScraper
           # @see XTwitterScraper::Models::X::Users::FollowDeleteAllParams
           def delete_all(id, params)
             parsed, options = XTwitterScraper::X::Users::FollowDeleteAllParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key"}
             @client.request(
               method: :delete,
               path: ["x/users/%1$s/follow", id],
-              body: parsed,
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
               model: XTwitterScraper::Models::X::Users::FollowDeleteAllResponse,
               options: options
             )

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

@@ -8,7 +8,7 @@ module XTwitterScraper
         # @return [XTwitterScraper::Resources::X::Users::Follow]
         attr_reader :follow
 
-        # Get user profile with follower counts and verification
+        # Get user profile with follower counts & verification
         #
         # @overload retrieve(id, request_options: {})
         #
@@ -28,13 +28,18 @@ module XTwitterScraper
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {XTwitterScraper::Models::X::UserRemoveFollowerParams} for more details.
+        #
         # Remove follower
         #
-        # @overload remove_follower(id, account:, request_options: {})
+        # @overload remove_follower(id, account:, idempotency_key:, request_options: {})
         #
-        # @param id [String] User ID to remove from your followers
+        # @param id [String] Path param: User ID to remove from your followers
         #
-        # @param account [String] X account identifier (@username or account ID)
+        # @param account [String] Body param: X account identifier (@username or account ID)
+        #
+        # @param idempotency_key [String] Header param: Generate one unique value for each intended write. Reuse it only w
         #
         # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -43,10 +48,12 @@ module XTwitterScraper
         # @see XTwitterScraper::Models::X::UserRemoveFollowerParams
         def remove_follower(id, params)
           parsed, options = XTwitterScraper::X::UserRemoveFollowerParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key"}
           @client.request(
             method: :post,
             path: ["x/users/%1$s/remove-follower", id],
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: XTwitterScraper::Models::X::UserRemoveFollowerResponse,
             options: options
           )
@@ -85,7 +92,7 @@ module XTwitterScraper
         #
         # @overload retrieve_followers(id, after: nil, cursor: nil, limit: nil, page_size: nil, request_options: {})
         #
-        # @param id [String] User ID or username
+        # @param id [String] Target user ID or username for follower lookup.
         #
         # @param after [String] Legacy cursor alias. Prefer cursor.
         #
@@ -152,7 +159,7 @@ module XTwitterScraper
         #
         # @param id [String] User ID or username for following lookup
         #
-        # @param after [String] Legacy cursor alias. Prefer cursor.
+        # @param after [String] Deprecated following cursor alias. Prefer cursor.
         #
         # @param cursor [String] Pagination cursor for following list
         #
@@ -487,7 +494,7 @@ module XTwitterScraper
         #
         # @overload retrieve_replies(id, any_words: nil, cashtags: nil, conversation_id: nil, cursor: nil, exact_phrase: nil, exclude_words: nil, from_user: nil, hashtags: nil, include_parent_tweet: 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, to_user: nil, until_date: nil, url: nil, verified_only: nil, request_options: {})
         #
-        # @param id [String] X user ID or username
+        # @param id [String] Target user ID or username for the replies timeline.
         #
         # @param any_words [String] Words or quoted phrases where any one can match. Separate with spaces, commas, o
         #
@@ -505,7 +512,7 @@ module XTwitterScraper
         #
         # @param hashtags [String] Hashtags separated by spaces, commas, or lines.
         #
-        # @param include_parent_tweet [Boolean] Include parent tweet for replies
+        # @param include_parent_tweet [Boolean] Include each reply's parent tweet.
         #
         # @param in_reply_to_tweet_id [String] Only replies to this tweet ID.
         #

data/lib/x_twitter_scraper/resources/x.rb

@@ -20,7 +20,6 @@ module XTwitterScraper
       # @return [XTwitterScraper::Resources::X::Dm]
       attr_reader :dm
 
-      # Media upload and download
       # @return [XTwitterScraper::Resources::X::Media]
       attr_reader :media
 
@@ -121,7 +120,7 @@ module XTwitterScraper
         )
       end
 
-      # Get trending hashtags and topics from X by region
+      # Get trending hashtags & topics from X by region
       #
       # @overload get_trends(count: nil, woeid: nil, request_options: {})
       #

data/lib/x_twitter_scraper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module XTwitterScraper
-  VERSION = "0.4.5"
+  VERSION = "0.5.2"
 end

data/rbi/x_twitter_scraper/client.rbi

@@ -41,7 +41,7 @@ module XTwitterScraper
     sig { returns(XTwitterScraper::Resources::Radar) }
     attr_reader :radar
 
-    # Real-time X account monitoring
+    # X account monitoring with 1-second checks
     sig { returns(XTwitterScraper::Resources::Monitors) }
     attr_reader :monitors
 

data/rbi/x_twitter_scraper/models/account_retrieve_response.rbi

@@ -126,11 +126,11 @@ module XTwitterScraper
         sig { returns(String) }
         attr_accessor :active_hourly_burn
 
-        # Estimated daily credits for 1 active instant monitor.
+        # Rounded daily estimate for 1 active monitor.
         sig { returns(String) }
         attr_accessor :credits_per_active_monitor_day
 
-        # Hourly credits charged for 1 active instant monitor.
+        # Hourly credits charged for 1 active monitor.
         sig { returns(String) }
         attr_accessor :credits_per_active_monitor_hour
 
@@ -162,9 +162,9 @@ module XTwitterScraper
           active_daily_estimate:,
           # Credits charged each hour for currently active monitors.
           active_hourly_burn:,
-          # Estimated daily credits for 1 active instant monitor.
+          # Rounded daily estimate for 1 active monitor.
           credits_per_active_monitor_day:,
-          # Hourly credits charged for 1 active instant monitor.
+          # Hourly credits charged for 1 active monitor.
           credits_per_active_monitor_hour:,
           # Webhook and event deliveries are included in monitor billing.
           events_included:,