x-twitter-scraper 0.1.0 → 0.2.0

package/src/resources/events.ts

@@ -28,6 +28,9 @@ export class Events extends APIResource {
   }
 }
 
+/**
+ * Monitor event summary with type, username, and occurrence time.
+ */
 export interface Event {
   id: string;
 
@@ -37,20 +40,32 @@ export interface Event {
 
   occurredAt: string;
 
+  /**
+   * Type of monitor event fired when account activity occurs.
+   */
   type: Shared.EventType;
 
   username: string;
 }
 
+/**
+ * Full monitor event including payload data and optional X event ID.
+ */
 export interface EventDetail {
   id: string;
 
+  /**
+   * Event payload — shape varies by event type (JSON)
+   */
   data: { [key: string]: unknown };
 
   monitorId: string;
 
   occurredAt: string;
 
+  /**
+   * Type of monitor event fired when account activity occurs.
+   */
   type: Shared.EventType;
 
   username: string;
@@ -68,14 +83,23 @@ export interface EventListResponse {
 
 export interface EventListParams {
   /**
-   * Cursor for pagination
+   * Cursor for keyset pagination
    */
   after?: string;
 
+  /**
+   * Filter events by type
+   */
   eventType?: Shared.EventType;
 
+  /**
+   * Maximum number of items to return (1-100, default 50)
+   */
   limit?: number;
 
+  /**
+   * Filter events by monitor ID
+   */
   monitorId?: string;
 }
 

package/src/resources/extractions.ts

@@ -12,6 +12,11 @@ import { path } from '../internal/utils/path';
 export class Extractions extends APIResource {
   /**
    * Get extraction results
+   *
+   * @example
+   * ```ts
+   * const extraction = await client.extractions.retrieve('id');
+   * ```
    */
   retrieve(
     id: string,
@@ -23,6 +28,11 @@ export class Extractions extends APIResource {
 
   /**
    * List extraction jobs
+   *
+   * @example
+   * ```ts
+   * const extractions = await client.extractions.list();
+   * ```
    */
   list(
     query: ExtractionListParams | null | undefined = {},
@@ -33,6 +43,14 @@ export class Extractions extends APIResource {
 
   /**
    * Estimate extraction cost
+   *
+   * @example
+   * ```ts
+   * const response = await client.extractions.estimateCost({
+   *   toolType: 'follower_explorer',
+   *   targetUsername: 'elonmusk',
+   * });
+   * ```
    */
   estimateCost(
     body: ExtractionEstimateCostParams,
@@ -43,6 +61,16 @@ export class Extractions extends APIResource {
 
   /**
    * Export extraction results
+   *
+   * @example
+   * ```ts
+   * const response = await client.extractions.exportResults(
+   *   'id',
+   * );
+   *
+   * const content = await response.blob();
+   * console.log(content);
+   * ```
    */
   exportResults(
     id: string,
@@ -59,12 +87,23 @@ export class Extractions extends APIResource {
 
   /**
    * Run extraction
+   *
+   * @example
+   * ```ts
+   * const response = await client.extractions.run({
+   *   toolType: 'follower_explorer',
+   *   targetUsername: 'elonmusk',
+   * });
+   * ```
    */
   run(body: ExtractionRunParams, options?: RequestOptions): APIPromise<ExtractionRunResponse> {
     return this._client.post('/extractions', { body, ...options });
   }
 }
 
+/**
+ * Extraction job tracking status, tool type, and result count.
+ */
 export interface ExtractionJob {
   id: string;
 
@@ -72,6 +111,9 @@ export interface ExtractionJob {
 
   status: 'running' | 'completed' | 'failed';
 
+  /**
+   * Identifier for the extraction tool used to run a job.
+   */
   toolType:
     | 'article_extractor'
     | 'community_extractor'
@@ -102,6 +144,9 @@ export interface ExtractionJob {
 export interface ExtractionRetrieveResponse {
   hasMore: boolean;
 
+  /**
+   * Extraction job metadata — shape varies by tool type (JSON)
+   */
   job: { [key: string]: unknown };
 
   results: Array<{ [key: string]: unknown }>;
@@ -134,6 +179,9 @@ export interface ExtractionRunResponse {
 
   status: 'running';
 
+  /**
+   * Identifier for the extraction tool used to run a job.
+   */
   toolType:
     | 'article_extractor'
     | 'community_extractor'
@@ -159,23 +207,35 @@ export interface ExtractionRunResponse {
 
 export interface ExtractionRetrieveParams {
   /**
-   * Cursor for pagination
+   * Cursor for keyset pagination
    */
   after?: string;
 
+  /**
+   * Maximum number of results to return (1-1000, default 100)
+   */
   limit?: number;
 }
 
 export interface ExtractionListParams {
   /**
-   * Cursor for pagination
+   * Cursor for keyset pagination
    */
   after?: string;
 
+  /**
+   * Maximum number of items to return (1-100, default 50)
+   */
   limit?: number;
 
+  /**
+   * Filter by job status
+   */
   status?: 'running' | 'completed' | 'failed';
 
+  /**
+   * Filter by extraction tool type
+   */
   toolType?:
     | 'article_extractor'
     | 'community_extractor'
@@ -200,6 +260,9 @@ export interface ExtractionListParams {
 }
 
 export interface ExtractionEstimateCostParams {
+  /**
+   * Identifier for the extraction tool used to run a job.
+   */
   toolType:
     | 'article_extractor'
     | 'community_extractor'
@@ -223,17 +286,17 @@ export interface ExtractionEstimateCostParams {
     | 'verified_follower_explorer';
 
   /**
-   * Raw advanced search query appended as-is (tweet_search_extractor)
+   * Raw advanced query string appended to the estimate (tweet_search_extractor)
    */
   advancedQuery?: string;
 
   /**
-   * Exact phrase to match (tweet_search_extractor)
+   * Exact phrase filter for search estimation
    */
   exactPhrase?: string;
 
   /**
-   * Words to exclude from results (tweet_search_extractor)
+   * Words excluded from estimated search results
    */
   excludeWords?: string;
 
@@ -251,10 +314,16 @@ export interface ExtractionEstimateCostParams {
 }
 
 export interface ExtractionExportResultsParams {
+  /**
+   * Export file format
+   */
   format?: 'csv' | 'json' | 'md' | 'md-document' | 'pdf' | 'txt' | 'xlsx';
 }
 
 export interface ExtractionRunParams {
+  /**
+   * Identifier for the extraction tool used to run a job.
+   */
   toolType:
     | 'article_extractor'
     | 'community_extractor'

package/src/resources/index.ts

@@ -116,6 +116,7 @@ export {
   X,
   type XGetArticleResponse,
   type XGetNotificationsResponse,
+  type XGetTrendsResponse,
   type XGetHomeTimelineParams,
   type XGetNotificationsParams,
 } from './x/x';

package/src/resources/integrations.ts

@@ -12,6 +12,16 @@ import { path } from '../internal/utils/path';
 export class Integrations extends APIResource {
   /**
    * Create integration
+   *
+   * @example
+   * ```ts
+   * const integration = await client.integrations.create({
+   *   config: { chatId: '-1001234567890' },
+   *   eventTypes: ['tweet.new', 'follower.gained'],
+   *   name: 'My Telegram Bot',
+   *   type: 'telegram',
+   * });
+   * ```
    */
   create(body: IntegrationCreateParams, options?: RequestOptions): APIPromise<Integration> {
     return this._client.post('/integrations', { body, ...options });
@@ -19,6 +29,13 @@ export class Integrations extends APIResource {
 
   /**
    * Get integration details
+   *
+   * @example
+   * ```ts
+   * const integration = await client.integrations.retrieve(
+   *   'id',
+   * );
+   * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<Integration> {
     return this._client.get(path`/integrations/${id}`, options);
@@ -26,6 +43,14 @@ export class Integrations extends APIResource {
 
   /**
    * Update integration
+   *
+   * @example
+   * ```ts
+   * const integration = await client.integrations.update('id', {
+   *   isActive: true,
+   *   name: 'My Telegram Bot',
+   * });
+   * ```
    */
   update(id: string, body: IntegrationUpdateParams, options?: RequestOptions): APIPromise<Integration> {
     return this._client.patch(path`/integrations/${id}`, { body, ...options });
@@ -33,6 +58,11 @@ export class Integrations extends APIResource {
 
   /**
    * List integrations
+   *
+   * @example
+   * ```ts
+   * const integrations = await client.integrations.list();
+   * ```
    */
   list(options?: RequestOptions): APIPromise<IntegrationListResponse> {
     return this._client.get('/integrations', options);
@@ -40,6 +70,11 @@ export class Integrations extends APIResource {
 
   /**
    * Delete integration
+   *
+   * @example
+   * ```ts
+   * const integration = await client.integrations.delete('id');
+   * ```
    */
   delete(id: string, options?: RequestOptions): APIPromise<IntegrationDeleteResponse> {
     return this._client.delete(path`/integrations/${id}`, options);
@@ -47,6 +82,13 @@ export class Integrations extends APIResource {
 
   /**
    * List integration delivery history
+   *
+   * @example
+   * ```ts
+   * const response = await client.integrations.listDeliveries(
+   *   'id',
+   * );
+   * ```
    */
   listDeliveries(
     id: string,
@@ -58,19 +100,33 @@ export class Integrations extends APIResource {
 
   /**
    * Send test delivery
+   *
+   * @example
+   * ```ts
+   * const response = await client.integrations.sendTest('id');
+   * ```
    */
   sendTest(id: string, options?: RequestOptions): APIPromise<IntegrationSendTestResponse> {
     return this._client.post(path`/integrations/${id}/test`, options);
   }
 }
 
+/**
+ * Third-party integration (e.g. Telegram) subscribed to monitor events.
+ */
 export interface Integration {
   id: string;
 
+  /**
+   * Integration config — shape varies by type (JSON)
+   */
   config: { [key: string]: unknown };
 
   createdAt: string;
 
+  /**
+   * Array of event types to subscribe to.
+   */
   eventTypes: Array<Shared.EventType>;
 
   isActive: boolean;
@@ -79,6 +135,9 @@ export interface Integration {
 
   type: 'telegram';
 
+  /**
+   * Event filter rules (JSON)
+   */
   filters?: { [key: string]: unknown };
 
   messageTemplate?: string;
@@ -88,6 +147,9 @@ export interface Integration {
   silentPush?: boolean;
 }
 
+/**
+ * Integration delivery attempt record with status and retry count.
+ */
 export interface IntegrationDelivery {
   id: string;
 
@@ -132,6 +194,9 @@ export interface IntegrationCreateParams {
    */
   config: IntegrationCreateParams.Config;
 
+  /**
+   * Array of event types to subscribe to.
+   */
   eventTypes: Array<Shared.EventType>;
 
   name: string;
@@ -149,12 +214,21 @@ export namespace IntegrationCreateParams {
 }
 
 export interface IntegrationUpdateParams {
+  /**
+   * Array of event types to subscribe to.
+   */
   eventTypes?: Array<Shared.EventType>;
 
+  /**
+   * Event filter rules (JSON)
+   */
   filters?: { [key: string]: unknown };
 
   isActive?: boolean;
 
+  /**
+   * Custom message template (JSON)
+   */
   messageTemplate?: { [key: string]: unknown };
 
   name?: string;
@@ -165,6 +239,9 @@ export interface IntegrationUpdateParams {
 }
 
 export interface IntegrationListDeliveriesParams {
+  /**
+   * Maximum number of items to return (1-100, default 50)
+   */
   limit?: number;
 }
 

package/src/resources/monitors.ts

@@ -12,6 +12,14 @@ import { path } from '../internal/utils/path';
 export class Monitors extends APIResource {
   /**
    * Create monitor
+   *
+   * @example
+   * ```ts
+   * const monitor = await client.monitors.create({
+   *   eventTypes: ['tweet.new', 'follower.gained'],
+   *   username: 'elonmusk',
+   * });
+   * ```
    */
   create(body: MonitorCreateParams, options?: RequestOptions): APIPromise<MonitorCreateResponse> {
     return this._client.post('/monitors', { body, ...options });
@@ -19,6 +27,11 @@ export class Monitors extends APIResource {
 
   /**
    * Get monitor
+   *
+   * @example
+   * ```ts
+   * const monitor = await client.monitors.retrieve('id');
+   * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<Monitor> {
     return this._client.get(path`/monitors/${id}`, options);
@@ -26,6 +39,14 @@ export class Monitors extends APIResource {
 
   /**
    * Update monitor
+   *
+   * @example
+   * ```ts
+   * const monitor = await client.monitors.update('id', {
+   *   eventTypes: ['tweet.new'],
+   *   isActive: true,
+   * });
+   * ```
    */
   update(id: string, body: MonitorUpdateParams, options?: RequestOptions): APIPromise<Monitor> {
     return this._client.patch(path`/monitors/${id}`, { body, ...options });
@@ -33,6 +54,11 @@ export class Monitors extends APIResource {
 
   /**
    * List monitors
+   *
+   * @example
+   * ```ts
+   * const monitors = await client.monitors.list();
+   * ```
    */
   list(options?: RequestOptions): APIPromise<MonitorListResponse> {
     return this._client.get('/monitors', options);
@@ -40,17 +66,28 @@ export class Monitors extends APIResource {
 
   /**
    * Deactivate monitor
+   *
+   * @example
+   * ```ts
+   * const response = await client.monitors.deactivate('id');
+   * ```
    */
   deactivate(id: string, options?: RequestOptions): APIPromise<MonitorDeactivateResponse> {
     return this._client.delete(path`/monitors/${id}`, options);
   }
 }
 
+/**
+ * Account monitor that tracks activity for a given X user.
+ */
 export interface Monitor {
   id: string;
 
   createdAt: string;
 
+  /**
+   * Array of event types to subscribe to.
+   */
   eventTypes: Array<Shared.EventType>;
 
   isActive: boolean;
@@ -65,6 +102,9 @@ export interface MonitorCreateResponse {
 
   createdAt: string;
 
+  /**
+   * Array of event types to subscribe to.
+   */
   eventTypes: Array<Shared.EventType>;
 
   username: string;
@@ -83,6 +123,9 @@ export interface MonitorDeactivateResponse {
 }
 
 export interface MonitorCreateParams {
+  /**
+   * Array of event types to subscribe to.
+   */
   eventTypes: Array<Shared.EventType>;
 
   /**
@@ -92,6 +135,9 @@ export interface MonitorCreateParams {
 }
 
 export interface MonitorUpdateParams {
+  /**
+   * Array of event types to subscribe to.
+   */
   eventTypes?: Array<Shared.EventType>;
 
   isActive?: boolean;

package/src/resources/radar.ts

@@ -19,6 +19,9 @@ export class Radar extends APIResource {
   }
 }
 
+/**
+ * Trending topic with score, category, source, and region.
+ */
 export interface RadarItem {
   category: string;
 
@@ -70,7 +73,7 @@ export interface RadarRetrieveTrendingTopicsParams {
    * Source filter. One of: github, google_trends, hacker_news, polymarket, reddit,
    * trustmrr, wikipedia
    */
-  source?: string;
+  source?: 'github' | 'google_trends' | 'hacker_news' | 'polymarket' | 'reddit' | 'trustmrr' | 'wikipedia';
 }
 
 export declare namespace Radar {

package/src/resources/shared.ts

@@ -3,6 +3,9 @@
 import * as TweetsAPI from './x/tweets/tweets';
 import * as UsersAPI from './x/users/users';
 
+/**
+ * Error response containing a machine-readable error code.
+ */
 export interface Error {
   error:
     | 'internal_error'
@@ -32,6 +35,9 @@ export interface Error {
     | 'x_api_unauthorized';
 }
 
+/**
+ * Type of monitor event fired when account activity occurs.
+ */
 export type EventType =
   | 'tweet.new'
   | 'tweet.reply'
@@ -40,6 +46,9 @@ export type EventType =
   | 'follower.gained'
   | 'follower.lost';
 
+/**
+ * Paginated list of tweets with cursor-based navigation.
+ */
 export interface PaginatedTweets {
   has_next_page: boolean;
 
@@ -48,6 +57,9 @@ export interface PaginatedTweets {
   tweets: Array<TweetsAPI.SearchTweet>;
 }
 
+/**
+ * Paginated list of user profiles with cursor-based navigation.
+ */
 export interface PaginatedUsers {
   has_next_page: boolean;