x-twitter-scraper 0.3.2 → 0.4.0

package/src/resources/extractions.ts

@@ -7,7 +7,7 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 /**
- * Bulk data extraction (20 tool types)
+ * Bulk data extraction (23 tool types)
  */
 export class Extractions extends APIResource {
   /**
@@ -66,6 +66,7 @@ export class Extractions extends APIResource {
    * ```ts
    * const response = await client.extractions.exportResults(
    *   'id',
+   *   { format: 'csv' },
    * );
    *
    * const content = await response.blob();
@@ -74,7 +75,7 @@ export class Extractions extends APIResource {
    */
   exportResults(
     id: string,
-    query: ExtractionExportResultsParams | null | undefined = {},
+    query: ExtractionExportResultsParams,
     options?: RequestOptions,
   ): APIPromise<Response> {
     return this._client.get(path`/extractions/${id}/export`, {
@@ -120,6 +121,7 @@ export interface ExtractionJob {
     | 'community_moderator_explorer'
     | 'community_post_extractor'
     | 'community_search'
+    | 'favoriters'
     | 'follower_explorer'
     | 'following_explorer'
     | 'list_follower_explorer'
@@ -134,6 +136,8 @@ export interface ExtractionJob {
     | 'space_explorer'
     | 'thread_extractor'
     | 'tweet_search_extractor'
+    | 'user_likes'
+    | 'user_media'
     | 'verified_follower_explorer';
 
   totalResults: number;
@@ -145,7 +149,7 @@ export interface ExtractionRetrieveResponse {
   hasMore: boolean;
 
   /**
-   * Extraction job metadata — shape varies by tool type (JSON)
+   * Extraction job metadata - shape varies by tool type (JSON)
    */
   job: { [key: string]: unknown };
 
@@ -171,7 +175,16 @@ export interface ExtractionEstimateCostResponse {
 
   estimatedResults: number;
 
-  source: string;
+  source:
+    | 'followers'
+    | 'following'
+    | 'paginationCap'
+    | 'posts'
+    | 'quoteCount'
+    | 'replyCount'
+    | 'resultsLimit'
+    | 'retweetCount'
+    | 'unknown';
 
   resolvedXUserId?: string;
 }
@@ -190,6 +203,7 @@ export interface ExtractionRunResponse {
     | 'community_moderator_explorer'
     | 'community_post_extractor'
     | 'community_search'
+    | 'favoriters'
     | 'follower_explorer'
     | 'following_explorer'
     | 'list_follower_explorer'
@@ -204,14 +218,16 @@ export interface ExtractionRunResponse {
     | 'space_explorer'
     | 'thread_extractor'
     | 'tweet_search_extractor'
+    | 'user_likes'
+    | 'user_media'
     | 'verified_follower_explorer';
 }
 
 export interface ExtractionRetrieveParams {
   /**
-   * Cursor for keyset pagination
+   * Cursor for keyset pagination from prior response next_cursor
    */
-  after?: string;
+  cursor?: string;
 
   /**
    * Maximum number of results to return (1-1000, default 100)
@@ -221,12 +237,15 @@ export interface ExtractionRetrieveParams {
 
 export interface ExtractionListParams {
   /**
-   * Cursor for keyset pagination
+   * Cursor for keyset pagination from prior response next_cursor
    */
-  after?: string;
+  cursor?: string;
 
   /**
-   * Maximum number of items to return (1-100, default 50)
+   * Maximum number of items to return (1-100, default 50). For paid per-result
+   * endpoints, the returned count may be lower when available usage balance cannot cover
+   * the requested page. If zero paid results are affordable, the endpoint returns
+   * 402 insufficient_credits.
    */
   limit?: number;
 
@@ -244,6 +263,7 @@ export interface ExtractionListParams {
     | 'community_moderator_explorer'
     | 'community_post_extractor'
     | 'community_search'
+    | 'favoriters'
     | 'follower_explorer'
     | 'following_explorer'
     | 'list_follower_explorer'
@@ -258,6 +278,8 @@ export interface ExtractionListParams {
     | 'space_explorer'
     | 'thread_extractor'
     | 'tweet_search_extractor'
+    | 'user_likes'
+    | 'user_media'
     | 'verified_follower_explorer';
 }
 
@@ -271,6 +293,7 @@ export interface ExtractionEstimateCostParams {
     | 'community_moderator_explorer'
     | 'community_post_extractor'
     | 'community_search'
+    | 'favoriters'
     | 'follower_explorer'
     | 'following_explorer'
     | 'list_follower_explorer'
@@ -285,6 +308,8 @@ export interface ExtractionEstimateCostParams {
     | 'space_explorer'
     | 'thread_extractor'
     | 'tweet_search_extractor'
+    | 'user_likes'
+    | 'user_media'
     | 'verified_follower_explorer';
 
   /**
@@ -292,34 +317,197 @@ export interface ExtractionEstimateCostParams {
    */
   advancedQuery?: string;
 
+  /**
+   * Alternative words or quoted phrases for estimated results. Separate with spaces,
+   * commas, or lines.
+   */
+  anyWords?: string;
+
+  /**
+   * Geo bounding box used for estimation, e.g. -74.1 40.6 -73.9 40.8
+   * (tweet_search_extractor)
+   */
+  boundingBox?: string;
+
+  /**
+   * Cashtags applied to the estimate, separated by spaces, commas, or lines.
+   */
+  cashtags?: string;
+
+  /**
+   * Conversation ID filter used for estimation (tweet_search_extractor)
+   */
+  conversationId?: string;
+
   /**
    * Exact phrase filter for search estimation
    */
   exactPhrase?: string;
 
   /**
-   * Words excluded from estimated search results
+   * Words or quoted phrases excluded from estimated results. Separate with spaces,
+   * commas, or lines.
    */
   excludeWords?: string;
 
+  /**
+   * Estimate only tweets from this author username (tweet_search_extractor)
+   */
+  fromUser?: string;
+
+  /**
+   * Hashtags applied to the estimate, separated by spaces, commas, or lines.
+   */
+  hashtags?: string;
+
+  /**
+   * Estimate only replies to this tweet ID (tweet_search_extractor)
+   */
+  inReplyToTweetId?: string;
+
+  /**
+   * Language code used for estimate filtering (tweet_search_extractor)
+   */
+  language?: string;
+
+  /**
+   * Estimate search results within this list ID (tweet_search_extractor)
+   */
+  listId?: string;
+
+  /**
+   * Media type used for estimate filtering (tweet_search_extractor)
+   */
+  mediaType?: 'images' | 'videos' | 'gifs' | 'media' | 'links' | 'none';
+
+  /**
+   * Estimate tweets mentioning this username (tweet_search_extractor)
+   */
+  mentioning?: string;
+
+  /**
+   * Minimum likes threshold for estimated results (tweet_search_extractor)
+   */
+  minFaves?: number;
+
+  /**
+   * Minimum quote count threshold for estimated results (tweet_search_extractor)
+   */
+  minQuotes?: number;
+
+  /**
+   * Minimum replies threshold for estimated results (tweet_search_extractor)
+   */
+  minReplies?: number;
+
+  /**
+   * Minimum retweets threshold for estimated results (tweet_search_extractor)
+   */
+  minRetweets?: number;
+
+  /**
+   * Estimate search results within this place ID (tweet_search_extractor)
+   */
+  place?: string;
+
+  /**
+   * Estimate search results within this country code (tweet_search_extractor)
+   */
+  placeCountry?: string;
+
+  /**
+   * Geo point radius used for estimation, e.g. -73.99 40.73 25mi
+   * (tweet_search_extractor)
+   */
+  pointRadius?: string;
+
+  /**
+   * Quote mode used for estimation (tweet_search_extractor)
+   */
+  quotes?: 'include' | 'exclude' | 'only';
+
+  /**
+   * Estimate only quotes of this tweet ID (tweet_search_extractor)
+   */
+  quotesOfTweetId?: string;
+
+  /**
+   * Reply mode used for estimation (tweet_search_extractor)
+   */
+  replies?: 'include' | 'exclude' | 'only';
+
+  /**
+   * Maximum number of results to estimate. When set, the estimate caps projected
+   * results to this value.
+   */
+  resultsLimit?: number;
+
+  /**
+   * Retweet mode used for estimation (tweet_search_extractor)
+   */
+  retweets?: 'include' | 'exclude' | 'only';
+
+  /**
+   * Estimate only retweets of this tweet ID (tweet_search_extractor)
+   */
+  retweetsOfTweetId?: string;
+
+  /**
+   * Required for tweet_search_extractor & community_search.
+   */
   searchQuery?: string;
 
+  /**
+   * Estimate start date in YYYY-MM-DD format (tweet_search_extractor)
+   */
+  sinceDate?: string;
+
+  /**
+   * Required for community_post_extractor & community_search.
+   */
   targetCommunityId?: string;
 
+  /**
+   * Required for list_follower_explorer, list_member_extractor &
+   * list_post_extractor.
+   */
   targetListId?: string;
 
+  /**
+   * Required for space_explorer.
+   */
   targetSpaceId?: string;
 
   targetTweetId?: string;
 
   targetUsername?: string;
+
+  /**
+   * Estimate replies sent to this username (tweet_search_extractor)
+   */
+  toUser?: string;
+
+  /**
+   * Estimate end date in YYYY-MM-DD format (tweet_search_extractor)
+   */
+  untilDate?: string;
+
+  /**
+   * URL substring or domain filter used for estimation (tweet_search_extractor)
+   */
+  url?: string;
+
+  /**
+   * Estimate only verified authors (tweet_search_extractor)
+   */
+  verifiedOnly?: boolean;
 }
 
 export interface ExtractionExportResultsParams {
   /**
    * Export file format
    */
-  format?: 'csv' | 'json' | 'md' | 'md-document' | 'pdf' | 'txt' | 'xlsx';
+  format: 'csv' | 'json' | 'md' | 'md-document' | 'pdf' | 'txt' | 'xlsx';
 }
 
 export interface ExtractionRunParams {
@@ -332,6 +520,7 @@ export interface ExtractionRunParams {
     | 'community_moderator_explorer'
     | 'community_post_extractor'
     | 'community_search'
+    | 'favoriters'
     | 'follower_explorer'
     | 'following_explorer'
     | 'list_follower_explorer'
@@ -346,6 +535,8 @@ export interface ExtractionRunParams {
     | 'space_explorer'
     | 'thread_extractor'
     | 'tweet_search_extractor'
+    | 'user_likes'
+    | 'user_media'
     | 'verified_follower_explorer';
 
   /**
@@ -353,27 +544,188 @@ export interface ExtractionRunParams {
    */
   advancedQuery?: string;
 
+  /**
+   * Words or quoted phrases where any one can match. Separate with spaces, commas,
+   * or lines. (tweet_search_extractor)
+   */
+  anyWords?: string;
+
+  /**
+   * Geo bounding box, e.g. -74.1 40.6 -73.9 40.8 (tweet_search_extractor)
+   */
+  boundingBox?: string;
+
+  /**
+   * Cashtags separated by spaces, commas, or lines. (tweet_search_extractor)
+   */
+  cashtags?: string;
+
+  /**
+   * Conversation ID filter (tweet_search_extractor)
+   */
+  conversationId?: string;
+
   /**
    * Exact phrase to match (tweet_search_extractor)
    */
   exactPhrase?: string;
 
   /**
-   * Words to exclude from results (tweet_search_extractor)
+   * Words or quoted phrases to exclude. Separate with spaces, commas, or lines.
+   * (tweet_search_extractor)
    */
   excludeWords?: string;
 
+  /**
+   * Filter by author username (tweet_search_extractor)
+   */
+  fromUser?: string;
+
+  /**
+   * Hashtags separated by spaces, commas, or lines. (tweet_search_extractor)
+   */
+  hashtags?: string;
+
+  /**
+   * Only replies to this tweet ID (tweet_search_extractor)
+   */
+  inReplyToTweetId?: string;
+
+  /**
+   * Language code filter (tweet_search_extractor)
+   */
+  language?: string;
+
+  /**
+   * Search within a list ID (tweet_search_extractor)
+   */
+  listId?: string;
+
+  /**
+   * Media type filter (tweet_search_extractor)
+   */
+  mediaType?: 'images' | 'videos' | 'gifs' | 'media' | 'links' | 'none';
+
+  /**
+   * Filter tweets mentioning a username (tweet_search_extractor)
+   */
+  mentioning?: string;
+
+  /**
+   * Minimum likes threshold (tweet_search_extractor)
+   */
+  minFaves?: number;
+
+  /**
+   * Minimum quote count threshold (tweet_search_extractor)
+   */
+  minQuotes?: number;
+
+  /**
+   * Minimum replies threshold (tweet_search_extractor)
+   */
+  minReplies?: number;
+
+  /**
+   * Minimum retweets threshold (tweet_search_extractor)
+   */
+  minRetweets?: number;
+
+  /**
+   * Search within a place ID (tweet_search_extractor)
+   */
+  place?: string;
+
+  /**
+   * Search within a country code (tweet_search_extractor)
+   */
+  placeCountry?: string;
+
+  /**
+   * Geo point radius, e.g. -73.99 40.73 25mi (tweet_search_extractor)
+   */
+  pointRadius?: string;
+
+  /**
+   * Quote mode (tweet_search_extractor)
+   */
+  quotes?: 'include' | 'exclude' | 'only';
+
+  /**
+   * Only quotes of this tweet ID (tweet_search_extractor)
+   */
+  quotesOfTweetId?: string;
+
+  /**
+   * Reply mode (tweet_search_extractor)
+   */
+  replies?: 'include' | 'exclude' | 'only';
+
+  /**
+   * Maximum number of results to extract. When set, the extraction stops after
+   * reaching this limit.
+   */
+  resultsLimit?: number;
+
+  /**
+   * Retweet mode (tweet_search_extractor)
+   */
+  retweets?: 'include' | 'exclude' | 'only';
+
+  /**
+   * Only retweets of this tweet ID (tweet_search_extractor)
+   */
+  retweetsOfTweetId?: string;
+
+  /**
+   * Required for tweet_search_extractor & community_search.
+   */
   searchQuery?: string;
 
+  /**
+   * Start date YYYY-MM-DD (tweet_search_extractor)
+   */
+  sinceDate?: string;
+
+  /**
+   * Required for community_post_extractor & community_search.
+   */
   targetCommunityId?: string;
 
+  /**
+   * Required for list_follower_explorer, list_member_extractor &
+   * list_post_extractor.
+   */
   targetListId?: string;
 
+  /**
+   * Required for space_explorer.
+   */
   targetSpaceId?: string;
 
   targetTweetId?: string;
 
   targetUsername?: string;
+
+  /**
+   * Filter replies sent to a username (tweet_search_extractor)
+   */
+  toUser?: string;
+
+  /**
+   * End date YYYY-MM-DD (tweet_search_extractor)
+   */
+  untilDate?: string;
+
+  /**
+   * URL substring or domain filter (tweet_search_extractor)
+   */
+  url?: string;
+
+  /**
+   * Only verified authors (tweet_search_extractor)
+   */
+  verifiedOnly?: boolean;
 }
 
 export declare namespace Extractions {