x-twitter-scraper 0.3.3 → 0.4.0

package/src/internal/request-options.ts

@@ -75,6 +75,8 @@ export type RequestOptions = {
    */
   defaultBaseURL?: string | undefined;
 
+  __security?: { apiKeyAuth?: boolean; oauthBearerAuth?: boolean };
+
   __binaryResponse?: boolean | undefined;
 };
 

package/src/internal/utils/log.ts

@@ -106,8 +106,9 @@ export const formatRequestDetails = (details: {
         ([name, value]) => [
           name,
           (
-            name.toLowerCase() === 'x-api-key' ||
             name.toLowerCase() === 'authorization' ||
+            name.toLowerCase() === 'api-key' ||
+            name.toLowerCase() === 'x-api-key' ||
             name.toLowerCase() === 'cookie' ||
             name.toLowerCase() === 'set-cookie'
           ) ?

package/src/resources/account.ts

@@ -56,6 +56,12 @@ export class Account extends APIResource {
 }
 
 export interface AccountRetrieveResponse {
+  monitorBilling: AccountRetrieveResponse.MonitorBilling;
+
+  /**
+   * @deprecated Monitor slots are unlimited. Use monitorBilling.unlimitedSlots
+   * instead.
+   */
   monitorsAllowed: number;
 
   monitorsUsed: number;
@@ -63,17 +69,78 @@ export interface AccountRetrieveResponse {
   plan: 'active' | 'inactive';
 
   creditInfo?: AccountRetrieveResponse.CreditInfo;
+
+  /**
+   * Linked X username, omitted when no X account is connected.
+   */
+  xUsername?: string;
 }
 
 export namespace AccountRetrieveResponse {
-  export interface CreditInfo {
-    autoTopupEnabled: boolean;
+  export interface MonitorBilling {
+    /**
+     * Estimated daily usage for currently active monitors.
+     */
+    activeDailyEstimate: string;
+
+    /**
+     * Usage charged each hour for currently active monitors.
+     */
+    activeHourlyBurn: string;
+
+    /**
+     * Estimated daily usage for 1 active instant monitor.
+     */
+    creditsPerActiveMonitorDay: string;
+
+    /**
+     * Hourly usage charged for 1 active instant monitor.
+     */
+    creditsPerActiveMonitorHour: string;
+
+    /**
+     * Webhook and event deliveries are included in monitor billing.
+     */
+    eventsIncluded: boolean;
+
+    /**
+     * Active monitors check every 1 second.
+     */
+    instantCheckIntervalSeconds: number;
+
+    /**
+     * Monitor slot count is unlimited.
+     */
+    unlimitedSlots: boolean;
+  }
 
-    balance: number;
+  export interface CreditInfo {
+    /**
+     * Dollar amount charged when automatic top-up runs.
+     */
+    autoTopupAmountDollars: number;
 
-    lifetimePurchased: number;
+    autoTopupEnabled: boolean;
 
-    lifetimeUsed: number;
+    /**
+     * Bigint string threshold that triggers automatic top-up when enabled.
+     */
+    autoTopupThreshold: string;
+
+    /**
+     * Bigint string to preserve precision above Number.MAX_SAFE_INTEGER.
+     */
+    balance: string;
+
+    /**
+     * Total purchased usage as a bigint string.
+     */
+    lifetimePurchased: string;
+
+    /**
+     * Total consumed usage as a bigint string.
+     */
+    lifetimeUsed: string;
   }
 }
 

package/src/resources/credits.ts

@@ -2,14 +2,37 @@
 
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 
 /**
- * Subscription, billing, and credits
+ * Subscription, billing, and usage balance
  */
 export class Credits extends APIResource {
   /**
-   * Get credits balance
+   * Redirect to an active top-up payment page
+   *
+   * @example
+   * ```ts
+   * await client.credits.redirectTopupCheckout({
+   *   session_id: 'session_id',
+   * });
+   * ```
+   */
+  redirectTopupCheckout(
+    query: CreditRedirectTopupCheckoutParams,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    return this._client.get('/credits/topup/redirect', {
+      query,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+      __security: {},
+    });
+  }
+
+  /**
+   * Get usage balance
    *
    * @example
    * ```ts
@@ -21,12 +44,30 @@ export class Credits extends APIResource {
   }
 
   /**
-   * Top up credits balance
+   * Get top-up billing status
+   *
+   * @example
+   * ```ts
+   * const response = await client.credits.retrieveTopupStatus({
+   *   session_id: 'session_id',
+   * });
+   * ```
+   */
+  retrieveTopupStatus(
+    query: CreditRetrieveTopupStatusParams,
+    options?: RequestOptions,
+  ): APIPromise<CreditRetrieveTopupStatusResponse> {
+    return this._client.get('/credits/topup/status', { query, ...options });
+  }
+
+  /**
+   * Create a Stripe Checkout session only after the user confirms. The request never
+   * completes payment or adds balance by itself.
    *
    * @example
    * ```ts
    * const response = await client.credits.topupBalance({
-   *   amount: 10000,
+   *   dollars: 10,
    * });
    * ```
    */
@@ -39,30 +80,96 @@ export class Credits extends APIResource {
 }
 
 export interface CreditRetrieveBalanceResponse {
+  /**
+   * Configured dollar amount for each automatic top-up.
+   */
+  auto_topup_amount_dollars: number;
+
   auto_topup_enabled: boolean;
 
-  balance: number;
+  /**
+   * Usage 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
+   * Number.MAX_SAFE_INTEGER.
+   */
+  balance: string;
+
+  /**
+   * Lifetime purchased usage as a bigint string.
+   */
+  lifetime_purchased: string;
+
+  /**
+   * Lifetime consumed usage as a bigint string.
+   */
+  lifetime_used: string;
+}
+
+export interface CreditRetrieveTopupStatusResponse {
+  status: 'paid' | 'processing' | 'failed' | 'expired';
 
-  lifetime_purchased: number;
+  /**
+   * Dollar amount requested for the top-up.
+   */
+  amount_dollars?: number | null;
 
-  lifetime_used: number;
+  /**
+   * Bigint string usage amount granted or pending.
+   */
+  credits?: string;
 }
 
 export interface CreditTopupBalanceResponse {
-  success: true;
+  /**
+   * Stable first-party Xquik redirect URL for the active Stripe Checkout session.
+   */
+  redirect_url: string;
+
+  /**
+   * Same stable first-party Xquik redirect URL as redirect_url. The response never
+   * exposes a raw Stripe Checkout URL.
+   */
+  url: string;
+}
+
+export interface CreditRedirectTopupCheckoutParams {
+  /**
+   * Billing session ID returned by the top-up billing flow.
+   */
+  session_id: string;
+}
+
+export interface CreditRetrieveTopupStatusParams {
+  /**
+   * Billing session ID returned by the top-up billing flow.
+   */
+  session_id: string;
 }
 
 export interface CreditTopupBalanceParams {
   /**
-   * Amount to top up in credits
+   * Amount to top up in US dollars. Minimum 10.
+   */
+  dollars: number;
+
+  /**
+   * Optional checkout locale. Defaults to en.
    */
-  amount: number;
+  locale?: string;
 }
 
 export declare namespace Credits {
   export {
     type CreditRetrieveBalanceResponse as CreditRetrieveBalanceResponse,
+    type CreditRetrieveTopupStatusResponse as CreditRetrieveTopupStatusResponse,
     type CreditTopupBalanceResponse as CreditTopupBalanceResponse,
+    type CreditRedirectTopupCheckoutParams as CreditRedirectTopupCheckoutParams,
+    type CreditRetrieveTopupStatusParams as CreditRetrieveTopupStatusParams,
     type CreditTopupBalanceParams as CreditTopupBalanceParams,
   };
 }

package/src/resources/drafts.ts

@@ -124,7 +124,10 @@ export interface DraftListParams {
   afterCursor?: 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;
 }

package/src/resources/draws.ts

@@ -15,7 +15,9 @@ export class Draws extends APIResource {
    *
    * @example
    * ```ts
-   * const draw = await client.draws.retrieve('id');
+   * const draw = await client.draws.retrieve(
+   *   'f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345',
+   * );
    * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<DrawRetrieveResponse> {
@@ -42,17 +44,16 @@ export class Draws extends APIResource {
    *
    * @example
    * ```ts
-   * const response = await client.draws.export('id');
+   * const response = await client.draws.export(
+   *   'f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345',
+   *   { format: 'csv' },
+   * );
    *
    * const content = await response.blob();
    * console.log(content);
    * ```
    */
-  export(
-    id: string,
-    query: DrawExportParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Response> {
+  export(id: string, query: DrawExportParams, options?: RequestOptions): APIPromise<Response> {
     return this._client.get(path`/draws/${id}/export`, {
       query,
       ...options,
@@ -62,7 +63,10 @@ export class Draws extends APIResource {
   }
 
   /**
-   * Run giveaway draw
+   * Runs a giveaway draw from a source tweet. The draw first checks that the usage
+   * balance can inspect the source tweet and at least 1 candidate. Available balance
+   * caps how many replies and retweeters can be inspected before filters and winner
+   * selection run.
    *
    * @example
    * ```ts
@@ -82,6 +86,9 @@ export class Draws extends APIResource {
  * Full giveaway draw with tweet metrics, entries, and timing.
  */
 export interface DrawDetail {
+  /**
+   * Draw public ID.
+   */
   id: string;
 
   createdAt: string;
@@ -115,6 +122,9 @@ export interface DrawDetail {
  * Giveaway draw summary with entry counts and status.
  */
 export interface DrawListItem {
+  /**
+   * Draw public ID for detail responses.
+   */
   id: string;
 
   createdAt: string;
@@ -163,10 +173,18 @@ export interface DrawListResponse {
 export interface DrawRunResponse {
   id: string;
 
+  /**
+   * Candidate entries inspected for this draw. This may
+   * be lower than the source tweet's full reply count.
+   */
   totalEntries: number;
 
   tweetId: string;
 
+  /**
+   * Entries from the inspected candidate set that passed all filters. This is not
+   * necessarily every valid reply on the source tweet when the available balance limits inspection.
+   */
   validEntries: number;
 
   winners: Array<Winner>;
@@ -174,12 +192,15 @@ export interface DrawRunResponse {
 
 export interface DrawListParams {
   /**
-   * 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;
 }
@@ -188,7 +209,7 @@ export interface DrawExportParams {
   /**
    * Export output format
    */
-  format?: 'csv' | 'json' | 'md' | 'md-document' | 'pdf' | 'txt' | 'xlsx';
+  format: 'csv' | 'json' | 'md' | 'md-document' | 'pdf' | 'txt' | 'xlsx';
 
   /**
    * Export winners or all entries

package/src/resources/events.ts

@@ -29,15 +29,23 @@ export class Events extends APIResource {
 }
 
 /**
- * Monitor event summary with type, username, and occurrence time.
+ * Monitor event summary with source metadata and occurrence time.
  */
 export interface Event {
   id: string;
 
   data: { [key: string]: unknown };
 
+  /**
+   * Account monitor ID for account events, or keyword monitor ID for keyword events.
+   */
   monitorId: string;
 
+  /**
+   * Source monitor type.
+   */
+  monitorType: 'account' | 'keyword';
+
   occurredAt: string;
 
   /**
@@ -45,7 +53,20 @@ export interface Event {
    */
   type: Shared.EventType;
 
-  username: string;
+  /**
+   * Keyword monitor ID, present for keyword monitor events.
+   */
+  keywordMonitorId?: string;
+
+  /**
+   * Keyword query, present for keyword monitor events.
+   */
+  query?: string;
+
+  /**
+   * Account username, present for account monitor events.
+   */
+  username?: string;
 }
 
 /**
@@ -55,12 +76,20 @@ export interface EventDetail {
   id: string;
 
   /**
-   * Event payload — shape varies by event type (JSON)
+   * Event payload - shape varies by event type (JSON)
    */
   data: { [key: string]: unknown };
 
+  /**
+   * Monitor ID associated with this detailed event payload.
+   */
   monitorId: string;
 
+  /**
+   * Source monitor type for this detailed event.
+   */
+  monitorType: 'account' | 'keyword';
+
   occurredAt: string;
 
   /**
@@ -68,7 +97,20 @@ export interface EventDetail {
    */
   type: Shared.EventType;
 
-  username: string;
+  /**
+   * Keyword monitor ID included on detailed keyword events.
+   */
+  keywordMonitorId?: string;
+
+  /**
+   * Keyword query for this detailed monitor event.
+   */
+  query?: string;
+
+  /**
+   * Account username for this detailed monitor event.
+   */
+  username?: string;
 
   xEventId?: string;
 }
@@ -83,9 +125,9 @@ export interface EventListResponse {
 
 export interface EventListParams {
   /**
-   * Cursor for keyset pagination
+   * Cursor for keyset pagination from prior response next_cursor
    */
-  after?: string;
+  cursor?: string;
 
   /**
    * Filter events by type
@@ -93,7 +135,10 @@ export interface EventListParams {
   eventType?: Shared.EventType;
 
   /**
-   * 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;