x-twitter-scraper 0.12.4 → 0.13.0

package/src/internal/decoders/line.ts

@@ -0,0 +1,140 @@
+// SPDX-FileCopyrightText: 2026 Xquik contributors
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { concatBytes, decodeUTF8, encodeUTF8 } from '../utils/bytes';
+
+export type Bytes = string | ArrayBuffer | Uint8Array | null | undefined;
+
+/**
+ * A re-implementation of httpx's `LineDecoder` in Python that handles incrementally
+ * reading lines from text.
+ *
+ * https://github.com/encode/httpx/blob/920333ea98118e9cf617f246905d7b202510941c/httpx/_decoders.py#L258
+ */
+export class LineDecoder {
+  static NEWLINE_CHARS = new Set(['\n', '\r']);
+  static NEWLINE_REGEXP = /\r\n|[\n\r]/g;
+
+  #buffer: Uint8Array;
+  #carriageReturnIndex: number | null;
+
+  constructor() {
+    this.#buffer = new Uint8Array();
+    this.#carriageReturnIndex = null;
+  }
+
+  decode(chunk: Bytes): string[] {
+    if (chunk == null) {
+      return [];
+    }
+
+    const binaryChunk =
+      chunk instanceof ArrayBuffer ? new Uint8Array(chunk)
+      : typeof chunk === 'string' ? encodeUTF8(chunk)
+      : chunk;
+
+    this.#buffer = concatBytes([this.#buffer, binaryChunk]);
+
+    const lines: string[] = [];
+    let patternIndex;
+    while ((patternIndex = findNewlineIndex(this.#buffer, this.#carriageReturnIndex)) != null) {
+      if (patternIndex.carriage && this.#carriageReturnIndex == null) {
+        // skip until we either get a corresponding `\n`, a new `\r` or nothing
+        this.#carriageReturnIndex = patternIndex.index;
+        continue;
+      }
+
+      // we got double \r or \rtext\n
+      if (
+        this.#carriageReturnIndex != null &&
+        (patternIndex.index !== this.#carriageReturnIndex + 1 || patternIndex.carriage)
+      ) {
+        lines.push(decodeUTF8(this.#buffer.subarray(0, this.#carriageReturnIndex - 1)));
+        this.#buffer = this.#buffer.subarray(this.#carriageReturnIndex);
+        this.#carriageReturnIndex = null;
+        continue;
+      }
+
+      const endIndex =
+        this.#carriageReturnIndex !== null ? patternIndex.preceding - 1 : patternIndex.preceding;
+
+      const line = decodeUTF8(this.#buffer.subarray(0, endIndex));
+      lines.push(line);
+
+      this.#buffer = this.#buffer.subarray(patternIndex.index);
+      this.#carriageReturnIndex = null;
+    }
+
+    return lines;
+  }
+
+  flush(): string[] {
+    if (!this.#buffer.length) {
+      return [];
+    }
+    return this.decode('\n');
+  }
+}
+
+/**
+ * This function searches the buffer for the end patterns, (\r or \n)
+ * and returns an object with the index preceding the matched newline and the
+ * index after the newline char. `null` is returned if no new line is found.
+ *
+ * ```ts
+ * findNewLineIndex('abc\ndef') -> { preceding: 2, index: 3 }
+ * ```
+ */
+function findNewlineIndex(
+  buffer: Uint8Array,
+  startIndex: number | null,
+): { preceding: number; index: number; carriage: boolean } | null {
+  const newline = 0x0a; // \n
+  const carriage = 0x0d; // \r
+
+  for (let i = startIndex ?? 0; i < buffer.length; i++) {
+    if (buffer[i] === newline) {
+      return { preceding: i, index: i + 1, carriage: false };
+    }
+
+    if (buffer[i] === carriage) {
+      return { preceding: i, index: i + 1, carriage: true };
+    }
+  }
+
+  return null;
+}
+
+export function findDoubleNewlineIndex(buffer: Uint8Array): number {
+  // This function searches the buffer for the end patterns (\r\r, \n\n, \r\n\r\n)
+  // and returns the index right after the first occurrence of any pattern,
+  // or -1 if none of the patterns are found.
+  const newline = 0x0a; // \n
+  const carriage = 0x0d; // \r
+
+  for (let i = 0; i < buffer.length - 1; i++) {
+    if (buffer[i] === newline && buffer[i + 1] === newline) {
+      // \n\n
+      return i + 2;
+    }
+    if (buffer[i] === carriage && buffer[i + 1] === carriage) {
+      // \r\r
+      return i + 2;
+    }
+    if (
+      buffer[i] === carriage &&
+      buffer[i + 1] === newline &&
+      i + 3 < buffer.length &&
+      buffer[i + 2] === carriage &&
+      buffer[i + 3] === newline
+    ) {
+      // \r\n\r\n
+      return i + 4;
+    }
+  }
+
+  return -1;
+}

package/src/internal/parse.ts

@@ -5,6 +5,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import type { FinalRequestOptions } from './request-options';
+import { Stream } from '../core/streaming';
 import { type XTwitterScraper } from '../client';
 import { formatRequestDetails, loggerFor } from './utils/log';
 
@@ -20,6 +21,14 @@ export type APIResponseProps = {
 export async function defaultParseResponse<T>(client: XTwitterScraper, props: APIResponseProps): Promise<T> {
   const { response, requestLogID, retryOfRequestLogID, startTime } = props;
   const body = await (async () => {
+    if (props.options.stream) {
+      loggerFor(client).debug('response', response.status, response.url, response.headers, response.body);
+
+      // Note: there is an invariant here that isn't represented in the type system
+      // that if you set `stream: true` the response type must also be `Stream<T>`
+      return Stream.fromSSEResponse(response, props.controller, client) as any;
+    }
+
     // fetch refuses to read the body when the status code is 204.
     if (response.status === 204) {
       return null as T;

package/src/resources/account.ts

@@ -13,7 +13,8 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class Account extends APIResource {
   /**
-   * Get account info
+   * Returns plan, credit, monitoring, and account settings for the authenticated
+   * user.
    *
    * @example
    * ```ts
@@ -25,7 +26,7 @@ export class Account extends APIResource {
   }
 
   /**
-   * Set linked X username
+   * Links an X username to the authenticated Xquik account.
    *
    * @example
    * ```ts
@@ -42,7 +43,7 @@ export class Account extends APIResource {
   }
 
   /**
-   * Update account locale
+   * Changes the locale used for account responses and notifications.
    *
    * @example
    * ```ts
@@ -72,6 +73,11 @@ export interface AccountRetrieveResponse {
 
   plan: 'active' | 'inactive';
 
+  /**
+   * Subscription state without billing provider identifiers.
+   */
+  subscription: AccountRetrieveResponse.Subscription;
+
   creditInfo?: AccountRetrieveResponse.CreditInfo;
 
   /**
@@ -83,24 +89,24 @@ export interface AccountRetrieveResponse {
 export namespace AccountRetrieveResponse {
   export interface MonitorBilling {
     /**
-     * Estimated daily usage for currently active monitors.
+     * Daily credits for currently active monitors.
      */
     activeDailyEstimate: string;
 
     /**
-     * Usage charged each hour for currently active monitors.
+     * Credits charged each hour for currently active monitors.
      */
     activeHourlyBurn: string;
 
     /**
-     * Rounded daily estimate for 1 active monitor.
+     * Daily credits charged for 1 active monitor.
      */
-    creditsPerActiveMonitorDay: string;
+    creditsPerActiveMonitorDay: '720';
 
     /**
-     * Hourly credits charged for 1 active monitor.
+     * Hourly credits charged for 1 active monitor. It is a monitor's only charge.
      */
-    creditsPerActiveMonitorHour: string;
+    creditsPerActiveMonitorHour: '30';
 
     /**
      * Webhook and event deliveries are included in monitor billing.
@@ -118,6 +124,22 @@ export namespace AccountRetrieveResponse {
     unlimitedSlots: boolean;
   }
 
+  /**
+   * Subscription state without billing provider identifiers.
+   */
+  export interface Subscription {
+    status: 'none' | 'active' | 'past_due' | 'canceling' | 'incomplete';
+
+    /**
+     * Renewal date, or the end date when canceling.
+     */
+    currentPeriodEnd?: string;
+
+    currentPeriodStart?: string;
+
+    tier?: 'starter' | 'pro' | 'business';
+  }
+
   export interface CreditInfo {
     /**
      * Dollar amount charged when automatic top-up runs.
@@ -126,10 +148,17 @@ export namespace AccountRetrieveResponse {
 
     autoTopupEnabled: boolean;
 
+    /**
+     * True when 3 declined charges in a row on one card stopped automatic top-up while
+     * it stays enabled. A paid top-up, a paid plan renewal, or the next automatic
+     * top-up on a new card clears it.
+     */
+    autoTopupStopped: boolean;
+
     /**
      * Bigint string threshold that triggers automatic top-up when enabled.
      */
-    autoTopupThreshold: string;
+    autoTopupThreshold: '10000' | '50000' | '100000' | '250000';
 
     /**
      * Bigint string to preserve precision above Number.MAX_SAFE_INTEGER.
@@ -137,12 +166,12 @@ export namespace AccountRetrieveResponse {
     balance: string;
 
     /**
-     * Total purchased usage as a bigint string.
+     * Total purchased credits as a bigint string.
      */
     lifetimePurchased: string;
 
     /**
-     * Total consumed usage as a bigint string.
+     * Total consumed credits as a bigint string.
      */
     lifetimeUsed: string;
   }

package/src/resources/compose.ts

@@ -13,10 +13,8 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class Compose extends APIResource {
   /**
-   * Run one step of Xquik's three-step writing workflow. Compose returns questions,
-   * editorial rules, and source-specific Radar recommendations. Refine returns
-   * goal-specific guidance. Score applies deterministic text checks. It does not
-   * predict reach or expose X ranking weights.
+   * Uses xai-org/x-algorithm facts to compose and refine text. Score checks text. It
+   * never predicts reach or engagement.
    *
    * @example
    * ```ts
@@ -24,6 +22,7 @@ export class Compose extends APIResource {
    *   step: 'compose',
    *   topic: 'PostgreSQL query planning',
    *   goal: 'engagement',
+   *   styleUsername: 'example_user',
    * });
    * ```
    */
@@ -32,20 +31,26 @@ export class Compose extends APIResource {
   }
 }
 
+/**
+ * Rules, questions, and research guidance for drafting a post.
+ */
 export type ComposeCreateResponse =
   | ComposeCreateResponse.ComposePrepareResult
   | ComposeCreateResponse.ComposeRefineResult
   | ComposeCreateResponse.ComposeScoreResult;
 
 export namespace ComposeCreateResponse {
+  /**
+   * Rules, questions, and research guidance for drafting a post.
+   */
   export interface ComposePrepareResult {
     /**
-     * Xquik editorial heuristics, ordered for the goal.
+     * Facts derived only from xai-org/x-algorithm.
      */
     contentRules: Array<ComposePrepareResult.ContentRule>;
 
     /**
-     * Published engagement signal names. Production multipliers are not published.
+     * Source ranking signals. Repository defaults may vary in production.
      */
     engagementMultipliers: Array<ComposePrepareResult.EngagementMultiplier>;
 
@@ -64,12 +69,14 @@ export namespace ComposeCreateResponse {
     nextStep: string;
 
     /**
-     * Sources and guidance for researching a fresh post angle.
+     * Deprecated compatibility field. Always empty.
+     *
+     * @deprecated
      */
     radarRecommendations: Array<ComposePrepareResult.RadarRecommendation>;
 
     /**
-     * Published signal names with unpublished weights as null.
+     * Source signals with production values withheld as null.
      */
     scorerWeights: Array<ComposePrepareResult.ScorerWeight>;
 
@@ -100,19 +107,30 @@ export namespace ComposeCreateResponse {
   }
 
   export namespace ComposePrepareResult {
+    /**
+     * One source-backed ranking fact returned during preparation.
+     */
     export interface ContentRule {
       rule: string;
     }
 
+    /**
+     * One ranking signal and its source-value limit.
+     */
     export interface EngagementMultiplier {
       /**
        * Human-readable published signal name.
        */
       action: string;
 
-      multiplier: 'Production weight not published by X';
+      multiplier: 'Source default; production value can vary';
     }
 
+    /**
+     * Deprecated compatibility schema. The response array is empty.
+     *
+     * @deprecated
+     */
     export interface RadarRecommendation {
       /**
        * Radar endpoint for this source.
@@ -132,9 +150,12 @@ export namespace ComposeCreateResponse {
       useFor: string;
     }
 
+    /**
+     * One source ranking signal without a production claim.
+     */
     export interface ScorerWeight {
       /**
-       * Signal direction and publication limit.
+       * Signal direction and production limit.
        */
       context: string;
 
@@ -144,28 +165,40 @@ export namespace ComposeCreateResponse {
       signal: string;
 
       /**
-       * X does not publish the production weight.
+       * Null prevents source defaults becoming production claims.
        */
       weight: null;
     }
 
+    /**
+     * A saved username style and analyzed post count.
+     */
     export interface SavedStyle {
+      /**
+       * Whole number from 0.
+       */
       tweetCount: number;
 
       username: string;
     }
   }
 
+  /**
+   * Source-backed guidance for refining a post.
+   */
   export interface ComposeRefineResult {
     /**
-     * Goal, tone, media, and editorial guidance.
+     * Request context and xai-org/x-algorithm guidance.
      */
     compositionGuidance: Array<string>;
 
+    /**
+     * @deprecated
+     */
     examplePatterns: Array<ComposeRefineResult.ExamplePattern>;
 
     /**
-     * X post intent seeded with the topic.
+     * X post intent generated for the refined topic.
      */
     intentUrl: string;
 
@@ -173,6 +206,11 @@ export namespace ComposeCreateResponse {
   }
 
   export namespace ComposeRefineResult {
+    /**
+     * Deprecated example-pattern schema. The response array is empty.
+     *
+     * @deprecated
+     */
     export interface ExamplePattern {
       description: string;
 
@@ -180,9 +218,12 @@ export namespace ComposeCreateResponse {
     }
   }
 
+  /**
+   * Posting validation without a fabricated ranking score.
+   */
   export interface ComposeScoreResult {
     /**
-     * Deterministic editorial checks. Not a reach prediction.
+     * Deterministic input validation. Not a reach prediction.
      */
     checklist: Array<ComposeScoreResult.Checklist>;
 
@@ -194,7 +235,7 @@ export namespace ComposeCreateResponse {
 
     topSuggestion: string;
 
-    totalChecks: 9;
+    totalChecks: 1;
 
     /**
      * Present only when every check passes.
@@ -203,6 +244,9 @@ export namespace ComposeCreateResponse {
   }
 
   export namespace ComposeScoreResult {
+    /**
+     * One deterministic draft check.
+     */
     export interface Checklist {
       factor: string;
 
@@ -216,12 +260,18 @@ export namespace ComposeCreateResponse {
   }
 }
 
+/**
+ * Inputs for preparing source-backed post guidance.
+ */
 export type ComposeCreateParams =
   | ComposeCreateParams.ComposePrepareRequest
   | ComposeCreateParams.ComposeRefineRequest
   | ComposeCreateParams.ComposeScoreRequest;
 
 export declare namespace ComposeCreateParams {
+  /**
+   * Inputs for preparing source-backed post guidance.
+   */
   export interface ComposePrepareRequest {
     step: 'compose';
 
@@ -231,7 +281,7 @@ export declare namespace ComposeCreateParams {
     topic: string;
 
     /**
-     * Editorial goal used to order the rules and questions.
+     * User goal used for one follow-up question.
      */
     goal?: 'engagement' | 'followers' | 'authority' | 'conversation';
 
@@ -243,9 +293,12 @@ export declare namespace ComposeCreateParams {
     [k: string]: unknown;
   }
 
+  /**
+   * Inputs for refining a post plan.
+   */
   export interface ComposeRefineRequest {
     /**
-     * Editorial goal for the guidance.
+     * User goal interpreted against published ranking signals.
      */
     goal: 'engagement' | 'followers' | 'authority' | 'conversation';
 
@@ -257,7 +310,7 @@ export declare namespace ComposeCreateParams {
     tone: string;
 
     /**
-     * Subject for the post.
+     * Subject to refine into a post.
      */
     topic: string;
 
@@ -279,21 +332,24 @@ export declare namespace ComposeCreateParams {
     [k: string]: unknown;
   }
 
+  /**
+   * Inputs for checking a post draft.
+   */
   export interface ComposeScoreRequest {
     /**
-     * Full post text for deterministic editorial checks.
+     * Full post text. The endpoint never assigns a ranking score.
      */
     draft: string;
 
     step: 'score';
 
     /**
-     * True when a separate link card is attached.
+     * @deprecated Ignored. Remove this field.
      */
     hasLink?: boolean;
 
     /**
-     * @deprecated Ignored. Remove this field. Use hasLink for a separate link card.
+     * @deprecated Ignored. Remove this field.
      */
     hasMedia?: boolean;
 

package/src/resources/credits.ts

@@ -10,11 +10,11 @@ import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 
 /**
- * Subscription, billing, and usage balance
+ * Subscription, billing, and credits
  */
 export class Credits extends APIResource {
   /**
-   * Redirect to an active top-up payment page
+   * Redirects to the active hosted top-up checkout.
    *
    * @example
    * ```ts
@@ -36,7 +36,7 @@ export class Credits extends APIResource {
   }
 
   /**
-   * Get usage balance
+   * Returns the account credit balance and usage context.
    *
    * @example
    * ```ts
@@ -48,7 +48,7 @@ export class Credits extends APIResource {
   }
 
   /**
-   * Get top-up billing status
+   * Returns verification status for a credit top-up.
    *
    * @example
    * ```ts
@@ -72,6 +72,7 @@ export class Credits extends APIResource {
    * ```ts
    * const response = await client.credits.topupBalance({
    *   dollars: 10,
+   *   locale: 'en',
    * });
    * ```
    */
@@ -92,24 +93,31 @@ export interface CreditRetrieveBalanceResponse {
   auto_topup_enabled: boolean;
 
   /**
-   * Usage balance threshold that triggers automatic top-up when enabled,
+   * Whether declined charges stopped automatic top-up while it is enabled. It stops
+   * after 3 declines in a row on one card. A paid top-up, a paid plan renewal, or
+   * the next automatic top-up on a new card clears it.
+   */
+  auto_topup_stopped: boolean;
+
+  /**
+   * Credit balance threshold that triggers automatic top-up when enabled,
    * represented as a bigint string.
    */
   auto_topup_threshold: string;
 
   /**
-   * Current usage balance as a bigint string to preserve precision above
+   * Current credit balance as a bigint string to preserve precision above
    * Number.MAX_SAFE_INTEGER.
    */
   balance: string;
 
   /**
-   * Lifetime purchased usage as a bigint string.
+   * Lifetime purchased credits as a bigint string.
    */
   lifetime_purchased: string;
 
   /**
-   * Lifetime consumed usage as a bigint string.
+   * Lifetime consumed credits as a bigint string.
    */
   lifetime_used: string;
 }
@@ -123,7 +131,7 @@ export interface CreditRetrieveTopupStatusResponse {
   amount_dollars?: number | null;
 
   /**
-   * Bigint string usage amount granted or pending.
+   * Bigint string credit amount granted or pending.
    */
   credits?: string;
 }
@@ -162,7 +170,8 @@ export interface CreditTopupBalanceParams {
   dollars: number;
 
   /**
-   * Optional checkout locale. Defaults to en.
+   * Optional site language for Stripe's return page. An unsupported 1 uses en, the
+   * default.
    */
   locale?: string;
 }