x-twitter-scraper 0.2.0 → 0.3.0

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,

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

@@ -36,7 +36,7 @@ export class Tweets extends APIResource {
   }
 
   /**
-   * Look up tweet
+   * Get tweet with full text, author, metrics and media
    *
    * @example
    * ```ts
@@ -76,7 +76,7 @@ export class Tweets extends APIResource {
   }
 
   /**
-   * Get users who liked a tweet
+   * List users who liked a tweet
    *
    * @example
    * ```ts
@@ -94,7 +94,7 @@ export class Tweets extends APIResource {
   }
 
   /**
-   * Get quote tweets of a tweet
+   * List quote tweets of a tweet
    *
    * @example
    * ```ts
@@ -112,7 +112,7 @@ export class Tweets extends APIResource {
   }
 
   /**
-   * Get replies to a tweet
+   * List replies to a tweet
    *
    * @example
    * ```ts
@@ -130,7 +130,7 @@ export class Tweets extends APIResource {
   }
 
   /**
-   * Get users who retweeted a tweet
+   * List users who retweeted a tweet
    *
    * @example
    * ```ts
@@ -148,7 +148,7 @@ export class Tweets extends APIResource {
   }
 
   /**
-   * Get thread context for a tweet
+   * Get full conversation thread for a tweet
    *
    * @example
    * ```ts
@@ -166,7 +166,7 @@ export class Tweets extends APIResource {
   }
 
   /**
-   * Search tweets
+   * Search tweets with X query operators and pagination
    *
    * @example
    * ```ts
@@ -180,48 +180,6 @@ export class Tweets extends APIResource {
   }
 }
 
-/**
- * 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;
-  }
-}
-
 /**
  * Author of a tweet with follower count and verification status.
  */
@@ -338,17 +296,28 @@ export interface TweetCreateParams {
    */
   account: string;
 
-  text: string;
-
   attachment_url?: string;
 
   community_id?: string;
 
   is_note_tweet?: boolean;
 
+  /**
+   * Array of media URLs to attach (mutually exclusive with media_ids)
+   */
+  media?: Array<string>;
+
+  /**
+   * Array of media IDs to attach (mutually exclusive with media)
+   */
   media_ids?: Array<string>;
 
   reply_to_tweet_id?: string;
+
+  /**
+   * Tweet text (optional when media is provided)
+   */
+  text?: string;
 }
 
 export interface TweetListParams {
@@ -462,7 +431,6 @@ Tweets.Retweet = Retweet;
 
 export declare namespace Tweets {
   export {
-    type SearchTweet as SearchTweet,
     type TweetAuthor as TweetAuthor,
     type TweetDetail as TweetDetail,
     type TweetCreateResponse as TweetCreateResponse,

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

@@ -9,7 +9,6 @@ export {
 } from './follow';
 export {
   Users,
-  type UserProfile,
   type UserRetrieveBatchParams,
   type UserRetrieveFollowersParams,
   type UserRetrieveFollowersYouKnowParams,

package/src/resources/x/users/users.ts

@@ -15,25 +15,25 @@ import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
 /**
- * X data lookups (subscription required)
+ * Look up, search, and explore user profiles and relationships
  */
 export class Users extends APIResource {
   follow: FollowAPI.Follow = new FollowAPI.Follow(this._client);
 
   /**
-   * Look up X user
+   * Get user profile with follower counts and verification
    *
    * @example
    * ```ts
    * const userProfile = await client.x.users.retrieve('id');
    * ```
    */
-  retrieve(id: string, options?: RequestOptions): APIPromise<UserProfile> {
+  retrieve(id: string, options?: RequestOptions): APIPromise<Shared.UserProfile> {
     return this._client.get(path`/x/users/${id}`, options);
   }
 
   /**
-   * Get multiple users by IDs
+   * Look up multiple users by IDs in one call
    *
    * @example
    * ```ts
@@ -47,7 +47,7 @@ export class Users extends APIResource {
   }
 
   /**
-   * Get user followers
+   * List followers of a user
    *
    * @example
    * ```ts
@@ -64,7 +64,7 @@ export class Users extends APIResource {
   }
 
   /**
-   * Get followers you know for a user
+   * List mutual followers between you and a user
    *
    * @example
    * ```ts
@@ -81,7 +81,7 @@ export class Users extends APIResource {
   }
 
   /**
-   * Get users this user follows
+   * List accounts a user follows
    *
    * @example
    * ```ts
@@ -98,7 +98,7 @@ export class Users extends APIResource {
   }
 
   /**
-   * Get tweets liked by a user
+   * List tweets liked by a user
    *
    * @example
    * ```ts
@@ -116,7 +116,7 @@ export class Users extends APIResource {
   }
 
   /**
-   * Get media tweets by a user
+   * List media tweets posted by a user
    *
    * @example
    * ```ts
@@ -134,7 +134,7 @@ export class Users extends APIResource {
   }
 
   /**
-   * Get tweets mentioning a user
+   * List tweets mentioning a user
    *
    * @example
    * ```ts
@@ -168,7 +168,7 @@ export class Users extends APIResource {
   }
 
   /**
-   * Get recent tweets by a user
+   * List recent tweets posted by a user
    *
    * @example
    * ```ts
@@ -186,7 +186,7 @@ export class Users extends APIResource {
   }
 
   /**
-   * Get verified followers
+   * List verified followers of a user
    *
    * @example
    * ```ts
@@ -203,33 +203,6 @@ export class Users extends APIResource {
   }
 }
 
-/**
- * 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;
-}
-
 export interface UserRetrieveBatchParams {
   /**
    * Comma-separated user IDs (max 100)
@@ -339,7 +312,6 @@ Users.Follow = Follow;
 
 export declare namespace Users {
   export {
-    type UserProfile as UserProfile,
     type UserRetrieveBatchParams as UserRetrieveBatchParams,
     type UserRetrieveFollowersParams as UserRetrieveFollowersParams,
     type UserRetrieveFollowersYouKnowParams as UserRetrieveFollowersYouKnowParams,