x-twitter-scraper 0.4.3 → 0.4.4

data/lib/x_twitter_scraper/models/draw_run_response.rb

@@ -10,6 +10,8 @@ module XTwitterScraper
       required :id, String
 
       # @!attribute total_entries
+      #   Candidate entries inspected for this draw after the credit-derived cap. This may
+      #   be lower than the source tweet's full reply count.
       #
       #   @return [Integer]
       required :total_entries, Integer, api_name: :totalEntries
@@ -20,6 +22,8 @@ module XTwitterScraper
       required :tweet_id, String, api_name: :tweetId
 
       # @!attribute valid_entries
+      #   Entries from the inspected candidate set that passed all filters. This is not
+      #   necessarily every valid reply on the source tweet when credits cap inspection.
       #
       #   @return [Integer]
       required :valid_entries, Integer, api_name: :validEntries
@@ -30,10 +34,17 @@ module XTwitterScraper
       required :winners, -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::Winner] }
 
       # @!method initialize(id:, total_entries:, tweet_id:, valid_entries:, winners:)
+      #   Some parameter documentations has been truncated, see
+      #   {XTwitterScraper::Models::DrawRunResponse} for more details.
+      #
       #   @param id [String]
-      #   @param total_entries [Integer]
+      #
+      #   @param total_entries [Integer] Candidate entries inspected for this draw after the credit-derived cap. This may
+      #
       #   @param tweet_id [String]
-      #   @param valid_entries [Integer]
+      #
+      #   @param valid_entries [Integer] Entries from the inspected candidate set that passed all filters. This is not ne
+      #
       #   @param winners [Array<XTwitterScraper::Models::Winner>]
     end
   end

data/lib/x_twitter_scraper/models/embedded_tweet.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    class EmbeddedTweet < XTwitterScraper::Internal::Type::BaseModel
+      # @!attribute id
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!attribute bookmark_count
+      #
+      #   @return [Integer]
+      required :bookmark_count, Integer, api_name: :bookmarkCount
+
+      # @!attribute like_count
+      #
+      #   @return [Integer]
+      required :like_count, Integer, api_name: :likeCount
+
+      # @!attribute quote_count
+      #
+      #   @return [Integer]
+      required :quote_count, Integer, api_name: :quoteCount
+
+      # @!attribute reply_count
+      #
+      #   @return [Integer]
+      required :reply_count, Integer, api_name: :replyCount
+
+      # @!attribute retweet_count
+      #
+      #   @return [Integer]
+      required :retweet_count, Integer, api_name: :retweetCount
+
+      # @!attribute text
+      #
+      #   @return [String]
+      required :text, String
+
+      # @!attribute view_count
+      #
+      #   @return [Integer]
+      required :view_count, Integer, api_name: :viewCount
+
+      # @!attribute author
+      #   X user profile with bio, follower counts, and verification status.
+      #
+      #   @return [XTwitterScraper::Models::UserProfile, nil]
+      optional :author, -> { XTwitterScraper::UserProfile }
+
+      # @!attribute content_disclosure
+      #   Content disclosure metadata shown by X when a tweet is labeled as paid
+      #   partnership content or AI-generated media.
+      #
+      #   @return [XTwitterScraper::Models::ContentDisclosure, nil]
+      optional :content_disclosure, -> { XTwitterScraper::ContentDisclosure }, api_name: :contentDisclosure
+
+      # @!attribute conversation_id
+      #
+      #   @return [String, nil]
+      optional :conversation_id, String, api_name: :conversationId
+
+      # @!attribute created_at
+      #
+      #   @return [String, nil]
+      optional :created_at, String, api_name: :createdAt
+
+      # @!attribute display_text_range
+      #
+      #   @return [Array<Integer>, nil]
+      optional :display_text_range,
+               XTwitterScraper::Internal::Type::ArrayOf[Integer],
+               api_name: :displayTextRange
+
+      # @!attribute entities
+      #
+      #   @return [Hash{Symbol=>Object}, nil]
+      optional :entities, XTwitterScraper::Internal::Type::HashOf[XTwitterScraper::Internal::Type::Unknown]
+
+      # @!attribute in_reply_to_id
+      #
+      #   @return [String, nil]
+      optional :in_reply_to_id, String, api_name: :inReplyToId
+
+      # @!attribute in_reply_to_user_id
+      #
+      #   @return [String, nil]
+      optional :in_reply_to_user_id, String, api_name: :inReplyToUserId
+
+      # @!attribute in_reply_to_username
+      #
+      #   @return [String, nil]
+      optional :in_reply_to_username, String, api_name: :inReplyToUsername
+
+      # @!attribute is_limited_reply
+      #
+      #   @return [Boolean, nil]
+      optional :is_limited_reply, XTwitterScraper::Internal::Type::Boolean, api_name: :isLimitedReply
+
+      # @!attribute is_note_tweet
+      #
+      #   @return [Boolean, nil]
+      optional :is_note_tweet, XTwitterScraper::Internal::Type::Boolean, api_name: :isNoteTweet
+
+      # @!attribute is_quote_status
+      #
+      #   @return [Boolean, nil]
+      optional :is_quote_status, XTwitterScraper::Internal::Type::Boolean, api_name: :isQuoteStatus
+
+      # @!attribute is_reply
+      #
+      #   @return [Boolean, nil]
+      optional :is_reply, XTwitterScraper::Internal::Type::Boolean, api_name: :isReply
+
+      # @!attribute lang
+      #
+      #   @return [String, nil]
+      optional :lang, String
+
+      # @!attribute media
+      #
+      #   @return [Array<XTwitterScraper::Models::TweetMedia>, nil]
+      optional :media, -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::TweetMedia] }
+
+      # @!attribute source
+      #
+      #   @return [String, nil]
+      optional :source, String
+
+      # @!attribute type
+      #
+      #   @return [String, nil]
+      optional :type, String
+
+      # @!attribute url
+      #
+      #   @return [String, nil]
+      optional :url, String
+
+      # @!method initialize(id:, bookmark_count:, like_count:, quote_count:, reply_count:, retweet_count:, text:, view_count:, author: nil, content_disclosure: nil, conversation_id: nil, created_at: nil, display_text_range: nil, entities: nil, in_reply_to_id: nil, in_reply_to_user_id: nil, in_reply_to_username: nil, is_limited_reply: nil, is_note_tweet: nil, is_quote_status: nil, is_reply: nil, lang: nil, media: nil, source: nil, type: nil, url: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {XTwitterScraper::Models::EmbeddedTweet} for more details.
+      #
+      #   Quoted or retweeted tweet context. Every object includes id, text, and
+      #   engagement metrics. A zero metric can mean X did not report the count. Author,
+      #   media, and conversation fields appear when available.
+      #
+      #   @param id [String]
+      #
+      #   @param bookmark_count [Integer]
+      #
+      #   @param like_count [Integer]
+      #
+      #   @param quote_count [Integer]
+      #
+      #   @param reply_count [Integer]
+      #
+      #   @param retweet_count [Integer]
+      #
+      #   @param text [String]
+      #
+      #   @param view_count [Integer]
+      #
+      #   @param author [XTwitterScraper::Models::UserProfile] X user profile with bio, follower counts, and verification status.
+      #
+      #   @param content_disclosure [XTwitterScraper::Models::ContentDisclosure] Content disclosure metadata shown by X when a tweet is labeled as paid partnersh
+      #
+      #   @param conversation_id [String]
+      #
+      #   @param created_at [String]
+      #
+      #   @param display_text_range [Array<Integer>]
+      #
+      #   @param entities [Hash{Symbol=>Object}]
+      #
+      #   @param in_reply_to_id [String]
+      #
+      #   @param in_reply_to_user_id [String]
+      #
+      #   @param in_reply_to_username [String]
+      #
+      #   @param is_limited_reply [Boolean]
+      #
+      #   @param is_note_tweet [Boolean]
+      #
+      #   @param is_quote_status [Boolean]
+      #
+      #   @param is_reply [Boolean]
+      #
+      #   @param lang [String]
+      #
+      #   @param media [Array<XTwitterScraper::Models::TweetMedia>]
+      #
+      #   @param source [String]
+      #
+      #   @param type [String]
+      #
+      #   @param url [String]
+    end
+  end
+end

data/lib/x_twitter_scraper/models/error.rb

@@ -5,46 +5,215 @@ module XTwitterScraper
     class Error < XTwitterScraper::Internal::Type::BaseModel
       # @!attribute error
       #
-      #   @return [Symbol, XTwitterScraper::Models::Error::Error]
-      required :error, enum: -> { XTwitterScraper::Error::Error }
+      #   @return [Symbol, XTwitterScraper::Models::Error::Error::LegacyErrorCode, XTwitterScraper::Models::Error::Error::StructuredError]
+      required :error, union: -> { XTwitterScraper::Error::Error }
 
       # @!method initialize(error:)
-      #   Error response containing a machine-readable error code.
+      #   Error response. Default v1 returns a legacy string error code. Send
+      #   `xquik-api-contract: 2026-04-29` to receive the structured best-practice error
+      #   object.
       #
-      #   @param error [Symbol, XTwitterScraper::Models::Error::Error]
+      #   @param error [Symbol, XTwitterScraper::Models::Error::Error::LegacyErrorCode, XTwitterScraper::Models::Error::Error::StructuredError]
 
       # @see XTwitterScraper::Models::Error#error
       module Error
-        extend XTwitterScraper::Internal::Type::Enum
-
-        INTERNAL_ERROR = :internal_error
-        INVALID_FORMAT = :invalid_format
-        INVALID_ID = :invalid_id
-        INVALID_INPUT = :invalid_input
-        INVALID_PARAMS = :invalid_params
-        INVALID_TOOL_TYPE = :invalid_tool_type
-        INVALID_TWEET_ID = :invalid_tweet_id
-        INVALID_TWEET_URL = :invalid_tweet_url
-        INVALID_USERNAME = :invalid_username
-        MISSING_PARAMS = :missing_params
-        MISSING_QUERY = :missing_query
-        MONITOR_ALREADY_EXISTS = :monitor_already_exists
-        MONITOR_LIMIT_REACHED = :monitor_limit_reached
-        NO_SUBSCRIPTION = :no_subscription
-        NOT_FOUND = :not_found
-        STREAM_REGISTRATION_FAILED = :stream_registration_failed
-        SUBSCRIPTION_INACTIVE = :subscription_inactive
-        TWEET_NOT_FOUND = :tweet_not_found
-        UNAUTHENTICATED = :unauthenticated
-        USAGE_LIMIT_REACHED = :usage_limit_reached
-        USER_NOT_FOUND = :user_not_found
-        WEBHOOK_INACTIVE = :webhook_inactive
-        X_API_RATE_LIMITED = :x_api_rate_limited
-        X_API_UNAVAILABLE = :x_api_unavailable
-        X_API_UNAUTHORIZED = :x_api_unauthorized
-
-        # @!method self.values
-        #   @return [Array<Symbol>]
+        extend XTwitterScraper::Internal::Type::Union
+
+        variant enum: -> { XTwitterScraper::Error::Error::LegacyErrorCode }
+
+        variant -> { XTwitterScraper::Error::Error::StructuredError }
+
+        module LegacyErrorCode
+          extend XTwitterScraper::Internal::Type::Enum
+
+          INTERNAL_ERROR = :internal_error
+          ACCOUNT_ALREADY_CONNECTED = :account_already_connected
+          ACCOUNT_NEEDS_REAUTH = :account_needs_reauth
+          ACCOUNT_NOT_FOUND = :account_not_found
+          ACCOUNT_REQUIRED = :account_required
+          ACCOUNT_RESTRICTED = :account_restricted
+          API_KEY_LIMIT_REACHED = :api_key_limit_reached
+          ARTICLE_NOT_FOUND = :article_not_found
+          DM_NOT_PERMITTED = :dm_not_permitted
+          INVALID_FORMAT = :invalid_format
+          INVALID_ID = :invalid_id
+          INVALID_INPUT = :invalid_input
+          INVALID_PARAMS = :invalid_params
+          INVALID_TOOL_TYPE = :invalid_tool_type
+          INVALID_TWEET_ID = :invalid_tweet_id
+          INVALID_TWEET_URL = :invalid_tweet_url
+          INVALID_USER_ID = :invalid_user_id
+          INVALID_USER_IDS = :invalid_user_ids
+          INVALID_USERNAME = :invalid_username
+          INVALID_JSON = :invalid_json
+          INSUFFICIENT_CREDITS = :insufficient_credits
+          LOGIN_COOLDOWN = :login_cooldown
+          LOGIN_FAILED = :login_failed
+          MEDIA_DOWNLOAD_FAILED = :media_download_failed
+          MISSING_PARAMS = :missing_params
+          MISSING_QUERY = :missing_query
+          MONITOR_ALREADY_EXISTS = :monitor_already_exists
+          NO_MEDIA = :no_media
+          NO_CREDITS = :no_credits
+          NO_SUBSCRIPTION = :no_subscription
+          NOT_FOUND = :not_found
+          PAYMENT_FAILED = :payment_failed
+          RATE_LIMIT_EXCEEDED = :rate_limit_exceeded
+          SERVICE_UNAVAILABLE = :service_unavailable
+          STYLE_NOT_FOUND = :style_not_found
+          SUBSCRIPTION_INACTIVE = :subscription_inactive
+          TWEET_NOT_FOUND = :tweet_not_found
+          UNAUTHENTICATED = :unauthenticated
+          UNSUPPORTED_FIELD = :unsupported_field
+          USER_NOT_FOUND = :user_not_found
+          X_ACCOUNT_FEATURE_REQUIRED = :x_account_feature_required
+          X_ACCOUNT_PROTECTED = :x_account_protected
+          X_ACCOUNT_SUSPENDED = :x_account_suspended
+          X_API_RATE_LIMITED = :x_api_rate_limited
+          X_API_UNAVAILABLE = :x_api_unavailable
+          X_API_UNAUTHORIZED = :x_api_unauthorized
+          X_AUTH_FAILURE = :x_auth_failure
+          X_CONTENT_TOO_LONG = :x_content_too_long
+          X_DAILY_LIMIT = :x_daily_limit
+          X_DM_NOT_ALLOWED = :x_dm_not_allowed
+          X_DUPLICATE_ACTION = :x_duplicate_action
+          X_LOGIN_AUTH_FAILED = :x_login_auth_failed
+          X_LOGIN_CHALLENGE = :x_login_challenge
+          X_LOGIN_DENIED = :x_login_denied
+          X_LOGIN_FAILED = :x_login_failed
+          X_LOGIN_PROXY_ERROR = :x_login_proxy_error
+          X_LOGIN_RATE_LIMITED = :x_login_rate_limited
+          X_LOGIN_SERVICE_UNAVAILABLE = :x_login_service_unavailable
+          X_LOGIN_SUSPENDED = :x_login_suspended
+          X_RATE_LIMITED = :x_rate_limited
+          X_REJECTED = :x_rejected
+          X_TARGET_NOT_FOUND = :x_target_not_found
+          X_TRANSIENT_ERROR = :x_transient_error
+          X_USER_LOOKUP_FAILED = :x_user_lookup_failed
+          X_WRITE_AMBIGUOUS = :x_write_ambiguous
+          X_WRITE_FAILED = :x_write_failed
+          X_WRITE_UNCONFIRMED = :x_write_unconfirmed
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
+        class StructuredError < XTwitterScraper::Internal::Type::BaseModel
+          # @!attribute code
+          #
+          #   @return [Symbol, XTwitterScraper::Models::Error::Error::StructuredError::Code]
+          required :code, enum: -> { XTwitterScraper::Error::Error::StructuredError::Code }
+
+          # @!attribute message
+          #
+          #   @return [String]
+          required :message, String
+
+          # @!attribute type
+          #
+          #   @return [Symbol, XTwitterScraper::Models::Error::Error::StructuredError::Type]
+          required :type, enum: -> { XTwitterScraper::Error::Error::StructuredError::Type }
+
+          # @!method initialize(code:, message:, type:)
+          #   @param code [Symbol, XTwitterScraper::Models::Error::Error::StructuredError::Code]
+          #   @param message [String]
+          #   @param type [Symbol, XTwitterScraper::Models::Error::Error::StructuredError::Type]
+
+          # @see XTwitterScraper::Models::Error::Error::StructuredError#code
+          module Code
+            extend XTwitterScraper::Internal::Type::Enum
+
+            INTERNAL_ERROR = :internal_error
+            ACCOUNT_ALREADY_CONNECTED = :account_already_connected
+            ACCOUNT_NEEDS_REAUTH = :account_needs_reauth
+            ACCOUNT_NOT_FOUND = :account_not_found
+            ACCOUNT_REQUIRED = :account_required
+            ACCOUNT_RESTRICTED = :account_restricted
+            API_KEY_LIMIT_REACHED = :api_key_limit_reached
+            ARTICLE_NOT_FOUND = :article_not_found
+            DM_NOT_PERMITTED = :dm_not_permitted
+            INVALID_FORMAT = :invalid_format
+            INVALID_ID = :invalid_id
+            INVALID_INPUT = :invalid_input
+            INVALID_PARAMS = :invalid_params
+            INVALID_TOOL_TYPE = :invalid_tool_type
+            INVALID_TWEET_ID = :invalid_tweet_id
+            INVALID_TWEET_URL = :invalid_tweet_url
+            INVALID_USER_ID = :invalid_user_id
+            INVALID_USER_IDS = :invalid_user_ids
+            INVALID_USERNAME = :invalid_username
+            INVALID_JSON = :invalid_json
+            INSUFFICIENT_CREDITS = :insufficient_credits
+            LOGIN_COOLDOWN = :login_cooldown
+            LOGIN_FAILED = :login_failed
+            MEDIA_DOWNLOAD_FAILED = :media_download_failed
+            MISSING_PARAMS = :missing_params
+            MISSING_QUERY = :missing_query
+            MONITOR_ALREADY_EXISTS = :monitor_already_exists
+            NO_MEDIA = :no_media
+            NO_CREDITS = :no_credits
+            NO_SUBSCRIPTION = :no_subscription
+            NOT_FOUND = :not_found
+            PAYMENT_FAILED = :payment_failed
+            RATE_LIMIT_EXCEEDED = :rate_limit_exceeded
+            SERVICE_UNAVAILABLE = :service_unavailable
+            STYLE_NOT_FOUND = :style_not_found
+            SUBSCRIPTION_INACTIVE = :subscription_inactive
+            TWEET_NOT_FOUND = :tweet_not_found
+            UNAUTHENTICATED = :unauthenticated
+            UNSUPPORTED_FIELD = :unsupported_field
+            USER_NOT_FOUND = :user_not_found
+            X_ACCOUNT_FEATURE_REQUIRED = :x_account_feature_required
+            X_ACCOUNT_PROTECTED = :x_account_protected
+            X_ACCOUNT_SUSPENDED = :x_account_suspended
+            X_API_RATE_LIMITED = :x_api_rate_limited
+            X_API_UNAVAILABLE = :x_api_unavailable
+            X_API_UNAUTHORIZED = :x_api_unauthorized
+            X_AUTH_FAILURE = :x_auth_failure
+            X_CONTENT_TOO_LONG = :x_content_too_long
+            X_DAILY_LIMIT = :x_daily_limit
+            X_DM_NOT_ALLOWED = :x_dm_not_allowed
+            X_DUPLICATE_ACTION = :x_duplicate_action
+            X_LOGIN_AUTH_FAILED = :x_login_auth_failed
+            X_LOGIN_CHALLENGE = :x_login_challenge
+            X_LOGIN_DENIED = :x_login_denied
+            X_LOGIN_FAILED = :x_login_failed
+            X_LOGIN_PROXY_ERROR = :x_login_proxy_error
+            X_LOGIN_RATE_LIMITED = :x_login_rate_limited
+            X_LOGIN_SERVICE_UNAVAILABLE = :x_login_service_unavailable
+            X_LOGIN_SUSPENDED = :x_login_suspended
+            X_RATE_LIMITED = :x_rate_limited
+            X_REJECTED = :x_rejected
+            X_TARGET_NOT_FOUND = :x_target_not_found
+            X_TRANSIENT_ERROR = :x_transient_error
+            X_USER_LOOKUP_FAILED = :x_user_lookup_failed
+            X_WRITE_AMBIGUOUS = :x_write_ambiguous
+            X_WRITE_FAILED = :x_write_failed
+            X_WRITE_UNCONFIRMED = :x_write_unconfirmed
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+
+          # @see XTwitterScraper::Models::Error::Error::StructuredError#type
+          module Type
+            extend XTwitterScraper::Internal::Type::Enum
+
+            API_ERROR = :api_error
+            AUTHENTICATION_ERROR = :authentication_error
+            BILLING_ERROR = :billing_error
+            DEPENDENCY_ERROR = :dependency_error
+            INVALID_REQUEST_ERROR = :invalid_request_error
+            PERMISSION_ERROR = :permission_error
+            RATE_LIMIT_ERROR = :rate_limit_error
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+
+        # @!method self.variants
+        #   @return [Array(Symbol, XTwitterScraper::Models::Error::Error::LegacyErrorCode, XTwitterScraper::Models::Error::Error::StructuredError)]
       end
     end
   end

data/lib/x_twitter_scraper/models/event.rb

@@ -14,10 +14,17 @@ module XTwitterScraper
       required :data, XTwitterScraper::Internal::Type::HashOf[XTwitterScraper::Internal::Type::Unknown]
 
       # @!attribute monitor_id
+      #   Account monitor ID for account events, or keyword monitor ID for keyword events.
       #
       #   @return [String]
       required :monitor_id, String, api_name: :monitorId
 
+      # @!attribute monitor_type
+      #   Source monitor type.
+      #
+      #   @return [Symbol, XTwitterScraper::Models::Event::MonitorType]
+      required :monitor_type, enum: -> { XTwitterScraper::Event::MonitorType }, api_name: :monitorType
+
       # @!attribute occurred_at
       #
       #   @return [Time]
@@ -29,25 +36,60 @@ module XTwitterScraper
       #   @return [Symbol, XTwitterScraper::Models::EventType]
       required :type, enum: -> { XTwitterScraper::EventType }
 
+      # @!attribute keyword_monitor_id
+      #   Keyword monitor ID, present for keyword monitor events.
+      #
+      #   @return [String, nil]
+      optional :keyword_monitor_id, String, api_name: :keywordMonitorId
+
+      # @!attribute query
+      #   Keyword query, present for keyword monitor events.
+      #
+      #   @return [String, nil]
+      optional :query, String
+
       # @!attribute username
+      #   Account username, present for account monitor events.
       #
-      #   @return [String]
-      required :username, String
+      #   @return [String, nil]
+      optional :username, String
 
-      # @!method initialize(id:, data:, monitor_id:, occurred_at:, type:, username:)
-      #   Monitor event summary with type, username, and occurrence time.
+      # @!method initialize(id:, data:, monitor_id:, monitor_type:, occurred_at:, type:, keyword_monitor_id: nil, query: nil, username: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {XTwitterScraper::Models::Event} for more details.
+      #
+      #   Monitor event summary with source metadata and occurrence time.
       #
       #   @param id [String]
       #
       #   @param data [Hash{Symbol=>Object}]
       #
-      #   @param monitor_id [String]
+      #   @param monitor_id [String] Account monitor ID for account events, or keyword monitor ID for keyword events.
+      #
+      #   @param monitor_type [Symbol, XTwitterScraper::Models::Event::MonitorType] Source monitor type.
       #
       #   @param occurred_at [Time]
       #
       #   @param type [Symbol, XTwitterScraper::Models::EventType] Type of monitor event fired when account activity occurs.
       #
-      #   @param username [String]
+      #   @param keyword_monitor_id [String] Keyword monitor ID, present for keyword monitor events.
+      #
+      #   @param query [String] Keyword query, present for keyword monitor events.
+      #
+      #   @param username [String] Account username, present for account monitor events.
+
+      # Source monitor type.
+      #
+      # @see XTwitterScraper::Models::Event#monitor_type
+      module MonitorType
+        extend XTwitterScraper::Internal::Type::Enum
+
+        ACCOUNT = :account
+        KEYWORD = :keyword
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
     end
   end
 end

data/lib/x_twitter_scraper/models/event_detail.rb

@@ -10,16 +10,23 @@ module XTwitterScraper
       required :id, String
 
       # @!attribute data
-      #   Event payload — shape varies by event type (JSON)
+      #   Event payload - shape varies by event type (JSON)
       #
       #   @return [Hash{Symbol=>Object}]
       required :data, XTwitterScraper::Internal::Type::HashOf[XTwitterScraper::Internal::Type::Unknown]
 
       # @!attribute monitor_id
+      #   Monitor ID associated with this detailed event payload.
       #
       #   @return [String]
       required :monitor_id, String, api_name: :monitorId
 
+      # @!attribute monitor_type
+      #   Source monitor type for this detailed event.
+      #
+      #   @return [Symbol, XTwitterScraper::Models::EventDetail::MonitorType]
+      required :monitor_type, enum: -> { XTwitterScraper::EventDetail::MonitorType }, api_name: :monitorType
+
       # @!attribute occurred_at
       #
       #   @return [Time]
@@ -31,32 +38,64 @@ module XTwitterScraper
       #   @return [Symbol, XTwitterScraper::Models::EventType]
       required :type, enum: -> { XTwitterScraper::EventType }
 
+      # @!attribute keyword_monitor_id
+      #   Keyword monitor ID included on detailed keyword events.
+      #
+      #   @return [String, nil]
+      optional :keyword_monitor_id, String, api_name: :keywordMonitorId
+
+      # @!attribute query
+      #   Keyword query for this detailed monitor event.
+      #
+      #   @return [String, nil]
+      optional :query, String
+
       # @!attribute username
+      #   Account username for this detailed monitor event.
       #
-      #   @return [String]
-      required :username, String
+      #   @return [String, nil]
+      optional :username, String
 
       # @!attribute x_event_id
       #
       #   @return [String, nil]
       optional :x_event_id, String, api_name: :xEventId
 
-      # @!method initialize(id:, data:, monitor_id:, occurred_at:, type:, username:, x_event_id: nil)
+      # @!method initialize(id:, data:, monitor_id:, monitor_type:, occurred_at:, type:, keyword_monitor_id: nil, query: nil, username: nil, x_event_id: nil)
       #   Full monitor event including payload data and optional X event ID.
       #
       #   @param id [String]
       #
-      #   @param data [Hash{Symbol=>Object}] Event payload — shape varies by event type (JSON)
+      #   @param data [Hash{Symbol=>Object}] Event payload - shape varies by event type (JSON)
+      #
+      #   @param monitor_id [String] Monitor ID associated with this detailed event payload.
       #
-      #   @param monitor_id [String]
+      #   @param monitor_type [Symbol, XTwitterScraper::Models::EventDetail::MonitorType] Source monitor type for this detailed event.
       #
       #   @param occurred_at [Time]
       #
       #   @param type [Symbol, XTwitterScraper::Models::EventType] Type of monitor event fired when account activity occurs.
       #
-      #   @param username [String]
+      #   @param keyword_monitor_id [String] Keyword monitor ID included on detailed keyword events.
+      #
+      #   @param query [String] Keyword query for this detailed monitor event.
+      #
+      #   @param username [String] Account username for this detailed monitor event.
       #
       #   @param x_event_id [String]
+
+      # Source monitor type for this detailed event.
+      #
+      # @see XTwitterScraper::Models::EventDetail#monitor_type
+      module MonitorType
+        extend XTwitterScraper::Internal::Type::Enum
+
+        ACCOUNT = :account
+        KEYWORD = :keyword
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
     end
   end
 end