x-twitter-scraper 0.2.1 → 0.3.1

package/src/resources/index.ts

@@ -17,7 +17,6 @@ export {
   type AccountSetXUsernameParams,
   type AccountUpdateLocaleParams,
 } from './account';
-export { Bot } from './bot/bot';
 export { Compose, type ComposeCreateResponse, type ComposeCreateParams } from './compose';
 export {
   Credits,
@@ -59,18 +58,6 @@ export {
   type ExtractionExportResultsParams,
   type ExtractionRunParams,
 } from './extractions';
-export {
-  Integrations,
-  type Integration,
-  type IntegrationDelivery,
-  type IntegrationListResponse,
-  type IntegrationDeleteResponse,
-  type IntegrationListDeliveriesResponse,
-  type IntegrationSendTestResponse,
-  type IntegrationCreateParams,
-  type IntegrationUpdateParams,
-  type IntegrationListDeliveriesParams,
-} from './integrations';
 export {
   Monitors,
   type Monitor,
@@ -119,4 +106,5 @@ export {
   type XGetTrendsResponse,
   type XGetHomeTimelineParams,
   type XGetNotificationsParams,
+  type XGetTrendsParams,
 } from './x/x';

package/src/resources/monitors.ts

@@ -16,7 +16,7 @@ export class Monitors extends APIResource {
    * @example
    * ```ts
    * const monitor = await client.monitors.create({
-   *   eventTypes: ['tweet.new', 'follower.gained'],
+   *   eventTypes: ['tweet.new', 'tweet.reply'],
    *   username: 'elonmusk',
    * });
    * ```

package/src/resources/radar.ts

@@ -5,7 +5,7 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 /**
- * Tweet composition, drafts, writing styles & radar
+ * AI tweet composition, drafts, writing styles, and radar
  */
 export class Radar extends APIResource {
   /**
@@ -20,10 +20,35 @@ export class Radar extends APIResource {
 }
 
 /**
- * Trending topic with score, category, source, and region.
+ * Trending topic with score, category, source, region, language, and
+ * source-specific metadata.
  */
 export interface RadarItem {
-  category: string;
+  /**
+   * Internal numeric identifier (stringified bigint).
+   */
+  id: string;
+
+  category: 'general' | 'tech' | 'dev' | 'science' | 'culture' | 'politics' | 'business' | 'entertainment';
+
+  createdAt: string;
+
+  language: string;
+
+  /**
+   * 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? }
+   */
+  metadata: { [key: string]: unknown };
 
   publishedAt: string;
 
@@ -31,7 +56,12 @@ export interface RadarItem {
 
   score: number;
 
-  source: string;
+  source: 'github' | 'google_trends' | 'hacker_news' | 'polymarket' | 'reddit' | 'trustmrr' | 'wikipedia';
+
+  /**
+   * Source-specific identifier used for deduplication.
+   */
+  sourceId: string;
 
   title: string;
 
@@ -43,27 +73,37 @@ export interface RadarItem {
 }
 
 export interface RadarRetrieveTrendingTopicsResponse {
+  hasMore: boolean;
+
   items: Array<RadarItem>;
 
-  total: number;
+  /**
+   * Opaque cursor for the next page (present only when hasMore is true).
+   */
+  nextCursor?: string;
 }
 
 export interface RadarRetrieveTrendingTopicsParams {
   /**
-   * Filter by category (general, tech, dev, etc.)
+   * Cursor for pagination (from prior response nextCursor).
    */
-  category?: string;
+  after?: string;
 
   /**
-   * Number of items to return
+   * Filter by category.
    */
-  count?: number;
+  category?: 'general' | 'tech' | 'dev' | 'science' | 'culture' | 'politics' | 'business' | 'entertainment';
 
   /**
-   * Lookback window in hours
+   * Lookback window in hours (1-168, default 24).
    */
   hours?: number;
 
+  /**
+   * Number of items to return (1-100, default 50).
+   */
+  limit?: number;
+
   /**
    * Region filter (us, global, etc.)
    */

package/src/resources/shared.ts

@@ -1,8 +1,5 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import * as TweetsAPI from './x/tweets/tweets';
-import * as UsersAPI from './x/users/users';
-
 /**
  * Error response containing a machine-readable error code.
  */
@@ -17,17 +14,17 @@ export interface Error {
     | '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'
-    | 'stream_registration_failed'
     | 'subscription_inactive'
     | 'tweet_not_found'
     | 'unauthenticated'
-    | 'usage_limit_reached'
     | 'user_not_found'
     | 'webhook_inactive'
     | 'x_api_rate_limited'
@@ -38,13 +35,7 @@ export interface Error {
 /**
  * Type of monitor event fired when account activity occurs.
  */
-export type EventType =
-  | 'tweet.new'
-  | 'tweet.reply'
-  | 'tweet.retweet'
-  | 'tweet.quote'
-  | 'follower.gained'
-  | 'follower.lost';
+export type EventType = 'tweet.new' | 'tweet.reply' | 'tweet.retweet' | 'tweet.quote';
 
 /**
  * Paginated list of tweets with cursor-based navigation.
@@ -54,7 +45,7 @@ export interface PaginatedTweets {
 
   next_cursor: string;
 
-  tweets: Array<TweetsAPI.SearchTweet>;
+  tweets: Array<SearchTweet>;
 }
 
 /**
@@ -65,5 +56,74 @@ export interface PaginatedUsers {
 
   next_cursor: string;
 
-  users: Array<UsersAPI.UserProfile>;
+  users: Array<UserProfile>;
+}
+
+/**
+ * Tweet returned from search results with inline author info.
+ */
+export interface SearchTweet {
+  id: string;
+
+  text: string;
+
+  author?: SearchTweet.Author;
+
+  bookmarkCount?: number;
+
+  createdAt?: string;
+
+  /**
+   * True for Note Tweets (long-form content, up to 25,000 characters)
+   */
+  isNoteTweet?: boolean;
+
+  likeCount?: number;
+
+  quoteCount?: number;
+
+  replyCount?: number;
+
+  retweetCount?: number;
+
+  viewCount?: number;
+}
+
+export namespace SearchTweet {
+  export interface Author {
+    id: string;
+
+    name: string;
+
+    username: string;
+
+    verified?: boolean;
+  }
+}
+
+/**
+ * X user profile with bio, follower counts, and verification status.
+ */
+export interface UserProfile {
+  id: string;
+
+  name: string;
+
+  username: string;
+
+  createdAt?: string;
+
+  description?: string;
+
+  followers?: number;
+
+  following?: number;
+
+  location?: string;
+
+  profilePicture?: string;
+
+  statusesCount?: number;
+
+  verified?: boolean;
 }

package/src/resources/styles.ts

@@ -7,7 +7,7 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 /**
- * Tweet composition, drafts, writing styles & radar
+ * AI tweet composition, drafts, writing styles, and radar
  */
 export class Styles extends APIResource {
   /**

package/src/resources/subscribe.ts

@@ -5,7 +5,7 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 /**
- * Subscription & billing
+ * Subscription, billing, and credits
  */
 export class Subscribe extends APIResource {
   /**

package/src/resources/trends.ts

@@ -5,11 +5,11 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 /**
- * Trending topics by region
+ * Trending topics and hashtags by region
  */
 export class Trends extends APIResource {
   /**
-   * Get regional trending topics
+   * Get trending hashtags and topics by region (alias)
    */
   list(
     query: TrendListParams | null | undefined = {},

package/src/resources/webhooks.ts

@@ -7,7 +7,7 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 /**
- * Webhook endpoint management & delivery
+ * Webhook endpoint management and delivery
  */
 export class Webhooks extends APIResource {
   /**
@@ -16,7 +16,7 @@ export class Webhooks extends APIResource {
    * @example
    * ```ts
    * const webhook = await client.webhooks.create({
-   *   eventTypes: ['tweet.new', 'follower.gained'],
+   *   eventTypes: ['tweet.new', 'tweet.reply'],
    *   url: 'https://example.com/webhook',
    * });
    * ```

package/src/resources/x/accounts.ts

@@ -22,7 +22,7 @@ export class Accounts extends APIResource {
    * ```
    */
   create(body: AccountCreateParams, options?: RequestOptions): APIPromise<AccountCreateResponse> {
-    return this._client.post('/x/accounts', { body, ...options, __security: { apiKeyAuth: true } });
+    return this._client.post('/x/accounts', { body, ...options });
   }
 
   /**
@@ -36,7 +36,7 @@ export class Accounts extends APIResource {
    * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<XAccountDetail> {
-    return this._client.get(path`/x/accounts/${id}`, { ...options, __security: { apiKeyAuth: true } });
+    return this._client.get(path`/x/accounts/${id}`, options);
   }
 
   /**
@@ -48,7 +48,7 @@ export class Accounts extends APIResource {
    * ```
    */
   list(options?: RequestOptions): APIPromise<AccountListResponse> {
-    return this._client.get('/x/accounts', { ...options, __security: { apiKeyAuth: true } });
+    return this._client.get('/x/accounts', options);
   }
 
   /**
@@ -60,7 +60,7 @@ export class Accounts extends APIResource {
    * ```
    */
   delete(id: string, options?: RequestOptions): APIPromise<AccountDeleteResponse> {
-    return this._client.delete(path`/x/accounts/${id}`, { ...options, __security: { apiKeyAuth: true } });
+    return this._client.delete(path`/x/accounts/${id}`, options);
   }
 
   /**
@@ -73,7 +73,7 @@ export class Accounts extends APIResource {
    * ```
    */
   bulkRetry(options?: RequestOptions): APIPromise<AccountBulkRetryResponse> {
-    return this._client.post('/x/accounts/bulk-retry', { ...options, __security: { apiKeyAuth: true } });
+    return this._client.post('/x/accounts/bulk-retry', options);
   }
 
   /**
@@ -88,11 +88,7 @@ export class Accounts extends APIResource {
    * ```
    */
   reauth(id: string, body: AccountReauthParams, options?: RequestOptions): APIPromise<AccountReauthResponse> {
-    return this._client.post(path`/x/accounts/${id}/reauth`, {
-      body,
-      ...options,
-      __security: { apiKeyAuth: true },
-    });
+    return this._client.post(path`/x/accounts/${id}/reauth`, { body, ...options });
   }
 }
 
@@ -104,6 +100,15 @@ export interface XAccount {
 
   createdAt: string;
 
+  /**
+   * Derived login/cookie health. `healthy` = cookies valid. `needsReauth` = user
+   * must submit fresh credentials. `locked` = X locked the account; unlock on x.com
+   * first. `suspended` = X banned the account. `recovering` = past cooldown, will
+   * auto-retry on next use. `temporaryIssue` = transient backend problem; retry
+   * shortly.
+   */
+  health: 'healthy' | 'locked' | 'needsReauth' | 'recovering' | 'suspended' | 'temporaryIssue';
+
   status: string;
 
   xUserId: string;
@@ -119,6 +124,8 @@ export interface XAccountDetail {
 
   createdAt: string;
 
+  health: 'healthy' | 'locked' | 'needsReauth' | 'recovering' | 'suspended' | 'temporaryIssue';
+
   status: string;
 
   xUserId: string;
@@ -132,14 +139,32 @@ export interface XAccountDetail {
   updatedAt?: string;
 }
 
+/**
+ * Sanitized X account summary returned by connect and reauth. Includes an optional
+ * `loginCountry` field surfaced only when the declared proxy region had no Driver
+ * capacity and the login fell back to a single US consumer device for this
+ * one-time action. Future activity continues to use the selected `proxy_country`;
+ * the field is omitted on normal logins.
+ */
 export interface AccountCreateResponse {
   id: string;
 
+  createdAt: string;
+
+  health: 'healthy' | 'locked' | 'needsReauth' | 'recovering' | 'suspended' | 'temporaryIssue';
+
   status: string;
 
   xUserId: string;
 
   xUsername: string;
+
+  /**
+   * ISO-3166-1 alpha-2 country code of the Driver consumer device used for this
+   * login. Present only when the US fallback was triggered because Driver had no
+   * capacity in the declared region. Omitted otherwise.
+   */
+  loginCountry?: string;
 }
 
 export interface AccountListResponse {
@@ -157,12 +182,32 @@ export interface AccountBulkRetryResponse {
   cleared: number;
 }
 
+/**
+ * Sanitized X account summary returned by connect and reauth. Includes an optional
+ * `loginCountry` field surfaced only when the declared proxy region had no Driver
+ * capacity and the login fell back to a single US consumer device for this
+ * one-time action. Future activity continues to use the selected `proxy_country`;
+ * the field is omitted on normal logins.
+ */
 export interface AccountReauthResponse {
   id: string;
 
+  createdAt: string;
+
+  health: 'healthy' | 'locked' | 'needsReauth' | 'recovering' | 'suspended' | 'temporaryIssue';
+
   status: string;
 
+  xUserId: string;
+
   xUsername: string;
+
+  /**
+   * ISO-3166-1 alpha-2 country code of the Driver consumer device used for this
+   * login. Present only when the US fallback was triggered because Driver had no
+   * capacity in the declared region. Omitted otherwise.
+   */
+  loginCountry?: string;
 }
 
 export interface AccountCreateParams {
@@ -198,6 +243,16 @@ export interface AccountReauthParams {
    */
   password: string;
 
+  /**
+   * Email for the X account (updates stored email)
+   */
+  email?: string;
+
+  /**
+   * Two-letter country code for login proxy region
+   */
+  proxy_country?: string;
+
   /**
    * TOTP secret for 2FA re-authentication
    */

package/src/resources/x/bookmarks.ts

@@ -6,7 +6,7 @@ import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
 /**
- * X data lookups (subscription required)
+ * Look up, search, and analyze individual tweets
  */
 export class Bookmarks extends APIResource {
   /**

package/src/resources/x/communities/communities.ts

@@ -50,7 +50,7 @@ export class Communities extends APIResource {
   }
 
   /**
-   * Get community details
+   * Get community name, description and member count
    *
    * @example
    * ```ts
@@ -64,7 +64,7 @@ export class Communities extends APIResource {
   }
 
   /**
-   * Get community members
+   * List members of a community
    *
    * @example
    * ```ts
@@ -81,7 +81,7 @@ export class Communities extends APIResource {
   }
 
   /**
-   * Get community moderators
+   * List moderators of a community
    *
    * @example
    * ```ts
@@ -98,7 +98,7 @@ export class Communities extends APIResource {
   }
 
   /**
-   * Search tweets across communities
+   * Search for communities by keyword
    *
    * @example
    * ```ts

package/src/resources/x/communities/tweets.ts

@@ -7,11 +7,11 @@ import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
 /**
- * X data lookups (subscription required)
+ * X Community info, members, and tweets
  */
 export class Tweets extends APIResource {
   /**
-   * Search tweets across all communities
+   * List tweets across all communities
    *
    * @example
    * ```ts
@@ -24,7 +24,7 @@ export class Tweets extends APIResource {
   }
 
   /**
-   * Get community tweets
+   * List tweets posted in a community
    *
    * @example
    * ```ts

package/src/resources/x/followers.ts

@@ -5,11 +5,11 @@ import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
 /**
- * X data lookups (subscription required)
+ * Look up, search, and explore user profiles and relationships
  */
 export class Followers extends APIResource {
   /**
-   * Check follow relationship
+   * Check if one user follows another
    *
    * @example
    * ```ts

package/src/resources/x/index.ts

@@ -57,7 +57,6 @@ export {
 } from './profile';
 export {
   Tweets,
-  type SearchTweet,
   type TweetAuthor,
   type TweetDetail,
   type TweetCreateResponse,
@@ -75,7 +74,6 @@ export {
 } from './tweets/index';
 export {
   Users,
-  type UserProfile,
   type UserRetrieveBatchParams,
   type UserRetrieveFollowersParams,
   type UserRetrieveFollowersYouKnowParams,
@@ -94,4 +92,5 @@ export {
   type XGetTrendsResponse,
   type XGetHomeTimelineParams,
   type XGetNotificationsParams,
+  type XGetTrendsParams,
 } from './x';

package/src/resources/x/lists.ts

@@ -7,11 +7,11 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 /**
- * X data lookups (subscription required)
+ * X List followers, members, and tweets
  */
 export class Lists extends APIResource {
   /**
-   * Get list followers
+   * List followers of an X List
    *
    * @example
    * ```ts
@@ -28,7 +28,7 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Get list members
+   * List members of an X List
    *
    * @example
    * ```ts
@@ -46,7 +46,7 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Get list tweets
+   * List tweets from an X List
    *
    * @example
    * ```ts

package/src/resources/x/media.ts

@@ -7,11 +7,11 @@ import { RequestOptions } from '../../internal/request-options';
 import { multipartFormRequestOptions } from '../../internal/uploads';
 
 /**
- * Media upload & download
+ * Media upload and download
  */
 export class Media extends APIResource {
   /**
-   * Download tweet media
+   * Download images and videos from tweets
    *
    * @example
    * ```ts

package/src/resources/x/tweets/index.ts

@@ -16,7 +16,6 @@ export {
 } from './retweet';
 export {
   Tweets,
-  type SearchTweet,
   type TweetAuthor,
   type TweetDetail,
   type TweetCreateResponse,