x-twitter-scraper 0.4.5 → 0.5.2

data/rbi/x_twitter_scraper/resources/x/tweets.rbi

@@ -16,7 +16,7 @@ module XTwitterScraper
         sig do
           params(
             account: String,
-            attachment_url: String,
+            idempotency_key: String,
             community_id: String,
             is_note_tweet: T::Boolean,
             media: T::Array[String],
@@ -26,23 +26,30 @@ module XTwitterScraper
           ).returns(XTwitterScraper::Models::X::TweetCreateResponse)
         end
         def create(
-          # X account (@username or account ID)
+          # Body param: X account (@username or account ID)
           account:,
-          attachment_url: nil,
+          # Header param: Generate one unique value for each intended write. Reuse it only
+          # when retrying the exact same account, action, target, and payload. A reused key
+          # returns the original action. Reusing it with different input returns 409. Replay
+          # protection remains active for at least 90 days.
+          idempotency_key:,
+          # Body param
           community_id: nil,
+          # Body param
           is_note_tweet: nil,
-          # Array of public media URLs to attach. Supports up to 4 images or exactly 1 MP4
-          # video up to 100 MB. Each URL must be publicly reachable. Attached media adds 2
-          # credits per started MB across all files.
+          # Body param: Array of public media URLs to attach. Supports up to 4 images or
+          # exactly 1 MP4 video up to 100 MB. Each URL must be publicly reachable. Attached
+          # media adds 2 credits per started MB across all files.
           media: nil,
+          # Body param
           reply_to_tweet_id: nil,
-          # Tweet text (optional when media is provided)
+          # Body param: Tweet text (optional when media is provided)
           text: nil,
           request_options: {}
         )
         end
 
-        # Get tweet with full text, author, metrics and media
+        # Get tweet with full text, author, metrics & media
         sig do
           params(
             id: String,
@@ -75,19 +82,27 @@ module XTwitterScraper
           params(
             id: String,
             account: String,
+            idempotency_key: String,
             request_options: XTwitterScraper::RequestOptions::OrHash
           ).returns(XTwitterScraper::Models::X::TweetDeleteResponse)
         end
         def delete(
-          # Tweet ID to delete
+          # Path param: Tweet ID to delete
           id,
-          # X account identifier (@username or account ID)
+          # Body param: X account identifier (@username or account ID)
           account:,
+          # Header param: Generate one unique value for each intended write. Reuse it only
+          # when retrying the exact same account, action, target, and payload. A reused key
+          # returns the original action. Reusing it with different input returns 409. Replay
+          # protection remains active for at least 90 days.
+          idempotency_key:,
           request_options: {}
         )
         end
 
-        # 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.
         sig do
           params(
             id: String,
@@ -222,7 +237,11 @@ module XTwitterScraper
         )
         end
 
-        # 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.
         sig do
           params(
             id: String,

data/rbi/x_twitter_scraper/resources/x/users/follow.rbi

@@ -11,14 +11,20 @@ module XTwitterScraper
             params(
               id: String,
               account: String,
+              idempotency_key: String,
               request_options: XTwitterScraper::RequestOptions::OrHash
             ).returns(XTwitterScraper::Models::X::Users::FollowCreateResponse)
           end
           def create(
-            # User ID to follow
+            # Path param: User ID to follow
             id,
-            # X account identifier (@username or account ID)
+            # Body param: X account identifier (@username or account ID)
             account:,
+            # Header param: Generate one unique value for each intended write. Reuse it only
+            # when retrying the exact same account, action, target, and payload. A reused key
+            # returns the original action. Reusing it with different input returns 409. Replay
+            # protection remains active for at least 90 days.
+            idempotency_key:,
             request_options: {}
           )
           end
@@ -28,16 +34,22 @@ module XTwitterScraper
             params(
               id: String,
               account: String,
+              idempotency_key: String,
               request_options: XTwitterScraper::RequestOptions::OrHash
             ).returns(
               XTwitterScraper::Models::X::Users::FollowDeleteAllResponse
             )
           end
           def delete_all(
-            # User ID to unfollow
+            # Path param: User ID to unfollow
             id,
-            # X account identifier (@username or account ID)
+            # Body param: X account identifier (@username or account ID)
             account:,
+            # Header param: Generate one unique value for each intended write. Reuse it only
+            # when retrying the exact same account, action, target, and payload. A reused key
+            # returns the original action. Reusing it with different input returns 409. Replay
+            # protection remains active for at least 90 days.
+            idempotency_key:,
             request_options: {}
           )
           end

data/rbi/x_twitter_scraper/resources/x/users.rbi

@@ -8,7 +8,7 @@ module XTwitterScraper
         sig { returns(XTwitterScraper::Resources::X::Users::Follow) }
         attr_reader :follow
 
-        # Get user profile with follower counts and verification
+        # Get user profile with follower counts & verification
         sig do
           params(
             id: String,
@@ -27,14 +27,20 @@ module XTwitterScraper
           params(
             id: String,
             account: String,
+            idempotency_key: String,
             request_options: XTwitterScraper::RequestOptions::OrHash
           ).returns(XTwitterScraper::Models::X::UserRemoveFollowerResponse)
         end
         def remove_follower(
-          # User ID to remove from your followers
+          # Path param: User ID to remove from your followers
           id,
-          # X account identifier (@username or account ID)
+          # Body param: X account identifier (@username or account ID)
           account:,
+          # Header param: Generate one unique value for each intended write. Reuse it only
+          # when retrying the exact same account, action, target, and payload. A reused key
+          # returns the original action. Reusing it with different input returns 409. Replay
+          # protection remains active for at least 90 days.
+          idempotency_key:,
           request_options: {}
         )
         end
@@ -66,7 +72,7 @@ module XTwitterScraper
           ).returns(XTwitterScraper::PaginatedUsers)
         end
         def retrieve_followers(
-          # User ID or username
+          # Target user ID or username for follower lookup.
           id,
           # Legacy cursor alias. Prefer cursor.
           after: nil,
@@ -120,7 +126,7 @@ module XTwitterScraper
         def retrieve_following(
           # User ID or username for following lookup
           id,
-          # Legacy cursor alias. Prefer cursor.
+          # Deprecated following cursor alias. Prefer cursor.
           after: nil,
           # Pagination cursor for following list
           cursor: nil,
@@ -493,7 +499,7 @@ module XTwitterScraper
           ).returns(XTwitterScraper::PaginatedTweets)
         end
         def retrieve_replies(
-          # X user ID or username
+          # Target user ID or username for the replies timeline.
           id,
           # Words or quoted phrases where any one can match. Separate with spaces, commas,
           # or lines.
@@ -512,7 +518,7 @@ module XTwitterScraper
           from_user: nil,
           # Hashtags separated by spaces, commas, or lines.
           hashtags: nil,
-          # Include parent tweet for replies
+          # Include each reply's parent tweet.
           include_parent_tweet: nil,
           # Only replies to this tweet ID.
           in_reply_to_tweet_id: nil,

data/rbi/x_twitter_scraper/resources/x.rbi

@@ -20,7 +20,6 @@ module XTwitterScraper
       sig { returns(XTwitterScraper::Resources::X::Dm) }
       attr_reader :dm
 
-      # Media upload and download
       sig { returns(XTwitterScraper::Resources::X::Media) }
       attr_reader :media
 
@@ -99,7 +98,7 @@ module XTwitterScraper
       )
       end
 
-      # Get trending hashtags and topics from X by region
+      # Get trending hashtags & topics from X by region
       sig do
         params(
           count: Integer,

data/sig/x_twitter_scraper/models/compose_create_params.rbs

@@ -1,136 +1,196 @@
 module XTwitterScraper
   module Models
     type compose_create_params =
-      {
-        step: XTwitterScraper::Models::ComposeCreateParams::step,
-        additional_context: String,
-        call_to_action: String,
-        draft: String,
-        goal: XTwitterScraper::Models::ComposeCreateParams::goal,
-        has_link: bool,
-        has_media: bool,
-        media_type: XTwitterScraper::Models::ComposeCreateParams::media_type,
-        style_username: String,
-        tone: String,
-        topic: String
-      }
+      { body: XTwitterScraper::Models::ComposeCreateParams::body }
       & XTwitterScraper::Internal::Type::request_parameters
 
     class ComposeCreateParams < XTwitterScraper::Internal::Type::BaseModel
       extend XTwitterScraper::Internal::Type::RequestParameters::Converter
       include XTwitterScraper::Internal::Type::RequestParameters
 
-      attr_accessor step: XTwitterScraper::Models::ComposeCreateParams::step
+      attr_accessor body: XTwitterScraper::Models::ComposeCreateParams::body
 
-      attr_reader additional_context: String?
+      def initialize: (
+        body: XTwitterScraper::Models::ComposeCreateParams::body,
+        ?request_options: XTwitterScraper::request_opts
+      ) -> void
 
-      def additional_context=: (String) -> String
+      def to_hash: -> {
+        body: XTwitterScraper::Models::ComposeCreateParams::body,
+        request_options: XTwitterScraper::RequestOptions
+      }
 
-      attr_reader call_to_action: String?
+      type body =
+        XTwitterScraper::ComposeCreateParams::Body::ComposePrepareRequest
+        | XTwitterScraper::ComposeCreateParams::Body::ComposeRefineRequest
+        | XTwitterScraper::ComposeCreateParams::Body::ComposeScoreRequest
 
-      def call_to_action=: (String) -> String
+      module Body
+        extend XTwitterScraper::Internal::Type::Union
 
-      attr_reader draft: String?
+        type compose_prepare_request =
+          {
+            step: :compose,
+            topic: String,
+            goal: XTwitterScraper::Models::ComposeCreateParams::Body::ComposePrepareRequest::goal,
+            style_username: String
+          }
 
-      def draft=: (String) -> String
+        class ComposePrepareRequest < XTwitterScraper::Internal::Type::BaseModel
+          attr_accessor step: :compose
 
-      attr_reader goal: XTwitterScraper::Models::ComposeCreateParams::goal?
+          attr_accessor topic: String
 
-      def goal=: (
-        XTwitterScraper::Models::ComposeCreateParams::goal
-      ) -> XTwitterScraper::Models::ComposeCreateParams::goal
+          attr_reader goal: XTwitterScraper::Models::ComposeCreateParams::Body::ComposePrepareRequest::goal?
 
-      attr_reader has_link: bool?
+          def goal=: (
+            XTwitterScraper::Models::ComposeCreateParams::Body::ComposePrepareRequest::goal
+          ) -> XTwitterScraper::Models::ComposeCreateParams::Body::ComposePrepareRequest::goal
 
-      def has_link=: (bool) -> bool
+          attr_reader style_username: String?
 
-      attr_reader has_media: bool?
+          def style_username=: (String) -> String
 
-      def has_media=: (bool) -> bool
+          def initialize: (
+            topic: String,
+            ?goal: XTwitterScraper::Models::ComposeCreateParams::Body::ComposePrepareRequest::goal,
+            ?style_username: String,
+            ?step: :compose
+          ) -> void
 
-      attr_reader media_type: XTwitterScraper::Models::ComposeCreateParams::media_type?
+          def to_hash: -> {
+            step: :compose,
+            topic: String,
+            goal: XTwitterScraper::Models::ComposeCreateParams::Body::ComposePrepareRequest::goal,
+            style_username: String
+          }
 
-      def media_type=: (
-        XTwitterScraper::Models::ComposeCreateParams::media_type
-      ) -> XTwitterScraper::Models::ComposeCreateParams::media_type
+          type goal = :engagement | :followers | :authority | :conversation
 
-      attr_reader style_username: String?
+          module Goal
+            extend XTwitterScraper::Internal::Type::Enum
 
-      def style_username=: (String) -> String
+            ENGAGEMENT: :engagement
+            FOLLOWERS: :followers
+            AUTHORITY: :authority
+            CONVERSATION: :conversation
 
-      attr_reader tone: String?
+            def self?.values: -> ::Array[XTwitterScraper::Models::ComposeCreateParams::Body::ComposePrepareRequest::goal]
+          end
+        end
 
-      def tone=: (String) -> String
+        type compose_refine_request =
+          {
+            goal: XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::goal,
+            step: :refine,
+            tone: String,
+            topic: String,
+            additional_context: String,
+            call_to_action: String,
+            media_type: XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::media_type
+          }
 
-      attr_reader topic: String?
+        class ComposeRefineRequest < XTwitterScraper::Internal::Type::BaseModel
+          attr_accessor goal: XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::goal
 
-      def topic=: (String) -> String
+          attr_accessor step: :refine
 
-      def initialize: (
-        step: XTwitterScraper::Models::ComposeCreateParams::step,
-        ?additional_context: String,
-        ?call_to_action: String,
-        ?draft: String,
-        ?goal: XTwitterScraper::Models::ComposeCreateParams::goal,
-        ?has_link: bool,
-        ?has_media: bool,
-        ?media_type: XTwitterScraper::Models::ComposeCreateParams::media_type,
-        ?style_username: String,
-        ?tone: String,
-        ?topic: String,
-        ?request_options: XTwitterScraper::request_opts
-      ) -> void
+          attr_accessor tone: String
 
-      def to_hash: -> {
-        step: XTwitterScraper::Models::ComposeCreateParams::step,
-        additional_context: String,
-        call_to_action: String,
-        draft: String,
-        goal: XTwitterScraper::Models::ComposeCreateParams::goal,
-        has_link: bool,
-        has_media: bool,
-        media_type: XTwitterScraper::Models::ComposeCreateParams::media_type,
-        style_username: String,
-        tone: String,
-        topic: String,
-        request_options: XTwitterScraper::RequestOptions
-      }
+          attr_accessor topic: String
 
-      type step = :compose | :refine | :score
+          attr_reader additional_context: String?
 
-      module Step
-        extend XTwitterScraper::Internal::Type::Enum
+          def additional_context=: (String) -> String
 
-        COMPOSE: :compose
-        REFINE: :refine
-        SCORE: :score
+          attr_reader call_to_action: String?
 
-        def self?.values: -> ::Array[XTwitterScraper::Models::ComposeCreateParams::step]
-      end
+          def call_to_action=: (String) -> String
 
-      type goal = :engagement | :followers | :authority | :conversation
+          attr_reader media_type: XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::media_type?
 
-      module Goal
-        extend XTwitterScraper::Internal::Type::Enum
+          def media_type=: (
+            XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::media_type
+          ) -> XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::media_type
 
-        ENGAGEMENT: :engagement
-        FOLLOWERS: :followers
-        AUTHORITY: :authority
-        CONVERSATION: :conversation
+          def initialize: (
+            goal: XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::goal,
+            tone: String,
+            topic: String,
+            ?additional_context: String,
+            ?call_to_action: String,
+            ?media_type: XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::media_type,
+            ?step: :refine
+          ) -> void
 
-        def self?.values: -> ::Array[XTwitterScraper::Models::ComposeCreateParams::goal]
-      end
+          def to_hash: -> {
+            goal: XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::goal,
+            step: :refine,
+            tone: String,
+            topic: String,
+            additional_context: String,
+            call_to_action: String,
+            media_type: XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::media_type
+          }
+
+          type goal = :engagement | :followers | :authority | :conversation
+
+          module Goal
+            extend XTwitterScraper::Internal::Type::Enum
+
+            ENGAGEMENT: :engagement
+            FOLLOWERS: :followers
+            AUTHORITY: :authority
+            CONVERSATION: :conversation
+
+            def self?.values: -> ::Array[XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::goal]
+          end
+
+          type media_type = :photo | :video | :none
+
+          module MediaType
+            extend XTwitterScraper::Internal::Type::Enum
+
+            PHOTO: :photo
+            VIDEO: :video
+            NONE: :none
+
+            def self?.values: -> ::Array[XTwitterScraper::Models::ComposeCreateParams::Body::ComposeRefineRequest::media_type]
+          end
+        end
+
+        type compose_score_request =
+          { draft: String, step: :score, has_link: bool, has_media: bool }
+
+        class ComposeScoreRequest < XTwitterScraper::Internal::Type::BaseModel
+          attr_accessor draft: String
+
+          attr_accessor step: :score
+
+          attr_reader has_link: bool?
+
+          def has_link=: (bool) -> bool
+
+          attr_reader has_media: bool?
 
-      type media_type = :photo | :video | :none
+          def has_media=: (bool) -> bool
 
-      module MediaType
-        extend XTwitterScraper::Internal::Type::Enum
+          def initialize: (
+            draft: String,
+            ?has_link: bool,
+            ?has_media: bool,
+            ?step: :score
+          ) -> void
 
-        PHOTO: :photo
-        VIDEO: :video
-        NONE: :none
+          def to_hash: -> {
+            draft: String,
+            step: :score,
+            has_link: bool,
+            has_media: bool
+          }
+        end
 
-        def self?.values: -> ::Array[XTwitterScraper::Models::ComposeCreateParams::media_type]
+        def self?.variants: -> ::Array[XTwitterScraper::Models::ComposeCreateParams::body]
       end
     end
   end