scavio 0.8.0 → 0.10.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
 
@@ -205,29 +205,36 @@ await client.x.trending({ country: "UnitedStates" });
 ### LinkedIn
 
 ```typescript
-// Person profile, about, posts, and contact
+// Person profile, about, and posts. A handle or a full LinkedIn URL works
+// anywhere a reference is taken.
 await client.linkedin.person({ username: "williamhgates" });
-await client.linkedin.personAbout({ username: "williamhgates" });
+await client.linkedin.personAbout({ url: "https://www.linkedin.com/in/williamhgates/" });
 await client.linkedin.personPosts({ username: "williamhgates" });
-await client.linkedin.personContact({ username: "williamhgates" });
 
-// Company profile, posts, people, and jobs
+// Company profile and posts
 await client.linkedin.company({ company: "microsoft" });
 await client.linkedin.companyPosts({ company: "microsoft" });
-await client.linkedin.companyPeople({ company: "microsoft" });
-await client.linkedin.companyJobs({ company: "microsoft" });
-
-// Search people, jobs, and posts
-await client.linkedin.searchPeople({ search: "john", title: "engineer" });
-await client.linkedin.searchJobs({ search: "software engineer" });
-await client.linkedin.searchPosts({ search: "AI agents" });
-
-// Job, post, and post comments
-await client.linkedin.job({ job_id: "3900000000" });
-await client.linkedin.post({ post_id: "7486820977411145728" });
-await client.linkedin.postComments({ post_id: "7486820977411145728", sort_order: "relevance" });
+
+// Jobs: search, then pull detail for one listing
+await client.linkedin.searchJobs({ search: "software engineer", location: "United States" });
+await client.linkedin.job({ job_id: "4415427228" });
+
+// A post and its comments (10 per page)
+await client.linkedin.post({ post_id: "7488618410256523265" });
+await client.linkedin.postComments({ post_id: "7488618410256523265", page: 1 });
 ```
 
+All LinkedIn endpoints cost 1 credit.
+
+> **Retired endpoints.** The upstream provider withdrew the datasets behind
+> `personContact`, `companyPeople`, `companyJobs`, `searchPeople` and
+> `searchPosts`. They remain callable but always return HTTP 410 and are never
+> billed. `company()` returns `featured_employees` (a small sample of staff), and
+> `searchJobs()` with a company name substitutes for `companyJobs()`.
+>
+> `personPosts` and `companyPosts` return up to 50 posts; the provider exposes no
+> further pages, so those endpoints no longer take a cursor.
+
 ### TikTok
 
 ```typescript
@@ -265,8 +272,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 +418,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) {
@@ -648,48 +756,78 @@ var LinkedInNamespace = class {
     this.client = client;
   }
   client;
+  /** Full profile: about text, experience, education, honours and links. */
   async person(options) {
     return this.client._post("/api/v1/linkedin/person", options);
   }
+  /** The about-only slice of the profile payload. */
   async personAbout(options) {
     return this.client._post("/api/v1/linkedin/person/about", options);
   }
+  /** Recent posts, up to 50. Upstream exposes no further pages. */
   async personPosts(options) {
     return this.client._post("/api/v1/linkedin/person/posts", options);
   }
-  async personContact(options) {
-    return this.client._post("/api/v1/linkedin/person/contact", options);
-  }
+  /** Company profile, including locations and featured employees. */
   async company(options) {
     return this.client._post("/api/v1/linkedin/company", options);
   }
+  /** Recent company posts, up to 50. Upstream exposes no further pages. */
   async companyPosts(options) {
     return this.client._post("/api/v1/linkedin/company/posts", options);
   }
-  async companyPeople(options) {
-    return this.client._post("/api/v1/linkedin/company/people", options);
-  }
-  async companyJobs(options) {
-    return this.client._post("/api/v1/linkedin/company/jobs", options);
-  }
-  async searchPeople(options) {
-    return this.client._post("/api/v1/linkedin/search/people", options);
-  }
+  /** Job search. Upstream rotates its result set, so repeat calls differ. */
   async searchJobs(options) {
     return this.client._post("/api/v1/linkedin/search/jobs", options);
   }
-  async searchPosts(options) {
-    return this.client._post("/api/v1/linkedin/search/posts", options);
-  }
+  /** Full detail for one job listing, including the hiring company. */
   async job(options) {
     return this.client._post("/api/v1/linkedin/job", options);
   }
+  /** Full detail for one post, including its top visible comments. */
   async post(options) {
     return this.client._post("/api/v1/linkedin/post", options);
   }
+  /** Comments with their replies, 10 per page. */
   async postComments(options) {
     return this.client._post("/api/v1/linkedin/post/comments", options);
   }
+  /**
+   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * never billed.
+   */
+  async personContact(options) {
+    return this.client._post("/api/v1/linkedin/person/contact", options);
+  }
+  /**
+   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * never billed. `company()` returns `featured_employees`, a small sample of
+   * staff profiles.
+   */
+  async companyPeople(options) {
+    return this.client._post("/api/v1/linkedin/company/people", options);
+  }
+  /**
+   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * never billed. Use `searchJobs()` with the company name as the search term.
+   */
+  async companyJobs(options) {
+    return this.client._post("/api/v1/linkedin/company/jobs", options);
+  }
+  /**
+   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * never billed.
+   */
+  async searchPeople(options) {
+    return this.client._post("/api/v1/linkedin/search/people", options);
+  }
+  /**
+   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * never billed.
+   */
+  async searchPosts(options) {
+    return this.client._post("/api/v1/linkedin/search/posts", options);
+  }
 };
 
 // src/client.ts
@@ -700,6 +838,7 @@ var Scavio = class {
   youtube;
   reddit;
   tiktok;
+  tiktokShop;
   instagram;
   x;
   linkedin;
@@ -727,6 +866,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);