scrapebadger 0.3.0 → 0.4.0

package/dist/twitter/index.d.cts

@@ -1,2 +1,2 @@
-export { _ as ApiResponse, ae as BillingLog, af as BillingLogList, j as CommunitiesClient, J as Community, E as CommunityBanner, K as CommunityMember, F as CommunityRule, p as CommunityTweetType, ag as ConnectOptions, a6 as ConnectedEvent, a3 as CreateMonitorParams, ac as DeliveryLog, ad as DeliveryLogList, a9 as ErrorEvent, aj as FilterRuleCreate, ao as FilterRuleDeliveryLog, ap as FilterRuleDeliveryLogListResponse, am as FilterRuleListResponse, al as FilterRulePricingTier, aq as FilterRulePricingTiersResponse, ai as FilterRuleResponse, ah as FilterRuleStatus, ak as FilterRuleUpdate, an as FilterRuleValidateResponse, G as GeoClient, l as GeoSearchOptions, H as Hashtag, D as List, $ as ListResponse, L as ListsClient, X as Location, M as Media, a0 as MonitorStatus, a7 as PingEvent, Z as Place, Y as PlaceTrends, r as Poll, q as PollOption, Q as QueryType, m as StreamClient, n as StreamEmitter, aa as StreamEvent, ab as StreamEventType, a1 as StreamMonitor, a2 as StreamMonitorList, a5 as StreamTweet, O as Trend, o as TrendCategory, k as TrendsClient, w as Tweet, a8 as TweetEvent, u as TweetPlace, i as TweetsClient, T as TwitterClient, a4 as UpdateMonitorParams, s as Url, x as User, y as UserAbout, z as UserIds, t as UserMention, U as UsersClient, v as verifyWebhookSignature } from '../index-DQ_jDTcQ.cjs';
+export { a3 as ApiResponse, $ as Article, aj as BillingLog, ak as BillingLogList, a2 as Broadcast, j as CommunitiesClient, K as Community, F as CommunityBanner, O as CommunityMember, a0 as CommunityNote, J as CommunityRule, q as CommunityTweetType, al as ConnectOptions, ab as ConnectedEvent, a8 as CreateMonitorParams, ah as DeliveryLog, ai as DeliveryLogList, ae as ErrorEvent, ao as FilterRuleCreate, at as FilterRuleDeliveryLog, au as FilterRuleDeliveryLogListResponse, ar as FilterRuleListResponse, aq as FilterRulePricingTier, av as FilterRulePricingTiersResponse, an as FilterRuleResponse, am as FilterRuleStatus, ap as FilterRuleUpdate, as as FilterRuleValidateResponse, G as GeoClient, l as GeoSearchOptions, H as Hashtag, E as List, a4 as ListResponse, L as ListsClient, Y as Location, M as Media, a5 as MonitorStatus, ac as PingEvent, _ as Place, Z as PlaceTrends, s as Poll, r as PollOption, Q as QueryType, a1 as Space, o as SpacesClient, m as StreamClient, n as StreamEmitter, af as StreamEvent, ag as StreamEventType, a6 as StreamMonitor, a7 as StreamMonitorList, aa as StreamTweet, X as Trend, p as TrendCategory, k as TrendsClient, x as Tweet, ad as TweetEvent, w as TweetPlace, i as TweetsClient, T as TwitterClient, a9 as UpdateMonitorParams, t as Url, y as User, z as UserAbout, D as UserIds, u as UserMention, U as UsersClient, v as verifyWebhookSignature } from '../index-CIZUd1Zr.cjs';
 import 'node:events';

package/dist/twitter/index.d.ts

@@ -1,2 +1,2 @@
-export { _ as ApiResponse, ae as BillingLog, af as BillingLogList, j as CommunitiesClient, J as Community, E as CommunityBanner, K as CommunityMember, F as CommunityRule, p as CommunityTweetType, ag as ConnectOptions, a6 as ConnectedEvent, a3 as CreateMonitorParams, ac as DeliveryLog, ad as DeliveryLogList, a9 as ErrorEvent, aj as FilterRuleCreate, ao as FilterRuleDeliveryLog, ap as FilterRuleDeliveryLogListResponse, am as FilterRuleListResponse, al as FilterRulePricingTier, aq as FilterRulePricingTiersResponse, ai as FilterRuleResponse, ah as FilterRuleStatus, ak as FilterRuleUpdate, an as FilterRuleValidateResponse, G as GeoClient, l as GeoSearchOptions, H as Hashtag, D as List, $ as ListResponse, L as ListsClient, X as Location, M as Media, a0 as MonitorStatus, a7 as PingEvent, Z as Place, Y as PlaceTrends, r as Poll, q as PollOption, Q as QueryType, m as StreamClient, n as StreamEmitter, aa as StreamEvent, ab as StreamEventType, a1 as StreamMonitor, a2 as StreamMonitorList, a5 as StreamTweet, O as Trend, o as TrendCategory, k as TrendsClient, w as Tweet, a8 as TweetEvent, u as TweetPlace, i as TweetsClient, T as TwitterClient, a4 as UpdateMonitorParams, s as Url, x as User, y as UserAbout, z as UserIds, t as UserMention, U as UsersClient, v as verifyWebhookSignature } from '../index-DQ_jDTcQ.js';
+export { a3 as ApiResponse, $ as Article, aj as BillingLog, ak as BillingLogList, a2 as Broadcast, j as CommunitiesClient, K as Community, F as CommunityBanner, O as CommunityMember, a0 as CommunityNote, J as CommunityRule, q as CommunityTweetType, al as ConnectOptions, ab as ConnectedEvent, a8 as CreateMonitorParams, ah as DeliveryLog, ai as DeliveryLogList, ae as ErrorEvent, ao as FilterRuleCreate, at as FilterRuleDeliveryLog, au as FilterRuleDeliveryLogListResponse, ar as FilterRuleListResponse, aq as FilterRulePricingTier, av as FilterRulePricingTiersResponse, an as FilterRuleResponse, am as FilterRuleStatus, ap as FilterRuleUpdate, as as FilterRuleValidateResponse, G as GeoClient, l as GeoSearchOptions, H as Hashtag, E as List, a4 as ListResponse, L as ListsClient, Y as Location, M as Media, a5 as MonitorStatus, ac as PingEvent, _ as Place, Z as PlaceTrends, s as Poll, r as PollOption, Q as QueryType, a1 as Space, o as SpacesClient, m as StreamClient, n as StreamEmitter, af as StreamEvent, ag as StreamEventType, a6 as StreamMonitor, a7 as StreamMonitorList, aa as StreamTweet, X as Trend, p as TrendCategory, k as TrendsClient, x as Tweet, ad as TweetEvent, w as TweetPlace, i as TweetsClient, T as TwitterClient, a9 as UpdateMonitorParams, t as Url, y as User, z as UserAbout, D as UserIds, u as UserMention, U as UsersClient, v as verifyWebhookSignature } from '../index-CIZUd1Zr.js';
 import 'node:events';

package/dist/twitter/index.js

@@ -16,12 +16,26 @@ function createPaginatedResponse(data, cursor) {
     hasMore: !!cursor
   };
 }
+var RATE_LIMIT_WARN_THRESHOLD = 0.2;
 async function* paginate(fetchPage, options = {}) {
   const { maxItems } = options;
   let cursor;
   let totalYielded = 0;
   do {
-    const response = await fetchPage(cursor);
+    const { response, rateLimit } = await fetchPage(cursor);
+    if (rateLimit) {
+      const { limit, remaining, reset } = rateLimit;
+      if (limit > 0 && remaining / limit < RATE_LIMIT_WARN_THRESHOLD) {
+        const nowSec = Date.now() / 1e3;
+        const windowRemainingSec = Math.max(reset - nowSec, 1);
+        const delayMs = remaining > 0 ? windowRemainingSec / remaining * 1e3 : windowRemainingSec * 1e3;
+        const resetInSec = Math.round(windowRemainingSec);
+        console.warn(
+          `\x1B[33m\u26A0 ScrapeBadger: Rate limit: ${remaining}/${limit} remaining (resets in ${resetInSec}s), throttling pagination\x1B[0m`
+        );
+        await sleep(delayMs);
+      }
+    }
     for (const item of response.data) {
       yield item;
       totalYielded++;
@@ -32,6 +46,9 @@ async function* paginate(fetchPage, options = {}) {
     cursor = response.nextCursor;
   } while (cursor);
 }
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 // src/twitter/tweets.ts
 var TweetsClient = class {
@@ -229,7 +246,8 @@ var TweetsClient = class {
    */
   async *getQuotesAll(tweetId, options = {}) {
     const fetchPage = async (cursor) => {
-      return this.getQuotes(tweetId, { ...options, cursor });
+      const { data, rateLimit } = await this.client.requestWithHeaders(`/v1/twitter/tweets/tweet/${tweetId}/quotes`, { params: { cursor } });
+      return { response: createPaginatedResponse(data.data ?? [], data.next_cursor), rateLimit };
     };
     yield* paginate(fetchPage, options);
   }
@@ -296,7 +314,15 @@ var TweetsClient = class {
    */
   async *searchAll(query, options = {}) {
     const fetchPage = async (cursor) => {
-      return this.search(query, { ...options, cursor });
+      const { data, rateLimit } = await this.client.requestWithHeaders("/v1/twitter/tweets/advanced_search", {
+        params: {
+          query,
+          query_type: options.queryType ?? "Top",
+          count: options.count,
+          cursor
+        }
+      });
+      return { response: createPaginatedResponse(data.data ?? [], data.next_cursor), rateLimit };
     };
     yield* paginate(fetchPage, options);
   }
@@ -340,10 +366,64 @@ var TweetsClient = class {
    */
   async *getUserTweetsAll(username, options = {}) {
     const fetchPage = async (cursor) => {
-      return this.getUserTweets(username, { ...options, cursor });
+      const { data, rateLimit } = await this.client.requestWithHeaders(`/v1/twitter/users/${username}/latest_tweets`, { params: { cursor } });
+      return { response: createPaginatedResponse(data.data ?? [], data.next_cursor), rateLimit };
     };
     yield* paginate(fetchPage, options);
   }
+  /**
+   * Get the edit history of a tweet.
+   *
+   * @param tweetId - The tweet ID to get edit history for.
+   * @returns Paginated response containing tweet versions.
+   *
+   * @example
+   * ```typescript
+   * const history = await client.twitter.tweets.getEditHistory("1234567890");
+   * console.log(`${history.data.length} version(s) of this tweet`);
+   * ```
+   */
+  async getEditHistory(tweetId) {
+    const response = await this.client.request(
+      `/v1/twitter/tweets/tweet/${tweetId}/edit_history`
+    );
+    return createPaginatedResponse(response.data ?? [], void 0);
+  }
+  /**
+   * Get community notes (Birdwatch) attached to a tweet.
+   *
+   * @param tweetId - The tweet ID to get community notes for.
+   * @returns Paginated response containing community notes.
+   *
+   * @example
+   * ```typescript
+   * const notes = await client.twitter.tweets.getCommunityNotes("1234567890");
+   * for (const note of notes.data) {
+   *   console.log(note.text);
+   * }
+   * ```
+   */
+  async getCommunityNotes(tweetId) {
+    const response = await this.client.request(
+      `/v1/twitter/tweets/tweet/${tweetId}/community_notes`
+    );
+    return createPaginatedResponse(response.data ?? [], void 0);
+  }
+  /**
+   * Get a long-form article by its ID.
+   *
+   * @param articleId - The article ID to fetch.
+   * @returns The article data.
+   *
+   * @example
+   * ```typescript
+   * const article = await client.twitter.tweets.getArticle("abc123");
+   * console.log(`${article.title}: ${article.text?.slice(0, 100)}...`);
+   * ```
+   */
+  async getArticle(articleId) {
+    return this.client.request(`/v1/twitter/tweets/article/${articleId}`);
+  }
 };
 
 // src/twitter/users.ts
@@ -450,7 +530,8 @@ var UsersClient = class {
    */
   async *getFollowersAll(username, options = {}) {
     const fetchPage = async (cursor) => {
-      return this.getFollowers(username, { ...options, cursor });
+      const { data, rateLimit } = await this.client.requestWithHeaders(`/v1/twitter/users/${username}/followers`, { params: { cursor } });
+      return { response: createPaginatedResponse(data.data ?? [], data.next_cursor), rateLimit };
     };
     yield* paginate(fetchPage, options);
   }
@@ -485,7 +566,8 @@ var UsersClient = class {
    */
   async *getFollowingAll(username, options = {}) {
     const fetchPage = async (cursor) => {
-      return this.getFollowing(username, { ...options, cursor });
+      const { data, rateLimit } = await this.client.requestWithHeaders(`/v1/twitter/users/${username}/followings`, { params: { cursor } });
+      return { response: createPaginatedResponse(data.data ?? [], data.next_cursor), rateLimit };
     };
     yield* paginate(fetchPage, options);
   }
@@ -648,10 +730,97 @@ var UsersClient = class {
    */
   async *searchAll(query, options = {}) {
     const fetchPage = async (cursor) => {
-      return this.search(query, { ...options, cursor });
+      const { data, rateLimit } = await this.client.requestWithHeaders("/v1/twitter/users/search_users", { params: { query, cursor } });
+      return { response: createPaginatedResponse(data.data ?? [], data.next_cursor), rateLimit };
     };
     yield* paginate(fetchPage, options);
   }
+  /**
+   * Get multiple users by their numeric IDs in a single request.
+   *
+   * @param userIds - List of user IDs to fetch.
+   * @returns Paginated response containing the matching users.
+   *
+   * @example
+   * ```typescript
+   * const users = await client.twitter.users.getByIds(["44196397", "783214"]);
+   * for (const user of users.data) {
+   *   console.log(`@${user.username}`);
+   * }
+   * ```
+   */
+  async getByIds(userIds) {
+    const response = await this.client.request(
+      "/v1/twitter/users/batch_by_ids",
+      { params: { user_ids: userIds.join(",") } }
+    );
+    return createPaginatedResponse(response.data ?? [], void 0);
+  }
+  /**
+   * Get multiple users by their usernames in a single request.
+   *
+   * @param usernames - List of usernames (without @) to fetch.
+   * @returns Paginated response containing the matching users.
+   *
+   * @example
+   * ```typescript
+   * const users = await client.twitter.users.getByUsernames(["elonmusk", "twitter"]);
+   * for (const user of users.data) {
+   *   console.log(`${user.name}: ${user.followers_count?.toLocaleString()} followers`);
+   * }
+   * ```
+   */
+  async getByUsernames(usernames) {
+    const response = await this.client.request(
+      "/v1/twitter/users/batch_by_usernames",
+      { params: { usernames: usernames.join(",") } }
+    );
+    return createPaginatedResponse(response.data ?? [], void 0);
+  }
+  /**
+   * Get tweets that mention a user.
+   *
+   * @param username - The user's username (without @).
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing tweets mentioning the user.
+   *
+   * @example
+   * ```typescript
+   * const mentions = await client.twitter.users.getMentions("elonmusk");
+   * for (const tweet of mentions.data) {
+   *   console.log(`@${tweet.username}: ${tweet.text.slice(0, 100)}...`);
+   * }
+   * ```
+   */
+  async getMentions(username, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${username}/mentions`,
+      { params: { count: options.count, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get long-form articles authored by a user.
+   *
+   * @param userId - The user's numeric ID.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing the user's articles as tweets.
+   *
+   * @example
+   * ```typescript
+   * const articles = await client.twitter.users.getArticles("44196397");
+   * for (const article of articles.data) {
+   *   console.log(article.text?.slice(0, 100));
+   * }
+   * ```
+   */
+  async getArticles(userId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${userId}/articles`,
+      { params: { count: options.count, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
 };
 
 // src/twitter/lists.ts
@@ -708,7 +877,8 @@ var ListsClient = class {
    */
   async *getTweetsAll(listId, options = {}) {
     const fetchPage = async (cursor) => {
-      return this.getTweets(listId, { ...options, cursor });
+      const { data, rateLimit } = await this.client.requestWithHeaders(`/v1/twitter/lists/${listId}/tweets`, { params: { cursor } });
+      return { response: createPaginatedResponse(data.data ?? [], data.next_cursor), rateLimit };
     };
     yield* paginate(fetchPage, options);
   }
@@ -743,7 +913,8 @@ var ListsClient = class {
    */
   async *getMembersAll(listId, options = {}) {
     const fetchPage = async (cursor) => {
-      return this.getMembers(listId, { ...options, cursor });
+      const { data, rateLimit } = await this.client.requestWithHeaders(`/v1/twitter/lists/${listId}/members`, { params: { cursor } });
+      return { response: createPaginatedResponse(data.data ?? [], data.next_cursor), rateLimit };
     };
     yield* paginate(fetchPage, options);
   }
@@ -796,6 +967,29 @@ var ListsClient = class {
     );
     return createPaginatedResponse(response.data ?? [], response.next_cursor);
   }
+  /**
+   * Search tweets within a specific list.
+   *
+   * @param listId - The list ID to search within.
+   * @param query - Search query string.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing matching tweets from the list.
+   *
+   * @example
+   * ```typescript
+   * const results = await client.twitter.lists.searchTweets("123456", "python");
+   * for (const tweet of results.data) {
+   *   console.log(`@${tweet.username}: ${tweet.text.slice(0, 100)}...`);
+   * }
+   * ```
+   */
+  async searchTweets(listId, query, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/lists/${listId}/search_tweets`,
+      { params: { query, count: options.count, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
 };
 
 // src/twitter/communities.ts
@@ -891,7 +1085,14 @@ var CommunitiesClient = class {
    */
   async *getTweetsAll(communityId, options = {}) {
     const fetchPage = async (cursor) => {
-      return this.getTweets(communityId, { ...options, cursor });
+      const { data, rateLimit } = await this.client.requestWithHeaders(`/v1/twitter/communities/${communityId}/tweets`, {
+        params: {
+          tweet_type: options.tweetType ?? "Top",
+          count: options.count ?? 40,
+          cursor
+        }
+      });
+      return { response: createPaginatedResponse(data.data ?? [], data.next_cursor), rateLimit };
     };
     yield* paginate(fetchPage, options);
   }
@@ -1831,6 +2032,46 @@ function verifyWebhookSignature(secret, body, signatureHeader) {
   }
 }
 
+// src/twitter/spaces.ts
+var SpacesClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get details for a specific Twitter Space.
+   *
+   * @param spaceId - The Space ID to fetch.
+   * @returns The Space data.
+   * @throws NotFoundError - If the Space doesn't exist.
+   *
+   * @example
+   * ```typescript
+   * const space = await client.twitter.spaces.getDetail("1eaKbrPPbPwKX");
+   * console.log(`${space.title} — ${space.participant_count} participants`);
+   * ```
+   */
+  async getDetail(spaceId) {
+    return this.client.request(`/v1/twitter/spaces/${spaceId}`);
+  }
+  /**
+   * Get details for a live video broadcast.
+   *
+   * @param broadcastId - The broadcast ID to fetch.
+   * @returns The broadcast data.
+   * @throws NotFoundError - If the broadcast doesn't exist.
+   *
+   * @example
+   * ```typescript
+   * const broadcast = await client.twitter.spaces.getBroadcast("broadcast123");
+   * console.log(`${broadcast.title}: ${broadcast.total_viewers} viewers`);
+   * ```
+   */
+  async getBroadcast(broadcastId) {
+    return this.client.request(`/v1/twitter/spaces/broadcast/${broadcastId}`);
+  }
+};
+
 // src/twitter/client.ts
 var TwitterClient = class {
   /** Client for tweet operations */
@@ -1847,6 +2088,8 @@ var TwitterClient = class {
   geo;
   /** Client for real-time stream monitor management and WebSocket streaming */
   stream;
+  /** Client for Twitter Spaces and live broadcast operations */
+  spaces;
   /**
    * Create a new Twitter client.
    *
@@ -1860,12 +2103,14 @@ var TwitterClient = class {
     this.trends = new TrendsClient(client);
     this.geo = new GeoClient(client);
     this.stream = new StreamClient(client);
+    this.spaces = new SpacesClient(client);
   }
 };
 
 exports.CommunitiesClient = CommunitiesClient;
 exports.GeoClient = GeoClient;
 exports.ListsClient = ListsClient;
+exports.SpacesClient = SpacesClient;
 exports.StreamClient = StreamClient;
 exports.TrendsClient = TrendsClient;
 exports.TweetsClient = TweetsClient;