scrapebadger 0.1.0

package/dist/twitter/index.mjs

@@ -0,0 +1,1105 @@
+// src/internal/pagination.ts
+function createPaginatedResponse(data, cursor) {
+  return {
+    data,
+    nextCursor: cursor,
+    hasMore: !!cursor
+  };
+}
+async function* paginate(fetchPage, options = {}) {
+  const { maxItems } = options;
+  let cursor;
+  let totalYielded = 0;
+  do {
+    const response = await fetchPage(cursor);
+    for (const item of response.data) {
+      yield item;
+      totalYielded++;
+      if (maxItems !== void 0 && totalYielded >= maxItems) {
+        return;
+      }
+    }
+    cursor = response.nextCursor;
+  } while (cursor);
+}
+
+// src/twitter/tweets.ts
+var TweetsClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get a single tweet by ID.
+   *
+   * @param tweetId - The tweet ID to fetch.
+   * @returns The tweet data.
+   * @throws NotFoundError - If the tweet doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const tweet = await client.twitter.tweets.getById("1234567890");
+   * console.log(`@${tweet.username}: ${tweet.text}`);
+   * ```
+   */
+  async getById(tweetId) {
+    return this.client.request(`/v1/twitter/tweets/tweet/${tweetId}`);
+  }
+  /**
+   * Get multiple tweets by their IDs.
+   *
+   * @param tweetIds - List of tweet IDs to fetch.
+   * @returns Paginated response containing the tweets.
+   *
+   * @example
+   * ```typescript
+   * const tweets = await client.twitter.tweets.getByIds([
+   *   "1234567890",
+   *   "0987654321"
+   * ]);
+   * for (const tweet of tweets.data) {
+   *   console.log(tweet.text);
+   * }
+   * ```
+   */
+  async getByIds(tweetIds) {
+    const tweetsParam = tweetIds.join(",");
+    const response = await this.client.request(
+      "/v1/twitter/tweets/",
+      { params: { tweets: tweetsParam } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get replies to a tweet.
+   *
+   * @param tweetId - The tweet ID to get replies for.
+   * @param options - Pagination options.
+   * @returns Paginated response containing reply tweets.
+   *
+   * @example
+   * ```typescript
+   * const replies = await client.twitter.tweets.getReplies("1234567890");
+   * for (const reply of replies.data) {
+   *   console.log(`@${reply.username}: ${reply.text}`);
+   * }
+   *
+   * // Get next page
+   * if (replies.hasMore) {
+   *   const more = await client.twitter.tweets.getReplies("1234567890", {
+   *     cursor: replies.nextCursor
+   *   });
+   * }
+   * ```
+   */
+  async getReplies(tweetId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/tweets/tweet/${tweetId}/replies`,
+      { params: { cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get users who retweeted a tweet.
+   *
+   * @param tweetId - The tweet ID to get retweeters for.
+   * @param options - Pagination options.
+   * @returns Paginated response containing users who retweeted.
+   *
+   * @example
+   * ```typescript
+   * const retweeters = await client.twitter.tweets.getRetweeters("1234567890");
+   * for (const user of retweeters.data) {
+   *   console.log(`@${user.username} retweeted`);
+   * }
+   * ```
+   */
+  async getRetweeters(tweetId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/tweets/tweet/${tweetId}/retweeters`,
+      { params: { cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get users who liked/favorited a tweet.
+   *
+   * @param tweetId - The tweet ID to get favoriters for.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing users who liked.
+   *
+   * @example
+   * ```typescript
+   * const likers = await client.twitter.tweets.getFavoriters("1234567890");
+   * console.log(`${likers.data.length} users liked this tweet`);
+   * ```
+   */
+  async getFavoriters(tweetId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/tweets/tweet/${tweetId}/favoriters`,
+      { params: { count: options.count ?? 40, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get tweets similar to a given tweet.
+   *
+   * @param tweetId - The tweet ID to find similar tweets for.
+   * @returns Paginated response containing similar tweets.
+   *
+   * @example
+   * ```typescript
+   * const similar = await client.twitter.tweets.getSimilar("1234567890");
+   * for (const tweet of similar.data) {
+   *   console.log(`Similar: ${tweet.text.slice(0, 100)}...`);
+   * }
+   * ```
+   */
+  async getSimilar(tweetId) {
+    const response = await this.client.request(
+      `/v1/twitter/tweets/tweet/${tweetId}/similar`
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Search for tweets.
+   *
+   * @param query - Search query string. Supports Twitter advanced search operators.
+   * @param options - Search options including query type and pagination.
+   * @returns Paginated response containing matching tweets.
+   *
+   * @example
+   * ```typescript
+   * // Basic search
+   * const results = await client.twitter.tweets.search("python programming");
+   *
+   * // Latest tweets only
+   * const latest = await client.twitter.tweets.search("python", {
+   *   queryType: "Latest"
+   * });
+   *
+   * // Advanced search operators
+   * const fromUser = await client.twitter.tweets.search("from:elonmusk lang:en");
+   * ```
+   */
+  async search(query, options = {}) {
+    const response = await this.client.request(
+      "/v1/twitter/tweets/advanced_search",
+      {
+        params: {
+          query,
+          query_type: options.queryType ?? "Top",
+          cursor: options.cursor
+        }
+      }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Iterate through all search results with automatic pagination.
+   *
+   * This is a convenience method that automatically handles pagination,
+   * yielding tweets one at a time.
+   *
+   * @param query - Search query string.
+   * @param options - Search and iteration options.
+   * @yields Tweet objects matching the search query.
+   *
+   * @example
+   * ```typescript
+   * // Get up to 1000 tweets
+   * for await (const tweet of client.twitter.tweets.searchAll("python", {
+   *   maxItems: 1000
+   * })) {
+   *   console.log(tweet.text);
+   * }
+   *
+   * // Collect into an array
+   * import { collectAll } from "scrapebadger";
+   * const tweets = await collectAll(
+   *   client.twitter.tweets.searchAll("python", { maxItems: 100 })
+   * );
+   * ```
+   */
+  async *searchAll(query, options = {}) {
+    const fetchPage = async (cursor) => {
+      return this.search(query, { ...options, cursor });
+    };
+    yield* paginate(fetchPage, options);
+  }
+  /**
+   * Get tweets from a user's timeline.
+   *
+   * @param username - Twitter username (without @).
+   * @param options - Pagination options.
+   * @returns Paginated response containing the user's tweets.
+   *
+   * @example
+   * ```typescript
+   * const tweets = await client.twitter.tweets.getUserTweets("elonmusk");
+   * for (const tweet of tweets.data) {
+   *   console.log(`${tweet.created_at}: ${tweet.text.slice(0, 100)}...`);
+   * }
+   * ```
+   */
+  async getUserTweets(username, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${username}/latest_tweets`,
+      { params: { cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Iterate through all tweets from a user with automatic pagination.
+   *
+   * @param username - Twitter username (without @).
+   * @param options - Iteration options.
+   * @yields Tweet objects from the user's timeline.
+   *
+   * @example
+   * ```typescript
+   * for await (const tweet of client.twitter.tweets.getUserTweetsAll("elonmusk", {
+   *   maxItems: 500
+   * })) {
+   *   console.log(tweet.text);
+   * }
+   * ```
+   */
+  async *getUserTweetsAll(username, options = {}) {
+    const fetchPage = async (cursor) => {
+      return this.getUserTweets(username, { ...options, cursor });
+    };
+    yield* paginate(fetchPage, options);
+  }
+};
+
+// src/twitter/users.ts
+var UsersClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get a user by their numeric ID.
+   *
+   * @param userId - The user's numeric ID.
+   * @returns The user profile.
+   * @throws NotFoundError - If the user doesn't exist.
+   *
+   * @example
+   * ```typescript
+   * const user = await client.twitter.users.getById("44196397");
+   * console.log(`@${user.username}`);
+   * ```
+   */
+  async getById(userId) {
+    return this.client.request(`/v1/twitter/users/${userId}/by_id`);
+  }
+  /**
+   * Get a user by their username.
+   *
+   * @param username - The user's username (without @).
+   * @returns The user profile.
+   * @throws NotFoundError - If the user doesn't exist.
+   *
+   * @example
+   * ```typescript
+   * const user = await client.twitter.users.getByUsername("elonmusk");
+   * console.log(`${user.name} has ${user.followers_count.toLocaleString()} followers`);
+   * ```
+   */
+  async getByUsername(username) {
+    return this.client.request(`/v1/twitter/users/${username}/by_username`);
+  }
+  /**
+   * Get extended "About" information for a user.
+   *
+   * Returns additional metadata including account location,
+   * username change history, and verification details.
+   *
+   * @param username - The user's username (without @).
+   * @returns Extended user information.
+   *
+   * @example
+   * ```typescript
+   * const about = await client.twitter.users.getAbout("elonmusk");
+   * console.log(`Account based in: ${about.account_based_in}`);
+   * console.log(`Username changes: ${about.username_changes}`);
+   * ```
+   */
+  async getAbout(username) {
+    return this.client.request(`/v1/twitter/users/${username}/about`);
+  }
+  /**
+   * Get a user's followers.
+   *
+   * @param username - The user's username (without @).
+   * @param options - Pagination options.
+   * @returns Paginated response containing follower users.
+   *
+   * @example
+   * ```typescript
+   * const followers = await client.twitter.users.getFollowers("elonmusk");
+   * for (const user of followers.data) {
+   *   console.log(`@${user.username}`);
+   * }
+   *
+   * // Get next page
+   * if (followers.hasMore) {
+   *   const more = await client.twitter.users.getFollowers("elonmusk", {
+   *     cursor: followers.nextCursor
+   *   });
+   * }
+   * ```
+   */
+  async getFollowers(username, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${username}/followers`,
+      { params: { cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Iterate through all followers with automatic pagination.
+   *
+   * @param username - The user's username (without @).
+   * @param options - Iteration options.
+   * @yields User objects for each follower.
+   *
+   * @example
+   * ```typescript
+   * for await (const follower of client.twitter.users.getFollowersAll("elonmusk", {
+   *   maxItems: 1000
+   * })) {
+   *   console.log(follower.username);
+   * }
+   * ```
+   */
+  async *getFollowersAll(username, options = {}) {
+    const fetchPage = async (cursor) => {
+      return this.getFollowers(username, { ...options, cursor });
+    };
+    yield* paginate(fetchPage, options);
+  }
+  /**
+   * Get users that a user is following.
+   *
+   * @param username - The user's username (without @).
+   * @param options - Pagination options.
+   * @returns Paginated response containing followed users.
+   *
+   * @example
+   * ```typescript
+   * const following = await client.twitter.users.getFollowing("elonmusk");
+   * for (const user of following.data) {
+   *   console.log(`Follows @${user.username}`);
+   * }
+   * ```
+   */
+  async getFollowing(username, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${username}/followings`,
+      { params: { cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Iterate through all following with automatic pagination.
+   *
+   * @param username - The user's username (without @).
+   * @param options - Iteration options.
+   * @yields User objects for each followed account.
+   */
+  async *getFollowingAll(username, options = {}) {
+    const fetchPage = async (cursor) => {
+      return this.getFollowing(username, { ...options, cursor });
+    };
+    yield* paginate(fetchPage, options);
+  }
+  /**
+   * Get a user's most recent followers.
+   *
+   * @param username - The user's username (without @).
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing recent followers.
+   */
+  async getLatestFollowers(username, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${username}/latest_followers`,
+      { params: { count: options.count ?? 200, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get accounts a user most recently followed.
+   *
+   * @param username - The user's username (without @).
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing recently followed users.
+   */
+  async getLatestFollowing(username, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${username}/latest_following`,
+      { params: { count: options.count ?? 200, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get follower IDs for a user.
+   *
+   * More efficient than getFollowers when you only need IDs.
+   *
+   * @param username - The user's username (without @).
+   * @param options - Pagination options with optional count.
+   * @returns UserIds containing list of follower IDs.
+   *
+   * @example
+   * ```typescript
+   * const ids = await client.twitter.users.getFollowerIds("elonmusk");
+   * console.log(`Found ${ids.ids.length.toLocaleString()} follower IDs`);
+   * ```
+   */
+  async getFollowerIds(username, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${username}/follower_ids`,
+      { params: { count: options.count ?? 5e3, cursor: options.cursor } }
+    );
+    return {
+      ids: response.data?.ids ?? [],
+      next_cursor: response.data?.next_cursor
+    };
+  }
+  /**
+   * Get following IDs for a user.
+   *
+   * More efficient than getFollowing when you only need IDs.
+   *
+   * @param username - The user's username (without @).
+   * @param options - Pagination options with optional count.
+   * @returns UserIds containing list of following IDs.
+   */
+  async getFollowingIds(username, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${username}/following_ids`,
+      { params: { count: options.count ?? 5e3, cursor: options.cursor } }
+    );
+    return {
+      ids: response.data?.ids ?? [],
+      next_cursor: response.data?.next_cursor
+    };
+  }
+  /**
+   * Get verified followers for a user.
+   *
+   * @param userId - The user's numeric ID.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing verified followers.
+   */
+  async getVerifiedFollowers(userId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${userId}/verified_followers`,
+      { params: { count: options.count ?? 20, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get followers that the authenticated user also follows.
+   *
+   * @param userId - The user's numeric ID.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing mutual connections.
+   */
+  async getFollowersYouKnow(userId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${userId}/followers_you_know`,
+      { params: { count: options.count ?? 20, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get premium accounts that a user subscribes to.
+   *
+   * @param userId - The user's numeric ID.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing subscribed accounts.
+   */
+  async getSubscriptions(userId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${userId}/subscriptions`,
+      { params: { count: options.count ?? 20, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get a user's highlighted tweets.
+   *
+   * @param userId - The user's numeric ID.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing highlighted tweets.
+   */
+  async getHighlights(userId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/users/${userId}/highlights`,
+      { params: { count: options.count ?? 20, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Search for users.
+   *
+   * @param query - Search query string.
+   * @param options - Pagination options.
+   * @returns Paginated response containing matching users.
+   *
+   * @example
+   * ```typescript
+   * const results = await client.twitter.users.search("python developer");
+   * for (const user of results.data) {
+   *   console.log(`@${user.username}: ${user.description}`);
+   * }
+   * ```
+   */
+  async search(query, options = {}) {
+    const response = await this.client.request(
+      "/v1/twitter/users/search_users",
+      { params: { query, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Iterate through all search results with automatic pagination.
+   *
+   * @param query - Search query string.
+   * @param options - Iteration options.
+   * @yields User objects matching the search query.
+   */
+  async *searchAll(query, options = {}) {
+    const fetchPage = async (cursor) => {
+      return this.search(query, { ...options, cursor });
+    };
+    yield* paginate(fetchPage, options);
+  }
+};
+
+// src/twitter/lists.ts
+var ListsClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get details for a specific list.
+   *
+   * @param listId - The list ID.
+   * @returns The list details.
+   * @throws NotFoundError - If the list doesn't exist.
+   *
+   * @example
+   * ```typescript
+   * const list = await client.twitter.lists.getDetail("123456");
+   * console.log(`${list.name} by @${list.username}`);
+   * console.log(`${list.member_count} members, ${list.subscriber_count} subscribers`);
+   * ```
+   */
+  async getDetail(listId) {
+    return this.client.request(`/v1/twitter/lists/${listId}/detail`);
+  }
+  /**
+   * Get tweets from a list's timeline.
+   *
+   * @param listId - The list ID.
+   * @param options - Pagination options.
+   * @returns Paginated response containing tweets from list members.
+   *
+   * @example
+   * ```typescript
+   * const tweets = await client.twitter.lists.getTweets("123456");
+   * for (const tweet of tweets.data) {
+   *   console.log(`@${tweet.username}: ${tweet.text.slice(0, 100)}...`);
+   * }
+   * ```
+   */
+  async getTweets(listId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/lists/${listId}/tweets`,
+      { params: { cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Iterate through all list tweets with automatic pagination.
+   *
+   * @param listId - The list ID.
+   * @param options - Iteration options.
+   * @yields Tweet objects from the list timeline.
+   */
+  async *getTweetsAll(listId, options = {}) {
+    const fetchPage = async (cursor) => {
+      return this.getTweets(listId, { ...options, cursor });
+    };
+    yield* paginate(fetchPage, options);
+  }
+  /**
+   * Get members of a list.
+   *
+   * @param listId - The list ID.
+   * @param options - Pagination options.
+   * @returns Paginated response containing list members.
+   *
+   * @example
+   * ```typescript
+   * const members = await client.twitter.lists.getMembers("123456");
+   * for (const user of members.data) {
+   *   console.log(`@${user.username}`);
+   * }
+   * ```
+   */
+  async getMembers(listId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/lists/${listId}/members`,
+      { params: { cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Iterate through all list members with automatic pagination.
+   *
+   * @param listId - The list ID.
+   * @param options - Iteration options.
+   * @yields User objects for each list member.
+   */
+  async *getMembersAll(listId, options = {}) {
+    const fetchPage = async (cursor) => {
+      return this.getMembers(listId, { ...options, cursor });
+    };
+    yield* paginate(fetchPage, options);
+  }
+  /**
+   * Get subscribers of a list.
+   *
+   * @param listId - The list ID.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing list subscribers.
+   */
+  async getSubscribers(listId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/lists/${listId}/subscribers`,
+      { params: { count: options.count ?? 20, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Search for lists.
+   *
+   * @param query - Search query string.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing matching lists.
+   *
+   * @example
+   * ```typescript
+   * const results = await client.twitter.lists.search("tech leaders");
+   * for (const list of results.data) {
+   *   console.log(`${list.name}: ${list.member_count} members`);
+   * }
+   * ```
+   */
+  async search(query, options = {}) {
+    const response = await this.client.request(
+      "/v1/twitter/lists/search",
+      { params: { query, count: options.count ?? 20, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get lists owned by the authenticated user.
+   *
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing the user's lists.
+   */
+  async getMyLists(options = {}) {
+    const response = await this.client.request(
+      "/v1/twitter/lists/my_lists",
+      { params: { count: options.count ?? 100, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+};
+
+// src/twitter/communities.ts
+var CommunitiesClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get details for a specific community.
+   *
+   * @param communityId - The community ID.
+   * @returns The community details including rules and admin info.
+   * @throws NotFoundError - If the community doesn't exist.
+   *
+   * @example
+   * ```typescript
+   * const community = await client.twitter.communities.getDetail("123456");
+   * console.log(`${community.name}`);
+   * console.log(`Members: ${community.member_count?.toLocaleString()}`);
+   * console.log(`Join policy: ${community.join_policy}`);
+   *
+   * if (community.rules) {
+   *   console.log("Rules:");
+   *   for (const rule of community.rules) {
+   *     console.log(`  - ${rule.name}`);
+   *   }
+   * }
+   * ```
+   */
+  async getDetail(communityId) {
+    return this.client.request(`/v1/twitter/communities/${communityId}`);
+  }
+  /**
+   * Get tweets from a community.
+   *
+   * @param communityId - The community ID.
+   * @param options - Options including tweet type, count, and pagination.
+   * @returns Paginated response containing community tweets.
+   *
+   * @example
+   * ```typescript
+   * // Get top tweets
+   * const tweets = await client.twitter.communities.getTweets("123456");
+   *
+   * // Get latest tweets
+   * const latest = await client.twitter.communities.getTweets("123456", {
+   *   tweetType: "Latest"
+   * });
+   * ```
+   */
+  async getTweets(communityId, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/communities/${communityId}/tweets`,
+      {
+        params: {
+          tweet_type: options.tweetType ?? "Top",
+          count: options.count ?? 40,
+          cursor: options.cursor
+        }
+      }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Iterate through all community tweets with automatic pagination.
+   *
+   * @param communityId - The community ID.
+   * @param options - Options including tweet type and iteration limits.
+   * @yields Tweet objects from the community.
+   */
+  async *getTweetsAll(communityId, options = {}) {
+    const fetchPage = async (cursor) => {
+      return this.getTweets(communityId, { ...options, cursor });
+    };
+    yield* paginate(fetchPage, options);
+  }
+  /**
+   * Get members of a community.
+   *
+   * @param communityId - The community ID.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing community members.
+   *
+   * @example
+   * ```typescript
+   * const members = await client.twitter.communities.getMembers("123456");
+   * for (const member of members.data) {
+   *   console.log(`@${member.user.username} (${member.role})`);
+   * }
+   * ```
+   */
+  async getMembers(communityId, options = {}) {
+    const response = await this.client.request(`/v1/twitter/communities/${communityId}/members`, {
+      params: { count: options.count ?? 20, cursor: options.cursor }
+    });
+    const data = (response.data ?? []).map((item) => {
+      if ("user" in item && item.user) {
+        return item;
+      }
+      const userItem = item;
+      return {
+        user: item,
+        role: userItem.role,
+        joined_at: userItem.joined_at
+      };
+    });
+    return createPaginatedResponse(data, response.next_cursor);
+  }
+  /**
+   * Get moderators of a community.
+   *
+   * @param communityId - The community ID.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing community moderators.
+   */
+  async getModerators(communityId, options = {}) {
+    const response = await this.client.request(`/v1/twitter/communities/${communityId}/moderators`, {
+      params: { count: options.count ?? 20, cursor: options.cursor }
+    });
+    const data = (response.data ?? []).map((item) => {
+      if ("user" in item && item.user) {
+        return item;
+      }
+      const userItem = item;
+      return {
+        user: item,
+        role: "moderator",
+        joined_at: userItem.joined_at
+      };
+    });
+    return createPaginatedResponse(data, response.next_cursor);
+  }
+  /**
+   * Search for communities.
+   *
+   * @param query - Search query string.
+   * @param options - Pagination options.
+   * @returns Paginated response containing matching communities.
+   *
+   * @example
+   * ```typescript
+   * const results = await client.twitter.communities.search("python developers");
+   * for (const community of results.data) {
+   *   console.log(`${community.name}: ${community.member_count} members`);
+   * }
+   * ```
+   */
+  async search(query, options = {}) {
+    const response = await this.client.request(
+      "/v1/twitter/communities/search",
+      { params: { query, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Search for tweets within a community.
+   *
+   * @param communityId - The community ID.
+   * @param query - Search query string.
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing matching tweets.
+   */
+  async searchTweets(communityId, query, options = {}) {
+    const response = await this.client.request(
+      `/v1/twitter/communities/${communityId}/search_tweets`,
+      { params: { query, count: options.count ?? 20, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+  /**
+   * Get the community timeline (tweets from communities you're in).
+   *
+   * @param options - Pagination options with optional count.
+   * @returns Paginated response containing community timeline tweets.
+   */
+  async getTimeline(options = {}) {
+    const response = await this.client.request(
+      "/v1/twitter/communities/timeline",
+      { params: { count: options.count ?? 20, cursor: options.cursor } }
+    );
+    return createPaginatedResponse(response.data ?? [], response.next_cursor);
+  }
+};
+
+// src/twitter/trends.ts
+var TrendsClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get trending topics.
+   *
+   * @param options - Options for filtering trends.
+   * @returns Paginated response containing trending topics.
+   *
+   * @example
+   * ```typescript
+   * // Get general trending topics
+   * const trends = await client.twitter.trends.getTrends();
+   *
+   * // Get news trends
+   * const newsTrends = await client.twitter.trends.getTrends({
+   *   category: "news"
+   * });
+   *
+   * for (const trend of trends.data) {
+   *   const count = trend.tweet_count?.toLocaleString() || "N/A";
+   *   console.log(`${trend.name}: ${count} tweets`);
+   * }
+   * ```
+   */
+  async getTrends(options = {}) {
+    const response = await this.client.request("/v1/twitter/trends/", {
+      params: {
+        category: options.category ?? "trending",
+        count: options.count ?? 20
+      }
+    });
+    return createPaginatedResponse(response.data ?? []);
+  }
+  /**
+   * Get trends for a specific location.
+   *
+   * @param woeid - Where On Earth ID for the location.
+   *   Common WOEIDs:
+   *   - 1: Worldwide
+   *   - 23424977: United States
+   *   - 23424975: United Kingdom
+   *   - 23424856: Japan
+   *   - 23424829: Germany
+   * @returns PlaceTrends containing location info and trends.
+   * @throws NotFoundError - If the WOEID is invalid.
+   *
+   * @example
+   * ```typescript
+   * // Get US trends
+   * const usTrends = await client.twitter.trends.getPlaceTrends(23424977);
+   * console.log(`Trends in ${usTrends.name}:`);
+   * for (const trend of usTrends.trends) {
+   *   console.log(`  - ${trend.name}`);
+   * }
+   *
+   * // Get worldwide trends
+   * const globalTrends = await client.twitter.trends.getPlaceTrends(1);
+   * ```
+   */
+  async getPlaceTrends(woeid) {
+    return this.client.request(`/v1/twitter/trends/place/${woeid}`);
+  }
+  /**
+   * Get all locations where trends are available.
+   *
+   * @returns Paginated response containing available trend locations.
+   *
+   * @example
+   * ```typescript
+   * const locations = await client.twitter.trends.getAvailableLocations();
+   *
+   * // Filter by country
+   * const usLocations = locations.data.filter(
+   *   loc => loc.country_code === "US"
+   * );
+   * console.log(`Found ${usLocations.length} US locations`);
+   *
+   * // Get countries only
+   * const countries = locations.data.filter(
+   *   loc => loc.place_type === "Country"
+   * );
+   * ```
+   */
+  async getAvailableLocations() {
+    const response = await this.client.request(
+      "/v1/twitter/trends/locations"
+    );
+    return createPaginatedResponse(response.data ?? []);
+  }
+};
+
+// src/twitter/geo.ts
+var GeoClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get details for a specific place.
+   *
+   * @param placeId - The Twitter place ID.
+   * @returns The place details.
+   * @throws NotFoundError - If the place doesn't exist.
+   *
+   * @example
+   * ```typescript
+   * const place = await client.twitter.geo.getDetail("5a110d312052166f");
+   * console.log(`${place.full_name}`);
+   * console.log(`Type: ${place.place_type}`);
+   * console.log(`Country: ${place.country}`);
+   * ```
+   */
+  async getDetail(placeId) {
+    return this.client.request(`/v1/twitter/geo/places/${placeId}`);
+  }
+  /**
+   * Search for geographic places.
+   *
+   * At least one of lat/long, query, or ip must be provided.
+   *
+   * @param options - Search options.
+   * @returns Paginated response containing matching places.
+   * @throws ValidationError - If no search parameters are provided.
+   *
+   * @example
+   * ```typescript
+   * // Search by name
+   * const places = await client.twitter.geo.search({ query: "San Francisco" });
+   * for (const place of places.data) {
+   *   console.log(`${place.full_name} (${place.place_type})`);
+   * }
+   *
+   * // Search by coordinates
+   * const nearby = await client.twitter.geo.search({
+   *   lat: 37.7749,
+   *   long: -122.4194,
+   *   granularity: "city"
+   * });
+   *
+   * // Search by IP
+   * const ipPlaces = await client.twitter.geo.search({ ip: "8.8.8.8" });
+   * ```
+   */
+  async search(options = {}) {
+    const response = await this.client.request("/v1/twitter/geo/search", {
+      params: {
+        lat: options.lat,
+        long: options.long,
+        query: options.query,
+        ip: options.ip,
+        granularity: options.granularity,
+        max_results: options.maxResults
+      }
+    });
+    return createPaginatedResponse(response.data ?? []);
+  }
+};
+
+// src/twitter/client.ts
+var TwitterClient = class {
+  /** Client for tweet operations */
+  tweets;
+  /** Client for user operations */
+  users;
+  /** Client for list operations */
+  lists;
+  /** Client for community operations */
+  communities;
+  /** Client for trends operations */
+  trends;
+  /** Client for geo/places operations */
+  geo;
+  /**
+   * Create a new Twitter client.
+   *
+   * @param client - The base HTTP client for making requests.
+   */
+  constructor(client) {
+    this.tweets = new TweetsClient(client);
+    this.users = new UsersClient(client);
+    this.lists = new ListsClient(client);
+    this.communities = new CommunitiesClient(client);
+    this.trends = new TrendsClient(client);
+    this.geo = new GeoClient(client);
+  }
+};
+
+export { CommunitiesClient, GeoClient, ListsClient, TrendsClient, TweetsClient, TwitterClient, UsersClient };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map