x-twitter-scraper 0.12.4 → 0.13.1

package/src/resources/webhooks.ts

@@ -2,8 +2,6 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import { APIResource } from '../core/resource';
 import * as Shared from './shared';
 import { APIPromise } from '../core/api-promise';
@@ -15,7 +13,7 @@ import { path } from '../internal/utils/path';
  */
 export class Webhooks extends APIResource {
   /**
-   * Create webhook
+   * Registers an endpoint for signed event deliveries.
    *
    * @example
    * ```ts
@@ -30,11 +28,12 @@ export class Webhooks extends APIResource {
   }
 
   /**
-   * Update webhook
+   * Updates an endpoint, event selection, or delivery settings.
    *
    * @example
    * ```ts
    * const webhook = await client.webhooks.update('id', {
+   *   eventTypes: ['tweet.new'],
    *   isActive: true,
    *   url: 'https://example.com/webhook',
    * });
@@ -45,19 +44,44 @@ export class Webhooks extends APIResource {
   }
 
   /**
-   * List webhooks
+   * Returns configured webhook endpoints and delivery states.
    *
    * @example
    * ```ts
    * const webhooks = await client.webhooks.list();
    * ```
    */
-  list(options?: RequestOptions): APIPromise<WebhookListResponse> {
-    return this._client.get('/webhooks', options);
+  list(
+    query: WebhookListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WebhookListResponse> {
+    return this._client.get('/webhooks', { query, ...options });
+  }
+
+  /**
+   * Returns a t.me link to @XquikBot that connects a Telegram chat to the account's
+   * monitor events. Opening it & pressing Start connects the chat, which then gets
+   * each event as a message. The link works once, within 15 minutes. The chat
+   * appears in the webhook list with the URL telegram:<chat ID>, with deliveries,
+   * retries & resume as any webhook. In the chat, /stop pauses its alerts. It costs
+   * no credits.
+   *
+   * @example
+   * ```ts
+   * const response = await client.webhooks.createTelegramLink({
+   *   eventTypes: ['tweet.new', 'tweet.reply'],
+   * });
+   * ```
+   */
+  createTelegramLink(
+    body: WebhookCreateTelegramLinkParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WebhookCreateTelegramLinkResponse> {
+    return this._client.post('/webhooks/telegram', { body, ...options });
   }
 
   /**
-   * Deactivate webhook
+   * Stops future deliveries to the selected webhook.
    *
    * @example
    * ```ts
@@ -69,19 +93,23 @@ export class Webhooks extends APIResource {
   }
 
   /**
-   * List webhook deliveries
+   * Returns delivery attempts and response outcomes, newest first.
    *
    * @example
    * ```ts
    * const response = await client.webhooks.listDeliveries('id');
    * ```
    */
-  listDeliveries(id: string, options?: RequestOptions): APIPromise<WebhookListDeliveriesResponse> {
-    return this._client.get(path`/webhooks/${id}/deliveries`, options);
+  listDeliveries(
+    id: string,
+    query: WebhookListDeliveriesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WebhookListDeliveriesResponse> {
+    return this._client.get(path`/webhooks/${id}/deliveries`, { query, ...options });
   }
 
   /**
-   * Test and resume webhook endpoint
+   * Tests the endpoint before resuming a manually paused webhook.
    *
    * @example
    * ```ts
@@ -93,7 +121,7 @@ export class Webhooks extends APIResource {
   }
 
   /**
-   * Test webhook endpoint
+   * Sends a signed test event to the configured endpoint.
    *
    * @example
    * ```ts
@@ -111,6 +139,9 @@ export class Webhooks extends APIResource {
 export interface Delivery {
   id: string;
 
+  /**
+   * Whole number from 0.
+   */
   attempts: number;
 
   createdAt: string;
@@ -140,8 +171,8 @@ export interface Webhook {
   createdAt: string;
 
   /**
-   * Endpoint delivery state. needs_attention means delivery stopped after repeated
-   * failures.
+   * Endpoint delivery state. paused means the user paused delivery. needs_attention
+   * marks repeated failures. Delivery attempts continue.
    */
   deliveryStatus: 'active' | 'paused' | 'needs_attention';
 
@@ -151,7 +182,7 @@ export interface Webhook {
   eventTypes: Array<Shared.EventType>;
 
   /**
-   * Consecutive delivery failures that pause the endpoint.
+   * Maximum reported failures before needs_attention. It does not pause delivery.
    */
   failureHardCap: number;
 
@@ -179,7 +210,23 @@ export interface WebhookCreateResponse {
 }
 
 export interface WebhookListResponse {
+  hasMore: boolean;
+
   webhooks: Array<Webhook>;
+
+  nextCursor?: string;
+}
+
+export interface WebhookCreateTelegramLinkResponse {
+  /**
+   * When the link stops working, 15 minutes on.
+   */
+  expiresAt: string;
+
+  /**
+   * Opens @XquikBot with the link's code.
+   */
+  url: string;
 }
 
 export interface WebhookDeactivateResponse {
@@ -188,6 +235,10 @@ export interface WebhookDeactivateResponse {
 
 export interface WebhookListDeliveriesResponse {
   deliveries: Array<Delivery>;
+
+  hasMore: boolean;
+
+  nextCursor?: string;
 }
 
 export interface WebhookResumeResponse {
@@ -216,7 +267,9 @@ export interface WebhookCreateParams {
   eventTypes: Array<Shared.EventType>;
 
   /**
-   * HTTPS URL
+   * HTTPS URL. A Discord channel webhook URL gets each event as a Discord message, &
+   * a Slack incoming webhook URL as a Slack message. To deliver to Telegram, use
+   * POST /webhooks/telegram instead.
    */
   url: string;
 }
@@ -232,17 +285,56 @@ export interface WebhookUpdateParams {
   url?: string;
 }
 
+export interface WebhookListParams {
+  /**
+   * 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 interface WebhookCreateTelegramLinkParams {
+  /**
+   * Array of event types to subscribe to.
+   */
+  eventTypes?: Array<Shared.EventType>;
+}
+
+export interface WebhookListDeliveriesParams {
+  /**
+   * Previous nextCursor. The after alias also works. Offset pagination is not
+   * supported.
+   */
+  cursor?: string;
+
+  /**
+   * Maximum deliveries per page: 1 to 100, default 100. Pass nextCursor as cursor
+   * for the next page.
+   */
+  limit?: number;
+}
+
 export declare namespace Webhooks {
   export {
     type Delivery as Delivery,
     type Webhook as Webhook,
     type WebhookCreateResponse as WebhookCreateResponse,
     type WebhookListResponse as WebhookListResponse,
+    type WebhookCreateTelegramLinkResponse as WebhookCreateTelegramLinkResponse,
     type WebhookDeactivateResponse as WebhookDeactivateResponse,
     type WebhookListDeliveriesResponse as WebhookListDeliveriesResponse,
     type WebhookResumeResponse as WebhookResumeResponse,
     type WebhookTestResponse as WebhookTestResponse,
     type WebhookCreateParams as WebhookCreateParams,
     type WebhookUpdateParams as WebhookUpdateParams,
+    type WebhookListParams as WebhookListParams,
+    type WebhookCreateTelegramLinkParams as WebhookCreateTelegramLinkParams,
+    type WebhookListDeliveriesParams as WebhookListDeliveriesParams,
   };
 }

package/src/resources/x/account-connection-attempts.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
@@ -10,7 +8,7 @@ import { path } from '../../internal/utils/path';
  */
 export class AccountConnectionAttempts extends APIResource {
   /**
-   * Get X account connection status
+   * Returns progress for an X account connection attempt.
    *
    * @example
    * ```ts

package/src/resources/x/account-connection-challenges.ts

@@ -2,8 +2,6 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
@@ -14,14 +12,15 @@ import { path } from '../../internal/utils/path';
  */
 export class AccountConnectionChallenges extends APIResource {
   /**
-   * Submit X account email verification code
+   * Submits the email code requested during X account connection.
    *
    * @example
    * ```ts
    * const response =
-   *   await client.x.accountConnectionChallenges.submit('id', {
-   *     email_code: '<EMAIL_VERIFICATION_CODE>',
-   *   });
+   *   await client.x.accountConnectionChallenges.submit(
+   *     'xch_AbCdEfGhIjKlMnOp',
+   *     { email_code: '<EMAIL_VERIFICATION_CODE>' },
+   *   );
    * ```
    */
   submit(
@@ -36,18 +35,45 @@ export class AccountConnectionChallenges extends APIResource {
 /**
  * Sanitized X account summary returned by connect and reauth.
  */
-export interface AccountConnectionChallengeSubmitResponse {
-  id: string;
+export type AccountConnectionChallengeSubmitResponse =
+  | AccountConnectionChallengeSubmitResponse.SanitizedXAccount
+  | AccountConnectionChallengeSubmitResponse.XAccountConnectionChallenge;
+
+export namespace AccountConnectionChallengeSubmitResponse {
+  /**
+   * Sanitized X account summary returned by connect and reauth.
+   */
+  export interface SanitizedXAccount {
+    id: string;
+
+    createdAt: string;
+
+    health: 'healthy' | 'locked' | 'needsReauth' | 'recovering' | 'suspended' | 'temporaryIssue';
+
+    status: 'active';
 
-  createdAt: string;
+    xUserId: string;
 
-  health: 'healthy' | 'locked' | 'needsReauth' | 'recovering' | 'suspended' | 'temporaryIssue';
+    xUsername: string;
+  }
+
+  /**
+   * Resumable account connection challenge. Submit the email code to finish the same
+   * connection attempt.
+   */
+  export interface XAccountConnectionChallenge {
+    id: string;
 
-  status: 'active';
+    expiresAt: string;
 
-  xUserId: string;
+    message: string;
 
-  xUsername: string;
+    object: 'x_account_connection_challenge';
+
+    status: 'requires_email_code';
+
+    username: string;
+  }
 }
 
 export interface AccountConnectionChallengeSubmitParams {

package/src/resources/x/accounts.ts

@@ -2,8 +2,6 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
@@ -14,7 +12,7 @@ import { path } from '../../internal/utils/path';
  */
 export class Accounts extends APIResource {
   /**
-   * Connect X account
+   * Starts a secure X account connection flow.
    *
    * @example
    * ```ts
@@ -31,7 +29,7 @@ export class Accounts extends APIResource {
   }
 
   /**
-   * Get X account details
+   * Returns one connected X account and its current status.
    *
    * @example
    * ```ts
@@ -45,19 +43,23 @@ export class Accounts extends APIResource {
   }
 
   /**
-   * List connected X accounts
+   * Returns connected accounts in creation order. Omit pagination for up to 10,000
+   * accounts. Send limit or cursor for legacy pagination.
    *
    * @example
    * ```ts
    * const accounts = await client.x.accounts.list();
    * ```
    */
-  list(options?: RequestOptions): APIPromise<AccountListResponse> {
-    return this._client.get('/x/accounts', options);
+  list(
+    query: AccountListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AccountListResponse> {
+    return this._client.get('/x/accounts', { query, ...options });
   }
 
   /**
-   * Disconnect X account
+   * Disconnects one X account and removes stored session access.
    *
    * @example
    * ```ts
@@ -82,7 +84,7 @@ export class Accounts extends APIResource {
   }
 
   /**
-   * Re-authenticate X account
+   * Starts re-authentication for an existing X account connection.
    *
    * @example
    * ```ts
@@ -121,7 +123,10 @@ export interface XAccount {
 
   xUsername: string;
 
-  cookiesObtainedAt?: string;
+  /**
+   * When the account last connected or reconnected.
+   */
+  connectedAt?: string;
 }
 
 /**
@@ -140,7 +145,11 @@ export interface XAccountDetail {
 
   xUsername: string;
 
-  cookiesObtainedAt?: string;
+  /**
+   * Last connection or reconnection time of this account. Omitted before its first
+   * login.
+   */
+  connectedAt?: string;
 
   updatedAt?: string;
 }
@@ -205,6 +214,16 @@ export namespace AccountCreateResponse {
 
 export interface AccountListResponse {
   accounts: Array<XAccount>;
+
+  /**
+   * Present on cursor-paginated responses.
+   */
+  hasMore?: boolean;
+
+  /**
+   * Pass unchanged as cursor when hasMore is true.
+   */
+  nextCursor?: string;
 }
 
 export interface AccountDeleteResponse {
@@ -252,11 +271,25 @@ export interface AccountCreateParams {
   totp_secret: string;
 
   /**
-   * X username
+   * X username of the account to connect, with or without @
    */
   username: string;
 }
 
+export interface AccountListParams {
+  /**
+   * Previous nextCursor. The after alias also works. Offset pagination is not
+   * supported.
+   */
+  cursor?: string;
+
+  /**
+   * Maximum items per page: 1 to 100, default 50. Credits can reduce paid results.
+   * With none affordable, it returns 402 insufficient_credits.
+   */
+  limit?: number;
+}
+
 export interface AccountReauthParams {
   /**
    * Updated account password
@@ -284,6 +317,7 @@ export declare namespace Accounts {
     type AccountBulkRetryResponse as AccountBulkRetryResponse,
     type AccountReauthResponse as AccountReauthResponse,
     type AccountCreateParams as AccountCreateParams,
+    type AccountListParams as AccountListParams,
     type AccountReauthParams as AccountReauthParams,
   };
 }