scrapebadger 0.7.0 → 0.8.0

package/dist/index.js

@@ -3275,6 +3275,684 @@ var GoogleClient = class {
   }
 };
 
+// src/reddit/search.ts
+var SearchClient3 = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Search Reddit posts.
+   *
+   * @param options - Search parameters.
+   * @param options.query - Search query string.
+   * @param options.subreddit - Restrict search to a specific subreddit.
+   * @param options.sort - Sort order (relevance, hot, top, new, comments).
+   * @param options.time - Time filter (hour, day, week, month, year, all).
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns Search results with posts and pagination metadata.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the search parameters are invalid.
+   *
+   * @example
+   * ```typescript
+   * const results = await client.reddit.search.posts({
+   *   query: "best practices",
+   *   subreddit: "programming",
+   *   sort: "top",
+   *   time: "month",
+   *   limit: 25,
+   * });
+   * console.log(`Found ${results.posts.length} posts`);
+   * ```
+   */
+  async posts(options) {
+    return this.client.request("/v1/reddit/search/posts", {
+      params: {
+        query: options.query,
+        subreddit: options.subreddit,
+        sort: options.sort,
+        time: options.time,
+        after: options.after,
+        limit: options.limit
+      }
+    });
+  }
+  /**
+   * Search Reddit subreddits.
+   *
+   * @param options - Search parameters.
+   * @param options.query - Search query string.
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns Matching subreddits with pagination metadata.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the search parameters are invalid.
+   *
+   * @example
+   * ```typescript
+   * const results = await client.reddit.search.subreddits({
+   *   query: "javascript",
+   *   limit: 10,
+   * });
+   * for (const sub of results.subreddits) {
+   *   console.log(`r/${sub.display_name}: ${sub.subscribers.toLocaleString()} subscribers`);
+   * }
+   * ```
+   */
+  async subreddits(options) {
+    return this.client.request(
+      "/v1/reddit/search/subreddits",
+      {
+        params: {
+          query: options.query,
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+  /**
+   * Search Reddit users.
+   *
+   * @param options - Search parameters.
+   * @param options.query - Search query string.
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns Matching users with pagination metadata.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the search parameters are invalid.
+   *
+   * @example
+   * ```typescript
+   * const results = await client.reddit.search.users({
+   *   query: "john",
+   *   limit: 20,
+   * });
+   * for (const user of results.users) {
+   *   console.log(`u/${user.name}: ${user.total_karma.toLocaleString()} karma`);
+   * }
+   * ```
+   */
+  async users(options) {
+    return this.client.request(
+      "/v1/reddit/search/users",
+      {
+        params: {
+          query: options.query,
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+  /**
+   * Get Reddit posts linking to a specific domain.
+   *
+   * @param options - Request parameters.
+   * @param options.domain - Domain name to search for (e.g. "github.com").
+   * @param options.sort - Sort order (hot, new, top, rising).
+   * @param options.time - Time filter for top sort (hour, day, week, month, year, all).
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns Posts linking to the domain with pagination metadata.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the parameters are invalid.
+   *
+   * @example
+   * ```typescript
+   * const results = await client.reddit.search.domainPosts({
+   *   domain: "github.com",
+   *   sort: "top",
+   *   time: "week",
+   *   limit: 25,
+   * });
+   * for (const post of results.posts) {
+   *   console.log(`r/${post.subreddit}: ${post.title}`);
+   * }
+   * ```
+   */
+  async domainPosts(options) {
+    return this.client.request(
+      "/v1/reddit/search/domain",
+      {
+        params: {
+          domain: options.domain,
+          sort: options.sort,
+          time: options.time,
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+};
+
+// src/reddit/posts.ts
+var PostsClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get trending/hot posts from Reddit or a specific subreddit.
+   *
+   * @param options - Request parameters.
+   * @param options.subreddit - Subreddit name (without r/). If omitted, returns site-wide posts.
+   * @param options.sort - Sort order (hot, new, top, rising, controversial).
+   * @param options.time - Time filter for top/controversial (hour, day, week, month, year, all).
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns Trending posts with pagination metadata.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const results = await client.reddit.posts.trending({
+   *   subreddit: "worldnews",
+   *   sort: "hot",
+   *   limit: 25,
+   * });
+   * for (const post of results.posts) {
+   *   console.log(`${post.title} (${post.num_comments} comments)`);
+   * }
+   * ```
+   */
+  async trending(options = {}) {
+    return this.client.request("/v1/reddit/posts", {
+      params: {
+        subreddit: options.subreddit,
+        sort: options.sort,
+        time: options.time,
+        after: options.after,
+        limit: options.limit
+      }
+    });
+  }
+  /**
+   * Get full details of a single Reddit post.
+   *
+   * @param postId - The Reddit post ID (e.g. "abc123" or "t3_abc123").
+   * @param options - Optional parameters.
+   * @param options.subreddit - Subreddit name (helps resolve the post URL).
+   * @returns Full post details.
+   * @throws NotFoundError - If the post doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.posts.get("abc123", { subreddit: "programming" });
+   * const { post } = response;
+   * console.log(`${post.title} by u/${post.author}`);
+   * console.log(`Score: ${post.score}, Comments: ${post.num_comments}`);
+   * ```
+   */
+  async get(postId, options = {}) {
+    return this.client.request(
+      `/v1/reddit/posts/${postId}`,
+      { params: { subreddit: options.subreddit } }
+    );
+  }
+  /**
+   * Get comments for a Reddit post.
+   *
+   * @param postId - The Reddit post ID (e.g. "abc123" or "t3_abc123").
+   * @param options - Optional parameters.
+   * @param options.subreddit - Subreddit name (helps resolve the post URL).
+   * @param options.sort - Comment sort order (confidence, top, new, controversial, old, qa).
+   * @param options.depth - Maximum comment tree depth.
+   * @param options.limit - Number of top-level comments to return.
+   * @returns Post details and nested comment tree.
+   * @throws NotFoundError - If the post doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.posts.comments("abc123", {
+   *   subreddit: "programming",
+   *   sort: "top",
+   *   limit: 50,
+   * });
+   * for (const comment of response.comments) {
+   *   console.log(`u/${comment.author}: ${comment.body.slice(0, 100)}`);
+   * }
+   * ```
+   */
+  async comments(postId, options = {}) {
+    return this.client.request(
+      `/v1/reddit/posts/${postId}/comments`,
+      {
+        params: {
+          subreddit: options.subreddit,
+          sort: options.sort,
+          depth: options.depth,
+          limit: options.limit
+        }
+      }
+    );
+  }
+  /**
+   * Get cross-posts and duplicate submissions of a Reddit post.
+   *
+   * @param postId - The Reddit post ID (e.g. "abc123" or "t3_abc123").
+   * @param options - Optional parameters.
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns The original post and its duplicate submissions.
+   * @throws NotFoundError - If the post doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.posts.duplicates("abc123");
+   * console.log(`Original: ${response.post.title}`);
+   * console.log(`Cross-posted ${response.duplicates.length} times`);
+   * for (const dupe of response.duplicates) {
+   *   console.log(`  r/${dupe.subreddit}: ${dupe.score} points`);
+   * }
+   * ```
+   */
+  async duplicates(postId, options = {}) {
+    return this.client.request(
+      `/v1/reddit/posts/${postId}/duplicates`,
+      {
+        params: {
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+};
+
+// src/reddit/subreddits.ts
+var SubredditsClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get a subreddit's full details and metadata.
+   *
+   * @param subreddit - Subreddit name (without r/ prefix).
+   * @returns Full subreddit details.
+   * @throws NotFoundError - If the subreddit doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.subreddits.get("javascript");
+   * const { subreddit } = response;
+   * console.log(`${subreddit.title}: ${subreddit.subscribers.toLocaleString()} members`);
+   * console.log(`Description: ${subreddit.public_description}`);
+   * ```
+   */
+  async get(subreddit) {
+    return this.client.request(
+      `/v1/reddit/subreddits/${subreddit}`
+    );
+  }
+  /**
+   * Get posts from a subreddit.
+   *
+   * @param subreddit - Subreddit name (without r/ prefix).
+   * @param options - Optional parameters.
+   * @param options.sort - Sort order (hot, new, top, rising, controversial).
+   * @param options.time - Time filter for top/controversial (hour, day, week, month, year, all).
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns Subreddit posts with pagination metadata.
+   * @throws NotFoundError - If the subreddit doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.subreddits.posts("typescript", {
+   *   sort: "top",
+   *   time: "week",
+   *   limit: 25,
+   * });
+   * for (const post of response.posts) {
+   *   console.log(`${post.title} — ${post.score} pts`);
+   * }
+   * ```
+   */
+  async posts(subreddit, options = {}) {
+    return this.client.request(
+      `/v1/reddit/subreddits/${subreddit}/posts`,
+      {
+        params: {
+          sort: options.sort,
+          time: options.time,
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+  /**
+   * Get the rules for a subreddit.
+   *
+   * @param subreddit - Subreddit name (without r/ prefix).
+   * @returns List of subreddit rules.
+   * @throws NotFoundError - If the subreddit doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.subreddits.rules("AskReddit");
+   * for (const rule of response.rules) {
+   *   console.log(`${rule.priority}. ${rule.short_name}`);
+   *   console.log(`   ${rule.description}`);
+   * }
+   * ```
+   */
+  async rules(subreddit) {
+    return this.client.request(
+      `/v1/reddit/subreddits/${subreddit}/rules`
+    );
+  }
+  /**
+   * Get the moderators of a subreddit.
+   *
+   * @param subreddit - Subreddit name (without r/ prefix).
+   * @param options - Optional parameters.
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return.
+   * @returns List of moderators with pagination metadata.
+   * @throws NotFoundError - If the subreddit doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.subreddits.moderators("programming");
+   * for (const mod of response.moderators) {
+   *   console.log(`u/${mod.name}: [${mod.mod_permissions.join(", ")}]`);
+   * }
+   * ```
+   */
+  async moderators(subreddit, options = {}) {
+    return this.client.request(
+      `/v1/reddit/subreddits/${subreddit}/moderators`,
+      {
+        params: {
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+  /**
+   * List all wiki pages in a subreddit.
+   *
+   * @param subreddit - Subreddit name (without r/ prefix).
+   * @returns List of wiki page slugs.
+   * @throws NotFoundError - If the subreddit doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.subreddits.wikiPages("rust");
+   * for (const page of response.pages) {
+   *   console.log(`/r/rust/wiki/${page}`);
+   * }
+   * ```
+   */
+  async wikiPages(subreddit) {
+    return this.client.request(
+      `/v1/reddit/subreddits/${subreddit}/wiki`
+    );
+  }
+  /**
+   * Get the content of a specific wiki page in a subreddit.
+   *
+   * @param subreddit - Subreddit name (without r/ prefix).
+   * @param page - Wiki page slug (e.g. "index", "faq").
+   * @returns Wiki page content and metadata.
+   * @throws NotFoundError - If the subreddit or wiki page doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.subreddits.wikiPage("learnprogramming", "faq");
+   * console.log(`Last edited by: u/${response.page.revision_by}`);
+   * console.log(response.page.content_md);
+   * ```
+   */
+  async wikiPage(subreddit, page) {
+    return this.client.request(
+      `/v1/reddit/subreddits/${subreddit}/wiki/${page}`
+    );
+  }
+  /**
+   * Get the most popular subreddits on Reddit.
+   *
+   * @param options - Optional parameters.
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns Popular subreddits with pagination metadata.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.subreddits.popular({ limit: 20 });
+   * for (const sub of response.subreddits) {
+   *   console.log(`r/${sub.display_name}: ${sub.subscribers.toLocaleString()} subscribers`);
+   * }
+   * ```
+   */
+  async popular(options = {}) {
+    return this.client.request(
+      "/v1/reddit/subreddits/popular",
+      {
+        params: {
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+  /**
+   * Get newly created subreddits on Reddit.
+   *
+   * @param options - Optional parameters.
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns New subreddits with pagination metadata.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.subreddits.newSubreddits({ limit: 20 });
+   * for (const sub of response.subreddits) {
+   *   console.log(`r/${sub.display_name} (created: ${new Date(sub.created_utc * 1000).toLocaleDateString()})`);
+   * }
+   * ```
+   */
+  async newSubreddits(options = {}) {
+    return this.client.request(
+      "/v1/reddit/subreddits/new",
+      {
+        params: {
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+};
+
+// src/reddit/users.ts
+var UsersClient3 = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get a Reddit user's profile.
+   *
+   * @param username - The Reddit username (without u/ prefix).
+   * @returns The user profile response.
+   * @throws NotFoundError - If the user doesn't exist or is suspended.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.users.get("spez");
+   * const { user } = response;
+   * console.log(`u/${user.name}`);
+   * console.log(`Karma: ${user.total_karma.toLocaleString()} (${user.link_karma} post, ${user.comment_karma} comment)`);
+   * console.log(`Account age: ${new Date(user.created_utc * 1000).toLocaleDateString()}`);
+   * ```
+   */
+  async get(username) {
+    return this.client.request(
+      `/v1/reddit/users/${username}`
+    );
+  }
+  /**
+   * Get posts submitted by a Reddit user.
+   *
+   * @param username - The Reddit username (without u/ prefix).
+   * @param options - Optional parameters.
+   * @param options.sort - Sort order (hot, new, top, controversial).
+   * @param options.time - Time filter for top/controversial (hour, day, week, month, year, all).
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns The user's posts with pagination metadata.
+   * @throws NotFoundError - If the user doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.users.posts("spez", {
+   *   sort: "top",
+   *   time: "all",
+   *   limit: 25,
+   * });
+   * for (const post of response.posts) {
+   *   console.log(`r/${post.subreddit}: ${post.title} (${post.score} pts)`);
+   * }
+   * ```
+   */
+  async posts(username, options = {}) {
+    return this.client.request(
+      `/v1/reddit/users/${username}/posts`,
+      {
+        params: {
+          sort: options.sort,
+          time: options.time,
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+  /**
+   * Get comments made by a Reddit user.
+   *
+   * @param username - The Reddit username (without u/ prefix).
+   * @param options - Optional parameters.
+   * @param options.sort - Sort order (hot, new, top, controversial).
+   * @param options.time - Time filter for top/controversial (hour, day, week, month, year, all).
+   * @param options.after - Pagination cursor for the next page.
+   * @param options.limit - Number of results to return (max 100).
+   * @returns The user's comments with pagination metadata.
+   * @throws NotFoundError - If the user doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.users.comments("spez", {
+   *   sort: "new",
+   *   limit: 50,
+   * });
+   * for (const comment of response.comments) {
+   *   console.log(`r/${comment.subreddit}: ${comment.body.slice(0, 80)}`);
+   * }
+   * ```
+   */
+  async comments(username, options = {}) {
+    return this.client.request(
+      `/v1/reddit/users/${username}/comments`,
+      {
+        params: {
+          sort: options.sort,
+          time: options.time,
+          after: options.after,
+          limit: options.limit
+        }
+      }
+    );
+  }
+  /**
+   * Get subreddits moderated by a Reddit user.
+   *
+   * @param username - The Reddit username (without u/ prefix).
+   * @returns Subreddits moderated by the user.
+   * @throws NotFoundError - If the user doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.users.moderated("spez");
+   * for (const sub of response.subreddits) {
+   *   console.log(`r/${sub.display_name}: ${sub.subscribers.toLocaleString()} subscribers`);
+   * }
+   * ```
+   */
+  async moderated(username) {
+    return this.client.request(
+      `/v1/reddit/users/${username}/moderated`
+    );
+  }
+  /**
+   * Get trophies awarded to a Reddit user.
+   *
+   * @param username - The Reddit username (without u/ prefix).
+   * @returns List of trophies awarded to the user.
+   * @throws NotFoundError - If the user doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   *
+   * @example
+   * ```typescript
+   * const response = await client.reddit.users.trophies("spez");
+   * for (const trophy of response.trophies) {
+   *   console.log(`${trophy.name}${trophy.description ? `: ${trophy.description}` : ""}`);
+   * }
+   * ```
+   */
+  async trophies(username) {
+    return this.client.request(
+      `/v1/reddit/users/${username}/trophies`
+    );
+  }
+};
+
+// src/reddit/client.ts
+var RedditClient = class {
+  /** Client for search operations (posts, subreddits, users, domain posts) */
+  search;
+  /** Client for post operations (trending, details, comments, duplicates) */
+  posts;
+  /** Client for subreddit operations (details, posts, rules, moderators, wiki) */
+  subreddits;
+  /** Client for user operations (profile, posts, comments, moderated, trophies) */
+  users;
+  /**
+   * Create a new Reddit client.
+   *
+   * @param client - The base HTTP client for making requests.
+   */
+  constructor(client) {
+    this.search = new SearchClient3(client);
+    this.posts = new PostsClient(client);
+    this.subreddits = new SubredditsClient(client);
+    this.users = new UsersClient3(client);
+  }
+};
+
 // src/client.ts
 var ScrapeBadger = class {
   baseClient;
@@ -3286,6 +3964,8 @@ var ScrapeBadger = class {
   vinted;
   /** Google Scraper API client — 19 Google product APIs */
   google;
+  /** Reddit scraper API client */
+  reddit;
   /**
    * Create a new ScrapeBadger client.
    *
@@ -3324,6 +4004,7 @@ var ScrapeBadger = class {
     this.web = new WebClient(this.baseClient);
     this.vinted = new VintedClient(this.baseClient);
     this.google = new GoogleClient(this.baseClient);
+    this.reddit = new RedditClient(this.baseClient);
   }
 };
 
@@ -3355,6 +4036,11 @@ exports.InsufficientCreditsError = InsufficientCreditsError;
 exports.ListsClient = ListsClient;
 exports.NotFoundError = NotFoundError;
 exports.RateLimitError = RateLimitError;
+exports.RedditClient = RedditClient;
+exports.RedditPostsClient = PostsClient;
+exports.RedditSearchClient = SearchClient3;
+exports.RedditSubredditsClient = SubredditsClient;
+exports.RedditUsersClient = UsersClient3;
 exports.ScrapeBadger = ScrapeBadger;
 exports.ScrapeBadgerError = ScrapeBadgerError;
 exports.ServerError = ServerError;