scavio 0.8.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # Scavio
 
-TypeScript SDK for the [Scavio Search API](https://scavio.dev) — real-time Google, Amazon, Walmart, YouTube, Reddit, TikTok, Instagram, X, and LinkedIn data.
+TypeScript SDK for the [Scavio Search API](https://scavio.dev) — real-time Google, Amazon, Walmart, YouTube, Reddit, TikTok, TikTok Shop, Instagram, X, and LinkedIn data.
 
 ## Install
 
@@ -265,8 +265,70 @@ await client.tiktok.userFollowers({ sec_user_id: "abc123" });
 await client.tiktok.userFollowings({ sec_user_id: "abc123" });
 ```
 
+### TikTok Shop
+
+Every TikTok Shop endpoint costs 1 credit. Two limits to design around:
+
+- `product()` resolves only about 44% of the product ids returned by `search()`.
+  Upstream has no detail data for the rest, so an HTTP 404 is a normal outcome, not an
+  error — skip the item instead of retrying. Search to product is not a reliable
+  pipeline. `product()` **throws** `NotFoundError` on that 404 (there is no `data`
+  field in the body to test), so a loop over search ids must catch it:
+
+  ```typescript
+  import { NotFoundError } from "scavio";
+
+  for (const productId of productIds) {
+    try {
+      const detail = await client.tiktokShop.product({ product_id: productId });
+    } catch (e) {
+      if (e instanceof NotFoundError) continue; // no detail upstream; skip
+      throw e;
+    }
+  }
+  ```
+
+  `productReviews()` often works for ids `product()` cannot resolve: of 8 such ids
+  tested, 8 returned HTTP 200 and 7 carried at least one review, so it is a useful
+  fallback source of product detail.
+- `product()` does not return a price; upstream masks it on the product page. Exact
+  prices come from `search()`, `shopProducts()`, and `categoryProducts()`.
+
+```typescript
+// Search products (US catalog, exact prices, cursor pagination)
+await client.tiktokShop.search({ search: "phone case" });
+
+// Keyword suggestions (8 regions)
+await client.tiktokShop.searchSuggestions({ search: "wireless", region: "US" });
+
+// Product detail (no price; a 404 is normal, see above)
+await client.tiktokShop.product({ product_id: "1732293553906094315" });
+
+// Product reviews (up to 200 per call)
+await client.tiktokShop.productReviews({
+  product_id: "1732293553906094315",
+  page_size: 200,
+  sort: "relevant",
+});
+
+// Category tree (28 top-level, 240 nodes)
+await client.tiktokShop.categories();
+
+// Products in a category (US and GB only)
+await client.tiktokShop.categoryProducts({ category_id: "601450" });
+
+// A shop's catalog, 30 per page
+await client.tiktokShop.shopProducts({ shop_id: "7495514739648989419" });
+
+// Resolve any TikTok Shop URL or share link to a product_id / shop_id
+await client.tiktokShop.resolve({ url: "https://vt.tiktok.com/ZT2AHoGsE/" });
+```
+
 ### Instagram
 
+Credit cost varies by endpoint: `userPosts` costs 2 credits, every other
+Instagram endpoint costs 8.
+
 ```typescript
 // User profile
 await client.instagram.profile({ username: "instagram" });
@@ -349,7 +411,7 @@ MIT
 - [Amazon Product API](https://scavio.dev/amazon-product-api) and [Walmart Product API](https://scavio.dev/walmart-product-api) — product search and details
 - [YouTube API](https://scavio.dev/youtube-transcript-api), [TikTok API](https://scavio.dev/tiktok-api), and [Instagram API](https://scavio.dev/instagram-api) — video and social media data
 - [Reddit API](https://scavio.dev/reddit-api) — posts and threaded comments
-- [X API](https://scavio.dev/x-api) and [LinkedIn API](https://scavio.dev/linkedin-api) — tweets, profiles, companies, and jobs
+- [X API](https://scavio.dev/docs/x-search) and [LinkedIn API](https://scavio.dev/docs/linkedin-person) — tweets, profiles, companies, and jobs
 
 Teams choosing between providers can [compare Scavio vs alternatives](https://scavio.dev/compare) side by side.
 

package/dist/index.cjs

@@ -466,6 +466,114 @@ var TikTokNamespace = class {
   }
 };
 
+// src/namespaces/tiktok-shop.ts
+var TikTokShopNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search TikTok Shop products by keyword (US catalog), up to 30 per page with
+   * exact prices, ratings, and shop details. Paginate with next_cursor and dedupe
+   * by product_id across pages.
+   *
+   * This is one of the three endpoints that return exact prices; tiktokShop.product()
+   * does not return a price. A product_id returned here is not guaranteed to resolve
+   * on tiktokShop.product() - only about 44% do.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/tiktok-shop/search", options);
+  }
+  /**
+   * Keyword autocomplete and expansion for a partial query, across 8 marketplace
+   * regions. Suggestions are not guaranteed prefix matches: a misspelling returns
+   * typo corrections, and results can include brand and shop names.
+   */
+  async searchSuggestions(options) {
+    return this.client._post("/api/v1/tiktok-shop/search/suggestions", options);
+  }
+  /**
+   * Full product detail: description, images, variants with stock, shipping, shop
+   * profile, category path, and top reviews.
+   *
+   * Two limits worth knowing before you build on this:
+   *
+   * 1. It resolves only about 44% of the product ids returned by tiktokShop.search().
+   *    Upstream has no detail data for the rest, so an HTTP 404 is a normal outcome,
+   *    not an error. Skip the item rather than retrying - retries do not help and no
+   *    other region carries it. Search to product is not a reliable pipeline.
+   *
+   *    This method throws `NotFoundError` on that 404 (there is no `data` field in
+   *    the response body to test), so a loop over search ids must catch it or it
+   *    dies on the first miss:
+   *
+   *    ```ts
+   *    import { NotFoundError } from "scavio";
+   *
+   *    for (const productId of productIds) {
+   *      try {
+   *        const detail = await client.tiktokShop.product({ product_id: productId });
+   *      } catch (e) {
+   *        if (e instanceof NotFoundError) continue; // no detail upstream; skip
+   *        throw e;
+   *      }
+   *    }
+   *    ```
+   *
+   *    tiktokShop.productReviews() often works for ids product() cannot resolve: of
+   *    8 such ids tested, 8 returned HTTP 200 and 7 carried at least one review, so
+   *    it is a useful fallback source of product detail.
+   * 2. It does NOT return a price. Upstream masks the price on the product page.
+   *    Exact prices come from tiktokShop.search(), tiktokShop.shopProducts(), and
+   *    tiktokShop.categoryProducts().
+   */
+  async product(options) {
+    return this.client._post("/api/v1/tiktok-shop/product", options);
+  }
+  /**
+   * Paginated product reviews with text, images, star histogram, and
+   * verified-purchase flags, up to 200 per call. total_reviews drifts between calls
+   * and must not be used to compute a page count; page with has_more instead.
+   */
+  async productReviews(options) {
+    return this.client._post("/api/v1/tiktok-shop/product/reviews", options);
+  }
+  /**
+   * The global TikTok Shop category tree: 28 top-level categories, 240 nodes, two
+   * levels deep. Category ids are identical in every region and names are always
+   * English.
+   */
+  async categories() {
+    return this.client._post("/api/v1/tiktok-shop/categories", {});
+  }
+  /**
+   * Products listed under a category id from tiktokShop.categories(), with exact
+   * prices. Page size is inconsistent upstream (15 to 20 per page), so always
+   * paginate with next_cursor rather than assuming a fixed page size. Category
+   * listings are shallow: after a few pages the source stops returning new products
+   * and has_more turns false, which is the end of the listing rather than an error.
+   */
+  async categoryProducts(options) {
+    return this.client._post("/api/v1/tiktok-shop/category/products", options);
+  }
+  /**
+   * A shop's product catalog, 30 per page, with exact prices. Shop follower count,
+   * location, and shop-level rating are not available here; call
+   * tiktokShop.product() for the full shop profile.
+   */
+  async shopProducts(options) {
+    return this.client._post("/api/v1/tiktok-shop/shop/products", options);
+  }
+  /**
+   * Resolve any TikTok Shop URL or share link to a product_id or shop_id, ready to
+   * pass to the other methods. Accepts canonical product and store pages,
+   * tiktok.com/view links, affiliate share links, and vt.tiktok.com short links.
+   */
+  async resolve(options) {
+    return this.client._post("/api/v1/tiktok-shop/resolve", options);
+  }
+};
+
 // src/namespaces/instagram.ts
 var InstagramNamespace = class {
   constructor(client) {
@@ -700,6 +808,7 @@ var Scavio = class {
   youtube;
   reddit;
   tiktok;
+  tiktokShop;
   instagram;
   x;
   linkedin;
@@ -727,6 +836,7 @@ var Scavio = class {
     this.youtube = new YouTubeNamespace(this);
     this.reddit = new RedditNamespace(this);
     this.tiktok = new TikTokNamespace(this);
+    this.tiktokShop = new TikTokShopNamespace(this);
     this.instagram = new InstagramNamespace(this);
     this.x = new XNamespace(this);
     this.linkedin = new LinkedInNamespace(this);