scrapebadger 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1414 @@
+// src/internal/exceptions.ts
+var ScrapeBadgerError = class _ScrapeBadgerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ScrapeBadgerError";
+    Object.setPrototypeOf(this, _ScrapeBadgerError.prototype);
+  }
+};
+var AuthenticationError = class _AuthenticationError extends ScrapeBadgerError {
+  constructor(message = "Authentication failed. Check your API key.") {
+    super(message);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends ScrapeBadgerError {
+  /** Unix timestamp when the rate limit resets */
+  retryAfter;
+  /** Maximum requests per minute for this tier */
+  limit;
+  /** Remaining requests in the current window */
+  remaining;
+  constructor(message = "Rate limit exceeded.", options) {
+    super(message);
+    this.name = "RateLimitError";
+    this.retryAfter = options?.retryAfter;
+    this.limit = options?.limit;
+    this.remaining = options?.remaining;
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var NotFoundError = class _NotFoundError extends ScrapeBadgerError {
+  /** The resource type that was not found */
+  resourceType;
+  /** The resource ID that was not found */
+  resourceId;
+  constructor(message = "Resource not found.", resourceType, resourceId) {
+    super(message);
+    this.name = "NotFoundError";
+    this.resourceType = resourceType;
+    this.resourceId = resourceId;
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends ScrapeBadgerError {
+  /** Validation errors by field */
+  errors;
+  constructor(message = "Validation error.", errors) {
+    super(message);
+    this.name = "ValidationError";
+    this.errors = errors;
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var ServerError = class _ServerError extends ScrapeBadgerError {
+  /** HTTP status code */
+  statusCode;
+  constructor(message = "Internal server error.", statusCode = 500) {
+    super(message);
+    this.name = "ServerError";
+    this.statusCode = statusCode;
+    Object.setPrototypeOf(this, _ServerError.prototype);
+  }
+};
+var TimeoutError = class _TimeoutError extends ScrapeBadgerError {
+  /** Timeout duration in milliseconds */
+  timeout;
+  constructor(message = "Request timed out.", timeout) {
+    super(message);
+    this.name = "TimeoutError";
+    this.timeout = timeout;
+    Object.setPrototypeOf(this, _TimeoutError.prototype);
+  }
+};
+var InsufficientCreditsError = class _InsufficientCreditsError extends ScrapeBadgerError {
+  /** Current credit balance */
+  creditsBalance;
+  constructor(message = "Insufficient credits.", creditsBalance) {
+    super(message);
+    this.name = "InsufficientCreditsError";
+    this.creditsBalance = creditsBalance;
+    Object.setPrototypeOf(this, _InsufficientCreditsError.prototype);
+  }
+};
+var AccountRestrictedError = class _AccountRestrictedError extends ScrapeBadgerError {
+  /** Reason for the restriction */
+  reason;
+  constructor(message = "Account restricted.", reason) {
+    super(message);
+    this.name = "AccountRestrictedError";
+    this.reason = reason;
+    Object.setPrototypeOf(this, _AccountRestrictedError.prototype);
+  }
+};
+
+// src/internal/client.ts
+var BaseClient = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Make an HTTP request to the API.
+   */
+  async request(path, options = {}) {
+    const { method = "GET", params, body, headers = {} } = options;
+    const url = new URL(path, this.config.baseUrl);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const requestHeaders = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "X-API-Key": this.config.apiKey,
+      "User-Agent": "scrapebadger-node/0.1.0",
+      ...headers
+    };
+    const fetchOptions = {
+      method,
+      headers: requestHeaders
+    };
+    if (body && method !== "GET") {
+      fetchOptions.body = JSON.stringify(body);
+    }
+    return this.executeWithRetry(url.toString(), fetchOptions);
+  }
+  /**
+   * Execute request with exponential backoff retry logic.
+   */
+  async executeWithRetry(url, options) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      try {
+        const response = await this.fetchWithTimeout(url, options);
+        return await this.handleResponse(response);
+      } catch (error) {
+        lastError = error;
+        if (error instanceof ScrapeBadgerError && !(error instanceof RateLimitError)) {
+          if (error instanceof AuthenticationError || error instanceof NotFoundError || error instanceof ValidationError || error instanceof InsufficientCreditsError || error instanceof AccountRestrictedError) {
+            throw error;
+          }
+        }
+        if (attempt === this.config.maxRetries) {
+          break;
+        }
+        const delay = this.config.retryDelay * Math.pow(2, attempt);
+        if (error instanceof RateLimitError && error.retryAfter) {
+          const retryDelay = (error.retryAfter - Date.now() / 1e3) * 1e3;
+          if (retryDelay > 0 && retryDelay < 6e4) {
+            await this.sleep(retryDelay);
+            continue;
+          }
+        }
+        await this.sleep(delay);
+      }
+    }
+    throw lastError ?? new ScrapeBadgerError("Request failed after retries");
+  }
+  /**
+   * Fetch with timeout support.
+   */
+  async fetchWithTimeout(url, options) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new TimeoutError(`Request timed out after ${this.config.timeout}ms`, this.config.timeout);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Handle HTTP response and convert errors.
+   */
+  async handleResponse(response) {
+    let data;
+    const contentType = response.headers.get("content-type");
+    if (contentType?.includes("application/json")) {
+      data = await response.json();
+    } else {
+      const text = await response.text();
+      data = { detail: text };
+    }
+    if (response.ok) {
+      return data;
+    }
+    const errorData = data;
+    const message = errorData.detail ?? errorData.message ?? "Request failed";
+    switch (response.status) {
+      case 401:
+        throw new AuthenticationError(message);
+      case 402:
+        throw new InsufficientCreditsError(message, errorData.credits_balance);
+      case 403:
+        if (message.toLowerCase().includes("restricted")) {
+          throw new AccountRestrictedError(message, errorData.reason);
+        }
+        throw new AuthenticationError(message);
+      case 404:
+        throw new NotFoundError(message);
+      case 422:
+        throw new ValidationError(message, errorData.errors);
+      case 429:
+        throw new RateLimitError(message, {
+          retryAfter: errorData.reset_at,
+          limit: errorData.limit,
+          remaining: errorData.remaining
+        });
+      default:
+        if (response.status >= 500) {
+          throw new ServerError(message, response.status);
+        }
+        throw new ScrapeBadgerError(message);
+    }
+  }
+  /**
+   * Sleep for a given duration.
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/internal/config.ts
+var DEFAULT_BASE_URL = "https://api.scrapebadger.com";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_DELAY = 1e3;
+function resolveConfig(config) {
+  if (!config.apiKey) {
+    throw new Error("API key is required");
+  }
+  return {
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+    timeout: config.timeout ?? DEFAULT_TIMEOUT,
+    maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+    retryDelay: config.retryDelay ?? DEFAULT_RETRY_DELAY
+  };
+}
+function getApiKeyFromEnv() {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env.SCRAPEBADGER_API_KEY;
+  }
+  return void 0;
+}
+
+// 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);
+}
+async function collectAll(generator) {
+  const items = [];
+  for await (const item of generator) {
+    items.push(item);
+  }
+  return items;
+}
+
+// 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);
+  }
+};
+
+// src/client.ts
+var ScrapeBadger = class {
+  baseClient;
+  /** Twitter API client */
+  twitter;
+  /**
+   * Create a new ScrapeBadger client.
+   *
+   * @param config - Configuration options. If apiKey is not provided,
+   *   it will be read from the SCRAPEBADGER_API_KEY environment variable.
+   * @throws Error if no API key is provided or found in environment.
+   *
+   * @example
+   * ```typescript
+   * // With explicit API key
+   * const client = new ScrapeBadger({ apiKey: "your-api-key" });
+   *
+   * // With custom options
+   * const client = new ScrapeBadger({
+   *   apiKey: "your-api-key",
+   *   baseUrl: "https://custom.api.com",
+   *   timeout: 60000,
+   *   maxRetries: 5
+   * });
+   *
+   * // Using environment variable
+   * // Set SCRAPEBADGER_API_KEY=your-api-key
+   * const client = new ScrapeBadger();
+   * ```
+   */
+  constructor(config = {}) {
+    const apiKey = config.apiKey ?? getApiKeyFromEnv();
+    if (!apiKey) {
+      throw new Error(
+        "API key is required. Pass it in the config or set SCRAPEBADGER_API_KEY environment variable."
+      );
+    }
+    const resolvedConfig = resolveConfig({ ...config, apiKey });
+    this.baseClient = new BaseClient(resolvedConfig);
+    this.twitter = new TwitterClient(this.baseClient);
+  }
+};
+
+export { AccountRestrictedError, AuthenticationError, CommunitiesClient, GeoClient, InsufficientCreditsError, ListsClient, NotFoundError, RateLimitError, ScrapeBadger, ScrapeBadgerError, ServerError, TimeoutError, TrendsClient, TweetsClient, TwitterClient, UsersClient, ValidationError, collectAll };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map