x-twitter-scraper 0.3.3 → 0.4.0

package/src/resources/shared.ts

@@ -1,11 +1,123 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 /**
- * 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 namespace ContentDisclosure {
+  export interface Advertising {
+    /**
+     * True when X labels the tweet as paid promotion content.
+     */
+    isPaidPromotion?: boolean;
+  }
+
+  export 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'
+    | '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'
@@ -13,32 +125,176 @@ export interface Error {
     | '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'
-    | 'monitor_limit_reached'
+    | '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'
-    | 'webhook_inactive'
+    | 'x_account_feature_required'
+    | 'x_account_protected'
+    | 'x_account_suspended'
     | 'x_api_rate_limited'
     | 'x_api_unavailable'
-    | 'x_api_unauthorized';
+    | '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 namespace Error {
+  export 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;
@@ -49,7 +305,11 @@ export interface PaginatedTweets {
 }
 
 /**
- * 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;
@@ -60,44 +320,156 @@ export interface PaginatedUsers {
 }
 
 /**
- * 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;
+  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;
 
-  bookmarkCount?: number;
+  /**
+   * 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;
+  /**
+   * 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;
 
-  quoteCount?: number;
+  /**
+   * 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;
 
-  replyCount?: number;
+  /**
+   * Client application used to post the tweet
+   */
+  source?: string;
 
-  retweetCount?: number;
+  type?: string;
 
-  viewCount?: number;
+  /**
+   * Tweet permalink URL
+   */
+  url?: string;
 }
 
-export namespace SearchTweet {
-  export interface Author {
-    id: string;
+/**
+ * Normalized media attached to a tweet.
+ */
+export interface TweetMedia {
+  /**
+   * Media preview URL
+   */
+  mediaUrl: string;
 
-    name: string;
+  type: 'photo' | 'video' | 'animated_gif';
 
-    username: string;
+  /**
+   * X media link from the tweet
+   */
+  url: string;
 
-    verified?: boolean;
+  /**
+   * Available video encodings, ordered as returned
+   */
+  videoVariants?: Array<TweetMedia.VideoVariant>;
+}
+
+export namespace TweetMedia {
+  export interface VideoVariant {
+    contentType: string;
+
+    url: string;
+
+    bitrate?: number;
   }
 }
 
@@ -111,19 +483,89 @@ export interface UserProfile {
 
   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>;
 }

package/src/resources/subscribe.ts

@@ -5,25 +5,46 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 /**
- * Subscription, billing, and credits
+ * Subscription, billing, and usage balance
  */
 export class Subscribe extends APIResource {
   /**
-   * Get checkout or billing URL
+   * Create a subscription checkout or billing-management URL only after the user
+   * confirms. The request never completes payment by itself.
+   *
+   * @example
+   * ```ts
+   * const subscribe = await client.subscribe.create({
+   *   tier: 'pro',
+   * });
+   * ```
    */
-  create(options?: RequestOptions): APIPromise<SubscribeCreateResponse> {
-    return this._client.post('/subscribe', options);
+  create(
+    body: SubscribeCreateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<SubscribeCreateResponse> {
+    return this._client.post('/subscribe', { body, ...options });
   }
 }
 
 export interface SubscribeCreateResponse {
-  url: string;
+  message: string;
+
+  status: 'checkout_created' | 'already_subscribed' | 'payment_issue';
 
-  message?: string;
+  url: string;
+}
 
-  status?: 'checkout_created' | 'already_subscribed' | 'payment_issue';
+export interface SubscribeCreateParams {
+  /**
+   * Subscription tier to pre-select.
+   */
+  tier?: 'starter' | 'pro' | 'business';
 }
 
 export declare namespace Subscribe {
-  export { type SubscribeCreateResponse as SubscribeCreateResponse };
+  export {
+    type SubscribeCreateResponse as SubscribeCreateResponse,
+    type SubscribeCreateParams as SubscribeCreateParams,
+  };
 }

package/src/resources/support/tickets.ts

@@ -30,7 +30,7 @@ export class Tickets extends APIResource {
    * @example
    * ```ts
    * const ticket = await client.support.tickets.retrieve(
-   *   'messages_value',
+   *   'tkt_a1b2c3d4e5f6a1b2c3d4e5f6',
    * );
    * ```
    */
@@ -43,9 +43,10 @@ export class Tickets extends APIResource {
    *
    * @example
    * ```ts
-   * const ticket = await client.support.tickets.update('id', {
-   *   status: 'resolved',
-   * });
+   * const ticket = await client.support.tickets.update(
+   *   'tkt_a1b2c3d4e5f6a1b2c3d4e5f6',
+   *   { status: 'resolved' },
+   * );
    * ```
    */
   update(id: string, body: TicketUpdateParams, options?: RequestOptions): APIPromise<TicketUpdateResponse> {
@@ -69,9 +70,10 @@ export class Tickets extends APIResource {
    *
    * @example
    * ```ts
-   * const response = await client.support.tickets.reply('id', {
-   *   body: 'Thank you for the update.',
-   * });
+   * const response = await client.support.tickets.reply(
+   *   'tkt_a1b2c3d4e5f6a1b2c3d4e5f6',
+   *   { body: 'Thank you for the update.' },
+   * );
    * ```
    */
   reply(id: string, body: TicketReplyParams, options?: RequestOptions): APIPromise<TicketReplyResponse> {

package/src/resources/trends.ts

@@ -41,12 +41,12 @@ export namespace TrendListResponse {
 
 export interface TrendListParams {
   /**
-   * Number of trending topics to return (1-50, default 30)
+   * Number of trending topics returned (1-50, default 30)
    */
   count?: number;
 
   /**
-   * Region WOEID (1=Worldwide, 23424977=US, 23424975=UK, 23424969=Turkey)
+   * Region Yahoo WOEID code (1=Worldwide, 23424977=US, 23424975=UK, 23424969=Turkey)
    */
   woeid?: number;
 }