x-twitter-scraper 0.12.3 → 0.13.0

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

@@ -8,12 +8,20 @@ export {
   Communities,
   type CommunityCreateResponse,
   type CommunityDeleteResponse,
+  type CommunityListSuggestedResponse,
+  type CommunityListTopicsResponse,
   type CommunityRetrieveInfoResponse,
   type CommunityCreateParams,
   type CommunityDeleteParams,
+  type CommunityFindParams,
+  type CommunityListPopularParams,
+  type CommunityListSuggestedParams,
+  type CommunityListTopicsParams,
+  type CommunityRetrieveInfoParams,
   type CommunityRetrieveMembersParams,
   type CommunityRetrieveModeratorsParams,
   type CommunityRetrieveSearchParams,
+  type CommunitySearchMembersParams,
 } from './communities';
 export {
   Join,
@@ -22,4 +30,5 @@ export {
   type JoinCreateParams,
   type JoinDeleteAllParams,
 } from './join';
+export { Media, type MediaListParams } from './media';
 export { Tweets, type TweetListParams, type TweetListByCommunityParams } from './tweets';

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

@@ -15,14 +15,17 @@ import { path } from '../../../internal/utils/path';
  */
 export class Join extends APIResource {
   /**
-   * Join community
+   * Joins an X Community through a connected account.
    *
    * @example
    * ```ts
-   * const join = await client.x.communities.join.create('id', {
-   *   account: '@elonmusk',
-   *   'Idempotency-Key': 'Idempotency-Key',
-   * });
+   * const join = await client.x.communities.join.create(
+   *   '1500000000000000000',
+   *   {
+   *     account: '@elonmusk',
+   *     'Idempotency-Key': 'Idempotency-Key',
+   *   },
+   * );
    * ```
    */
   create(id: string, params: JoinCreateParams, options?: RequestOptions): APIPromise<JoinCreateResponse> {
@@ -35,12 +38,12 @@ export class Join extends APIResource {
   }
 
   /**
-   * Leave community
+   * Leaves an X Community through a connected account.
    *
    * @example
    * ```ts
    * const response = await client.x.communities.join.deleteAll(
-   *   'id',
+   *   '1500000000000000000',
    *   {
    *     account: '@elonmusk',
    *     'Idempotency-Key': 'Idempotency-Key',
@@ -63,9 +66,9 @@ export class Join extends APIResource {
 }
 
 /**
- * Durable write lifecycle record. Poll statusUrl until terminal is true. Reusing
- * the original Idempotency-Key returns this same record. Submit a new write only
- * when safeToRetry is true, using a new key.
+ * Durable write record. Poll statusUrl until terminal is true. Reusing its
+ * Idempotency-Key returns this record. Create another action only when safeToRetry
+ * is true.
  */
 export interface JoinCreateResponse {
   id: string;
@@ -86,6 +89,7 @@ export interface JoinCreateResponse {
     | 'unfollow'
     | 'remove_follower'
     | 'send_dm'
+    | 'delete_dm'
     | 'upload_media'
     | 'update_profile'
     | 'update_avatar'
@@ -130,7 +134,7 @@ export interface JoinCreateResponse {
   retryable: boolean;
 
   /**
-   * True only when no write was dispatched and a new idempotency key may be used.
+   * True only when X did not get the write and a new idempotency key may be used.
    */
   safeToRetry: boolean;
 
@@ -186,6 +190,10 @@ export interface JoinCreateResponse {
    */
   expiresAt?: string;
 
+  /**
+   * True when this answers a retry of an earlier request with the same
+   * Idempotency-Key.
+   */
   idempotent?: boolean;
 
   /**
@@ -262,6 +270,9 @@ export namespace JoinCreateResponse {
   export interface NextAction {
     type: 'poll' | 'retry' | 'verify_result' | 'fix_request';
 
+    /**
+     * Milliseconds to wait before you poll or retry.
+     */
     afterMs?: number;
 
     requiresNewIdempotencyKey?: boolean;
@@ -306,9 +317,9 @@ export namespace JoinCreateResponse {
 }
 
 /**
- * Durable write lifecycle record. Poll statusUrl until terminal is true. Reusing
- * the original Idempotency-Key returns this same record. Submit a new write only
- * when safeToRetry is true, using a new key.
+ * Durable write record. Poll statusUrl until terminal is true. Reusing its
+ * Idempotency-Key returns this record. Create another action only when safeToRetry
+ * is true.
  */
 export interface JoinDeleteAllResponse {
   id: string;
@@ -329,6 +340,7 @@ export interface JoinDeleteAllResponse {
     | 'unfollow'
     | 'remove_follower'
     | 'send_dm'
+    | 'delete_dm'
     | 'upload_media'
     | 'update_profile'
     | 'update_avatar'
@@ -373,7 +385,7 @@ export interface JoinDeleteAllResponse {
   retryable: boolean;
 
   /**
-   * True only when no write was dispatched and a new idempotency key may be used.
+   * True only when X did not get the write and a new idempotency key may be used.
    */
   safeToRetry: boolean;
 
@@ -429,6 +441,10 @@ export interface JoinDeleteAllResponse {
    */
   expiresAt?: string;
 
+  /**
+   * True when this answers a retry of an earlier request with the same
+   * Idempotency-Key.
+   */
   idempotent?: boolean;
 
   /**
@@ -505,6 +521,9 @@ export namespace JoinDeleteAllResponse {
   export interface NextAction {
     type: 'poll' | 'retry' | 'verify_result' | 'fix_request';
 
+    /**
+     * Milliseconds to wait before you poll or retry.
+     */
     afterMs?: number;
 
     requiresNewIdempotencyKey?: boolean;
@@ -555,10 +574,12 @@ export interface JoinCreateParams {
   account: string;
 
   /**
-   * Header param: Generate one unique value for each intended write. Reuse it only
-   * when retrying the exact same account, action, target, and payload. A reused key
-   * returns the original action. Reusing it with different input returns 409. Replay
-   * protection remains active for at least 90 days.
+   * Header param: Use one unique value per intended write. Reuse it only for an
+   * identical retry. A matching retry returns the first answer again, with
+   * idempotent: true added. It keeps the first status, body & Retry-After. It sends
+   * nothing to X & charges nothing. While the first request runs, a retry returns
+   * 202 & the action. Different input returns 409. Protection lasts at least 90
+   * days.
    */
   'Idempotency-Key': string;
 }
@@ -570,10 +591,12 @@ export interface JoinDeleteAllParams {
   account: string;
 
   /**
-   * Header param: Generate one unique value for each intended write. Reuse it only
-   * when retrying the exact same account, action, target, and payload. A reused key
-   * returns the original action. Reusing it with different input returns 409. Replay
-   * protection remains active for at least 90 days.
+   * Header param: Use one unique value per intended write. Reuse it only for an
+   * identical retry. A matching retry returns the first answer again, with
+   * idempotent: true added. It keeps the first status, body & Retry-After. It sends
+   * nothing to X & charges nothing. While the first request runs, a retry returns
+   * 202 & the action. Different input returns 409. Protection lasts at least 90
+   * days.
    */
   'Idempotency-Key': string;
 }

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

@@ -0,0 +1,251 @@
+// 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 { APIResource } from '../../../core/resource';
+import * as Shared from '../../shared';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Find X Communities & read their info, members, posts & media
+ */
+export class Media extends APIResource {
+  /**
+   * Returns the tweets with photos or videos on one community's Media tab, newest
+   * first. Each tweet costs 1 credit.
+   *
+   * @example
+   * ```ts
+   * const paginatedTweets =
+   *   await client.x.communities.media.list('id');
+   * ```
+   */
+  list(
+    id: string,
+    query: MediaListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Shared.PaginatedTweets> {
+    return this._client.get(path`/x/communities/${id}/media`, { query, ...options });
+  }
+}
+
+export interface MediaListParams {
+  /**
+   * Words or quoted phrases where any one can match. Separate with spaces, commas,
+   * or lines.
+   */
+  anyWords?: string;
+
+  /**
+   * Only return tweets from Blue-verified authors.
+   */
+  blueVerifiedOnly?: boolean;
+
+  /**
+   * Cashtags separated by spaces, commas, or lines.
+   */
+  cashtags?: string;
+
+  /**
+   * Conversation ID filter.
+   */
+  conversationId?: string;
+
+  /**
+   * Pagination cursor for collection results. Also read as next_cursor, next_token,
+   * pagination_token or continuation_token.
+   */
+  cursor?: string;
+
+  /**
+   * Match this literal phrase, including any hyphens.
+   */
+  exactPhrase?: string;
+
+  /**
+   * Words or quoted phrases to exclude. Separate with spaces, commas, or lines.
+   */
+  excludeWords?: string;
+
+  /**
+   * Fields to keep in each row, comma-separated. Use dots for nested fields, such as
+   * author.username. A list keeps the field in each item. Case & underscores do not
+   * matter. A row that lacks a field leaves it out. Cursors, counts & diagnostics
+   * always stay. An unknown name answers 400 unknown_field with the valid names,
+   * before any read. The price stays the same. SDK row types then hold only the
+   * named fields.
+   */
+  fields?: string;
+
+  /**
+   * Filter by author username.
+   */
+  fromUser?: string;
+
+  /**
+   * Hashtags separated by spaces, commas, or lines.
+   */
+  hashtags?: string;
+
+  /**
+   * Only replies to this tweet ID.
+   */
+  inReplyToTweetId?: string;
+
+  /**
+   * Filter by language. Alias `lang` is accepted.
+   */
+  language?: string;
+
+  /**
+   * Maximum likes threshold. maxLikes & max_likes also work.
+   */
+  maxFaves?: number;
+
+  /**
+   * Return Tweets at or below this ID.
+   */
+  maxId?: string;
+
+  /**
+   * Maximum quotes threshold.
+   */
+  maxQuotes?: number;
+
+  /**
+   * Maximum replies threshold.
+   */
+  maxReplies?: number;
+
+  /**
+   * Maximum retweets threshold.
+   */
+  maxRetweets?: number;
+
+  /**
+   * Filter media. Aliases: has_video, has_media.
+   */
+  mediaType?: 'images' | 'videos' | 'gifs' | 'media' | 'links' | 'none';
+
+  /**
+   * Filter tweets mentioning a username.
+   */
+  mentioning?: string;
+
+  /**
+   * Minimum bookmark count threshold.
+   */
+  minBookmarks?: number;
+
+  /**
+   * Minimum likes. Aliases: minFaves, min_likes, min_faves.
+   */
+  minLikes?: number;
+
+  /**
+   * Minimum quote count threshold.
+   */
+  minQuotes?: number;
+
+  /**
+   * Minimum replies threshold.
+   */
+  minReplies?: number;
+
+  /**
+   * Minimum retweets threshold.
+   */
+  minRetweets?: number;
+
+  /**
+   * Minimum view count threshold.
+   */
+  minViews?: number;
+
+  /**
+   * Only return native reposts.
+   */
+  nativeRetweets?: boolean;
+
+  /**
+   * Fields to drop from each row, comma-separated. It takes the same names as
+   * fields. With fields, it drops from the kept fields.
+   */
+  omit?: string;
+
+  /**
+   * Items per page (1-100, default 20). Source, filters or credits can return fewer.
+   * Follow next_cursor for more pages. Aliases: limit, count, max_results, maxItems,
+   * max_items & per_page.
+   */
+  pageSize?: number;
+
+  /**
+   * Only when the caller requests a quote mode.
+   */
+  quotes?: 'include' | 'exclude' | 'only';
+
+  /**
+   * Only quotes of this tweet ID.
+   */
+  quotesOfTweetId?: string;
+
+  /**
+   * Reply mode. Exclude keeps own-thread replies.
+   */
+  replies?: 'include' | 'exclude' | 'only';
+
+  /**
+   * Only when the caller requests a repost mode.
+   */
+  retweets?: 'include' | 'exclude' | 'only';
+
+  /**
+   * Only retweets of this tweet ID.
+   */
+  retweetsOfTweetId?: string;
+
+  /**
+   * Start date in YYYY-MM-DD format, as a UTC day.
+   */
+  sinceDate?: string;
+
+  /**
+   * Return Tweets whose IDs exceed this ID.
+   */
+  sinceId?: string;
+
+  /**
+   * Filter replies sent to a username.
+   */
+  toUser?: string;
+
+  /**
+   * End date in YYYY-MM-DD format, as a UTC day, inclusive, so its own posts count.
+   */
+  untilDate?: string;
+
+  /**
+   * URL substring or domain filter.
+   */
+  url?: string;
+
+  /**
+   * Only return tweets from verified authors.
+   */
+  verifiedOnly?: boolean;
+
+  /**
+   * Keeps Tweets from a recent window, such as 90m or 7d. Use a whole number & s, m,
+   * h or d.
+   */
+  withinTime?: string;
+}
+
+export declare namespace Media {
+  export { type MediaListParams as MediaListParams };
+}