x-twitter-scraper 0.4.2 → 0.4.4

data/rbi/x_twitter_scraper/resources/drafts.rbi

@@ -2,7 +2,7 @@
 
 module XTwitterScraper
   module Resources
-    # Tweet composition, drafts, writing styles & radar
+    # AI tweet composition, drafts, writing styles, and radar
     class Drafts
       # Save a tweet draft
       sig do
@@ -24,7 +24,7 @@ module XTwitterScraper
         ).returns(XTwitterScraper::DraftDetail)
       end
       def retrieve(
-        # Resource ID (stringified bigint)
+        # Resource ID returned by the matching create or list endpoint.
         id,
         request_options: {}
       )
@@ -41,7 +41,10 @@ module XTwitterScraper
       def list(
         # Cursor for pagination
         after_cursor: nil,
-        # Maximum number of items to return (1-100, default 50)
+        # Maximum number of items to return (1-100, default 50). For paid per-result
+        # endpoints, the returned count may be lower when remaining credits cannot cover
+        # the requested page. If zero paid results are affordable, the endpoint returns
+        # 402 insufficient_credits.
         limit: nil,
         request_options: {}
       )
@@ -55,7 +58,7 @@ module XTwitterScraper
         ).void
       end
       def delete(
-        # Resource ID (stringified bigint)
+        # Resource ID returned by the matching create or list endpoint.
         id,
         request_options: {}
       )

data/rbi/x_twitter_scraper/resources/draws.rbi

@@ -12,7 +12,7 @@ module XTwitterScraper
         ).returns(XTwitterScraper::Models::DrawRetrieveResponse)
       end
       def retrieve(
-        # Resource ID (stringified bigint)
+        # Draw public ID returned by create and list draw responses.
         id,
         request_options: {}
       )
@@ -21,15 +21,18 @@ module XTwitterScraper
       # List draws
       sig do
         params(
-          after: String,
+          cursor: String,
           limit: Integer,
           request_options: XTwitterScraper::RequestOptions::OrHash
         ).returns(XTwitterScraper::Models::DrawListResponse)
       end
       def list(
-        # Cursor for keyset pagination
-        after: nil,
-        # Maximum number of items to return (1-100, default 50)
+        # Cursor for keyset pagination from prior response next_cursor
+        cursor: nil,
+        # Maximum number of items to return (1-100, default 50). For paid per-result
+        # endpoints, the returned count may be lower when remaining credits cannot cover
+        # the requested page. If zero paid results are affordable, the endpoint returns
+        # 402 insufficient_credits.
         limit: nil,
         request_options: {}
       )
@@ -45,17 +48,20 @@ module XTwitterScraper
         ).returns(StringIO)
       end
       def export(
-        # Resource ID (stringified bigint)
+        # Draw public ID returned by create and list draw responses.
         id,
         # Export output format
-        format_: nil,
+        format_:,
         # Export winners or all entries
         type: nil,
         request_options: {}
       )
       end
 
-      # Run giveaway draw
+      # Runs a giveaway draw from a source tweet. The draw first checks the minimum
+      # credits needed to inspect the source tweet and at least one candidate. Remaining
+      # credits cap how many replies and retweeters can be inspected before filters and
+      # winner selection run.
       sig do
         params(
           tweet_url: String,

data/rbi/x_twitter_scraper/resources/events.rbi

@@ -12,7 +12,7 @@ module XTwitterScraper
         ).returns(XTwitterScraper::EventDetail)
       end
       def retrieve(
-        # Resource ID (stringified bigint)
+        # Resource ID returned by the matching create or list endpoint.
         id,
         request_options: {}
       )
@@ -21,7 +21,7 @@ module XTwitterScraper
       # List events
       sig do
         params(
-          after: String,
+          cursor: String,
           event_type: XTwitterScraper::EventType::OrSymbol,
           limit: Integer,
           monitor_id: String,
@@ -29,11 +29,14 @@ module XTwitterScraper
         ).returns(XTwitterScraper::Models::EventListResponse)
       end
       def list(
-        # Cursor for keyset pagination
-        after: nil,
+        # Cursor for keyset pagination from prior response next_cursor
+        cursor: nil,
         # Filter events by type
         event_type: nil,
-        # Maximum number of items to return (1-100, default 50)
+        # Maximum number of items to return (1-100, default 50). For paid per-result
+        # endpoints, the returned count may be lower when remaining credits cannot cover
+        # the requested page. If zero paid results are affordable, the endpoint returns
+        # 402 insufficient_credits.
         limit: nil,
         # Filter events by monitor ID
         monitor_id: nil,

data/rbi/x_twitter_scraper/resources/extractions.rbi

@@ -2,13 +2,13 @@
 
 module XTwitterScraper
   module Resources
-    # Bulk data extraction (20 tool types)
+    # Bulk data extraction (23 tool types)
     class Extractions
       # Get extraction results
       sig do
         params(
           id: String,
-          after: String,
+          cursor: String,
           limit: Integer,
           request_options: XTwitterScraper::RequestOptions::OrHash
         ).returns(XTwitterScraper::Models::ExtractionRetrieveResponse)
@@ -16,8 +16,8 @@ module XTwitterScraper
       def retrieve(
         # Extraction public ID (UUID)
         id,
-        # Cursor for keyset pagination
-        after: nil,
+        # Cursor for keyset pagination from prior response next_cursor
+        cursor: nil,
         # Maximum number of results to return (1-1000, default 100)
         limit: nil,
         request_options: {}
@@ -27,7 +27,7 @@ module XTwitterScraper
       # List extraction jobs
       sig do
         params(
-          after: String,
+          cursor: String,
           limit: Integer,
           status: XTwitterScraper::ExtractionListParams::Status::OrSymbol,
           tool_type: XTwitterScraper::ExtractionListParams::ToolType::OrSymbol,
@@ -35,9 +35,12 @@ module XTwitterScraper
         ).returns(XTwitterScraper::Models::ExtractionListResponse)
       end
       def list(
-        # Cursor for keyset pagination
-        after: nil,
-        # Maximum number of items to return (1-100, default 50)
+        # Cursor for keyset pagination from prior response next_cursor
+        cursor: nil,
+        # Maximum number of items to return (1-100, default 50). For paid per-result
+        # endpoints, the returned count may be lower when remaining credits cannot cover
+        # the requested page. If zero paid results are affordable, the endpoint returns
+        # 402 insufficient_credits.
         limit: nil,
         # Filter by job status
         status: nil,
@@ -53,14 +56,47 @@ module XTwitterScraper
           tool_type:
             XTwitterScraper::ExtractionEstimateCostParams::ToolType::OrSymbol,
           advanced_query: String,
+          any_words: String,
+          bounding_box: String,
+          cashtags: String,
+          conversation_id: String,
           exact_phrase: String,
           exclude_words: String,
+          from_user: String,
+          hashtags: String,
+          in_reply_to_tweet_id: String,
+          language: String,
+          list_id: String,
+          media_type:
+            XTwitterScraper::ExtractionEstimateCostParams::MediaType::OrSymbol,
+          mentioning: String,
+          min_faves: Integer,
+          min_quotes: Integer,
+          min_replies: Integer,
+          min_retweets: Integer,
+          place: String,
+          place_country: String,
+          point_radius: String,
+          quotes:
+            XTwitterScraper::ExtractionEstimateCostParams::Quotes::OrSymbol,
+          quotes_of_tweet_id: String,
+          replies:
+            XTwitterScraper::ExtractionEstimateCostParams::Replies::OrSymbol,
+          results_limit: Integer,
+          retweets:
+            XTwitterScraper::ExtractionEstimateCostParams::Retweets::OrSymbol,
+          retweets_of_tweet_id: String,
           search_query: String,
+          since_date: Date,
           target_community_id: String,
           target_list_id: String,
           target_space_id: String,
           target_tweet_id: String,
           target_username: String,
+          to_user: String,
+          until_date: Date,
+          url: String,
+          verified_only: T::Boolean,
           request_options: XTwitterScraper::RequestOptions::OrHash
         ).returns(XTwitterScraper::Models::ExtractionEstimateCostResponse)
       end
@@ -69,16 +105,84 @@ module XTwitterScraper
         tool_type:,
         # Raw advanced query string appended to the estimate (tweet_search_extractor)
         advanced_query: nil,
+        # Alternative words or quoted phrases for estimated results. Separate with spaces,
+        # commas, or lines.
+        any_words: nil,
+        # Geo bounding box used for estimation, e.g. -74.1 40.6 -73.9 40.8
+        # (tweet_search_extractor)
+        bounding_box: nil,
+        # Cashtags applied to the estimate, separated by spaces, commas, or lines.
+        cashtags: nil,
+        # Conversation ID filter used for estimation (tweet_search_extractor)
+        conversation_id: nil,
         # Exact phrase filter for search estimation
         exact_phrase: nil,
-        # Words excluded from estimated search results
+        # Words or quoted phrases excluded from estimated results. Separate with spaces,
+        # commas, or lines.
         exclude_words: nil,
+        # Estimate only tweets from this author username (tweet_search_extractor)
+        from_user: nil,
+        # Hashtags applied to the estimate, separated by spaces, commas, or lines.
+        hashtags: nil,
+        # Estimate only replies to this tweet ID (tweet_search_extractor)
+        in_reply_to_tweet_id: nil,
+        # Language code used for estimate filtering (tweet_search_extractor)
+        language: nil,
+        # Estimate search results within this list ID (tweet_search_extractor)
+        list_id: nil,
+        # Media type used for estimate filtering (tweet_search_extractor)
+        media_type: nil,
+        # Estimate tweets mentioning this username (tweet_search_extractor)
+        mentioning: nil,
+        # Minimum likes threshold for estimated results (tweet_search_extractor)
+        min_faves: nil,
+        # Minimum quote count threshold for estimated results (tweet_search_extractor)
+        min_quotes: nil,
+        # Minimum replies threshold for estimated results (tweet_search_extractor)
+        min_replies: nil,
+        # Minimum retweets threshold for estimated results (tweet_search_extractor)
+        min_retweets: nil,
+        # Estimate search results within this place ID (tweet_search_extractor)
+        place: nil,
+        # Estimate search results within this country code (tweet_search_extractor)
+        place_country: nil,
+        # Geo point radius used for estimation, e.g. -73.99 40.73 25mi
+        # (tweet_search_extractor)
+        point_radius: nil,
+        # Quote mode used for estimation (tweet_search_extractor)
+        quotes: nil,
+        # Estimate only quotes of this tweet ID (tweet_search_extractor)
+        quotes_of_tweet_id: nil,
+        # Reply mode used for estimation (tweet_search_extractor)
+        replies: nil,
+        # Maximum number of results to estimate. When set, the estimate caps projected
+        # results to this value.
+        results_limit: nil,
+        # Retweet mode used for estimation (tweet_search_extractor)
+        retweets: nil,
+        # Estimate only retweets of this tweet ID (tweet_search_extractor)
+        retweets_of_tweet_id: nil,
+        # Required for tweet_search_extractor & community_search.
         search_query: nil,
+        # Estimate start date in YYYY-MM-DD format (tweet_search_extractor)
+        since_date: nil,
+        # Required for community_post_extractor & community_search.
         target_community_id: nil,
+        # Required for list_follower_explorer, list_member_extractor &
+        # list_post_extractor.
         target_list_id: nil,
+        # Required for space_explorer.
         target_space_id: nil,
         target_tweet_id: nil,
         target_username: nil,
+        # Estimate replies sent to this username (tweet_search_extractor)
+        to_user: nil,
+        # Estimate end date in YYYY-MM-DD format (tweet_search_extractor)
+        until_date: nil,
+        # URL substring or domain filter used for estimation (tweet_search_extractor)
+        url: nil,
+        # Estimate only verified authors (tweet_search_extractor)
+        verified_only: nil,
         request_options: {}
       )
       end
@@ -96,7 +200,7 @@ module XTwitterScraper
         # Extraction public ID
         id,
         # Export file format
-        format_: nil,
+        format_:,
         request_options: {}
       )
       end
@@ -106,14 +210,43 @@ module XTwitterScraper
         params(
           tool_type: XTwitterScraper::ExtractionRunParams::ToolType::OrSymbol,
           advanced_query: String,
+          any_words: String,
+          bounding_box: String,
+          cashtags: String,
+          conversation_id: String,
           exact_phrase: String,
           exclude_words: String,
+          from_user: String,
+          hashtags: String,
+          in_reply_to_tweet_id: String,
+          language: String,
+          list_id: String,
+          media_type: XTwitterScraper::ExtractionRunParams::MediaType::OrSymbol,
+          mentioning: String,
+          min_faves: Integer,
+          min_quotes: Integer,
+          min_replies: Integer,
+          min_retweets: Integer,
+          place: String,
+          place_country: String,
+          point_radius: String,
+          quotes: XTwitterScraper::ExtractionRunParams::Quotes::OrSymbol,
+          quotes_of_tweet_id: String,
+          replies: XTwitterScraper::ExtractionRunParams::Replies::OrSymbol,
+          results_limit: Integer,
+          retweets: XTwitterScraper::ExtractionRunParams::Retweets::OrSymbol,
+          retweets_of_tweet_id: String,
           search_query: String,
+          since_date: Date,
           target_community_id: String,
           target_list_id: String,
           target_space_id: String,
           target_tweet_id: String,
           target_username: String,
+          to_user: String,
+          until_date: Date,
+          url: String,
+          verified_only: T::Boolean,
           request_options: XTwitterScraper::RequestOptions::OrHash
         ).returns(XTwitterScraper::Models::ExtractionRunResponse)
       end
@@ -122,16 +255,82 @@ module XTwitterScraper
         tool_type:,
         # Raw advanced search query appended as-is (tweet_search_extractor)
         advanced_query: nil,
+        # Words or quoted phrases where any one can match. Separate with spaces, commas,
+        # or lines. (tweet_search_extractor)
+        any_words: nil,
+        # Geo bounding box, e.g. -74.1 40.6 -73.9 40.8 (tweet_search_extractor)
+        bounding_box: nil,
+        # Cashtags separated by spaces, commas, or lines. (tweet_search_extractor)
+        cashtags: nil,
+        # Conversation ID filter (tweet_search_extractor)
+        conversation_id: nil,
         # Exact phrase to match (tweet_search_extractor)
         exact_phrase: nil,
-        # Words to exclude from results (tweet_search_extractor)
+        # Words or quoted phrases to exclude. Separate with spaces, commas, or lines.
+        # (tweet_search_extractor)
         exclude_words: nil,
+        # Filter by author username (tweet_search_extractor)
+        from_user: nil,
+        # Hashtags separated by spaces, commas, or lines. (tweet_search_extractor)
+        hashtags: nil,
+        # Only replies to this tweet ID (tweet_search_extractor)
+        in_reply_to_tweet_id: nil,
+        # Language code filter (tweet_search_extractor)
+        language: nil,
+        # Search within a list ID (tweet_search_extractor)
+        list_id: nil,
+        # Media type filter (tweet_search_extractor)
+        media_type: nil,
+        # Filter tweets mentioning a username (tweet_search_extractor)
+        mentioning: nil,
+        # Minimum likes threshold (tweet_search_extractor)
+        min_faves: nil,
+        # Minimum quote count threshold (tweet_search_extractor)
+        min_quotes: nil,
+        # Minimum replies threshold (tweet_search_extractor)
+        min_replies: nil,
+        # Minimum retweets threshold (tweet_search_extractor)
+        min_retweets: nil,
+        # Search within a place ID (tweet_search_extractor)
+        place: nil,
+        # Search within a country code (tweet_search_extractor)
+        place_country: nil,
+        # Geo point radius, e.g. -73.99 40.73 25mi (tweet_search_extractor)
+        point_radius: nil,
+        # Quote mode (tweet_search_extractor)
+        quotes: nil,
+        # Only quotes of this tweet ID (tweet_search_extractor)
+        quotes_of_tweet_id: nil,
+        # Reply mode (tweet_search_extractor)
+        replies: nil,
+        # Maximum number of results to extract. When set, the extraction stops after
+        # reaching this limit.
+        results_limit: nil,
+        # Retweet mode (tweet_search_extractor)
+        retweets: nil,
+        # Only retweets of this tweet ID (tweet_search_extractor)
+        retweets_of_tweet_id: nil,
+        # Required for tweet_search_extractor & community_search.
         search_query: nil,
+        # Start date YYYY-MM-DD (tweet_search_extractor)
+        since_date: nil,
+        # Required for community_post_extractor & community_search.
         target_community_id: nil,
+        # Required for list_follower_explorer, list_member_extractor &
+        # list_post_extractor.
         target_list_id: nil,
+        # Required for space_explorer.
         target_space_id: nil,
         target_tweet_id: nil,
         target_username: nil,
+        # Filter replies sent to a username (tweet_search_extractor)
+        to_user: nil,
+        # End date YYYY-MM-DD (tweet_search_extractor)
+        until_date: nil,
+        # URL substring or domain filter (tweet_search_extractor)
+        url: nil,
+        # Only verified authors (tweet_search_extractor)
+        verified_only: nil,
         request_options: {}
       )
       end

data/rbi/x_twitter_scraper/resources/guest_wallets.rbi

@@ -0,0 +1,76 @@
+# typed: strong
+
+module XTwitterScraper
+  module Resources
+    # Accountless prepaid access for paid read endpoints
+    class GuestWallets
+      # Create a one-use Stripe-hosted checkout after the user explicitly confirms a
+      # $10-$250 USD amount. This request creates no charge by itself. The user opens
+      # checkout_url on Stripe. This endpoint returns the paid-read API key without
+      # requiring an Xquik account, email, dashboard, or Xquik web page. An idempotent
+      # replay returns the same key.
+      sig do
+        params(
+          amount_minor: Integer,
+          idempotency_key: String,
+          currency: Symbol,
+          request_options: XTwitterScraper::RequestOptions::OrHash
+        ).returns(XTwitterScraper::Models::GuestWalletCreateResponse)
+      end
+      def create(
+        # Body param: Confirmed USD amount in cents.
+        amount_minor:,
+        # Header param: Generate a cryptographically random UUID v4. Reuse it only to
+        # retry the same wallet and amount request. Initial wallet creation can recover
+        # the API key from this value, so store it as a secret and never log it.
+        idempotency_key:,
+        # Body param
+        currency: :usd,
+        request_options: {}
+      )
+      end
+
+      # Poll after Stripe payment. Use usable to decide whether paid reads can run. An
+      # active wallet can remain usable while a top-up is pending. A new wallet becomes
+      # usable only after verified webhook fulfillment. Send the guest key as
+      # Authorization: Bearer.
+      sig do
+        params(
+          request_options: XTwitterScraper::RequestOptions::OrHash
+        ).returns(XTwitterScraper::Models::GuestWalletRetrieveStatusResponse)
+      end
+      def retrieve_status(request_options: {})
+      end
+
+      # Create a one-use Stripe-hosted checkout for an existing paid-read guest key
+      # after the user explicitly confirms a $10-$250 USD amount. The key remains the
+      # same. This request creates no charge by itself and never redirects through an
+      # Xquik web page.
+      sig do
+        params(
+          amount_minor: Integer,
+          idempotency_key: String,
+          currency: Symbol,
+          request_options: XTwitterScraper::RequestOptions::OrHash
+        ).returns(XTwitterScraper::Models::GuestWalletTopupResponse)
+      end
+      def topup(
+        # Body param: Confirmed USD amount in cents.
+        amount_minor:,
+        # Header param: Generate a cryptographically random UUID v4. Reuse it only to
+        # retry the same wallet and amount request. Initial wallet creation can recover
+        # the API key from this value, so store it as a secret and never log it.
+        idempotency_key:,
+        # Body param
+        currency: :usd,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: XTwitterScraper::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/x_twitter_scraper/resources/monitors/keywords.rbi

@@ -0,0 +1,95 @@
+# typed: strong
+
+module XTwitterScraper
+  module Resources
+    class Monitors
+      # Real-time X account monitoring
+      class Keywords
+        # Creates an instant keyword monitor. Keyword monitors are unlimited. Active
+        # monitors check every 1 second and cost 21 credits per hour. Events and webhook
+        # deliveries are included. Creation requires available credits for the first
+        # hourly charge.
+        sig do
+          params(
+            event_types: T::Array[XTwitterScraper::EventType::OrSymbol],
+            query: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(XTwitterScraper::Models::Monitors::KeywordCreateResponse)
+        end
+        def create(
+          # Array of event types to subscribe to.
+          event_types:,
+          # X search query to monitor. Whitespace is normalized.
+          query:,
+          request_options: {}
+        )
+        end
+
+        # Get keyword monitor
+        sig do
+          params(
+            id: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(XTwitterScraper::Models::Monitors::KeywordRetrieveResponse)
+        end
+        def retrieve(
+          # Resource ID returned by the matching create or list endpoint.
+          id,
+          request_options: {}
+        )
+        end
+
+        # Update keyword monitor
+        sig do
+          params(
+            id: String,
+            event_types: T::Array[XTwitterScraper::EventType::OrSymbol],
+            is_active: T::Boolean,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(XTwitterScraper::Models::Monitors::KeywordUpdateResponse)
+        end
+        def update(
+          # Resource ID returned by the matching create or list endpoint.
+          id,
+          # Array of event types to subscribe to.
+          event_types: nil,
+          is_active: nil,
+          request_options: {}
+        )
+        end
+
+        # List keyword monitors
+        sig do
+          params(
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(XTwitterScraper::Models::Monitors::KeywordListResponse)
+        end
+        def list(request_options: {})
+        end
+
+        # Delete keyword monitor
+        sig do
+          params(
+            id: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(
+            XTwitterScraper::Models::Monitors::KeywordDeactivateResponse
+          )
+        end
+        def deactivate(
+          # Resource ID returned by the matching create or list endpoint.
+          id,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig do
+          params(client: XTwitterScraper::Client).returns(T.attached_class)
+        end
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/x_twitter_scraper/resources/monitors.rbi

@@ -4,7 +4,14 @@ module XTwitterScraper
   module Resources
     # Real-time X account monitoring
     class Monitors
-      # Create monitor
+      # Real-time X account monitoring
+      sig { returns(XTwitterScraper::Resources::Monitors::Keywords) }
+      attr_reader :keywords
+
+      # Creates an instant monitor. Monitors are unlimited. Active monitors check every
+      # 1 second and cost 21 credits per hour. Events and webhook deliveries are
+      # included. Creation requires available credits for the first hourly charge and
+      # username lookup.
       sig do
         params(
           event_types: T::Array[XTwitterScraper::EventType::OrSymbol],
@@ -29,7 +36,7 @@ module XTwitterScraper
         ).returns(XTwitterScraper::Monitor)
       end
       def retrieve(
-        # Resource ID (stringified bigint)
+        # Resource ID returned by the matching create or list endpoint.
         id,
         request_options: {}
       )
@@ -45,7 +52,7 @@ module XTwitterScraper
         ).returns(XTwitterScraper::Monitor)
       end
       def update(
-        # Resource ID (stringified bigint)
+        # Resource ID returned by the matching create or list endpoint.
         id,
         # Array of event types to subscribe to.
         event_types: nil,
@@ -63,7 +70,7 @@ module XTwitterScraper
       def list(request_options: {})
       end
 
-      # Deactivate monitor
+      # Delete monitor
       sig do
         params(
           id: String,
@@ -71,7 +78,7 @@ module XTwitterScraper
         ).returns(XTwitterScraper::Models::MonitorDeactivateResponse)
       end
       def deactivate(
-        # Resource ID (stringified bigint)
+        # Resource ID returned by the matching create or list endpoint.
         id,
         request_options: {}
       )