x-twitter-scraper 0.3.3 → 0.4.0

package/src/resources/webhooks.ts

@@ -76,6 +76,18 @@ export class Webhooks extends APIResource {
     return this._client.get(path`/webhooks/${id}/deliveries`, options);
   }
 
+  /**
+   * Test and resume webhook endpoint
+   *
+   * @example
+   * ```ts
+   * const response = await client.webhooks.resume('id');
+   * ```
+   */
+  resume(id: string, options?: RequestOptions): APIPromise<WebhookResumeResponse> {
+    return this._client.post(path`/webhooks/${id}/resume`, options);
+  }
+
   /**
    * Test webhook endpoint
    *
@@ -116,13 +128,29 @@ export interface Delivery {
 export interface Webhook {
   id: string;
 
+  /**
+   * Consecutive failed delivery attempts since the last success.
+   */
+  consecutiveFailures: number;
+
   createdAt: string;
 
+  /**
+   * Endpoint delivery state. needs_attention means delivery stopped after repeated
+   * failures.
+   */
+  deliveryStatus: 'active' | 'paused' | 'needs_attention';
+
   /**
    * Array of event types to subscribe to.
    */
   eventTypes: Array<Shared.EventType>;
 
+  /**
+   * Consecutive delivery failures that pause the endpoint.
+   */
+  failureHardCap: number;
+
   isActive: boolean;
 
   url: string;
@@ -138,6 +166,9 @@ export interface WebhookCreateResponse {
    */
   eventTypes: Array<Shared.EventType>;
 
+  /**
+   * Plaintext HMAC signing secret returned only at creation.
+   */
   secret: string;
 
   url: string;
@@ -155,6 +186,17 @@ export interface WebhookListDeliveriesResponse {
   deliveries: Array<Delivery>;
 }
 
+export interface WebhookResumeResponse {
+  statusCode: number;
+
+  success: boolean;
+
+  /**
+   * Webhook endpoint registered to receive event deliveries.
+   */
+  webhook: Webhook;
+}
+
 export interface WebhookTestResponse {
   statusCode: number;
 
@@ -194,6 +236,7 @@ export declare namespace Webhooks {
     type WebhookListResponse as WebhookListResponse,
     type WebhookDeactivateResponse as WebhookDeactivateResponse,
     type WebhookListDeliveriesResponse as WebhookListDeliveriesResponse,
+    type WebhookResumeResponse as WebhookResumeResponse,
     type WebhookTestResponse as WebhookTestResponse,
     type WebhookCreateParams as WebhookCreateParams,
     type WebhookUpdateParams as WebhookUpdateParams,

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

@@ -0,0 +1,61 @@
+// 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';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Connected X account management
+ */
+export class AccountConnectionChallenges extends APIResource {
+  /**
+   * Submit X account email verification code
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.x.accountConnectionChallenges.submit('id', {
+   *     email_code: '123456',
+   *   });
+   * ```
+   */
+  submit(
+    id: string,
+    body: AccountConnectionChallengeSubmitParams,
+    options?: RequestOptions,
+  ): APIPromise<AccountConnectionChallengeSubmitResponse> {
+    return this._client.post(path`/x/account-connection-challenges/${id}/submit`, { body, ...options });
+  }
+}
+
+/**
+ * Sanitized X account summary returned by connect and reauth.
+ */
+export interface AccountConnectionChallengeSubmitResponse {
+  id: string;
+
+  createdAt: string;
+
+  health: 'healthy' | 'locked' | 'needsReauth' | 'recovering' | 'suspended' | 'temporaryIssue';
+
+  status: string;
+
+  xUserId: string;
+
+  xUsername: string;
+}
+
+export interface AccountConnectionChallengeSubmitParams {
+  /**
+   * Code sent to the account email.
+   */
+  email_code: string;
+}
+
+export declare namespace AccountConnectionChallenges {
+  export {
+    type AccountConnectionChallengeSubmitResponse as AccountConnectionChallengeSubmitResponse,
+    type AccountConnectionChallengeSubmitParams as AccountConnectionChallengeSubmitParams,
+  };
+}

package/src/resources/x/accounts.ts

@@ -16,7 +16,7 @@ export class Accounts extends APIResource {
    * ```ts
    * const account = await client.x.accounts.create({
    *   email: 'user@example.com',
-   *   password: 's3cur3Pa$$w0rd',
+   *   password: '<ACCOUNT_PASSWORD>',
    *   username: 'elonmusk',
    * });
    * ```
@@ -82,8 +82,8 @@ export class Accounts extends APIResource {
    * @example
    * ```ts
    * const response = await client.x.accounts.reauth('id', {
-   *   password: 'password_value',
-   *   totp_secret: 'totp_secret_value',
+   *   password: '<ACCOUNT_PASSWORD>',
+   *   totp_secret: '<TOTP_SECRET>',
    * });
    * ```
    */
@@ -93,7 +93,7 @@ export class Accounts extends APIResource {
 }
 
 /**
- * Linked X account summary with username and connection status.
+ * Linked X account summary with connection status, health, and timestamp metadata.
  */
 export interface XAccount {
   id: string;
@@ -101,23 +101,26 @@ export interface XAccount {
   createdAt: string;
 
   /**
-   * Derived login/cookie health. `healthy` = cookies valid. `needsReauth` = user
-   * must submit fresh credentials. `locked` = X locked the account; unlock on x.com
-   * first. `suspended` = X banned the account. `recovering` = past cooldown, will
-   * auto-retry on next use. `temporaryIssue` = transient backend problem; retry
-   * shortly.
+   * Derived connection health. `healthy` = ready. `needsReauth` = reconnect the
+   * account. `locked` = unlock the account on x.com first. `suspended` = X
+   * suspended the account. `recovering` = retry is available after cooldown.
+   * `temporaryIssue` = retry shortly.
    */
   health: 'healthy' | 'locked' | 'needsReauth' | 'recovering' | 'suspended' | 'temporaryIssue';
 
   status: string;
 
+  updatedAt: string;
+
   xUserId: string;
 
   xUsername: string;
+
+  cookiesObtainedAt?: string;
 }
 
 /**
- * Full X account details including proxy, cookies, and update timestamp.
+ * Connected X account details with health and timestamp metadata.
  */
 export interface XAccountDetail {
   id: string;
@@ -134,17 +137,11 @@ export interface XAccountDetail {
 
   cookiesObtainedAt?: string;
 
-  proxyCountry?: string;
-
   updatedAt?: string;
 }
 
 /**
- * Sanitized X account summary returned by connect and reauth. Includes an optional
- * `loginCountry` field surfaced only when the selected login region was
- * temporarily unavailable and the login used a one-time US session for this
- * one-time action. Future activity continues to use the selected `proxy_country`;
- * the field is omitted on normal logins.
+ * Sanitized X account summary returned by connect and reauth.
  */
 export interface AccountCreateResponse {
   id: string;
@@ -158,13 +155,6 @@ export interface AccountCreateResponse {
   xUserId: string;
 
   xUsername: string;
-
-  /**
-   * ISO-3166-1 alpha-2 country code of the login service session used for this
-   * login. Present only when the US fallback was triggered because the selected
-   * login region was temporarily unavailable. Omitted otherwise.
-   */
-  loginCountry?: string;
 }
 
 export interface AccountListResponse {
@@ -183,11 +173,7 @@ export interface AccountBulkRetryResponse {
 }
 
 /**
- * Sanitized X account summary returned by connect and reauth. Includes an optional
- * `loginCountry` field surfaced only when the selected login region was
- * temporarily unavailable and the login used a one-time US session for this
- * one-time action. Future activity continues to use the selected `proxy_country`;
- * the field is omitted on normal logins.
+ * Sanitized X account summary returned by connect and reauth.
  */
 export interface AccountReauthResponse {
   id: string;
@@ -201,13 +187,6 @@ export interface AccountReauthResponse {
   xUserId: string;
 
   xUsername: string;
-
-  /**
-   * ISO-3166-1 alpha-2 country code of the login service session used for this
-   * login. Present only when the US fallback was triggered because the selected
-   * login region was temporarily unavailable. Omitted otherwise.
-   */
-  loginCountry?: string;
 }
 
 export interface AccountCreateParams {
@@ -226,11 +205,6 @@ export interface AccountCreateParams {
    */
   username: string;
 
-  /**
-   * Proxy country code
-   */
-  proxy_country?: string;
-
   /**
    * TOTP secret for 2FA
    */
@@ -248,11 +222,6 @@ export interface AccountReauthParams {
    */
   email?: string;
 
-  /**
-   * Two-letter country code for login proxy region
-   */
-  proxy_country?: string;
-
   /**
    * TOTP secret for 2FA re-authentication
    */

package/src/resources/x/bookmarks.ts

@@ -40,8 +40,14 @@ export class Bookmarks extends APIResource {
 export interface BookmarkRetrieveFoldersResponse {
   folders: Array<BookmarkRetrieveFoldersResponse.Folder>;
 
+  /**
+   * Always false for the current bookmark folder route
+   */
   has_next_page: boolean;
 
+  /**
+   * Always empty for the current bookmark folder route
+   */
   next_cursor: string;
 }
 

package/src/resources/x/communities/communities.ts

@@ -3,7 +3,13 @@
 import { APIResource } from '../../../core/resource';
 import * as Shared from '../../shared';
 import * as JoinAPI from './join';
-import { Join, JoinCreateParams, JoinDeleteAllParams } from './join';
+import {
+  Join,
+  JoinCreateParams,
+  JoinCreateResponse,
+  JoinDeleteAllParams,
+  JoinDeleteAllResponse,
+} from './join';
 import * as TweetsAPI from './tweets';
 import { TweetListByCommunityParams, TweetListParams, Tweets } from './tweets';
 import { APIPromise } from '../../../core/api-promise';
@@ -98,12 +104,15 @@ export class Communities extends APIResource {
   }
 
   /**
-   * Search for communities by keyword
+   * Returns tweets, not community records. Requires a Community ID.
    *
    * @example
    * ```ts
    * const paginatedTweets =
-   *   await client.x.communities.retrieveSearch({ q: 'q' });
+   *   await client.x.communities.retrieveSearch({
+   *     communityId: '321669910225',
+   *     q: 'q',
+   *   });
    * ```
    */
   retrieveSearch(
@@ -114,17 +123,6 @@ export class Communities extends APIResource {
   }
 }
 
-/**
- * Result of a community join or leave action.
- */
-export interface CommunityActionResult {
-  communityId: string;
-
-  communityName: string;
-
-  success: true;
-}
-
 export interface CommunityCreateResponse {
   communityId: string;
 
@@ -164,11 +162,28 @@ export namespace CommunityRetrieveInfoResponse {
      */
     created_at?: string;
 
+    creator?: Community.Creator;
+
     /**
      * About text for the community
      */
     description?: string;
 
+    /**
+     * Invitation policy
+     */
+    invites_policy?: string;
+
+    /**
+     * Whether the authenticated viewer is a member
+     */
+    is_member?: boolean;
+
+    /**
+     * Whether the community is marked sensitive
+     */
+    is_nsfw?: boolean;
+
     /**
      * Join policy (open or restricted)
      */
@@ -194,6 +209,11 @@ export namespace CommunityRetrieveInfoResponse {
      */
     primary_topic?: Community.PrimaryTopic;
 
+    /**
+     * Authenticated viewer's community role
+     */
+    role?: string;
+
     /**
      * Community rules
      */
@@ -201,6 +221,16 @@ export namespace CommunityRetrieveInfoResponse {
   }
 
   export namespace Community {
+    export interface Creator {
+      id: string;
+
+      username: string;
+
+      verified: boolean;
+
+      name?: string;
+    }
+
     /**
      * Primary topic
      */
@@ -254,6 +284,13 @@ export interface CommunityRetrieveMembersParams {
    * Pagination cursor
    */
   cursor?: string;
+
+  /**
+   * Items per page (20-200, default 20). This is an upper bound for paid
+   * authenticated calls: available usage balance can reduce the returned page size, and
+   * zero affordable results returns 402 insufficient_credits.
+   */
+  pageSize?: number;
 }
 
 export interface CommunityRetrieveModeratorsParams {
@@ -264,6 +301,11 @@ export interface CommunityRetrieveModeratorsParams {
 }
 
 export interface CommunityRetrieveSearchParams {
+  /**
+   * Numeric ID of the community whose posts to search
+   */
+  communityId: string;
+
   /**
    * Search query
    */
@@ -274,10 +316,19 @@ export interface CommunityRetrieveSearchParams {
    */
   cursor?: string;
 
+  /**
+   * Maximum items requested from this page (1-100, default 20). The response can
+   * contain fewer items because the source returned fewer, filters removed items, or
+   * the available usage balance covers fewer results. Keep requesting next_cursor while
+   * has_next_page is true, even when a page is empty. The deprecated limit and count
+   * aliases remain accepted.
+   */
+  pageSize?: number;
+
   /**
    * Sort order (Latest or Top)
    */
-  queryType?: string;
+  queryType?: 'Latest' | 'Top';
 }
 
 Communities.Join = Join;
@@ -285,7 +336,6 @@ Communities.Tweets = Tweets;
 
 export declare namespace Communities {
   export {
-    type CommunityActionResult as CommunityActionResult,
     type CommunityCreateResponse as CommunityCreateResponse,
     type CommunityDeleteResponse as CommunityDeleteResponse,
     type CommunityRetrieveInfoResponse as CommunityRetrieveInfoResponse,
@@ -298,6 +348,8 @@ export declare namespace Communities {
 
   export {
     Join as Join,
+    type JoinCreateResponse as JoinCreateResponse,
+    type JoinDeleteAllResponse as JoinDeleteAllResponse,
     type JoinCreateParams as JoinCreateParams,
     type JoinDeleteAllParams as JoinDeleteAllParams,
   };

package/src/resources/x/communities/index.ts

@@ -2,7 +2,6 @@
 
 export {
   Communities,
-  type CommunityActionResult,
   type CommunityCreateResponse,
   type CommunityDeleteResponse,
   type CommunityRetrieveInfoResponse,
@@ -12,5 +11,11 @@ export {
   type CommunityRetrieveModeratorsParams,
   type CommunityRetrieveSearchParams,
 } from './communities';
-export { Join, type JoinCreateParams, type JoinDeleteAllParams } from './join';
+export {
+  Join,
+  type JoinCreateResponse,
+  type JoinDeleteAllResponse,
+  type JoinCreateParams,
+  type JoinDeleteAllParams,
+} from './join';
 export { Tweets, type TweetListParams, type TweetListByCommunityParams } from './tweets';

package/src/resources/x/communities/join.ts

@@ -1,7 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../../core/resource';
-import * as CommunitiesAPI from './communities';
 import { APIPromise } from '../../../core/api-promise';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
@@ -15,17 +14,12 @@ export class Join extends APIResource {
    *
    * @example
    * ```ts
-   * const communityActionResult =
-   *   await client.x.communities.join.create('id', {
-   *     account: '@elonmusk',
-   *   });
+   * const join = await client.x.communities.join.create('id', {
+   *   account: '@elonmusk',
+   * });
    * ```
    */
-  create(
-    id: string,
-    body: JoinCreateParams,
-    options?: RequestOptions,
-  ): APIPromise<CommunitiesAPI.CommunityActionResult> {
+  create(id: string, body: JoinCreateParams, options?: RequestOptions): APIPromise<JoinCreateResponse> {
     return this._client.post(path`/x/communities/${id}/join`, { body, ...options });
   }
 
@@ -34,21 +28,29 @@ export class Join extends APIResource {
    *
    * @example
    * ```ts
-   * const communityActionResult =
-   *   await client.x.communities.join.deleteAll('id', {
-   *     account: '@elonmusk',
-   *   });
+   * const response = await client.x.communities.join.deleteAll(
+   *   'id',
+   *   { account: '@elonmusk' },
+   * );
    * ```
    */
   deleteAll(
     id: string,
     body: JoinDeleteAllParams,
     options?: RequestOptions,
-  ): APIPromise<CommunitiesAPI.CommunityActionResult> {
+  ): APIPromise<JoinDeleteAllResponse> {
     return this._client.delete(path`/x/communities/${id}/join`, { body, ...options });
   }
 }
 
+export interface JoinCreateResponse {
+  success: true;
+}
+
+export interface JoinDeleteAllResponse {
+  success: true;
+}
+
 export interface JoinCreateParams {
   /**
    * X account identifier (@username or account ID)
@@ -64,5 +66,10 @@ export interface JoinDeleteAllParams {
 }
 
 export declare namespace Join {
-  export { type JoinCreateParams as JoinCreateParams, type JoinDeleteAllParams as JoinDeleteAllParams };
+  export {
+    type JoinCreateResponse as JoinCreateResponse,
+    type JoinDeleteAllResponse as JoinDeleteAllResponse,
+    type JoinCreateParams as JoinCreateParams,
+    type JoinDeleteAllParams as JoinDeleteAllParams,
+  };
 }

package/src/resources/x/communities/tweets.ts

@@ -11,12 +11,15 @@ import { path } from '../../../internal/utils/path';
  */
 export class Tweets extends APIResource {
   /**
-   * List tweets across all communities
+   * Requires a Community ID and keyword query.
    *
    * @example
    * ```ts
    * const paginatedTweets =
-   *   await client.x.communities.tweets.list({ q: 'q' });
+   *   await client.x.communities.tweets.list({
+   *     communityId: '321669910225',
+   *     q: 'q',
+   *   });
    * ```
    */
   list(query: TweetListParams, options?: RequestOptions): APIPromise<Shared.PaginatedTweets> {
@@ -43,19 +46,33 @@ export class Tweets extends APIResource {
 
 export interface TweetListParams {
   /**
-   * Search query for cross-community tweets
+   * Numeric ID of the community to search
+   */
+  communityId: string;
+
+  /**
+   * Keyword query within the selected community
    */
   q: string;
 
   /**
-   * Pagination cursor for cross-community results
+   * Pagination cursor for community results
    */
   cursor?: string;
 
   /**
-   * Sort order for cross-community results (Latest or Top)
+   * Maximum items requested from this page (1-100, default 20). The response can
+   * contain fewer items because the source returned fewer, filters removed items, or
+   * the available usage balance covers fewer results. Keep requesting next_cursor while
+   * has_next_page is true, even when a page is empty. The deprecated limit and count
+   * aliases remain accepted.
    */
-  queryType?: string;
+  pageSize?: number;
+
+  /**
+   * Sort order for community results (Latest or Top)
+   */
+  queryType?: 'Latest' | 'Top';
 }
 
 export interface TweetListByCommunityParams {
@@ -63,6 +80,15 @@ export interface TweetListByCommunityParams {
    * Pagination cursor for community tweets
    */
   cursor?: string;
+
+  /**
+   * Maximum items requested from this page (1-100, default 20). The response can
+   * contain fewer items because the source returned fewer, filters removed items, or
+   * the available usage balance covers fewer results. Keep requesting next_cursor while
+   * has_next_page is true, even when a page is empty. The deprecated limit and count
+   * aliases remain accepted.
+   */
+  pageSize?: number;
 }
 
 export declare namespace Tweets {