x-twitter-scraper 0.12.3 → 0.13.0

package/src/resources/guest-wallets.ts

@@ -41,7 +41,8 @@ export class GuestWallets extends APIResource {
   /**
    * Poll after payment. Use usable to decide whether paid reads can run. An active
    * wallet can remain usable while a top-up is pending. A new wallet becomes usable
-   * only after payment is verified. Send the guest key as Authorization: Bearer.
+   * only after payment is verified. Send the guest key as Authorization: Bearer
+   * xq_...
    *
    * @example
    * ```ts
@@ -119,7 +120,7 @@ export interface GuestWalletCreateResponse {
   credential_notice: 'Store api_key and the Idempotency-Key securely before sharing checkout_url. No email recovery is available.';
 
   /**
-   * Usage granted after verified payment.
+   * Credits granted after verified payment.
    */
   credits: string;
 
@@ -164,7 +165,7 @@ export interface GuestWalletRetrieveStatusResponse {
   balance: string;
 
   /**
-   * Latest guest wallet purchase fulfillment state.
+   * Latest purchase state. This does not determine usability.
    */
   latest_purchase: GuestWalletRetrieveStatusResponse.LatestPurchase | null;
 
@@ -229,7 +230,7 @@ export namespace GuestWalletRetrieveStatusResponse {
 }
 
 /**
- * Pending hosted checkout and guest wallet purchase details.
+ * Existing guest wallet top-up response without a new key.
  */
 export interface GuestWalletTopupResponse {
   account_required: false;
@@ -245,7 +246,7 @@ export interface GuestWalletTopupResponse {
   checkout_url: string;
 
   /**
-   * Usage granted after verified payment.
+   * Credits granted after verified payment.
    */
   credits: string;
 

package/src/resources/index.ts

@@ -43,12 +43,20 @@ export {
   type DrawExportParams,
   type DrawRunParams,
 } from './draws';
-export { Events, type Event, type EventDetail, type EventListResponse, type EventListParams } from './events';
+export {
+  Events,
+  type Event,
+  type EventDetail,
+  type EventListResponse,
+  type EventListParams,
+  type EventStreamParams,
+} from './events';
 export {
   Extractions,
   type ExtractionJob,
   type ExtractionRetrieveResponse,
   type ExtractionListResponse,
+  type ExtractionCancelResponse,
   type ExtractionEstimateCostResponse,
   type ExtractionRunResponse,
   type ExtractionRetrieveParams,
@@ -74,6 +82,7 @@ export {
   type MonitorDeactivateResponse,
   type MonitorCreateParams,
   type MonitorUpdateParams,
+  type MonitorListParams,
 } from './monitors/monitors';
 export {
   Radar,
@@ -89,6 +98,7 @@ export {
   type StyleCompareResponse,
   type StyleGetPerformanceResponse,
   type StyleUpdateParams,
+  type StyleListParams,
   type StyleAnalyzeParams,
   type StyleCompareParams,
 } from './styles';
@@ -101,19 +111,32 @@ export {
   type Webhook,
   type WebhookCreateResponse,
   type WebhookListResponse,
+  type WebhookCreateTelegramLinkResponse,
   type WebhookDeactivateResponse,
   type WebhookListDeliveriesResponse,
   type WebhookResumeResponse,
   type WebhookTestResponse,
   type WebhookCreateParams,
   type WebhookUpdateParams,
+  type WebhookListParams,
+  type WebhookCreateTelegramLinkParams,
+  type WebhookListDeliveriesParams,
 } from './webhooks';
 export {
   X,
+  type XAutocompleteSearchResponse,
   type XGetArticleResponse,
+  type XGetHashflagsResponse,
   type XGetNotificationsResponse,
+  type XGetTrendLocationsResponse,
   type XGetTrendsResponse,
+  type XSearchPlacesResponse,
+  type XAutocompleteSearchParams,
+  type XGetArticleParams,
+  type XGetHashflagsParams,
   type XGetHomeTimelineParams,
   type XGetNotificationsParams,
+  type XGetTrendLocationsParams,
   type XGetTrendsParams,
+  type XSearchPlacesParams,
 } from './x/x';

package/src/resources/monitors/index.ts

@@ -13,6 +13,7 @@ export {
   type KeywordDeactivateResponse,
   type KeywordCreateParams,
   type KeywordUpdateParams,
+  type KeywordListParams,
 } from './keywords';
 export {
   Monitors,
@@ -22,4 +23,5 @@ export {
   type MonitorDeactivateResponse,
   type MonitorCreateParams,
   type MonitorUpdateParams,
+  type MonitorListParams,
 } from './monitors';

package/src/resources/monitors/keywords.ts

@@ -15,15 +15,16 @@ import { path } from '../../internal/utils/path';
  */
 export class Keywords extends APIResource {
   /**
-   * Creates a keyword monitor. Keyword monitors are unlimited. Active monitors check
-   * every 1 second and cost 21 credits per hour. Events and webhook deliveries are
-   * included. Creation requires available credits for the first hourly charge.
+   * Creates a keyword monitor, with no count limit. Active monitors check every
+   * second for 30 credits an hour, events & webhook deliveries included. That hourly
+   * price is a monitor's only charge. Creation needs the credits of the first hour.
    *
    * @example
    * ```ts
    * const keyword = await client.monitors.keywords.create({
    *   eventTypes: ['tweet.new'],
    *   query: 'xquik OR "x api"',
+   *   name: 'Launch mentions',
    * });
    * ```
    */
@@ -32,7 +33,7 @@ export class Keywords extends APIResource {
   }
 
   /**
-   * Get keyword monitor
+   * Returns configuration and status for one keyword monitor.
    *
    * @example
    * ```ts
@@ -46,13 +47,17 @@ export class Keywords extends APIResource {
   }
 
   /**
-   * Update keyword monitor
+   * Updates mutable settings for an existing keyword monitor.
    *
    * @example
    * ```ts
    * const keyword = await client.monitors.keywords.update(
    *   'id',
-   *   { eventTypes: ['tweet.new'], isActive: true },
+   *   {
+   *     eventTypes: ['tweet.new'],
+   *     isActive: true,
+   *     name: 'Launch mentions',
+   *   },
    * );
    * ```
    */
@@ -61,19 +66,23 @@ export class Keywords extends APIResource {
   }
 
   /**
-   * List keyword monitors
+   * Returns keyword monitors with their current operating states.
    *
    * @example
    * ```ts
    * const keywords = await client.monitors.keywords.list();
    * ```
    */
-  list(options?: RequestOptions): APIPromise<KeywordListResponse> {
-    return this._client.get('/monitors/keywords', options);
+  list(
+    query: KeywordListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<KeywordListResponse> {
+    return this._client.get('/monitors/keywords', { query, ...options });
   }
 
   /**
-   * Delete keyword monitor
+   * Stops one keyword monitor, then removes its stored events in bounded batches.
+   * Poll statusUrl until the monitor returns 404.
    *
    * @example
    * ```ts
@@ -103,11 +112,16 @@ export interface KeywordCreateResponse {
   isActive: boolean;
 
   /**
-   * Next hourly usage charge time for this keyword query monitor.
+   * Next hourly credit charge time for this keyword query monitor.
    */
   nextBillingAt: string;
 
   query: string;
+
+  /**
+   * Customer-set label of the keyword monitor, when set.
+   */
+  name?: string;
 }
 
 /**
@@ -126,11 +140,16 @@ export interface KeywordRetrieveResponse {
   isActive: boolean;
 
   /**
-   * Next hourly usage charge time for this keyword query monitor.
+   * Next hourly credit charge time for this keyword query monitor.
    */
   nextBillingAt: string;
 
   query: string;
+
+  /**
+   * Customer-set label of the keyword monitor, when set.
+   */
+  name?: string;
 }
 
 /**
@@ -149,17 +168,29 @@ export interface KeywordUpdateResponse {
   isActive: boolean;
 
   /**
-   * Next hourly usage charge time for this keyword query monitor.
+   * Next hourly credit charge time for this keyword query monitor.
    */
   nextBillingAt: string;
 
   query: string;
+
+  /**
+   * Customer-set label of the keyword monitor, when set.
+   */
+  name?: string;
 }
 
 export interface KeywordListResponse {
+  hasMore: boolean;
+
   monitors: Array<KeywordListResponse.Monitor>;
 
+  /**
+   * Keyword monitors on this page.
+   */
   total: number;
+
+  nextCursor?: string;
 }
 
 export namespace KeywordListResponse {
@@ -179,15 +210,27 @@ export namespace KeywordListResponse {
     isActive: boolean;
 
     /**
-     * Next hourly usage charge time for this keyword query monitor.
+     * Next hourly credit charge time for this keyword query monitor.
      */
     nextBillingAt: string;
 
     query: string;
+
+    /**
+     * Customer-set label of the keyword monitor, when set.
+     */
+    name?: string;
   }
 }
 
 export interface KeywordDeactivateResponse {
+  deletionStatus: 'deleting';
+
+  /**
+   * Poll this monitor URL until it returns 404.
+   */
+  statusUrl: string;
+
   success: true;
 }
 
@@ -201,6 +244,11 @@ export interface KeywordCreateParams {
    * X search query to monitor. Whitespace is normalized.
    */
   query: string;
+
+  /**
+   * Your own label for the keyword monitor. Its events carry it as monitorName.
+   */
+  name?: string;
 }
 
 export interface KeywordUpdateParams {
@@ -210,6 +258,25 @@ export interface KeywordUpdateParams {
   eventTypes?: Array<Shared.EventType>;
 
   isActive?: boolean;
+
+  /**
+   * New label for the keyword monitor. Send null to remove it.
+   */
+  name?: string | null;
+}
+
+export interface KeywordListParams {
+  /**
+   * Previous nextCursor. The after alias also works. Offset pagination is not
+   * supported.
+   */
+  cursor?: string;
+
+  /**
+   * Maximum items per page: 1 to 200, default 200. Pass nextCursor as cursor for the
+   * next page.
+   */
+  limit?: number;
 }
 
 export declare namespace Keywords {
@@ -221,5 +288,6 @@ export declare namespace Keywords {
     type KeywordDeactivateResponse as KeywordDeactivateResponse,
     type KeywordCreateParams as KeywordCreateParams,
     type KeywordUpdateParams as KeywordUpdateParams,
+    type KeywordListParams as KeywordListParams,
   };
 }

package/src/resources/monitors/monitors.ts

@@ -11,6 +11,7 @@ import {
   KeywordCreateParams,
   KeywordCreateResponse,
   KeywordDeactivateResponse,
+  KeywordListParams,
   KeywordListResponse,
   KeywordRetrieveResponse,
   KeywordUpdateParams,
@@ -28,16 +29,16 @@ export class Monitors extends APIResource {
   keywords: KeywordsAPI.Keywords = new KeywordsAPI.Keywords(this._client);
 
   /**
-   * Creates an account monitor. Monitors are unlimited. Active monitors check every
-   * 1 second and cost 21 credits per hour. Events and webhook deliveries are
-   * included. Creation requires available credits for the first hourly charge and
-   * username lookup.
+   * Creates an account monitor, with no count limit. Active monitors check every
+   * second for 30 credits an hour, events & webhook deliveries included. That hourly
+   * price is a monitor's only charge. Creation needs the credits of the first hour.
    *
    * @example
    * ```ts
    * const monitor = await client.monitors.create({
    *   eventTypes: ['tweet.new', 'tweet.reply'],
    *   username: 'elonmusk',
+   *   name: 'Launch watch',
    * });
    * ```
    */
@@ -46,7 +47,7 @@ export class Monitors extends APIResource {
   }
 
   /**
-   * Get monitor
+   * Returns configuration and status for one account monitor.
    *
    * @example
    * ```ts
@@ -58,13 +59,14 @@ export class Monitors extends APIResource {
   }
 
   /**
-   * Update monitor
+   * Updates mutable settings for an existing account monitor.
    *
    * @example
    * ```ts
    * const monitor = await client.monitors.update('id', {
    *   eventTypes: ['tweet.new'],
    *   isActive: true,
+   *   name: 'Launch watch',
    * });
    * ```
    */
@@ -73,19 +75,23 @@ export class Monitors extends APIResource {
   }
 
   /**
-   * List monitors
+   * Returns account monitors with their current operating states.
    *
    * @example
    * ```ts
    * const monitors = await client.monitors.list();
    * ```
    */
-  list(options?: RequestOptions): APIPromise<MonitorListResponse> {
-    return this._client.get('/monitors', options);
+  list(
+    query: MonitorListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<MonitorListResponse> {
+    return this._client.get('/monitors', { query, ...options });
   }
 
   /**
-   * Delete monitor
+   * Stops one account monitor, then removes its stored events in bounded batches.
+   * Poll statusUrl until the monitor returns 404.
    *
    * @example
    * ```ts
@@ -113,7 +119,7 @@ export interface Monitor {
   isActive: boolean;
 
   /**
-   * Next hourly usage charge time for this account monitor.
+   * Next hourly credit charge time for this account monitor.
    */
   nextBillingAt: string;
 
@@ -121,6 +127,11 @@ export interface Monitor {
 
   xUserId: string;
 
+  /**
+   * Customer-set label of the account monitor, when set.
+   */
+  name?: string;
+
   /**
    * When Xquik automatically paused this monitor.
    */
@@ -129,7 +140,7 @@ export interface Monitor {
   /**
    * Why Xquik automatically paused this monitor.
    */
-  pausedReason?: 'x_user_not_found';
+  pausedReason?: 'x_account_protected' | 'x_user_not_found';
 }
 
 export interface MonitorCreateResponse {
@@ -145,7 +156,7 @@ export interface MonitorCreateResponse {
   isActive: boolean;
 
   /**
-   * Next hourly usage charge time. New active monitors are due immediately.
+   * Next hourly credit charge time. New active monitors are due immediately.
    */
   nextBillingAt: string;
 
@@ -155,12 +166,26 @@ export interface MonitorCreateResponse {
 }
 
 export interface MonitorListResponse {
+  hasMore: boolean;
+
   monitors: Array<Monitor>;
 
+  /**
+   * Account monitors on this page.
+   */
   total: number;
+
+  nextCursor?: string;
 }
 
 export interface MonitorDeactivateResponse {
+  deletionStatus: 'deleting';
+
+  /**
+   * Poll this monitor URL until it returns 404.
+   */
+  statusUrl: string;
+
   success: true;
 }
 
@@ -171,9 +196,15 @@ export interface MonitorCreateParams {
   eventTypes: Array<Shared.EventType>;
 
   /**
-   * X username (without @)
+   * X username to monitor, with or without @
    */
   username: string;
+
+  /**
+   * Your label for the monitor. Its events carry it as monitorName. Whitespace is
+   * normalized.
+   */
+  name?: string;
 }
 
 export interface MonitorUpdateParams {
@@ -183,6 +214,25 @@ export interface MonitorUpdateParams {
   eventTypes?: Array<Shared.EventType>;
 
   isActive?: boolean;
+
+  /**
+   * New label for the account monitor. Send null to remove the label.
+   */
+  name?: string | null;
+}
+
+export interface MonitorListParams {
+  /**
+   * Previous nextCursor. The after alias also works. Offset pagination is not
+   * supported.
+   */
+  cursor?: string;
+
+  /**
+   * Maximum items per page: 1 to 200, default 200. Pass nextCursor as cursor for the
+   * next page.
+   */
+  limit?: number;
 }
 
 Monitors.Keywords = Keywords;
@@ -195,6 +245,7 @@ export declare namespace Monitors {
     type MonitorDeactivateResponse as MonitorDeactivateResponse,
     type MonitorCreateParams as MonitorCreateParams,
     type MonitorUpdateParams as MonitorUpdateParams,
+    type MonitorListParams as MonitorListParams,
   };
 
   export {
@@ -206,5 +257,6 @@ export declare namespace Monitors {
     type KeywordDeactivateResponse as KeywordDeactivateResponse,
     type KeywordCreateParams as KeywordCreateParams,
     type KeywordUpdateParams as KeywordUpdateParams,
+    type KeywordListParams as KeywordListParams,
   };
 }

package/src/resources/radar.ts

@@ -13,7 +13,7 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class Radar extends APIResource {
   /**
-   * Get trending topics from curated sources
+   * Returns current topics and sources for writing research.
    */
   retrieveTrendingTopics(
     query: RadarRetrieveTrendingTopicsParams | null | undefined = {},
@@ -43,33 +43,26 @@ export interface RadarItem {
   language: string;
 
   /**
-   * Source-specific fields. Shape varies per source:
-   *
+   * Source fields vary:
    * - reddit: { author, authorId?, subreddit, subredditId?, subredditSubscribers?,
    *   sourceFormat, score?, upvoteRatio?, estimatedUpvotes?, estimatedDownvotes?,
    *   numberComments?, numberCrossposts?, selftext?, contentUrl?, domain?,
    *   postHint?, linkFlairText?, distinguished?, totalAwardsReceived?, viewCount?,
    *   editedAt?, galleryImageUrls?, redditVideo?, archived?, contestMode?,
    *   isCrosspostable?, isMeta?, isNsfw?, isOriginalContent?, isRobotIndexable?,
-   *   isSelf?, isSpoiler?, isVideo?, locked?, stickied? }. `score` is Reddit's
-   *   public net score. Exact public upvote and downvote counts are not available.
-   *   Estimated counts derive from the public score and upvote ratio, which Reddit
-   *   may fuzz. Comment bodies are not included. Current items combine public
-   *   listing discovery with server-rendered post data and use `sourceFormat: html`;
-   *   `json` and `rss` remain for legacy rows.
-   * - github: { starsToday: number }
-   * - hacker_news: { points: number, numberComments: number }
-   * - google_trends: { approxTraffic: number }
-   * - polymarket: { volume24hr: number }
-   * - wikipedia: { views: number }
+   *   isSelf?, isSpoiler?, isVideo?, locked?, stickied? }.
+   * - github: { starsToday }
+   * - hacker_news: { points, numberComments }
+   * - google_trends: { approxTraffic }
+   * - polymarket: { volume24hr }
+   * - wikipedia: { views }
    * - trustmrr: { mrr, growthPercent, last30Days, total, customers,
    *   activeSubscriptions, onSale, xHandle?, category?, askingPrice?, country?,
    *   foundedDate?, googleSearchImpressionsLast30Days?, growthMrrPercent?,
    *   multiple?, paymentProvider?, profitMarginLast30Days?, rank?,
-   *   revenuePerVisitor?, targetAudience?, visitorsLast30Days? } For the startup
-   *   growth source, xHandle is the founder's X username without @. The rank field
-   *   is the source's revenue rank. Result order represents reported 30-day
-   *   revenue-growth rank.
+   *   revenuePerVisitor?, targetAudience?, visitorsLast30Days? } Reddit score is
+   *   public net. Vote estimates use its fuzzed ratio. Comments are omitted. Startup
+   *   xHandle omits @. rank is its growth rank.
    */
   metadata: RadarItem.Metadata;
 
@@ -100,43 +93,45 @@ export interface RadarItem {
 
 export namespace RadarItem {
   /**
-   * Source-specific fields. Shape varies per source:
-   *
+   * Source fields vary:
    * - reddit: { author, authorId?, subreddit, subredditId?, subredditSubscribers?,
    *   sourceFormat, score?, upvoteRatio?, estimatedUpvotes?, estimatedDownvotes?,
    *   numberComments?, numberCrossposts?, selftext?, contentUrl?, domain?,
    *   postHint?, linkFlairText?, distinguished?, totalAwardsReceived?, viewCount?,
    *   editedAt?, galleryImageUrls?, redditVideo?, archived?, contestMode?,
    *   isCrosspostable?, isMeta?, isNsfw?, isOriginalContent?, isRobotIndexable?,
-   *   isSelf?, isSpoiler?, isVideo?, locked?, stickied? }. `score` is Reddit's
-   *   public net score. Exact public upvote and downvote counts are not available.
-   *   Estimated counts derive from the public score and upvote ratio, which Reddit
-   *   may fuzz. Comment bodies are not included. Current items combine public
-   *   listing discovery with server-rendered post data and use `sourceFormat: html`;
-   *   `json` and `rss` remain for legacy rows.
-   * - github: { starsToday: number }
-   * - hacker_news: { points: number, numberComments: number }
-   * - google_trends: { approxTraffic: number }
-   * - polymarket: { volume24hr: number }
-   * - wikipedia: { views: number }
+   *   isSelf?, isSpoiler?, isVideo?, locked?, stickied? }.
+   * - github: { starsToday }
+   * - hacker_news: { points, numberComments }
+   * - google_trends: { approxTraffic }
+   * - polymarket: { volume24hr }
+   * - wikipedia: { views }
    * - trustmrr: { mrr, growthPercent, last30Days, total, customers,
    *   activeSubscriptions, onSale, xHandle?, category?, askingPrice?, country?,
    *   foundedDate?, googleSearchImpressionsLast30Days?, growthMrrPercent?,
    *   multiple?, paymentProvider?, profitMarginLast30Days?, rank?,
-   *   revenuePerVisitor?, targetAudience?, visitorsLast30Days? } For the startup
-   *   growth source, xHandle is the founder's X username without @. The rank field
-   *   is the source's revenue rank. Result order represents reported 30-day
-   *   revenue-growth rank.
+   *   revenuePerVisitor?, targetAudience?, visitorsLast30Days? } Reddit score is
+   *   public net. Vote estimates use its fuzzed ratio. Comments are omitted. Startup
+   *   xHandle omits @. rank is its growth rank.
    */
   export interface Metadata {
     author?: string;
 
     contentUrl?: string;
 
+    /**
+     * Whole number from 0.
+     */
     estimatedDownvotes?: number;
 
+    /**
+     * Whole number from 0.
+     */
     estimatedUpvotes?: number;
 
+    /**
+     * Whole number from 0.
+     */
     numberComments?: number;
 
     score?: number;
@@ -169,7 +164,8 @@ export interface RadarRetrieveTrendingTopicsResponse {
 
 export interface RadarRetrieveTrendingTopicsParams {
   /**
-   * Cursor for pagination (from prior response nextCursor).
+   * Cursor for pagination, from the prior response's nextCursor. A cursor the radar
+   * can't read gets 400 `invalid_input`.
    */
   after?: string;