x-twitter-scraper 0.1.0 → 0.2.1

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

@@ -1,12 +1,12 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../../core/resource';
+import * as Shared from '../../shared';
 import * as JoinAPI from './join';
 import { Join, JoinCreateParams, JoinDeleteAllParams } from './join';
 import * as TweetsAPI from './tweets';
-import { TweetListParams, Tweets } from './tweets';
+import { TweetListByCommunityParams, TweetListParams, Tweets } from './tweets';
 import { APIPromise } from '../../../core/api-promise';
-import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
@@ -16,6 +16,15 @@ export class Communities extends APIResource {
 
   /**
    * Create community
+   *
+   * @example
+   * ```ts
+   * const community = await client.x.communities.create({
+   *   account: '@elonmusk',
+   *   name: 'Example Name',
+   *   description: 'A community for Tesla enthusiasts',
+   * });
+   * ```
    */
   create(body: CommunityCreateParams, options?: RequestOptions): APIPromise<CommunityCreateResponse> {
     return this._client.post('/x/communities', { body, ...options });
@@ -23,6 +32,14 @@ export class Communities extends APIResource {
 
   /**
    * Delete community
+   *
+   * @example
+   * ```ts
+   * const community = await client.x.communities.delete('id', {
+   *   account: '@elonmusk',
+   *   community_name: 'Tesla Fans',
+   * });
+   * ```
    */
   delete(
     id: string,
@@ -34,6 +51,13 @@ export class Communities extends APIResource {
 
   /**
    * Get community details
+   *
+   * @example
+   * ```ts
+   * const response = await client.x.communities.retrieveInfo(
+   *   'id',
+   * );
+   * ```
    */
   retrieveInfo(id: string, options?: RequestOptions): APIPromise<CommunityRetrieveInfoResponse> {
     return this._client.get(path`/x/communities/${id}/info`, options);
@@ -41,46 +65,58 @@ export class Communities extends APIResource {
 
   /**
    * Get community members
+   *
+   * @example
+   * ```ts
+   * const paginatedUsers =
+   *   await client.x.communities.retrieveMembers('id');
+   * ```
    */
   retrieveMembers(
     id: string,
     query: CommunityRetrieveMembersParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<void> {
-    return this._client.get(path`/x/communities/${id}/members`, {
-      query,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  ): APIPromise<Shared.PaginatedUsers> {
+    return this._client.get(path`/x/communities/${id}/members`, { query, ...options });
   }
 
   /**
    * Get community moderators
+   *
+   * @example
+   * ```ts
+   * const paginatedUsers =
+   *   await client.x.communities.retrieveModerators('id');
+   * ```
    */
   retrieveModerators(
     id: string,
     query: CommunityRetrieveModeratorsParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<void> {
-    return this._client.get(path`/x/communities/${id}/moderators`, {
-      query,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  ): APIPromise<Shared.PaginatedUsers> {
+    return this._client.get(path`/x/communities/${id}/moderators`, { query, ...options });
   }
 
   /**
    * Search tweets across communities
+   *
+   * @example
+   * ```ts
+   * const paginatedTweets =
+   *   await client.x.communities.retrieveSearch({ q: 'q' });
+   * ```
    */
-  retrieveSearch(query: CommunityRetrieveSearchParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.get('/x/communities/search', {
-      query,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  retrieveSearch(
+    query: CommunityRetrieveSearchParams,
+    options?: RequestOptions,
+  ): APIPromise<Shared.PaginatedTweets> {
+    return this._client.get('/x/communities/search', { query, ...options });
   }
 }
 
+/**
+ * Result of a community join or leave action.
+ */
 export interface CommunityActionResult {
   communityId: string;
 
@@ -105,12 +141,88 @@ export interface CommunityRetrieveInfoResponse {
   /**
    * Community info object
    */
-  community: unknown;
+  community: CommunityRetrieveInfoResponse.Community;
+}
+
+export namespace CommunityRetrieveInfoResponse {
+  /**
+   * Community info object
+   */
+  export interface Community {
+    /**
+     * Unique community identifier
+     */
+    id: string;
+
+    /**
+     * Community banner image URL
+     */
+    banner_url?: string;
+
+    /**
+     * Community creation timestamp
+     */
+    created_at?: string;
+
+    /**
+     * About text for the community
+     */
+    description?: string;
+
+    /**
+     * Join policy (open or restricted)
+     */
+    join_policy?: string;
+
+    /**
+     * Total member count
+     */
+    member_count?: number;
+
+    /**
+     * Total moderator count
+     */
+    moderator_count?: number;
+
+    /**
+     * Display name of the community
+     */
+    name?: string;
+
+    /**
+     * Primary topic
+     */
+    primary_topic?: Community.PrimaryTopic;
+
+    /**
+     * Community rules
+     */
+    rules?: Array<Community.Rule>;
+  }
+
+  export namespace Community {
+    /**
+     * Primary topic
+     */
+    export interface PrimaryTopic {
+      id?: string;
+
+      name?: string;
+    }
+
+    export interface Rule {
+      id?: string;
+
+      description?: string;
+
+      name?: string;
+    }
+  }
 }
 
 export interface CommunityCreateParams {
   /**
-   * X account (@username or account ID)
+   * X account (@username or ID) creating the community
    */
   account: string;
 
@@ -127,7 +239,7 @@ export interface CommunityCreateParams {
 
 export interface CommunityDeleteParams {
   /**
-   * X account (@username or account ID)
+   * X account (@username or ID) deleting the community
    */
   account: string;
 
@@ -146,7 +258,7 @@ export interface CommunityRetrieveMembersParams {
 
 export interface CommunityRetrieveModeratorsParams {
   /**
-   * Pagination cursor
+   * Pagination cursor for community moderators
    */
   cursor?: string;
 }
@@ -158,7 +270,7 @@ export interface CommunityRetrieveSearchParams {
   q: string;
 
   /**
-   * Pagination cursor
+   * Pagination cursor for community search
    */
   cursor?: string;
 
@@ -190,5 +302,9 @@ export declare namespace Communities {
     type JoinDeleteAllParams as JoinDeleteAllParams,
   };
 
-  export { Tweets as Tweets, type TweetListParams as TweetListParams };
+  export {
+    Tweets as Tweets,
+    type TweetListParams as TweetListParams,
+    type TweetListByCommunityParams as TweetListByCommunityParams,
+  };
 }

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

@@ -13,4 +13,4 @@ export {
   type CommunityRetrieveSearchParams,
 } from './communities';
 export { Join, type JoinCreateParams, type JoinDeleteAllParams } from './join';
-export { Tweets, type TweetListParams } from './tweets';
+export { Tweets, type TweetListParams, type TweetListByCommunityParams } from './tweets';

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

@@ -12,6 +12,14 @@ import { path } from '../../../internal/utils/path';
 export class Join extends APIResource {
   /**
    * Join community
+   *
+   * @example
+   * ```ts
+   * const communityActionResult =
+   *   await client.x.communities.join.create('id', {
+   *     account: '@elonmusk',
+   *   });
+   * ```
    */
   create(
     id: string,
@@ -23,6 +31,14 @@ export class Join extends APIResource {
 
   /**
    * Leave community
+   *
+   * @example
+   * ```ts
+   * const communityActionResult =
+   *   await client.x.communities.join.deleteAll('id', {
+   *     account: '@elonmusk',
+   *   });
+   * ```
    */
   deleteAll(
     id: string,
@@ -35,14 +51,14 @@ export class Join extends APIResource {
 
 export interface JoinCreateParams {
   /**
-   * X account (@username or account ID)
+   * X account identifier (@username or account ID)
    */
   account: string;
 }
 
 export interface JoinDeleteAllParams {
   /**
-   * X account (@username or account ID)
+   * X account identifier (@username or account ID)
    */
   account: string;
 }

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

@@ -1,9 +1,10 @@
 // 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 { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
 
 /**
  * X data lookups (subscription required)
@@ -11,33 +12,62 @@ import { RequestOptions } from '../../../internal/request-options';
 export class Tweets extends APIResource {
   /**
    * Search tweets across all communities
+   *
+   * @example
+   * ```ts
+   * const paginatedTweets =
+   *   await client.x.communities.tweets.list({ q: 'q' });
+   * ```
    */
-  list(query: TweetListParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.get('/x/communities/tweets', {
-      query,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  list(query: TweetListParams, options?: RequestOptions): APIPromise<Shared.PaginatedTweets> {
+    return this._client.get('/x/communities/tweets', { query, ...options });
+  }
+
+  /**
+   * Get community tweets
+   *
+   * @example
+   * ```ts
+   * const paginatedTweets =
+   *   await client.x.communities.tweets.listByCommunity('id');
+   * ```
+   */
+  listByCommunity(
+    id: string,
+    query: TweetListByCommunityParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Shared.PaginatedTweets> {
+    return this._client.get(path`/x/communities/${id}/tweets`, { query, ...options });
   }
 }
 
 export interface TweetListParams {
   /**
-   * Search query
+   * Search query for cross-community tweets
    */
   q: string;
 
   /**
-   * Pagination cursor
+   * Pagination cursor for cross-community results
    */
   cursor?: string;
 
   /**
-   * Sort order (Latest or Top)
+   * Sort order for cross-community results (Latest or Top)
    */
   queryType?: string;
 }
 
+export interface TweetListByCommunityParams {
+  /**
+   * Pagination cursor for community tweets
+   */
+  cursor?: string;
+}
+
 export declare namespace Tweets {
-  export { type TweetListParams as TweetListParams };
+  export {
+    type TweetListParams as TweetListParams,
+    type TweetListByCommunityParams as TweetListByCommunityParams,
+  };
 }

package/src/resources/x/dm.ts

@@ -8,6 +8,13 @@ import { path } from '../../internal/utils/path';
 export class Dm extends APIResource {
   /**
    * Get DM conversation history
+   *
+   * @example
+   * ```ts
+   * const response = await client.x.dm.retrieveHistory(
+   *   'userId',
+   * );
+   * ```
    */
   retrieveHistory(
     userID: string,
@@ -19,6 +26,16 @@ export class Dm extends APIResource {
 
   /**
    * Send direct message
+   *
+   * @example
+   * ```ts
+   * const response = await client.x.dm.send('userId', {
+   *   account: '@elonmusk',
+   *   text: 'Example text content',
+   *   media_ids: ['1234567890123456789'],
+   *   reply_to_message_id: '1234567890123456789',
+   * });
+   * ```
    */
   send(userID: string, body: DmSendParams, options?: RequestOptions): APIPromise<DmSendResponse> {
     return this._client.post(path`/x/dm/${userID}`, { body, ...options });
@@ -55,7 +72,7 @@ export interface DmSendResponse {
 
 export interface DmRetrieveHistoryParams {
   /**
-   * Pagination cursor from previous response
+   * Pagination cursor for DM history
    */
   cursor?: string;
 
@@ -67,7 +84,7 @@ export interface DmRetrieveHistoryParams {
 
 export interface DmSendParams {
   /**
-   * X account (@username or account ID)
+   * X account (@username or ID) sending the DM
    */
   account: string;
 

package/src/resources/x/followers.ts

@@ -10,6 +10,14 @@ import { RequestOptions } from '../../internal/request-options';
 export class Followers extends APIResource {
   /**
    * Check follow relationship
+   *
+   * @example
+   * ```ts
+   * const response = await client.x.followers.check({
+   *   source: 'source',
+   *   target: 'target',
+   * });
+   * ```
    */
   check(query: FollowerCheckParams, options?: RequestOptions): APIPromise<FollowerCheckResponse> {
     return this._client.get('/x/followers/check', { query, ...options });

package/src/resources/x/index.ts

@@ -7,6 +7,7 @@ export {
   type AccountCreateResponse,
   type AccountListResponse,
   type AccountDeleteResponse,
+  type AccountBulkRetryResponse,
   type AccountReauthResponse,
   type AccountCreateParams,
   type AccountReauthParams,
@@ -90,6 +91,7 @@ export {
   X,
   type XGetArticleResponse,
   type XGetNotificationsResponse,
+  type XGetTrendsResponse,
   type XGetHomeTimelineParams,
   type XGetNotificationsParams,
 } from './x';

package/src/resources/x/lists.ts

@@ -1,8 +1,8 @@
 // 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 { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
@@ -12,67 +12,75 @@ import { path } from '../../internal/utils/path';
 export class Lists extends APIResource {
   /**
    * Get list followers
+   *
+   * @example
+   * ```ts
+   * const paginatedUsers =
+   *   await client.x.lists.retrieveFollowers('id');
+   * ```
    */
   retrieveFollowers(
     id: string,
     query: ListRetrieveFollowersParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<void> {
-    return this._client.get(path`/x/lists/${id}/followers`, {
-      query,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  ): APIPromise<Shared.PaginatedUsers> {
+    return this._client.get(path`/x/lists/${id}/followers`, { query, ...options });
   }
 
   /**
    * Get list members
+   *
+   * @example
+   * ```ts
+   * const paginatedUsers = await client.x.lists.retrieveMembers(
+   *   'id',
+   * );
+   * ```
    */
   retrieveMembers(
     id: string,
     query: ListRetrieveMembersParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<void> {
-    return this._client.get(path`/x/lists/${id}/members`, {
-      query,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  ): APIPromise<Shared.PaginatedUsers> {
+    return this._client.get(path`/x/lists/${id}/members`, { query, ...options });
   }
 
   /**
    * Get list tweets
+   *
+   * @example
+   * ```ts
+   * const paginatedTweets = await client.x.lists.retrieveTweets(
+   *   'id',
+   * );
+   * ```
    */
   retrieveTweets(
     id: string,
     query: ListRetrieveTweetsParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<void> {
-    return this._client.get(path`/x/lists/${id}/tweets`, {
-      query,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  ): APIPromise<Shared.PaginatedTweets> {
+    return this._client.get(path`/x/lists/${id}/tweets`, { query, ...options });
   }
 }
 
 export interface ListRetrieveFollowersParams {
   /**
-   * Pagination cursor
+   * Pagination cursor for list followers
    */
   cursor?: string;
 }
 
 export interface ListRetrieveMembersParams {
   /**
-   * Pagination cursor
+   * Pagination cursor for list members
    */
   cursor?: string;
 }
 
 export interface ListRetrieveTweetsParams {
   /**
-   * Pagination cursor
+   * Pagination cursor for list tweets
    */
   cursor?: string;
 

package/src/resources/x/media.ts

@@ -12,6 +12,13 @@ import { multipartFormRequestOptions } from '../../internal/uploads';
 export class Media extends APIResource {
   /**
    * Download tweet media
+   *
+   * @example
+   * ```ts
+   * const response = await client.x.media.download({
+   *   tweetInput: 'https://x.com/elonmusk/status/1234567890',
+   * });
+   * ```
    */
   download(body: MediaDownloadParams, options?: RequestOptions): APIPromise<MediaDownloadResponse> {
     return this._client.post('/x/media/download', { body, ...options });
@@ -19,6 +26,15 @@ export class Media extends APIResource {
 
   /**
    * Upload media
+   *
+   * @example
+   * ```ts
+   * const response = await client.x.media.upload({
+   *   account: '@elonmusk',
+   *   file: fs.createReadStream('path/to/file'),
+   *   is_long_video: true,
+   * });
+   * ```
    */
   upload(body: MediaUploadParams, options?: RequestOptions): APIPromise<MediaUploadResponse> {
     return this._client.post('/x/media', multipartFormRequestOptions({ body, ...options }, this._client));
@@ -57,7 +73,7 @@ export interface MediaDownloadParams {
 
 export interface MediaUploadParams {
   /**
-   * X account (@username or account ID)
+   * X account (@username or ID) uploading media
    */
   account: string;
 

package/src/resources/x/profile.ts

@@ -12,6 +12,17 @@ import { multipartFormRequestOptions } from '../../internal/uploads';
 export class Profile extends APIResource {
   /**
    * Update X profile
+   *
+   * @example
+   * ```ts
+   * const profile = await client.x.profile.update({
+   *   account: '@elonmusk',
+   *   description: 'description_value',
+   *   location: 'location_value',
+   *   name: 'Example Name',
+   *   url: 'https://xquik.com/example',
+   * });
+   * ```
    */
   update(body: ProfileUpdateParams, options?: RequestOptions): APIPromise<ProfileUpdateResponse> {
     return this._client.patch('/x/profile', { body, ...options });
@@ -19,6 +30,14 @@ export class Profile extends APIResource {
 
   /**
    * Update profile avatar
+   *
+   * @example
+   * ```ts
+   * const response = await client.x.profile.updateAvatar({
+   *   account: '@elonmusk',
+   *   file: fs.createReadStream('path/to/file'),
+   * });
+   * ```
    */
   updateAvatar(
     body: ProfileUpdateAvatarParams,
@@ -32,6 +51,14 @@ export class Profile extends APIResource {
 
   /**
    * Update profile banner
+   *
+   * @example
+   * ```ts
+   * const response = await client.x.profile.updateBanner({
+   *   account: '@elonmusk',
+   *   file: fs.createReadStream('path/to/file'),
+   * });
+   * ```
    */
   updateBanner(
     body: ProfileUpdateBannerParams,
@@ -58,7 +85,7 @@ export interface ProfileUpdateBannerResponse {
 
 export interface ProfileUpdateParams {
   /**
-   * X account (@username or account ID)
+   * X account (@username or ID) to update profile
    */
   account: string;
 
@@ -82,7 +109,7 @@ export interface ProfileUpdateParams {
 
 export interface ProfileUpdateAvatarParams {
   /**
-   * X account (@username or account ID)
+   * X account (@username or ID) for avatar update
    */
   account: string;
 
@@ -94,7 +121,7 @@ export interface ProfileUpdateAvatarParams {
 
 export interface ProfileUpdateBannerParams {
   /**
-   * X account (@username or account ID)
+   * X account (@username or ID) for banner update
    */
   account: string;