scavio 0.18.0 → 0.19.0

package/README.md

@@ -1,7 +1,7 @@
 # Scavio
 
-TypeScript SDK for the [Scavio API](https://scavio.dev) — real-time web scraping
-and data extraction across 32 platforms on one API key, plus `extract()` to read
+TypeScript SDK for the [Scavio API](https://scavio.dev?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) — real-time web scraping
+and data extraction across 33 platforms on one API key, plus `extract()` to read
 any URL as clean Markdown.
 
 Structured JSON in, structured JSON out. No proxies, no headless browsers, no
@@ -10,7 +10,7 @@ per-site parsers to maintain.
 - **Search and SERP** — Google (organic, news, maps, shopping, flights, hotels, trends, AI Mode)
 - **E-commerce** — Amazon, Walmart, Costco, eBay, Target, Home Depot, TikTok Shop
 - **Real estate and travel** — Zillow, Redfin, Booking, Airbnb, Tripadvisor
-- **Reviews and local** — Yelp, G2, Capterra, Glassdoor, App Store, Google Play
+- **Reviews and local** — Trustpilot, Yelp, G2, Capterra, Glassdoor, App Store, Google Play
 - **Jobs and companies** — Indeed, Glassdoor, SEC EDGAR, Companies House
 - **Ads transparency** — Google Ads Transparency Center, Meta Ad Library
 - **Social and video** — YouTube, TikTok, Instagram, Threads, X, LinkedIn, Reddit, Kuaishou
@@ -66,6 +66,10 @@ limit on simultaneous in-flight requests: 1 on free and pay-as-you-go, 5 on
 Project, 10 on Bootstrap, 15 on Startup, 50 on Growth, and unlimited on
 Enterprise.
 
+Every request carries `X-Client-Source: scavio-js`. From Node.js (and other
+server runtimes) it also sends `User-Agent: scavio-js/<version>` (since 0.18.1);
+browsers do not allow a script to set `User-Agent`, so it is omitted there.
+
 ## API Reference
 
 ### Extract (any URL)
@@ -894,6 +898,52 @@ under a billed 200, so pass back the `slug` or `reviews_url` that `search` or
 already ships inside `product`. `vendor` is null on the product profile —
 Capterra does not publish it there.
 
+### Trustpilot
+
+Six endpoints, new in 0.19.0, 2 credits each.
+
+```typescript
+// Businesses matching a keyword, up to 100 per page.
+const found = await client.trustpilot.search({ query: "vpn", country: "US", page_size: 10 });
+
+// Full profile: TrustScore, rating distribution, reply rate and days to reply on
+// negative reviews, AI summary and topics, similar businesses, 20 newest reviews.
+const profile = await client.trustpilot.business({ domain: "nordvpn.com" });
+
+// Filtered reviews, 20 per page.
+const bad = await client.trustpilot.reviews({
+  domain: "nordvpn.com",
+  stars: [1, 2],
+  language: "en",
+  date_range: "last30days",
+});
+
+// The category tree, then ranked businesses in one category.
+const tree = await client.trustpilot.categories();
+const ranked = await client.trustpilot.category({
+  category_id: "vpn_service",
+  sort: "reviews_count",
+  min_trust_score: 4,
+  claimed_only: true,
+});
+
+// One review by id, with the business it is about.
+const one = await client.trustpilot.review({ review_id: "6aca2504b52cc4b518bf4b75" });
+```
+
+`business` and `reviews` take exactly one of `domain` or `url` (any
+trustpilot.com/review/ page). Reviews are capped at 10 pages of 20 (200) per
+filter combination; `max_page` says how far one goes, and slicing by `stars`,
+`language`, `date_range`, `topics` or `search` reaches more. `total_filtered`
+counts every match, so a date range doubles as review velocity. Topic ids for
+the `topics` filter come from `business`'s `topics`. Search and category rows
+carry `email` and `phone` only when the business published them; the AI summary
+and topics appear only when Trustpilot has them for the requested `language`.
+`min_trust_score` is a minimum star rating (3, 4 or 4.5): Trustpilot rounds
+TrustScore to stars, so 4 includes TrustScore 3.8 and up. An unknown business,
+review or category returns a 404 (`NotFoundError`) and is billed. No TrustScore
+history is returned.
+
 ### SEC EDGAR
 
 **Start with `lookup()`.** Callers hold a ticker; EDGAR is keyed by CIK.
@@ -1036,24 +1086,24 @@ MIT
 
 ## About Scavio
 
-[Scavio](https://scavio.dev) is a unified web data and
-[search API for AI agents](https://scavio.dev/search-api-for-ai-agents) — one API
+[Scavio](https://scavio.dev?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) is a unified web data and
+[search API for AI agents](https://scavio.dev/search-api-for-ai-agents?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) — one API
 key, structured JSON, no proxies or browser farms to run. It is a real-time
-[Tavily alternative](https://scavio.dev/alternatives/tavily) and
-[SerpAPI alternative](https://scavio.dev/alternatives/serpapi), and with
+[Tavily alternative](https://scavio.dev/alternatives/tavily?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) and
+[SerpAPI alternative](https://scavio.dev/alternatives/serpapi?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme), and with
 `extract()` it also covers the read-any-URL job people reach for Firecrawl to do.
 
 What teams build on it:
 
-- **SERP and answer engines** — [Google Search API](https://scavio.dev/google-search-api) for organic results, news, images, maps and the knowledge graph
-- **Price and catalog monitoring** — [Amazon Product API](https://scavio.dev/amazon-product-api), [Walmart Product API](https://scavio.dev/walmart-product-api), eBay, Target and Home Depot product, review and seller data
+- **SERP and answer engines** — [Google Search API](https://scavio.dev/google-search-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) for organic results, news, images, maps and the knowledge graph
+- **Price and catalog monitoring** — [Amazon Product API](https://scavio.dev/amazon-product-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme), [Walmart Product API](https://scavio.dev/walmart-product-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme), eBay, Target and Home Depot product, review and seller data
 - **Real estate and travel pipelines** — Zillow and Redfin listings and market stats, Booking, Airbnb and Tripadvisor rates and reviews
-- **Review mining and competitive research** — Yelp, G2, Capterra, Glassdoor, App Store and Google Play reviews on one shape
+- **Review mining and competitive research** — Trustpilot, Yelp, G2, Capterra, Glassdoor, App Store and Google Play reviews on one shape
 - **Recruiting and company intelligence** — Indeed jobs, Glassdoor salaries, SEC EDGAR filings and XBRL facts, UK Companies House officers and filing history
 - **Ad and creative intelligence** — Google Ads Transparency Center and Meta Ad Library creatives
-- **Social listening** — [YouTube API](https://scavio.dev/youtube-transcript-api), [TikTok API](https://scavio.dev/tiktok-api), [Instagram API](https://scavio.dev/instagram-api), [Reddit API](https://scavio.dev/reddit-api), [X API](https://scavio.dev/docs/x-search), [LinkedIn API](https://scavio.dev/docs/linkedin-person), Threads and Kuaishou
+- **Social listening** — [YouTube API](https://scavio.dev/youtube-transcript-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme), [TikTok API](https://scavio.dev/tiktok-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme), [Instagram API](https://scavio.dev/instagram-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme), [Reddit API](https://scavio.dev/reddit-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme), [X API](https://scavio.dev/docs/x-search?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme), [LinkedIn API](https://scavio.dev/docs/linkedin-person?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme), Threads and Kuaishou
 - **RAG ingestion** — `extract()` reads any URL and hands back readability Markdown ready to chunk and embed
 
-Teams choosing between providers can [compare Scavio vs alternatives](https://scavio.dev/compare) side by side.
+Teams choosing between providers can [compare Scavio vs alternatives](https://scavio.dev/compare?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) side by side.
 
-Get a free [API key](https://dashboard.scavio.dev/sign-up) and explore the [documentation](https://scavio.dev/docs/introduction).
+Get a free [API key](https://dashboard.scavio.dev/sign-up?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) and explore the [documentation](https://scavio.dev/docs/introduction?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme).

package/dist/index.cjs

@@ -60,6 +60,7 @@ __export(index_exports, {
   TikTokNamespace: () => TikTokNamespace,
   TikTokShopNamespace: () => TikTokShopNamespace,
   TripadvisorNamespace: () => TripadvisorNamespace,
+  TrustpilotNamespace: () => TrustpilotNamespace,
   WalmartNamespace: () => WalmartNamespace,
   XNamespace: () => XNamespace,
   YelpNamespace: () => YelpNamespace,
@@ -199,12 +200,25 @@ function parseRetryAfter(header) {
 var BASE_URL = "https://api.scavio.dev";
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
+var SDK_VERSION = true ? "0.19.0" : "0.0.0";
+var USER_AGENT = `scavio-js/${SDK_VERSION}`;
+function isServerRuntime() {
+  const g = globalThis;
+  if (typeof g.window !== "undefined" && typeof g.document !== "undefined") {
+    return false;
+  }
+  return typeof g.process?.versions?.node === "string";
+}
 function buildHeaders(apiKey) {
-  return {
+  const headers = {
     Authorization: `Bearer ${apiKey}`,
     "Content-Type": "application/json",
     "X-Client-Source": "scavio-js"
   };
+  if (isServerRuntime()) {
+    headers["User-Agent"] = USER_AGENT;
+  }
+  return headers;
 }
 function stripUndefined(obj) {
   const result = {};
@@ -2462,6 +2476,79 @@ var CostcoNamespace = class {
   }
 };
 
+// src/namespaces/trustpilot.ts
+var TrustpilotNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search Trustpilot businesses by keyword in one country: TrustScore, star
+   * rating, review count, categories, website, and the email, phone and
+   * address the business published. Up to 100 businesses per page.
+   *
+   * Costs 2 credits.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/trustpilot/search", options);
+  }
+  /**
+   * A Trustpilot business profile: TrustScore, rating distribution, review
+   * languages, categories, contact details, claimed and verification status,
+   * reply rate and reply speed on negative reviews, consumer alerts, the AI
+   * review summary and topics, similar businesses, and the 20 newest reviews
+   * in the chosen language. Pass exactly one of domain or url.
+   *
+   * Costs 2 credits.
+   */
+  async business(options) {
+    return this.client._post("/api/v1/trustpilot/business", options);
+  }
+  /**
+   * One page of 20 Trustpilot reviews for a business, filtered by stars,
+   * language, date range, topics, text search, verified-only and
+   * with-replies, sorted by recency or relevance. Returns total_filtered, so a
+   * date range doubles as review velocity. Up to 10 pages (200 reviews) per
+   * filter combination. Pass exactly one of domain or url.
+   *
+   * Costs 2 credits.
+   */
+  async reviews(options) {
+    return this.client._post("/api/v1/trustpilot/reviews", options);
+  }
+  /**
+   * The full Trustpilot category tree (top-level categories and their
+   * subcategories), or categories matching a name. Every category_id works
+   * with category().
+   *
+   * Costs 2 credits.
+   */
+  async categories(options = {}) {
+    return this.client._post("/api/v1/trustpilot/categories", options);
+  }
+  /**
+   * Businesses ranked in a Trustpilot category for one country, with
+   * TrustScore, review count, location, website, email and phone. Sort by
+   * relevance, review count or latest review, set a minimum star rating, or
+   * keep claimed profiles only. 20 per page.
+   *
+   * Costs 2 credits.
+   */
+  async category(options) {
+    return this.client._post("/api/v1/trustpilot/category", options);
+  }
+  /**
+   * One Trustpilot review by id: rating, title, full text, dates,
+   * verification, the reviewer's public profile summary, the business reply,
+   * and the business it is about.
+   *
+   * Costs 2 credits.
+   */
+  async review(options) {
+    return this.client._post("/api/v1/trustpilot/review", options);
+  }
+};
+
 // src/client.ts
 var DEFAULT_MAX_REQUESTS_PER_SECOND = 1;
 var MAX_REQUESTS_PER_SECOND = 50;
@@ -2498,6 +2585,7 @@ var Scavio = class {
   googleAds;
   metaAds;
   costco;
+  trustpilot;
   apiKey;
   baseUrl;
   timeout;
@@ -2550,6 +2638,7 @@ var Scavio = class {
     this.googleAds = new GoogleAdsNamespace(this);
     this.metaAds = new MetaAdsNamespace(this);
     this.costco = new CostcoNamespace(this);
+    this.trustpilot = new TrustpilotNamespace(this);
   }
   /** @internal */
   async _post(path, body) {
@@ -2648,6 +2737,7 @@ var Scavio = class {
   TikTokNamespace,
   TikTokShopNamespace,
   TripadvisorNamespace,
+  TrustpilotNamespace,
   WalmartNamespace,
   XNamespace,
   YelpNamespace,