scrapebadger 0.12.0 → 0.14.0

package/dist/index.js

@@ -8,6 +8,9 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var WebSocket__default = /*#__PURE__*/_interopDefault(WebSocket);
 
+// src/internal/version.ts
+var SDK_VERSION = "0.13.1";
+
 // src/internal/exceptions.ts
 var ScrapeBadgerError = class _ScrapeBadgerError extends Error {
   constructor(message) {
@@ -156,7 +159,7 @@ var BaseClient = class {
       "Content-Type": "application/json",
       Accept: "application/json",
       "X-API-Key": this.config.apiKey,
-      "User-Agent": "scrapebadger-node/0.3.1",
+      "User-Agent": `scrapebadger-node/${SDK_VERSION}`,
       ...headers
     };
     const fetchOptions = {
@@ -2528,6 +2531,19 @@ var SearchClient = class {
    * });
    * console.log(`Found ${results.pagination.total_entries} items`);
    * ```
+   *
+   * @example
+   * ```typescript
+   * // Filter results to sellers physically located in France or Belgium.
+   * // Billing: 1 base credit + 1 credit per uncached seller looked up.
+   * const local = await client.vinted.search.search({
+   *   query: "vintage jacket",
+   *   seller_country: "fr,be",
+   * });
+   * for (const item of local.items) {
+   *   console.log(`${item.title} — seller in ${item.seller_country_code}`);
+   * }
+   * ```
    */
   async search(params) {
     return this.client.request("/v1/vinted/search", {
@@ -2541,7 +2557,8 @@ var SearchClient = class {
         brand_ids: params.brand_ids,
         color_ids: params.color_ids,
         status_ids: params.status_ids,
-        order: params.order
+        order: params.order,
+        seller_country: params.seller_country
       }
     });
   }
@@ -4189,6 +4206,612 @@ var AmazonClient = class {
   }
 };
 
+// src/shopee/search.ts
+var SearchClient5 = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Search Shopee for products by keyword.
+   *
+   * @param params - Search parameters including keyword, market, pagination, and sort.
+   * @returns Search result page with matched products and pagination metadata.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the parameters are invalid.
+   */
+  async search(params) {
+    return this.client.request("/v1/shopee/search", {
+      params: {
+        keyword: params.keyword,
+        market: params.market,
+        limit: params.limit,
+        offset: params.offset,
+        sort_by: params.sort_by
+      }
+    });
+  }
+  /**
+   * List products within a specific Shopee category.
+   *
+   * @param categoryId - The Shopee category ID.
+   * @param options - Optional parameters (market, limit, offset, sort_by).
+   * @returns Search result page with products in the category.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the category ID or market is invalid.
+   */
+  async categoryItems(categoryId, options = {}) {
+    return this.client.request(
+      `/v1/shopee/category/${categoryId}/items`,
+      {
+        params: {
+          market: options.market,
+          limit: options.limit,
+          offset: options.offset,
+          sort_by: options.sort_by
+        }
+      }
+    );
+  }
+};
+
+// src/shopee/products.ts
+var ProductsClient3 = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get full product detail (PDP) for a Shopee item.
+   *
+   * @param shopId - The Shopee shop identifier.
+   * @param itemId - The Shopee item identifier.
+   * @param options - Optional parameters (market).
+   * @returns Full product detail including pricing, ratings, images, and variations.
+   * @throws NotFoundError - If the product doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the market code is invalid.
+   */
+  async get(shopId, itemId, options = {}) {
+    return this.client.request(
+      `/v1/shopee/product/${shopId}/${itemId}`,
+      { params: { market: options.market } }
+    );
+  }
+};
+
+// src/shopee/reviews.ts
+var ReviewsClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get product reviews for a Shopee item.
+   *
+   * @param shopId - The Shopee shop identifier.
+   * @param itemId - The Shopee item identifier.
+   * @param options - Optional parameters (market, limit, offset, rating, filter).
+   * @returns Reviews result page with review items and aggregate summary.
+   * @throws NotFoundError - If the product doesn't exist.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the parameters are invalid.
+   */
+  async get(shopId, itemId, options = {}) {
+    return this.client.request(
+      `/v1/shopee/product/${shopId}/${itemId}/reviews`,
+      {
+        params: {
+          market: options.market,
+          limit: options.limit,
+          offset: options.offset,
+          rating: options.rating,
+          filter: options.filter
+        }
+      }
+    );
+  }
+};
+
+// src/shopee/reference.ts
+var ReferenceClient3 = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get all supported Shopee marketplaces.
+   *
+   * @returns Markets response with all supported Shopee markets (0 credits).
+   */
+  async markets() {
+    return this.client.request("/v1/shopee/markets");
+  }
+  /**
+   * Get the full category tree for a Shopee market.
+   *
+   * @param options - Optional parameters (market).
+   * @returns Category tree with all top-level and nested category nodes.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the market code is invalid.
+   */
+  async categories(options = {}) {
+    return this.client.request("/v1/shopee/categories", {
+      params: { market: options.market }
+    });
+  }
+};
+
+// src/shopee/client.ts
+var ShopeeClient = class {
+  /** Client for keyword search and category-item listing */
+  search;
+  /** Client for full product detail pages */
+  products;
+  /** Client for product reviews and rating summaries */
+  reviews;
+  /** Client for reference data (markets, category tree) */
+  reference;
+  /**
+   * Create a new Shopee client.
+   *
+   * @param client - The base HTTP client for making requests.
+   */
+  constructor(client) {
+    this.search = new SearchClient5(client);
+    this.products = new ProductsClient3(client);
+    this.reviews = new ReviewsClient(client);
+    this.reference = new ReferenceClient3(client);
+  }
+};
+
+// src/tiktok/users.ts
+var UsersClient4 = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get a TikTok user's full profile.
+   *
+   * @param username - The user's @handle (without the leading '@').
+   * @param options - Optional parameters (region).
+   * @returns The user profile response.
+   * @throws NotFoundError - If the user doesn't exist.
+   */
+  async get(username, options = {}) {
+    return this.client.request(`/v1/tiktok/users/${username}`, {
+      params: { region: options.region }
+    });
+  }
+  /**
+   * Get a TikTok user's posted videos.
+   *
+   * @param username - The user's @handle.
+   * @param options - Optional parameters (region, count, cursor).
+   * @returns A cursor-paginated list of videos.
+   */
+  async videos(username, options = {}) {
+    return this.client.request(`/v1/tiktok/users/${username}/videos`, {
+      params: { region: options.region, count: options.count, cursor: options.cursor }
+    });
+  }
+  /**
+   * Get a TikTok user's followers (best-effort; often guest-gated).
+   *
+   * @deprecated Requires an authenticated session; currently returns 410.
+   * Kept for forward-compatibility — the endpoint may be re-enabled when
+   * session-based access is supported.
+   *
+   * @param username - The user's @handle.
+   * @param options - Optional parameters (region, count, cursor).
+   * @returns A cursor-paginated list of follower authors.
+   */
+  async followers(username, options = {}) {
+    return this.client.request(`/v1/tiktok/users/${username}/followers`, {
+      params: { region: options.region, count: options.count, cursor: options.cursor }
+    });
+  }
+  /**
+   * Get accounts a TikTok user follows (best-effort).
+   *
+   * @deprecated Requires an authenticated session; currently returns 410.
+   * Kept for forward-compatibility — the endpoint may be re-enabled when
+   * session-based access is supported.
+   *
+   * @param username - The user's @handle.
+   * @param options - Optional parameters (region, count, cursor).
+   * @returns A cursor-paginated list of followed authors.
+   */
+  async following(username, options = {}) {
+    return this.client.request(`/v1/tiktok/users/${username}/following`, {
+      params: { region: options.region, count: options.count, cursor: options.cursor }
+    });
+  }
+  /**
+   * Get a TikTok user's liked videos (only if their Liked tab is public).
+   *
+   * @deprecated Requires an authenticated session; currently returns 410.
+   * Kept for forward-compatibility — the endpoint may be re-enabled when
+   * session-based access is supported.
+   *
+   * @param username - The user's @handle.
+   * @param options - Optional parameters (region, count).
+   * @returns A cursor-paginated list of videos.
+   */
+  async liked(username, options = {}) {
+    return this.client.request(`/v1/tiktok/users/${username}/liked`, {
+      params: { region: options.region, count: options.count }
+    });
+  }
+  /**
+   * Get videos a TikTok user has reposted.
+   *
+   * @param username - The user's @handle.
+   * @param options - Optional parameters (region, count).
+   * @returns A cursor-paginated list of videos.
+   */
+  async reposts(username, options = {}) {
+    return this.client.request(`/v1/tiktok/users/${username}/reposts`, {
+      params: { region: options.region, count: options.count }
+    });
+  }
+};
+
+// src/tiktok/videos.ts
+var VideosClient2 = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get full metadata for a single TikTok video/post.
+   *
+   * @param videoId - The video/post id.
+   * @param options - Optional parameters (region, username).
+   * @returns The video detail response.
+   * @throws NotFoundError - If the video doesn't exist.
+   */
+  async get(videoId, options = {}) {
+    return this.client.request(`/v1/tiktok/videos/${videoId}`, {
+      params: { region: options.region, username: options.username }
+    });
+  }
+  /**
+   * Get top-level comments on a TikTok video.
+   *
+   * @param videoId - The video/post id.
+   * @param options - Optional parameters (region, count, cursor).
+   * @returns A cursor-paginated list of comments.
+   */
+  async comments(videoId, options = {}) {
+    return this.client.request(`/v1/tiktok/videos/${videoId}/comments`, {
+      params: { region: options.region, count: options.count, cursor: options.cursor }
+    });
+  }
+  /**
+   * Get replies to a TikTok comment (best-effort).
+   *
+   * @param commentId - The comment id.
+   * @param options - Parameters including the required `videoId` (region, count, cursor).
+   * @returns A cursor-paginated list of reply comments.
+   */
+  async commentReplies(commentId, options) {
+    return this.client.request(`/v1/tiktok/comments/${commentId}/replies`, {
+      params: {
+        video_id: options.videoId,
+        region: options.region,
+        count: options.count,
+        cursor: options.cursor
+      }
+    });
+  }
+  /**
+   * Get TikTok's related videos for a given video.
+   *
+   * @param videoId - The video/post id.
+   * @param options - Optional parameters (region, count).
+   * @returns A cursor-paginated list of related videos.
+   */
+  async related(videoId, options = {}) {
+    return this.client.request(`/v1/tiktok/videos/${videoId}/related`, {
+      params: { region: options.region, count: options.count }
+    });
+  }
+  /**
+   * Get subtitle/caption tracks for a TikTok video.
+   *
+   * @param videoId - The video/post id.
+   * @param options - Optional parameters (region).
+   * @returns The transcript response with subtitle tracks and voice-to-text.
+   */
+  async transcript(videoId, options = {}) {
+    return this.client.request(`/v1/tiktok/videos/${videoId}/transcript`, {
+      params: { region: options.region }
+    });
+  }
+  /**
+   * Get cheap unauthenticated oEmbed metadata for a TikTok URL.
+   *
+   * @param url - Full TikTok video or profile URL.
+   * @param options - Optional parameters (region).
+   * @returns The oEmbed metadata.
+   */
+  async oembed(url, options = {}) {
+    return this.client.request("/v1/tiktok/oembed", {
+      params: { url, region: options.region }
+    });
+  }
+};
+
+// src/tiktok/search.ts
+var SearchClient6 = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * General TikTok search — video results from the Top feed.
+   *
+   * @param params - Search parameters including query, region, count, cursor.
+   * @returns A cursor-paginated list of videos.
+   */
+  async search(params) {
+    return this.client.request("/v1/tiktok/search", {
+      params: {
+        query: params.query,
+        region: params.region,
+        count: params.count,
+        cursor: params.cursor
+      }
+    });
+  }
+  /**
+   * Search TikTok videos by keyword.
+   *
+   * @param params - Search parameters including query, region, count, cursor.
+   * @returns A cursor-paginated list of videos.
+   */
+  async videos(params) {
+    return this.client.request("/v1/tiktok/search/videos", {
+      params: {
+        query: params.query,
+        region: params.region,
+        count: params.count,
+        cursor: params.cursor
+      }
+    });
+  }
+  /**
+   * Search TikTok users by keyword.
+   *
+   * @param params - Search parameters including query, region, count, cursor.
+   * @returns A cursor-paginated list of matching users.
+   */
+  async users(params) {
+    return this.client.request("/v1/tiktok/search/users", {
+      params: {
+        query: params.query,
+        region: params.region,
+        count: params.count,
+        cursor: params.cursor
+      }
+    });
+  }
+  /**
+   * Search TikTok hashtags by keyword.
+   *
+   * @param params - Search parameters including query, region, count, cursor.
+   * @returns A cursor-paginated list of matching hashtags.
+   */
+  async hashtags(params) {
+    return this.client.request("/v1/tiktok/search/hashtags", {
+      params: {
+        query: params.query,
+        region: params.region,
+        count: params.count,
+        cursor: params.cursor
+      }
+    });
+  }
+};
+
+// src/tiktok/music.ts
+var MusicClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get TikTok sound/music detail.
+   *
+   * @param musicId - The sound/music id.
+   * @param options - Optional parameters (region).
+   * @returns The music detail response.
+   * @throws NotFoundError - If the music doesn't exist.
+   */
+  async get(musicId, options = {}) {
+    return this.client.request(`/v1/tiktok/music/${musicId}`, {
+      params: { region: options.region }
+    });
+  }
+  /**
+   * Get videos using a given TikTok sound.
+   *
+   * @param musicId - The sound/music id.
+   * @param options - Optional parameters (region, count, cursor).
+   * @returns A cursor-paginated list of videos.
+   */
+  async videos(musicId, options = {}) {
+    return this.client.request(`/v1/tiktok/music/${musicId}/videos`, {
+      params: { region: options.region, count: options.count, cursor: options.cursor }
+    });
+  }
+};
+
+// src/tiktok/hashtags.ts
+var HashtagsClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get TikTok hashtag/challenge detail.
+   *
+   * @param name - The hashtag name (without the leading '#').
+   * @param options - Optional parameters (region).
+   * @returns The hashtag detail response.
+   * @throws NotFoundError - If the hashtag doesn't exist.
+   */
+  async get(name, options = {}) {
+    return this.client.request(`/v1/tiktok/hashtags/${name}`, {
+      params: { region: options.region }
+    });
+  }
+  /**
+   * Get videos tagged with a TikTok hashtag.
+   *
+   * @param name - The hashtag name (without the leading '#').
+   * @param options - Optional parameters (region, count, cursor).
+   * @returns A cursor-paginated list of videos.
+   */
+  async videos(name, options = {}) {
+    return this.client.request(`/v1/tiktok/hashtags/${name}/videos`, {
+      params: { region: options.region, count: options.count, cursor: options.cursor }
+    });
+  }
+};
+
+// src/tiktok/trending.ts
+var TrendingClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get trending videos from the TikTok Explore feed.
+   *
+   * @param options - Optional parameters (region, count).
+   * @returns A cursor-paginated list of trending videos.
+   */
+  async videos(options = {}) {
+    return this.client.request("/v1/tiktok/trending/videos", {
+      params: { region: options.region, count: options.count }
+    });
+  }
+  /**
+   * Get trending hashtags (mobile Discover surface — view_count + creators).
+   *
+   * @param options - Optional parameters (region, period, count).
+   * @returns The trending hashtags response.
+   */
+  async hashtags(options = {}) {
+    return this.client.request(
+      "/v1/tiktok/trending/hashtags",
+      { params: { region: options.region, period: options.period, count: options.count } }
+    );
+  }
+  /**
+   * Get trending songs/sounds (mobile hot-music feed — ranked by usage).
+   *
+   * @param options - Optional parameters (region, period, count).
+   * @returns The trending songs response.
+   */
+  async songs(options = {}) {
+    return this.client.request(
+      "/v1/tiktok/trending/songs",
+      { params: { region: options.region, period: options.period, count: options.count } }
+    );
+  }
+};
+
+// src/tiktok/ads.ts
+var AdsClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Search TikTok's Commercial Content Library (ad transparency) by keyword or advertiser.
+   *
+   * @param params - Optional parameters (query, advertiser_id, region, days, sort, offset, search_id, count).
+   * @returns The ad-library search response with ads and pagination.
+   */
+  async search(params = {}) {
+    return this.client.request("/v1/tiktok/ads/search", {
+      params: {
+        query: params.query,
+        advertiser_id: params.advertiser_id,
+        region: params.region,
+        days: params.days,
+        sort: params.sort,
+        offset: params.offset,
+        search_id: params.search_id,
+        count: params.count
+      }
+    });
+  }
+};
+
+// src/tiktok/reference.ts
+var ReferenceClient4 = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List supported TikTok content regions.
+   *
+   * @returns The regions response with all supported content regions.
+   */
+  async regions() {
+    return this.client.request("/v1/tiktok/regions");
+  }
+  /**
+   * Check the health of the TikTok scraper service.
+   *
+   * @returns The raw health payload from the scraper service.
+   */
+  async health() {
+    return this.client.request("/v1/tiktok/health");
+  }
+};
+
+// src/tiktok/client.ts
+var TikTokClient = class {
+  /** Client for profiles, videos, followers, following, liked, reposts */
+  users;
+  /** Client for video detail, comments, replies, related, transcript, oEmbed */
+  videos;
+  /** Client for keyword search across videos, users, and hashtags */
+  search;
+  /** Client for sound/music detail and videos using a sound */
+  music;
+  /** Client for hashtag detail and tagged videos */
+  hashtags;
+  /** Client for trending videos, hashtags, and songs */
+  trending;
+  /** Client for the Commercial Content Library (ad transparency) */
+  ads;
+  /** Client for reference data (regions) and service health */
+  reference;
+  /**
+   * Create a new TikTok client.
+   *
+   * @param client - The base HTTP client for making requests.
+   */
+  constructor(client) {
+    this.users = new UsersClient4(client);
+    this.videos = new VideosClient2(client);
+    this.search = new SearchClient6(client);
+    this.music = new MusicClient(client);
+    this.hashtags = new HashtagsClient(client);
+    this.trending = new TrendingClient(client);
+    this.ads = new AdsClient(client);
+    this.reference = new ReferenceClient4(client);
+  }
+};
+
 // src/client.ts
 var ScrapeBadger = class {
   baseClient;
@@ -4204,6 +4827,10 @@ var ScrapeBadger = class {
   reddit;
   /** Amazon scraper API client — 14 endpoints */
   amazon;
+  /** Shopee scraper API client — 6 endpoints across 11 markets */
+  shopee;
+  /** TikTok scraper API client — 26 endpoints */
+  tiktok;
   /**
    * Create a new ScrapeBadger client.
    *
@@ -4244,6 +4871,8 @@ var ScrapeBadger = class {
     this.google = new GoogleClient(this.baseClient);
     this.reddit = new RedditClient(this.baseClient);
     this.amazon = new AmazonClient(this.baseClient);
+    this.shopee = new ShopeeClient(this.baseClient);
+    this.tiktok = new TikTokClient(this.baseClient);
   }
 };
 
@@ -4289,8 +4918,22 @@ exports.RedditUsersClient = UsersClient3;
 exports.ScrapeBadger = ScrapeBadger;
 exports.ScrapeBadgerError = ScrapeBadgerError;
 exports.ServerError = ServerError;
+exports.ShopeeClient = ShopeeClient;
+exports.ShopeeProductsClient = ProductsClient3;
+exports.ShopeeReferenceClient = ReferenceClient3;
+exports.ShopeeReviewsClient = ReviewsClient;
+exports.ShopeeSearchClient = SearchClient5;
 exports.SpacesClient = SpacesClient;
 exports.StreamClient = StreamClient;
+exports.TikTokAdsClient = AdsClient;
+exports.TikTokClient = TikTokClient;
+exports.TikTokHashtagsClient = HashtagsClient;
+exports.TikTokMusicClient = MusicClient;
+exports.TikTokReferenceClient = ReferenceClient4;
+exports.TikTokSearchClient = SearchClient6;
+exports.TikTokTrendingClient = TrendingClient;
+exports.TikTokUsersClient = UsersClient4;
+exports.TikTokVideosClient = VideosClient2;
 exports.TimeoutError = TimeoutError;
 exports.TrendsClient = TrendsClient;
 exports.TweetsClient = TweetsClient;