x-twitter-scraper 0.3.3 → 0.4.0

package/resources/shared.d.mts

@@ -1,15 +1,100 @@
 /**
- * Error response containing a machine-readable error code.
+ * Content disclosure metadata shown by X when a tweet is labeled as paid
+ * partnership content or AI-generated media.
+ */
+export interface ContentDisclosure {
+    advertising?: ContentDisclosure.Advertising;
+    aiGenerated?: ContentDisclosure.AIGenerated;
+}
+export declare namespace ContentDisclosure {
+    interface Advertising {
+        /**
+         * True when X labels the tweet as paid promotion content.
+         */
+        isPaidPromotion?: boolean;
+    }
+    interface AIGenerated {
+        /**
+         * Whether the disclosure can be edited on X.
+         */
+        canEdit?: boolean;
+        /**
+         * Source of the AI-generated media disclosure.
+         */
+        detectionSource?: string;
+        /**
+         * True when X labels the tweet as containing AI-generated media.
+         */
+        hasAiGeneratedMedia?: boolean;
+    }
+}
+/**
+ * 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.
+ */
+export interface EmbeddedTweet {
+    id: string;
+    bookmarkCount: number;
+    likeCount: number;
+    quoteCount: number;
+    replyCount: number;
+    retweetCount: number;
+    text: string;
+    viewCount: number;
+    /**
+     * X user profile with bio, follower counts, and verification status.
+     */
+    author?: UserProfile;
+    /**
+     * Content disclosure metadata shown by X when a tweet is labeled as paid
+     * partnership content or AI-generated media.
+     */
+    contentDisclosure?: ContentDisclosure;
+    conversationId?: string;
+    createdAt?: string;
+    displayTextRange?: Array<number>;
+    entities?: {
+        [key: string]: unknown;
+    };
+    inReplyToId?: string;
+    inReplyToUserId?: string;
+    inReplyToUsername?: string;
+    isLimitedReply?: boolean;
+    isNoteTweet?: boolean;
+    isQuoteStatus?: boolean;
+    isReply?: boolean;
+    lang?: string;
+    media?: Array<TweetMedia>;
+    source?: string;
+    type?: string;
+    url?: string;
+}
+/**
+ * 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.
  */
 export interface Error {
-    error: 'internal_error' | 'invalid_format' | 'invalid_id' | 'invalid_input' | 'invalid_params' | 'invalid_tool_type' | 'invalid_tweet_id' | 'invalid_tweet_url' | 'invalid_username' | 'insufficient_credits' | 'missing_params' | 'missing_query' | 'monitor_already_exists' | 'monitor_limit_reached' | 'no_credits' | 'no_subscription' | 'not_found' | 'subscription_inactive' | 'tweet_not_found' | 'unauthenticated' | 'user_not_found' | 'webhook_inactive' | 'x_api_rate_limited' | 'x_api_unavailable' | 'x_api_unauthorized';
+    error: 'internal_error' | 'account_already_connected' | 'account_needs_reauth' | 'account_not_found' | 'account_required' | 'account_restricted' | 'api_key_limit_reached' | 'article_not_found' | 'dm_not_permitted' | 'invalid_format' | 'invalid_id' | 'invalid_input' | 'invalid_params' | 'invalid_tool_type' | 'invalid_tweet_id' | 'invalid_tweet_url' | 'invalid_user_id' | 'invalid_user_ids' | 'invalid_username' | 'invalid_json' | 'insufficient_credits' | 'login_cooldown' | 'login_failed' | 'media_download_failed' | 'missing_params' | 'missing_query' | 'monitor_already_exists' | 'no_media' | 'no_credits' | 'no_subscription' | 'not_found' | 'payment_failed' | 'rate_limit_exceeded' | 'service_unavailable' | 'style_not_found' | 'subscription_inactive' | 'tweet_not_found' | 'unauthenticated' | 'unsupported_field' | 'user_not_found' | 'x_account_feature_required' | 'x_account_protected' | 'x_account_suspended' | 'x_api_rate_limited' | 'x_api_unavailable' | 'x_api_unauthorized' | 'x_auth_failure' | 'x_content_too_long' | 'x_daily_limit' | 'x_dm_not_allowed' | 'x_duplicate_action' | 'x_login_auth_failed' | 'x_login_challenge' | 'x_login_denied' | 'x_login_failed' | 'x_login_proxy_error' | 'x_login_rate_limited' | 'x_login_service_unavailable' | 'x_login_suspended' | 'x_rate_limited' | 'x_rejected' | 'x_target_not_found' | 'x_transient_error' | 'x_user_lookup_failed' | 'x_write_ambiguous' | 'x_write_failed' | 'x_write_unconfirmed' | Error.StructuredError;
+}
+export declare namespace Error {
+    interface StructuredError {
+        code: 'internal_error' | 'account_already_connected' | 'account_needs_reauth' | 'account_not_found' | 'account_required' | 'account_restricted' | 'api_key_limit_reached' | 'article_not_found' | 'dm_not_permitted' | 'invalid_format' | 'invalid_id' | 'invalid_input' | 'invalid_params' | 'invalid_tool_type' | 'invalid_tweet_id' | 'invalid_tweet_url' | 'invalid_user_id' | 'invalid_user_ids' | 'invalid_username' | 'invalid_json' | 'insufficient_credits' | 'login_cooldown' | 'login_failed' | 'media_download_failed' | 'missing_params' | 'missing_query' | 'monitor_already_exists' | 'no_media' | 'no_credits' | 'no_subscription' | 'not_found' | 'payment_failed' | 'rate_limit_exceeded' | 'service_unavailable' | 'style_not_found' | 'subscription_inactive' | 'tweet_not_found' | 'unauthenticated' | 'unsupported_field' | 'user_not_found' | 'x_account_feature_required' | 'x_account_protected' | 'x_account_suspended' | 'x_api_rate_limited' | 'x_api_unavailable' | 'x_api_unauthorized' | 'x_auth_failure' | 'x_content_too_long' | 'x_daily_limit' | 'x_dm_not_allowed' | 'x_duplicate_action' | 'x_login_auth_failed' | 'x_login_challenge' | 'x_login_denied' | 'x_login_failed' | 'x_login_proxy_error' | 'x_login_rate_limited' | 'x_login_service_unavailable' | 'x_login_suspended' | 'x_rate_limited' | 'x_rejected' | 'x_target_not_found' | 'x_transient_error' | 'x_user_lookup_failed' | 'x_write_ambiguous' | 'x_write_failed' | 'x_write_unconfirmed';
+        message: string;
+        type: 'api_error' | 'authentication_error' | 'billing_error' | 'dependency_error' | 'invalid_request_error' | 'permission_error' | 'rate_limit_error';
+    }
 }
 /**
  * Type of monitor event fired when account activity occurs.
  */
-export type EventType = 'tweet.new' | 'tweet.reply' | 'tweet.retweet' | 'tweet.quote';
+export type EventType = 'tweet.new' | 'tweet.reply' | 'tweet.retweet' | 'tweet.quote' | 'tweet.media' | 'tweet.link' | 'tweet.poll' | 'tweet.mention' | 'tweet.hashtag' | 'tweet.longform' | 'profile.avatar.changed' | 'profile.banner.changed' | 'profile.name.changed' | 'profile.username.changed' | 'profile.bio.changed' | 'profile.location.changed' | 'profile.url.changed' | 'profile.verified.changed' | 'profile.protected.changed' | 'profile.pinned_tweet.changed' | 'profile.unavailable.changed';
 /**
- * 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 the available usage balance covers
+ * 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.
  */
 export interface PaginatedTweets {
     has_next_page: boolean;
@@ -17,7 +102,11 @@ export interface PaginatedTweets {
     tweets: Array<SearchTweet>;
 }
 /**
- * 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 the available usage balance covers 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.
  */
 export interface PaginatedUsers {
     has_next_page: boolean;
@@ -25,30 +114,124 @@ export interface PaginatedUsers {
     users: Array<UserProfile>;
 }
 /**
- * Tweet returned from search results with inline author info.
+ * Tweet returned from search results with inline author info. A zero metric can
+ * mean X did not report the count.
  */
 export interface SearchTweet {
     id: string;
+    bookmarkCount: number;
+    likeCount: number;
+    quoteCount: number;
+    replyCount: number;
+    retweetCount: number;
     text: string;
-    author?: SearchTweet.Author;
-    bookmarkCount?: number;
+    viewCount: number;
+    /**
+     * X user profile with bio, follower counts, and verification status.
+     */
+    author?: UserProfile;
+    /**
+     * Content disclosure metadata shown by X when a tweet is labeled as paid
+     * partnership content or AI-generated media.
+     */
+    contentDisclosure?: ContentDisclosure;
+    /**
+     * Root tweet ID for the search result conversation
+     */
+    conversationId?: string;
     createdAt?: string;
+    /**
+     * Start and end offsets for rendered tweet text
+     */
+    displayTextRange?: Array<number>;
+    /**
+     * Parsed search-result entities including URLs, mentions, hashtags, and media
+     * markers
+     */
+    entities?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Tweet ID being replied to
+     */
+    inReplyToId?: string;
+    /**
+     * User ID being replied to
+     */
+    inReplyToUserId?: string;
+    /**
+     * Username being replied to
+     */
+    inReplyToUsername?: string;
+    /**
+     * Whether the tweet has limited reply permissions
+     */
+    isLimitedReply?: boolean;
     /**
      * True for Note Tweets (long-form content, up to 25,000 characters)
      */
     isNoteTweet?: boolean;
-    likeCount?: number;
-    quoteCount?: number;
-    replyCount?: number;
-    retweetCount?: number;
-    viewCount?: number;
+    /**
+     * True when this search result quotes another tweet
+     */
+    isQuoteStatus?: boolean;
+    /**
+     * True when this search result is a reply
+     */
+    isReply?: boolean;
+    /**
+     * Tweet language code
+     */
+    lang?: string;
+    /**
+     * Search-result media attachments, omitted when no media is present
+     */
+    media?: Array<TweetMedia>;
+    /**
+     * 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.
+     */
+    quoted_tweet?: EmbeddedTweet;
+    /**
+     * 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.
+     */
+    retweeted_tweet?: EmbeddedTweet;
+    /**
+     * Client application used to post the tweet
+     */
+    source?: string;
+    type?: string;
+    /**
+     * Tweet permalink URL
+     */
+    url?: string;
 }
-export declare namespace SearchTweet {
-    interface Author {
-        id: string;
-        name: string;
-        username: string;
-        verified?: boolean;
+/**
+ * Normalized media attached to a tweet.
+ */
+export interface TweetMedia {
+    /**
+     * Media preview URL
+     */
+    mediaUrl: string;
+    type: 'photo' | 'video' | 'animated_gif';
+    /**
+     * X media link from the tweet
+     */
+    url: string;
+    /**
+     * Available video encodings, ordered as returned
+     */
+    videoVariants?: Array<TweetMedia.VideoVariant>;
+}
+export declare namespace TweetMedia {
+    interface VideoVariant {
+        contentType: string;
+        url: string;
+        bitrate?: number;
     }
 }
 /**
@@ -58,13 +241,62 @@ export interface UserProfile {
     id: string;
     name: string;
     username: string;
+    automatedBy?: string;
+    canDm?: boolean;
+    /**
+     * Community role when returned by community member reads
+     */
+    communityRole?: string;
+    coverPicture?: string;
     createdAt?: string;
     description?: string;
+    favouritesCount?: number;
     followers?: number;
     following?: number;
+    hasCustomTimelines?: boolean;
+    isAutomated?: boolean;
+    /**
+     * Whether X shows a blue verification badge
+     */
+    isBlueVerified?: boolean;
+    isTranslator?: boolean;
+    /**
+     * Whether X marks the profile as verified
+     */
+    isVerified?: boolean;
     location?: string;
+    mediaCount?: number;
+    pinnedTweetIds?: Array<string>;
+    possiblySensitive?: boolean;
+    /**
+     * Structured profile bio with entity annotations
+     */
+    profile_bio?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Original X profile banner field when available
+     */
+    profileBannerUrl?: string;
     profilePicture?: string;
+    /**
+     * Whether the profile protects its posts
+     */
+    protected?: boolean;
     statusesCount?: number;
+    unavailable?: boolean;
+    unavailableReason?: string;
+    url?: string;
     verified?: boolean;
+    verifiedType?: string;
+    /**
+     * Whether this profile follows the authenticated viewer
+     */
+    viewerFollowedBy?: boolean;
+    /**
+     * Whether the authenticated viewer follows this profile
+     */
+    viewerFollowing?: boolean;
+    withheldInCountries?: Array<string>;
 }
 //# sourceMappingURL=shared.d.mts.map

package/resources/shared.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.mts","sourceRoot":"","sources":["../src/resources/shared.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,KAAK,EACD,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,kBAAkB,GAClB,mBAAmB,GACnB,kBAAkB,GAClB,sBAAsB,GACtB,gBAAgB,GAChB,eAAe,GACf,wBAAwB,GACxB,uBAAuB,GACvB,YAAY,GACZ,iBAAiB,GACjB,WAAW,GACX,uBAAuB,GACvB,iBAAiB,GACjB,iBAAiB,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,oBAAoB,GACpB,mBAAmB,GACnB,oBAAoB,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,aAAa,GAAG,eAAe,GAAG,aAAa,CAAC;AAEtF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,OAAO,CAAC;IAEvB,WAAW,EAAE,MAAM,CAAC;IAEpB,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,OAAO,CAAC;IAEvB,WAAW,EAAE,MAAM,CAAC;IAEpB,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IAEX,IAAI,EAAE,MAAM,CAAC;IAEb,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC;IAE5B,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yBAAiB,WAAW,CAAC;IAC3B,UAAiB,MAAM;QACrB,EAAE,EAAE,MAAM,CAAC;QAEX,IAAI,EAAE,MAAM,CAAC;QAEb,QAAQ,EAAE,MAAM,CAAC;QAEjB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB;CACF;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IAEX,IAAI,EAAE,MAAM,CAAC;IAEb,QAAQ,EAAE,MAAM,CAAC;IAEjB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}
+{"version":3,"file":"shared.d.mts","sourceRoot":"","sources":["../src/resources/shared.ts"],"names":[],"mappings":"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"}

package/resources/shared.d.ts

@@ -1,15 +1,100 @@
 /**
- * Error response containing a machine-readable error code.
+ * Content disclosure metadata shown by X when a tweet is labeled as paid
+ * partnership content or AI-generated media.
+ */
+export interface ContentDisclosure {
+    advertising?: ContentDisclosure.Advertising;
+    aiGenerated?: ContentDisclosure.AIGenerated;
+}
+export declare namespace ContentDisclosure {
+    interface Advertising {
+        /**
+         * True when X labels the tweet as paid promotion content.
+         */
+        isPaidPromotion?: boolean;
+    }
+    interface AIGenerated {
+        /**
+         * Whether the disclosure can be edited on X.
+         */
+        canEdit?: boolean;
+        /**
+         * Source of the AI-generated media disclosure.
+         */
+        detectionSource?: string;
+        /**
+         * True when X labels the tweet as containing AI-generated media.
+         */
+        hasAiGeneratedMedia?: boolean;
+    }
+}
+/**
+ * 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.
+ */
+export interface EmbeddedTweet {
+    id: string;
+    bookmarkCount: number;
+    likeCount: number;
+    quoteCount: number;
+    replyCount: number;
+    retweetCount: number;
+    text: string;
+    viewCount: number;
+    /**
+     * X user profile with bio, follower counts, and verification status.
+     */
+    author?: UserProfile;
+    /**
+     * Content disclosure metadata shown by X when a tweet is labeled as paid
+     * partnership content or AI-generated media.
+     */
+    contentDisclosure?: ContentDisclosure;
+    conversationId?: string;
+    createdAt?: string;
+    displayTextRange?: Array<number>;
+    entities?: {
+        [key: string]: unknown;
+    };
+    inReplyToId?: string;
+    inReplyToUserId?: string;
+    inReplyToUsername?: string;
+    isLimitedReply?: boolean;
+    isNoteTweet?: boolean;
+    isQuoteStatus?: boolean;
+    isReply?: boolean;
+    lang?: string;
+    media?: Array<TweetMedia>;
+    source?: string;
+    type?: string;
+    url?: string;
+}
+/**
+ * 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.
  */
 export interface Error {
-    error: 'internal_error' | 'invalid_format' | 'invalid_id' | 'invalid_input' | 'invalid_params' | 'invalid_tool_type' | 'invalid_tweet_id' | 'invalid_tweet_url' | 'invalid_username' | 'insufficient_credits' | 'missing_params' | 'missing_query' | 'monitor_already_exists' | 'monitor_limit_reached' | 'no_credits' | 'no_subscription' | 'not_found' | 'subscription_inactive' | 'tweet_not_found' | 'unauthenticated' | 'user_not_found' | 'webhook_inactive' | 'x_api_rate_limited' | 'x_api_unavailable' | 'x_api_unauthorized';
+    error: 'internal_error' | 'account_already_connected' | 'account_needs_reauth' | 'account_not_found' | 'account_required' | 'account_restricted' | 'api_key_limit_reached' | 'article_not_found' | 'dm_not_permitted' | 'invalid_format' | 'invalid_id' | 'invalid_input' | 'invalid_params' | 'invalid_tool_type' | 'invalid_tweet_id' | 'invalid_tweet_url' | 'invalid_user_id' | 'invalid_user_ids' | 'invalid_username' | 'invalid_json' | 'insufficient_credits' | 'login_cooldown' | 'login_failed' | 'media_download_failed' | 'missing_params' | 'missing_query' | 'monitor_already_exists' | 'no_media' | 'no_credits' | 'no_subscription' | 'not_found' | 'payment_failed' | 'rate_limit_exceeded' | 'service_unavailable' | 'style_not_found' | 'subscription_inactive' | 'tweet_not_found' | 'unauthenticated' | 'unsupported_field' | 'user_not_found' | 'x_account_feature_required' | 'x_account_protected' | 'x_account_suspended' | 'x_api_rate_limited' | 'x_api_unavailable' | 'x_api_unauthorized' | 'x_auth_failure' | 'x_content_too_long' | 'x_daily_limit' | 'x_dm_not_allowed' | 'x_duplicate_action' | 'x_login_auth_failed' | 'x_login_challenge' | 'x_login_denied' | 'x_login_failed' | 'x_login_proxy_error' | 'x_login_rate_limited' | 'x_login_service_unavailable' | 'x_login_suspended' | 'x_rate_limited' | 'x_rejected' | 'x_target_not_found' | 'x_transient_error' | 'x_user_lookup_failed' | 'x_write_ambiguous' | 'x_write_failed' | 'x_write_unconfirmed' | Error.StructuredError;
+}
+export declare namespace Error {
+    interface StructuredError {
+        code: 'internal_error' | 'account_already_connected' | 'account_needs_reauth' | 'account_not_found' | 'account_required' | 'account_restricted' | 'api_key_limit_reached' | 'article_not_found' | 'dm_not_permitted' | 'invalid_format' | 'invalid_id' | 'invalid_input' | 'invalid_params' | 'invalid_tool_type' | 'invalid_tweet_id' | 'invalid_tweet_url' | 'invalid_user_id' | 'invalid_user_ids' | 'invalid_username' | 'invalid_json' | 'insufficient_credits' | 'login_cooldown' | 'login_failed' | 'media_download_failed' | 'missing_params' | 'missing_query' | 'monitor_already_exists' | 'no_media' | 'no_credits' | 'no_subscription' | 'not_found' | 'payment_failed' | 'rate_limit_exceeded' | 'service_unavailable' | 'style_not_found' | 'subscription_inactive' | 'tweet_not_found' | 'unauthenticated' | 'unsupported_field' | 'user_not_found' | 'x_account_feature_required' | 'x_account_protected' | 'x_account_suspended' | 'x_api_rate_limited' | 'x_api_unavailable' | 'x_api_unauthorized' | 'x_auth_failure' | 'x_content_too_long' | 'x_daily_limit' | 'x_dm_not_allowed' | 'x_duplicate_action' | 'x_login_auth_failed' | 'x_login_challenge' | 'x_login_denied' | 'x_login_failed' | 'x_login_proxy_error' | 'x_login_rate_limited' | 'x_login_service_unavailable' | 'x_login_suspended' | 'x_rate_limited' | 'x_rejected' | 'x_target_not_found' | 'x_transient_error' | 'x_user_lookup_failed' | 'x_write_ambiguous' | 'x_write_failed' | 'x_write_unconfirmed';
+        message: string;
+        type: 'api_error' | 'authentication_error' | 'billing_error' | 'dependency_error' | 'invalid_request_error' | 'permission_error' | 'rate_limit_error';
+    }
 }
 /**
  * Type of monitor event fired when account activity occurs.
  */
-export type EventType = 'tweet.new' | 'tweet.reply' | 'tweet.retweet' | 'tweet.quote';
+export type EventType = 'tweet.new' | 'tweet.reply' | 'tweet.retweet' | 'tweet.quote' | 'tweet.media' | 'tweet.link' | 'tweet.poll' | 'tweet.mention' | 'tweet.hashtag' | 'tweet.longform' | 'profile.avatar.changed' | 'profile.banner.changed' | 'profile.name.changed' | 'profile.username.changed' | 'profile.bio.changed' | 'profile.location.changed' | 'profile.url.changed' | 'profile.verified.changed' | 'profile.protected.changed' | 'profile.pinned_tweet.changed' | 'profile.unavailable.changed';
 /**
- * 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 the available usage balance covers
+ * 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.
  */
 export interface PaginatedTweets {
     has_next_page: boolean;
@@ -17,7 +102,11 @@ export interface PaginatedTweets {
     tweets: Array<SearchTweet>;
 }
 /**
- * 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 the available usage balance covers 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.
  */
 export interface PaginatedUsers {
     has_next_page: boolean;
@@ -25,30 +114,124 @@ export interface PaginatedUsers {
     users: Array<UserProfile>;
 }
 /**
- * Tweet returned from search results with inline author info.
+ * Tweet returned from search results with inline author info. A zero metric can
+ * mean X did not report the count.
  */
 export interface SearchTweet {
     id: string;
+    bookmarkCount: number;
+    likeCount: number;
+    quoteCount: number;
+    replyCount: number;
+    retweetCount: number;
     text: string;
-    author?: SearchTweet.Author;
-    bookmarkCount?: number;
+    viewCount: number;
+    /**
+     * X user profile with bio, follower counts, and verification status.
+     */
+    author?: UserProfile;
+    /**
+     * Content disclosure metadata shown by X when a tweet is labeled as paid
+     * partnership content or AI-generated media.
+     */
+    contentDisclosure?: ContentDisclosure;
+    /**
+     * Root tweet ID for the search result conversation
+     */
+    conversationId?: string;
     createdAt?: string;
+    /**
+     * Start and end offsets for rendered tweet text
+     */
+    displayTextRange?: Array<number>;
+    /**
+     * Parsed search-result entities including URLs, mentions, hashtags, and media
+     * markers
+     */
+    entities?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Tweet ID being replied to
+     */
+    inReplyToId?: string;
+    /**
+     * User ID being replied to
+     */
+    inReplyToUserId?: string;
+    /**
+     * Username being replied to
+     */
+    inReplyToUsername?: string;
+    /**
+     * Whether the tweet has limited reply permissions
+     */
+    isLimitedReply?: boolean;
     /**
      * True for Note Tweets (long-form content, up to 25,000 characters)
      */
     isNoteTweet?: boolean;
-    likeCount?: number;
-    quoteCount?: number;
-    replyCount?: number;
-    retweetCount?: number;
-    viewCount?: number;
+    /**
+     * True when this search result quotes another tweet
+     */
+    isQuoteStatus?: boolean;
+    /**
+     * True when this search result is a reply
+     */
+    isReply?: boolean;
+    /**
+     * Tweet language code
+     */
+    lang?: string;
+    /**
+     * Search-result media attachments, omitted when no media is present
+     */
+    media?: Array<TweetMedia>;
+    /**
+     * 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.
+     */
+    quoted_tweet?: EmbeddedTweet;
+    /**
+     * 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.
+     */
+    retweeted_tweet?: EmbeddedTweet;
+    /**
+     * Client application used to post the tweet
+     */
+    source?: string;
+    type?: string;
+    /**
+     * Tweet permalink URL
+     */
+    url?: string;
 }
-export declare namespace SearchTweet {
-    interface Author {
-        id: string;
-        name: string;
-        username: string;
-        verified?: boolean;
+/**
+ * Normalized media attached to a tweet.
+ */
+export interface TweetMedia {
+    /**
+     * Media preview URL
+     */
+    mediaUrl: string;
+    type: 'photo' | 'video' | 'animated_gif';
+    /**
+     * X media link from the tweet
+     */
+    url: string;
+    /**
+     * Available video encodings, ordered as returned
+     */
+    videoVariants?: Array<TweetMedia.VideoVariant>;
+}
+export declare namespace TweetMedia {
+    interface VideoVariant {
+        contentType: string;
+        url: string;
+        bitrate?: number;
     }
 }
 /**
@@ -58,13 +241,62 @@ export interface UserProfile {
     id: string;
     name: string;
     username: string;
+    automatedBy?: string;
+    canDm?: boolean;
+    /**
+     * Community role when returned by community member reads
+     */
+    communityRole?: string;
+    coverPicture?: string;
     createdAt?: string;
     description?: string;
+    favouritesCount?: number;
     followers?: number;
     following?: number;
+    hasCustomTimelines?: boolean;
+    isAutomated?: boolean;
+    /**
+     * Whether X shows a blue verification badge
+     */
+    isBlueVerified?: boolean;
+    isTranslator?: boolean;
+    /**
+     * Whether X marks the profile as verified
+     */
+    isVerified?: boolean;
     location?: string;
+    mediaCount?: number;
+    pinnedTweetIds?: Array<string>;
+    possiblySensitive?: boolean;
+    /**
+     * Structured profile bio with entity annotations
+     */
+    profile_bio?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Original X profile banner field when available
+     */
+    profileBannerUrl?: string;
     profilePicture?: string;
+    /**
+     * Whether the profile protects its posts
+     */
+    protected?: boolean;
     statusesCount?: number;
+    unavailable?: boolean;
+    unavailableReason?: string;
+    url?: string;
     verified?: boolean;
+    verifiedType?: string;
+    /**
+     * Whether this profile follows the authenticated viewer
+     */
+    viewerFollowedBy?: boolean;
+    /**
+     * Whether the authenticated viewer follows this profile
+     */
+    viewerFollowing?: boolean;
+    withheldInCountries?: Array<string>;
 }
 //# sourceMappingURL=shared.d.ts.map