x-twitter-scraper 0.4.1 → 0.5.1

package/src/resources/compose.ts

@@ -9,14 +9,17 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class Compose extends APIResource {
   /**
-   * Compose, refine, or score a tweet
+   * Run one step of Xquik's three-step writing workflow. Compose returns questions
+   * and editorial rules. Refine returns goal-specific guidance. Score applies
+   * deterministic text checks. It does not predict reach or expose X ranking
+   * weights.
    *
    * @example
    * ```ts
    * const compose = await client.compose.create({
    *   step: 'compose',
+   *   topic: 'PostgreSQL query planning',
    *   goal: 'engagement',
-   *   topic: 'AI trends in 2025',
    * });
    * ```
    */
@@ -25,85 +28,249 @@ export class Compose extends APIResource {
   }
 }
 
-export interface ComposeCreateResponse {
-  /**
-   * AI feedback on the draft
-   */
-  feedback?: string;
+export type ComposeCreateResponse =
+  | ComposeCreateResponse.ComposePrepareResult
+  | ComposeCreateResponse.ComposeRefineResult
+  | ComposeCreateResponse.ComposeScoreResult;
 
-  /**
-   * Engagement score (0-100)
-   */
-  score?: number;
+export namespace ComposeCreateResponse {
+  export interface ComposePrepareResult {
+    /**
+     * Xquik editorial heuristics, ordered for the goal.
+     */
+    contentRules: Array<ComposePrepareResult.ContentRule>;
 
-  /**
-   * Improvement suggestions
-   */
-  suggestions?: Array<string>;
+    /**
+     * Published engagement signal names. Production multipliers are not published.
+     */
+    engagementMultipliers: Array<ComposePrepareResult.EngagementMultiplier>;
 
-  /**
-   * Generated or refined tweet text
-   */
-  text?: string;
+    /**
+     * Publication limit for timing and decay claims.
+     */
+    engagementVelocity: string;
+
+    followUpQuestions: Array<string>;
+
+    /**
+     * X post intent seeded with the topic.
+     */
+    intentUrl: string;
+
+    nextStep: string;
+
+    /**
+     * Published signal names with unpublished weights as null.
+     */
+    scorerWeights: Array<ComposePrepareResult.ScorerWeight>;
+
+    /**
+     * Signal source and evidence limits.
+     */
+    source: string;
+
+    /**
+     * Negative engagement predictions in the public model.
+     */
+    topPenalties: Array<string>;
+
+    /**
+     * Style analyses saved to the account.
+     */
+    savedStyles?: Array<ComposePrepareResult.SavedStyle>;
+
+    /**
+     * Next action when no cached style is available.
+     */
+    styleNote?: string;
+
+    /**
+     * Cached examples for the requested style username.
+     */
+    styleTweets?: Array<string>;
+  }
+
+  export namespace ComposePrepareResult {
+    export interface ContentRule {
+      rule: string;
+    }
+
+    export interface EngagementMultiplier {
+      /**
+       * Human-readable published signal name.
+       */
+      action: string;
+
+      multiplier: 'Production weight not published by X';
+    }
+
+    export interface ScorerWeight {
+      /**
+       * Signal direction and publication limit.
+       */
+      context: string;
+
+      /**
+       * Signal name from X's public ranking repository.
+       */
+      signal: string;
+
+      /**
+       * X does not publish the production weight.
+       */
+      weight: null;
+    }
+
+    export interface SavedStyle {
+      tweetCount: number;
+
+      username: string;
+    }
+  }
+
+  export interface ComposeRefineResult {
+    /**
+     * Goal, tone, media, and editorial guidance.
+     */
+    compositionGuidance: Array<string>;
+
+    examplePatterns: Array<ComposeRefineResult.ExamplePattern>;
+
+    /**
+     * X post intent seeded with the topic.
+     */
+    intentUrl: string;
+
+    nextStep: string;
+  }
+
+  export namespace ComposeRefineResult {
+    export interface ExamplePattern {
+      description: string;
+
+      pattern: string;
+    }
+  }
+
+  export interface ComposeScoreResult {
+    /**
+     * Deterministic editorial checks. Not a reach prediction.
+     */
+    checklist: Array<ComposeScoreResult.Checklist>;
+
+    nextStep: string;
+
+    passed: boolean;
+
+    passedCount: number;
+
+    topSuggestion: string;
 
-  [k: string]: unknown;
+    totalChecks: 9;
+
+    /**
+     * Present only when every check passes.
+     */
+    intentUrl?: string;
+  }
+
+  export namespace ComposeScoreResult {
+    export interface Checklist {
+      factor: string;
+
+      passed: boolean;
+
+      /**
+       * Present only when the check fails.
+       */
+      suggestion?: string;
+    }
+  }
 }
 
-export interface ComposeCreateParams {
-  /**
-   * Workflow step
-   */
-  step: 'compose' | 'refine' | 'score';
+export type ComposeCreateParams =
+  | ComposeCreateParams.ComposePrepareRequest
+  | ComposeCreateParams.ComposeRefineRequest
+  | ComposeCreateParams.ComposeScoreRequest;
 
-  /**
-   * Extra context or URLs (refine)
-   */
-  additionalContext?: string;
+export declare namespace ComposeCreateParams {
+  export interface ComposePrepareRequest {
+    step: 'compose';
 
-  /**
-   * Desired call to action (refine)
-   */
-  callToAction?: string;
+    /**
+     * Subject for the post.
+     */
+    topic: string;
 
-  /**
-   * Tweet draft text to evaluate (score)
-   */
-  draft?: string;
+    /**
+     * Editorial goal used to order the rules and questions.
+     */
+    goal?: 'engagement' | 'followers' | 'authority' | 'conversation';
 
-  /**
-   * Optimization goal
-   */
-  goal?: 'engagement' | 'followers' | 'authority' | 'conversation';
+    /**
+     * Username from a style analysis saved to this account.
+     */
+    styleUsername?: string;
 
-  /**
-   * Whether a link is attached (score)
-   */
-  hasLink?: boolean;
+    [k: string]: unknown;
+  }
 
-  /**
-   * Whether media is attached (score)
-   */
-  hasMedia?: boolean;
+  export interface ComposeRefineRequest {
+    /**
+     * Editorial goal for the guidance.
+     */
+    goal: 'engagement' | 'followers' | 'authority' | 'conversation';
 
-  /**
-   * Media type (refine)
-   */
-  mediaType?: 'photo' | 'video' | 'none';
+    step: 'refine';
 
-  /**
-   * Cached style username for voice matching (compose)
-   */
-  styleUsername?: string;
+    /**
+     * Requested writing tone.
+     */
+    tone: string;
 
-  /**
-   * Desired tone (refine)
-   */
-  tone?: string;
+    /**
+     * Subject for the post.
+     */
+    topic: string;
 
-  /**
-   * Tweet topic (compose, refine)
-   */
-  topic?: string;
+    /**
+     * Audience, constraints, sources, or other writing context.
+     */
+    additionalContext?: string;
+
+    /**
+     * Specific action the draft should request.
+     */
+    callToAction?: string;
+
+    /**
+     * Planned media type.
+     */
+    mediaType?: 'photo' | 'video' | 'none';
+
+    [k: string]: unknown;
+  }
+
+  export interface ComposeScoreRequest {
+    /**
+     * Full post text for deterministic editorial checks.
+     */
+    draft: string;
+
+    step: 'score';
+
+    /**
+     * True when a separate link card is attached.
+     */
+    hasLink?: boolean;
+
+    /**
+     * @deprecated Ignored. Remove this field. Use hasLink for a separate link card.
+     */
+    hasMedia?: boolean;
+
+    [k: string]: unknown;
+  }
 }
 
 export declare namespace Compose {

package/src/resources/credits.ts

@@ -146,7 +146,7 @@ export interface CreditRedirectTopupCheckoutParams {
 
 export interface CreditRetrieveTopupStatusParams {
   /**
-   * Billing session ID returned by the top-up billing flow.
+   * Top-up session ID to inspect.
    */
   session_id: string;
 }

package/src/resources/extractions.ts

@@ -453,7 +453,7 @@ export interface ExtractionEstimateCostParams {
   retweetsOfTweetId?: string;
 
   /**
-   * Required for tweet_search_extractor & community_search.
+   * Query used to price tweet_search_extractor or community_search.
    */
   searchQuery?: string;
 
@@ -463,18 +463,18 @@ export interface ExtractionEstimateCostParams {
   sinceDate?: string;
 
   /**
-   * Required for community_post_extractor & community_search.
+   * Community ID used to price community_post_extractor or community_search.
    */
   targetCommunityId?: string;
 
   /**
-   * Required for list_follower_explorer, list_member_extractor &
+   * List ID used to price list_follower_explorer, list_member_extractor, or
    * list_post_extractor.
    */
   targetListId?: string;
 
   /**
-   * Required for space_explorer.
+   * Space ID used to price space_explorer.
    */
   targetSpaceId?: string;
 

package/src/resources/guest-wallets.ts

@@ -289,7 +289,7 @@ export namespace GuestWalletTopupResponse {
 
 export interface GuestWalletCreateParams {
   /**
-   * Body param: Confirmed USD amount in cents.
+   * Body param: USD cents accepted for this checkout.
    */
   amount_minor: number;
 
@@ -308,7 +308,7 @@ export interface GuestWalletCreateParams {
 
 export interface GuestWalletTopupParams {
   /**
-   * Body param: Confirmed USD amount in cents.
+   * Body param: USD cents accepted for this checkout.
    */
   amount_minor: number;
 

package/src/resources/monitors/keywords.ts

@@ -7,13 +7,13 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 /**
- * Real-time X account monitoring
+ * X account monitoring with 1-second checks
  */
 export class Keywords extends APIResource {
   /**
-   * Creates an instant keyword monitor. Keyword monitors are unlimited. Active
-   * monitors check every 1 second. Events and webhook deliveries are included.
-   * Creation requires an available usage balance.
+   * 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.
    *
    * @example
    * ```ts

package/src/resources/monitors/monitors.ts

@@ -18,15 +18,16 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 /**
- * Real-time X account monitoring
+ * X account monitoring with 1-second checks
  */
 export class Monitors extends APIResource {
   keywords: KeywordsAPI.Keywords = new KeywordsAPI.Keywords(this._client);
 
   /**
-   * Creates an instant monitor. Monitors are unlimited. Active monitors check every
-   * 1 second. Events and webhook deliveries are included. Creation requires an
-   * available usage balance.
+   * 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.
    *
    * @example
    * ```ts

package/src/resources/shared.ts

@@ -149,6 +149,39 @@ export interface Error {
     | 'unauthenticated'
     | 'unsupported_field'
     | 'user_not_found'
+    | 'body_too_large'
+    | 'checkout_unavailable'
+    | 'connection_challenge_expired'
+    | 'connection_challenge_inactive'
+    | 'draft_not_found'
+    | 'favoriters_unavailable'
+    | 'forbidden'
+    | 'guest_wallet_unavailable'
+    | 'guest_wallets_disabled'
+    | 'guest_wallets_unavailable'
+    | 'idempotency_conflict'
+    | 'idempotency_key_conflict'
+    | 'invalid_community_id'
+    | 'invalid_idempotency_key'
+    | 'invalid_list_id'
+    | 'invalid_payment_amount'
+    | 'invalid_range'
+    | 'login_rate_limited'
+    | 'missing_idempotency_key'
+    | 'missing_ids'
+    | 'no_cached_style'
+    | 'passkey_required'
+    | 'rate_limited'
+    | 'read_request_timeout'
+    | 'replies_incomplete'
+    | 'support_media_rate_limit'
+    | 'support_request_rate_limit'
+    | 'too_many_ids'
+    | 'unknown_field'
+    | 'unsupported_media_type'
+    | 'webhook_inactive'
+    | 'write_tracking_unavailable'
+    | 'x_write_unconfirmed'
     | 'x_account_feature_required'
     | 'x_account_protected'
     | 'x_account_suspended'
@@ -175,8 +208,27 @@ export interface Error {
     | 'x_user_lookup_failed'
     | 'x_write_ambiguous'
     | 'x_write_failed'
-    | 'x_write_unconfirmed'
     | Error.StructuredError;
+
+  /**
+   * Human-readable error guidance.
+   */
+  message?: string;
+
+  /**
+   * Machine-readable reason for a login cooldown.
+   */
+  reason?: string;
+
+  /**
+   * Seconds until the next permitted request.
+   */
+  retryAfter?: number;
+
+  /**
+   * Required wait in milliseconds.
+   */
+  retryAfterMs?: number;
 }
 
 export namespace Error {
@@ -222,6 +274,39 @@ export namespace Error {
       | 'unauthenticated'
       | 'unsupported_field'
       | 'user_not_found'
+      | 'body_too_large'
+      | 'checkout_unavailable'
+      | 'connection_challenge_expired'
+      | 'connection_challenge_inactive'
+      | 'draft_not_found'
+      | 'favoriters_unavailable'
+      | 'forbidden'
+      | 'guest_wallet_unavailable'
+      | 'guest_wallets_disabled'
+      | 'guest_wallets_unavailable'
+      | 'idempotency_conflict'
+      | 'idempotency_key_conflict'
+      | 'invalid_community_id'
+      | 'invalid_idempotency_key'
+      | 'invalid_list_id'
+      | 'invalid_payment_amount'
+      | 'invalid_range'
+      | 'login_rate_limited'
+      | 'missing_idempotency_key'
+      | 'missing_ids'
+      | 'no_cached_style'
+      | 'passkey_required'
+      | 'rate_limited'
+      | 'read_request_timeout'
+      | 'replies_incomplete'
+      | 'support_media_rate_limit'
+      | 'support_request_rate_limit'
+      | 'too_many_ids'
+      | 'unknown_field'
+      | 'unsupported_media_type'
+      | 'webhook_inactive'
+      | 'write_tracking_unavailable'
+      | 'x_write_unconfirmed'
       | 'x_account_feature_required'
       | 'x_account_protected'
       | 'x_account_suspended'
@@ -247,8 +332,7 @@ export namespace Error {
       | 'x_transient_error'
       | 'x_user_lookup_failed'
       | 'x_write_ambiguous'
-      | 'x_write_failed'
-      | 'x_write_unconfirmed';
+      | 'x_write_failed';
 
     message: string;
 
@@ -359,7 +443,7 @@ export interface SearchTweet {
   createdAt?: string;
 
   /**
-   * Start and end offsets for rendered tweet text
+   * Rendered text's start and end offsets.
    */
   displayTextRange?: Array<number>;
 
@@ -370,17 +454,17 @@ export interface SearchTweet {
   entities?: { [key: string]: unknown };
 
   /**
-   * Tweet ID being replied to
+   * ID of the tweet this result replies to.
    */
   inReplyToId?: string;
 
   /**
-   * User ID being replied to
+   * ID of the user this result replies to.
    */
   inReplyToUserId?: string;
 
   /**
-   * Username being replied to
+   * Username this result replies to.
    */
   inReplyToUsername?: string;
 
@@ -405,7 +489,7 @@ export interface SearchTweet {
   isReply?: boolean;
 
   /**
-   * Tweet language code
+   * Search result language code.
    */
   lang?: string;
 
@@ -436,7 +520,7 @@ export interface SearchTweet {
   type?: string;
 
   /**
-   * Tweet permalink URL
+   * Search result permalink.
    */
   url?: string;
 }