x-twitter-scraper 0.4.2 → 0.4.4

data/lib/x_twitter_scraper/models/monitors/keyword_list_response.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    module Monitors
+      # @see XTwitterScraper::Resources::Monitors::Keywords#list
+      class KeywordListResponse < XTwitterScraper::Internal::Type::BaseModel
+        # @!attribute monitors
+        #
+        #   @return [Array<XTwitterScraper::Models::Monitors::KeywordListResponse::Monitor>]
+        required :monitors,
+                 -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::Models::Monitors::KeywordListResponse::Monitor] }
+
+        # @!attribute total
+        #
+        #   @return [Integer]
+        required :total, Integer
+
+        # @!method initialize(monitors:, total:)
+        #   @param monitors [Array<XTwitterScraper::Models::Monitors::KeywordListResponse::Monitor>]
+        #   @param total [Integer]
+
+        class Monitor < XTwitterScraper::Internal::Type::BaseModel
+          # @!attribute id
+          #
+          #   @return [String]
+          required :id, String
+
+          # @!attribute created_at
+          #
+          #   @return [Time]
+          required :created_at, Time, api_name: :createdAt
+
+          # @!attribute event_types
+          #   Array of event types to subscribe to.
+          #
+          #   @return [Array<Symbol, XTwitterScraper::Models::EventType>]
+          required :event_types,
+                   -> { XTwitterScraper::Internal::Type::ArrayOf[enum: XTwitterScraper::EventType] },
+                   api_name: :eventTypes
+
+          # @!attribute is_active
+          #
+          #   @return [Boolean]
+          required :is_active, XTwitterScraper::Internal::Type::Boolean, api_name: :isActive
+
+          # @!attribute next_billing_at
+          #   Next hourly credit charge time for this keyword query monitor.
+          #
+          #   @return [Time]
+          required :next_billing_at, Time, api_name: :nextBillingAt
+
+          # @!attribute query
+          #
+          #   @return [String]
+          required :query, String
+
+          # @!method initialize(id:, created_at:, event_types:, is_active:, next_billing_at:, query:)
+          #   Keyword monitor that tracks matching public X activity.
+          #
+          #   @param id [String]
+          #
+          #   @param created_at [Time]
+          #
+          #   @param event_types [Array<Symbol, XTwitterScraper::Models::EventType>] Array of event types to subscribe to.
+          #
+          #   @param is_active [Boolean]
+          #
+          #   @param next_billing_at [Time] Next hourly credit charge time for this keyword query monitor.
+          #
+          #   @param query [String]
+        end
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/models/monitors/keyword_retrieve_params.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    module Monitors
+      # @see XTwitterScraper::Resources::Monitors::Keywords#retrieve
+      class KeywordRetrieveParams < XTwitterScraper::Internal::Type::BaseModel
+        extend XTwitterScraper::Internal::Type::RequestParameters::Converter
+        include XTwitterScraper::Internal::Type::RequestParameters
+
+        # @!attribute id
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!method initialize(id:, request_options: {})
+        #   @param id [String]
+        #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/models/monitors/keyword_retrieve_response.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    module Monitors
+      # @see XTwitterScraper::Resources::Monitors::Keywords#retrieve
+      class KeywordRetrieveResponse < XTwitterScraper::Internal::Type::BaseModel
+        # @!attribute id
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute created_at
+        #
+        #   @return [Time]
+        required :created_at, Time, api_name: :createdAt
+
+        # @!attribute event_types
+        #   Array of event types to subscribe to.
+        #
+        #   @return [Array<Symbol, XTwitterScraper::Models::EventType>]
+        required :event_types,
+                 -> { XTwitterScraper::Internal::Type::ArrayOf[enum: XTwitterScraper::EventType] },
+                 api_name: :eventTypes
+
+        # @!attribute is_active
+        #
+        #   @return [Boolean]
+        required :is_active, XTwitterScraper::Internal::Type::Boolean, api_name: :isActive
+
+        # @!attribute next_billing_at
+        #   Next hourly credit charge time for this keyword query monitor.
+        #
+        #   @return [Time]
+        required :next_billing_at, Time, api_name: :nextBillingAt
+
+        # @!attribute query
+        #
+        #   @return [String]
+        required :query, String
+
+        # @!method initialize(id:, created_at:, event_types:, is_active:, next_billing_at:, query:)
+        #   Keyword monitor that tracks matching public X activity.
+        #
+        #   @param id [String]
+        #
+        #   @param created_at [Time]
+        #
+        #   @param event_types [Array<Symbol, XTwitterScraper::Models::EventType>] Array of event types to subscribe to.
+        #
+        #   @param is_active [Boolean]
+        #
+        #   @param next_billing_at [Time] Next hourly credit charge time for this keyword query monitor.
+        #
+        #   @param query [String]
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/models/monitors/keyword_update_params.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    module Monitors
+      # @see XTwitterScraper::Resources::Monitors::Keywords#update
+      class KeywordUpdateParams < XTwitterScraper::Internal::Type::BaseModel
+        extend XTwitterScraper::Internal::Type::RequestParameters::Converter
+        include XTwitterScraper::Internal::Type::RequestParameters
+
+        # @!attribute id
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute event_types
+        #   Array of event types to subscribe to.
+        #
+        #   @return [Array<Symbol, XTwitterScraper::Models::EventType>, nil]
+        optional :event_types,
+                 -> { XTwitterScraper::Internal::Type::ArrayOf[enum: XTwitterScraper::EventType] },
+                 api_name: :eventTypes
+
+        # @!attribute is_active
+        #
+        #   @return [Boolean, nil]
+        optional :is_active, XTwitterScraper::Internal::Type::Boolean, api_name: :isActive
+
+        # @!method initialize(id:, event_types: nil, is_active: nil, request_options: {})
+        #   @param id [String]
+        #
+        #   @param event_types [Array<Symbol, XTwitterScraper::Models::EventType>] Array of event types to subscribe to.
+        #
+        #   @param is_active [Boolean]
+        #
+        #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/models/monitors/keyword_update_response.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    module Monitors
+      # @see XTwitterScraper::Resources::Monitors::Keywords#update
+      class KeywordUpdateResponse < XTwitterScraper::Internal::Type::BaseModel
+        # @!attribute id
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute created_at
+        #
+        #   @return [Time]
+        required :created_at, Time, api_name: :createdAt
+
+        # @!attribute event_types
+        #   Array of event types to subscribe to.
+        #
+        #   @return [Array<Symbol, XTwitterScraper::Models::EventType>]
+        required :event_types,
+                 -> { XTwitterScraper::Internal::Type::ArrayOf[enum: XTwitterScraper::EventType] },
+                 api_name: :eventTypes
+
+        # @!attribute is_active
+        #
+        #   @return [Boolean]
+        required :is_active, XTwitterScraper::Internal::Type::Boolean, api_name: :isActive
+
+        # @!attribute next_billing_at
+        #   Next hourly credit charge time for this keyword query monitor.
+        #
+        #   @return [Time]
+        required :next_billing_at, Time, api_name: :nextBillingAt
+
+        # @!attribute query
+        #
+        #   @return [String]
+        required :query, String
+
+        # @!method initialize(id:, created_at:, event_types:, is_active:, next_billing_at:, query:)
+        #   Keyword monitor that tracks matching public X activity.
+        #
+        #   @param id [String]
+        #
+        #   @param created_at [Time]
+        #
+        #   @param event_types [Array<Symbol, XTwitterScraper::Models::EventType>] Array of event types to subscribe to.
+        #
+        #   @param is_active [Boolean]
+        #
+        #   @param next_billing_at [Time] Next hourly credit charge time for this keyword query monitor.
+        #
+        #   @param query [String]
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/models/paginated_tweets.rb

@@ -15,15 +15,19 @@ module XTwitterScraper
 
       # @!attribute tweets
       #
-      #   @return [Array<XTwitterScraper::Models::X::SearchTweet>]
-      required :tweets, -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::X::SearchTweet] }
+      #   @return [Array<XTwitterScraper::Models::SearchTweet>]
+      required :tweets, -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::SearchTweet] }
 
       # @!method initialize(has_next_page:, next_cursor:, tweets:)
-      #   Paginated list of tweets with cursor-based navigation.
+      #   Paginated tweet results. The item count can be lower than pageSize when the
+      #   source returns fewer tweets, filters remove tweets, or remaining credits cover
+      #   fewer results. Follow next_cursor while has_next_page is true. An empty page can
+      #   still have has_next_page true after filtering. Zero affordable results returns
+      #   402 insufficient_credits.
       #
       #   @param has_next_page [Boolean]
       #   @param next_cursor [String]
-      #   @param tweets [Array<XTwitterScraper::Models::X::SearchTweet>]
+      #   @param tweets [Array<XTwitterScraper::Models::SearchTweet>]
     end
   end
 end

data/lib/x_twitter_scraper/models/paginated_users.rb

@@ -15,15 +15,19 @@ module XTwitterScraper
 
       # @!attribute users
       #
-      #   @return [Array<XTwitterScraper::Models::X::UserProfile>]
-      required :users, -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::X::UserProfile] }
+      #   @return [Array<XTwitterScraper::Models::UserProfile>]
+      required :users, -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::UserProfile] }
 
       # @!method initialize(has_next_page:, next_cursor:, users:)
-      #   Paginated list of user profiles with cursor-based navigation.
+      #   Paginated user profiles. The item count can be lower than pageSize when the
+      #   source returns fewer profiles or remaining credits cover fewer results. Follow
+      #   next_cursor while has_next_page is true. A relationship can naturally contain
+      #   fewer profiles than requested. Zero affordable results returns 402
+      #   insufficient_credits.
       #
       #   @param has_next_page [Boolean]
       #   @param next_cursor [String]
-      #   @param users [Array<XTwitterScraper::Models::X::UserProfile>]
+      #   @param users [Array<XTwitterScraper::Models::UserProfile>]
     end
   end
 end

data/lib/x_twitter_scraper/models/radar_item.rb

@@ -3,10 +3,42 @@
 module XTwitterScraper
   module Models
     class RadarItem < XTwitterScraper::Internal::Type::BaseModel
+      # @!attribute id
+      #   Radar item identifier.
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute category
       #
+      #   @return [Symbol, XTwitterScraper::Models::RadarItem::Category]
+      required :category, enum: -> { XTwitterScraper::RadarItem::Category }
+
+      # @!attribute created_at
+      #
+      #   @return [Time]
+      required :created_at, Time, api_name: :createdAt
+
+      # @!attribute language
+      #
       #   @return [String]
-      required :category, String
+      required :language, String
+
+      # @!attribute metadata
+      #   Source-specific fields. Shape varies per source:
+      #
+      #   - reddit: { subreddit: string, author: string }
+      #   - github: { starsToday: number }
+      #   - hacker_news: { points: number, numberComments: number }
+      #   - google_trends: { approxTraffic: number }
+      #   - polymarket: { volume24hr: number }
+      #   - wikipedia: { views: number }
+      #   - trustmrr: { mrr, growthPercent, last30Days, total, customers,
+      #     activeSubscriptions, onSale, xHandle?, category?, askingPrice?, country?,
+      #     growthMrrPercent?, multiple?, paymentProvider?, rank? }
+      #
+      #   @return [Hash{Symbol=>Object}]
+      required :metadata, XTwitterScraper::Internal::Type::HashOf[XTwitterScraper::Internal::Type::Unknown]
 
       # @!attribute published_at
       #
@@ -25,8 +57,14 @@ module XTwitterScraper
 
       # @!attribute source
       #
+      #   @return [Symbol, XTwitterScraper::Models::RadarItem::Source]
+      required :source, enum: -> { XTwitterScraper::RadarItem::Source }
+
+      # @!attribute source_id
+      #   Source-specific identifier used for deduplication.
+      #
       #   @return [String]
-      required :source, String
+      required :source_id, String, api_name: :sourceId
 
       # @!attribute title
       #
@@ -48,18 +86,73 @@ module XTwitterScraper
       #   @return [String, nil]
       optional :url, String
 
-      # @!method initialize(category:, published_at:, region:, score:, source:, title:, description: nil, image_url: nil, url: nil)
-      #   Trending topic with score, category, source, and region.
+      # @!method initialize(id:, category:, created_at:, language:, metadata:, published_at:, region:, score:, source:, source_id:, title:, description: nil, image_url: nil, url: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {XTwitterScraper::Models::RadarItem} for more details.
+      #
+      #   Trending topic with score, category, source, region, language, and
+      #   source-specific metadata.
+      #
+      #   @param id [String] Radar item identifier.
+      #
+      #   @param category [Symbol, XTwitterScraper::Models::RadarItem::Category]
+      #
+      #   @param created_at [Time]
+      #
+      #   @param language [String]
+      #
+      #   @param metadata [Hash{Symbol=>Object}] Source-specific fields. Shape varies per source:
       #
-      #   @param category [String]
       #   @param published_at [Time]
+      #
       #   @param region [String]
+      #
       #   @param score [Float]
-      #   @param source [String]
+      #
+      #   @param source [Symbol, XTwitterScraper::Models::RadarItem::Source]
+      #
+      #   @param source_id [String] Source-specific identifier used for deduplication.
+      #
       #   @param title [String]
+      #
       #   @param description [String]
+      #
       #   @param image_url [String]
+      #
       #   @param url [String]
+
+      # @see XTwitterScraper::Models::RadarItem#category
+      module Category
+        extend XTwitterScraper::Internal::Type::Enum
+
+        GENERAL = :general
+        TECH = :tech
+        DEV = :dev
+        SCIENCE = :science
+        CULTURE = :culture
+        POLITICS = :politics
+        BUSINESS = :business
+        ENTERTAINMENT = :entertainment
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      # @see XTwitterScraper::Models::RadarItem#source
+      module Source
+        extend XTwitterScraper::Internal::Type::Enum
+
+        GITHUB = :github
+        GOOGLE_TRENDS = :google_trends
+        HACKER_NEWS = :hacker_news
+        POLYMARKET = :polymarket
+        REDDIT = :reddit
+        TRUSTMRR = :trustmrr
+        WIKIPEDIA = :wikipedia
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
     end
   end
 end

data/lib/x_twitter_scraper/models/radar_retrieve_trending_topics_params.rb

@@ -7,26 +7,32 @@ module XTwitterScraper
       extend XTwitterScraper::Internal::Type::RequestParameters::Converter
       include XTwitterScraper::Internal::Type::RequestParameters
 
-      # @!attribute category
-      #   Filter by category (general, tech, dev, etc.)
+      # @!attribute after
+      #   Cursor for pagination (from prior response nextCursor).
       #
       #   @return [String, nil]
-      optional :category, String
+      optional :after, String
 
-      # @!attribute count
-      #   Number of items to return
+      # @!attribute category
+      #   Filter by category.
       #
-      #   @return [Integer, nil]
-      optional :count, Integer
+      #   @return [Symbol, XTwitterScraper::Models::RadarRetrieveTrendingTopicsParams::Category, nil]
+      optional :category, enum: -> { XTwitterScraper::RadarRetrieveTrendingTopicsParams::Category }
 
       # @!attribute hours
-      #   Lookback window in hours
+      #   Lookback window in hours (1-72, default 6).
       #
       #   @return [Integer, nil]
       optional :hours, Integer
 
+      # @!attribute limit
+      #   Number of items to return (1-100, default 50).
+      #
+      #   @return [Integer, nil]
+      optional :limit, Integer
+
       # @!attribute region
-      #   Region filter (us, global, etc.)
+      #   Region filter. Use `global` or a region code such as `US`, `GB`, `TR`, or `ES`.
       #
       #   @return [String, nil]
       optional :region, String
@@ -38,22 +44,41 @@ module XTwitterScraper
       #   @return [Symbol, XTwitterScraper::Models::RadarRetrieveTrendingTopicsParams::Source, nil]
       optional :source, enum: -> { XTwitterScraper::RadarRetrieveTrendingTopicsParams::Source }
 
-      # @!method initialize(category: nil, count: nil, hours: nil, region: nil, source: nil, request_options: {})
+      # @!method initialize(after: nil, category: nil, hours: nil, limit: nil, region: nil, source: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {XTwitterScraper::Models::RadarRetrieveTrendingTopicsParams} for more details.
       #
-      #   @param category [String] Filter by category (general, tech, dev, etc.)
+      #   @param after [String] Cursor for pagination (from prior response nextCursor).
+      #
+      #   @param category [Symbol, XTwitterScraper::Models::RadarRetrieveTrendingTopicsParams::Category] Filter by category.
       #
-      #   @param count [Integer] Number of items to return
+      #   @param hours [Integer] Lookback window in hours (1-72, default 6).
       #
-      #   @param hours [Integer] Lookback window in hours
+      #   @param limit [Integer] Number of items to return (1-100, default 50).
       #
-      #   @param region [String] Region filter (us, global, etc.)
+      #   @param region [String] Region filter. Use `global` or a region code such as `US`, `GB`, `TR`, or `ES`.
       #
       #   @param source [Symbol, XTwitterScraper::Models::RadarRetrieveTrendingTopicsParams::Source] Source filter. One of: github, google_trends, hacker_news, polymarket, reddit, t
       #
       #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
 
+      # Filter by category.
+      module Category
+        extend XTwitterScraper::Internal::Type::Enum
+
+        GENERAL = :general
+        TECH = :tech
+        DEV = :dev
+        SCIENCE = :science
+        CULTURE = :culture
+        POLITICS = :politics
+        BUSINESS = :business
+        ENTERTAINMENT = :entertainment
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
       # Source filter. One of: github, google_trends, hacker_news, polymarket, reddit,
       # trustmrr, wikipedia
       module Source

data/lib/x_twitter_scraper/models/radar_retrieve_trending_topics_response.rb

@@ -4,19 +4,28 @@ module XTwitterScraper
   module Models
     # @see XTwitterScraper::Resources::Radar#retrieve_trending_topics
     class RadarRetrieveTrendingTopicsResponse < XTwitterScraper::Internal::Type::BaseModel
+      # @!attribute has_more
+      #
+      #   @return [Boolean]
+      required :has_more, XTwitterScraper::Internal::Type::Boolean, api_name: :hasMore
+
       # @!attribute items
       #
       #   @return [Array<XTwitterScraper::Models::RadarItem>]
       required :items, -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::RadarItem] }
 
-      # @!attribute total
+      # @!attribute next_cursor
+      #   Opaque cursor for the next page (present only when hasMore is true).
       #
-      #   @return [Integer]
-      required :total, Integer
+      #   @return [String, nil]
+      optional :next_cursor, String, api_name: :nextCursor
 
-      # @!method initialize(items:, total:)
+      # @!method initialize(has_more:, items:, next_cursor: nil)
+      #   @param has_more [Boolean]
+      #
       #   @param items [Array<XTwitterScraper::Models::RadarItem>]
-      #   @param total [Integer]
+      #
+      #   @param next_cursor [String] Opaque cursor for the next page (present only when hasMore is true).
     end
   end
 end