scavio 0.36.0 → 0.38.0

package/README.md

@@ -1,7 +1,7 @@
 # Scavio
 
 TypeScript SDK for the [Scavio API](https://scavio.dev?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) — real-time structured web
-data across 60 platforms on one API key, plus `extract()` to read
+data across 61 platforms on one API key, plus `extract()` to read
 any URL as clean Markdown, and `extract.map()` / `extract.crawl()` /
 `extract.batch()` to map, crawl and batch-extract whole websites.
 
@@ -9,7 +9,7 @@ Structured JSON in, structured JSON out. No per-site parsers to maintain.
 
 - **Search and SERP** — Google (organic, news, maps, shopping, flights, hotels, trends, AI Mode)
 - **AI assistants** — ChatGPT and Gemini answers with the sources they cite and the products they recommend
-- **E-commerce** — Amazon, Walmart, Costco, Lowe's, Sam's Club, Canadian Tire, Dollar General, Sephora, Ulta Beauty, ALDI, Micro Center, Walgreens, CVS, Whole Foods, Harbor Freight, PetSmart, Petco, iHerb, Chewy, Menards, Nordstrom, Mercado Libre, eBay, Target, Home Depot, TikTok Shop
+- **E-commerce** — Amazon, Walmart, Costco, Lowe's, Sam's Club, Canadian Tire, Dollar General, Sephora, Ulta Beauty, ALDI, Micro Center, Walgreens, CVS, Whole Foods, Harbor Freight, PetSmart, Petco, iHerb, Chewy, Menards, Nordstrom, Nordstrom Rack, Mercado Libre, eBay, Target, Home Depot, TikTok Shop
 - **Real estate and travel** — Zillow, Redfin, Realtor.com, Rightmove, Booking, Airbnb, Tripadvisor
 - **Reviews and local** — Trustpilot, Yelp, G2, Capterra, Glassdoor, App Store, Google Play
 - **Jobs and companies** — Indeed, Glassdoor, SEC EDGAR, Companies House
@@ -685,10 +685,10 @@ to `MENARDS_PRODUCT_TIMEOUT` (120s). None ever lowers a longer client timeout.
 
 ### [Nordstrom](https://scavio.dev/docs/nordstrom-search?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme)
 
-Seven endpoints, nordstrom.com (US site only). `search` and `product` are new in
+Eight endpoints, nordstrom.com (US site only). `search` and `product` are new in
 0.35.0; `category`, `brand`, `stores`, `availability` and `suggestions` are new
-in 0.36.0. `availability` costs 10 credits (the product page plus the store
-lookup); every other call costs 5.
+in 0.36.0; `reviews` is new in 0.37.0. `availability` costs 10 credits (the
+product page plus the store lookup) and `reviews` 10; every other call costs 5.
 
 - `search`, `category` and `brand` return 24 products a page with current and
   original price ranges, percent off, on-sale flag, rating, review count,
@@ -703,6 +703,15 @@ lookup); every other call costs 5.
   as a sku with UPC, price, price type, `in_stock` and the `quantity` available
   to ship. `in_stock` is true when the sku can be shipped or picked up in a
   store, so a sku can be in stock with `quantity` 0 (store-only).
+- `reviews` takes `url` or `style_id` and returns the product's full review
+  history, up to `max_reviews` per call (1-200, default 60). `sort` is
+  `most_helpful` (default), `most_recent`, `highest_rated` or `lowest_rated`;
+  filter with `stars` (e.g. `[1, 2]`), `verified_only`, `with_photos` or a text
+  `search` (`search` cannot be combined with `sort`). The response carries the
+  `summary` (average rating, total reviews, histogram, size and width rating,
+  praised and criticized features with a quote, rating-only count), the
+  `ai_summary`, `total_results`, `returned` and `has_more`. Rating-only reviews
+  are included with `title` and `text` null.
 - `availability` takes `url` or `style_id` (optionally `sku_id`) and returns per
   sku `ship_quantity`, `pickup_available`, `pick_quantity` and the stores that
   can do in-store pickup. Quantities are chain-wide; per store Nordstrom only
@@ -736,12 +745,68 @@ for (const sku of (stock as any).data.skus) {
 
 const ideas = await client.nordstrom.suggestions({ query: "nike air" });
 console.log((ideas as any).data.suggestions);
+
+const rev = (await client.nordstrom.reviews({ style_id: "7737947", sort: "most_recent", max_reviews: 100 })) as any;
+const { summary } = rev.data;
+console.log(summary.average_rating, summary.total_reviews, summary.ratings_histogram, summary.size_rating);
+console.log(rev.data.total_results, rev.data.returned, rev.data.has_more, rev.data.ai_summary);
+for (const r of rev.data.reviews.slice(0, 5)) {
+  console.log(r.date, r.rating, r.title, r.text, r.size_purchased, r.helpful_votes, r.badges, r.photos.length);
+}
+const critical = await client.nordstrom.reviews({ style_id: "7737947", stars: [1, 2], verified_only: true });
 ```
 
 `product` returns the reviews shown on the product page (up to about 13) plus
-the total review count and star histogram; the full review history is not
-available. An unknown style id, sku id, category or brand is a 404. Every call
-raises the request timeout to `NORDSTROM_TIMEOUT` (120s), never lowering a
+the total review count and star histogram; `reviews` returns the rest. An
+unknown style id, sku id, category or brand is a 404. Every call raises the
+request timeout to `NORDSTROM_TIMEOUT` (120s), except `reviews`, which takes
+20-60s (up to about 100s at 200 reviews) and raises it to
+`NORDSTROM_REVIEWS_TIMEOUT` (150s). Neither ever lowers a longer client timeout.
+If the upstream page still fails after the API's own retries, the call is an
+unbilled 502. For nordstromrack.com use `client.nordstromRack` (next section).
+
+### [Nordstrom Rack](https://scavio.dev/docs/nordstromrack-search?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme)
+
+Eight endpoints, new in 0.38.0, nordstromrack.com (US site only), on
+`client.nordstromRack`: a separate platform from `client.nordstrom` with the
+same methods, options and credit costs (`availability` and `reviews` 10, the
+rest 5).
+
+- `category` takes Rack's `/shop` and `/clearance` paths: departments, deals,
+  new arrivals, Clear the Rack (`/clearance`, `/clearance/women/clothing`) and
+  flash events (`/shop/flash` lists the live events as subcategories,
+  `/shop/flash/event-7` opens one). There is no `/browse` on Rack.
+- `brand` takes `/brands/<slug>` (`/brands/adidas`); Rack brand pages carry no
+  id, so the nordstrom.com `--<id>` form is a 404.
+- Every product row carries `clearance_price_range`, and during Clear the Rack
+  a clearance item can carry an extra percent off on top:
+  `promotion_price_range` is the price after it and `promotion_percent_off`
+  the extra percent. All three are null when not set; no response carries
+  event start or end dates.
+- `stores` and `availability` cover Rack stores only; pickup quantities are
+  chain-wide.
+- `reviews` returns Rack's own review pool, separate from nordstrom.com's, so
+  the same style can show a different rating and review count on each.
+
+```ts
+const clr = (await client.nordstromRack.category({ category: "/clearance/women", sort: "percent_off" })) as any;
+for (const p of clr.data.products.slice(0, 5)) {
+  console.log(p.style_id, p.name, p.price, p.clearance_price_range, p.promotion_price_range, p.promotion_percent_off);
+}
+
+const events = (await client.nordstromRack.category({ category: "/shop/flash" })) as any;
+console.log(events.data.category.subcategories.map((e: any) => e.path));
+
+const item = await client.nordstromRack.product({ style_id: "8816500" });
+const brand = await client.nordstromRack.brand({ brand: "/brands/adidas" });
+const stock = await client.nordstromRack.availability({ style_id: "7737947" });
+const near = await client.nordstromRack.stores({ zip: "10001" });
+const rev = await client.nordstromRack.reviews({ style_id: "7737947", max_reviews: 50 });
+```
+
+Every call raises the request timeout to `NORDSTROM_RACK_TIMEOUT` (120s),
+except `reviews`, which takes 15-60s (up to about 100s at 200 reviews) and
+raises it to `NORDSTROM_RACK_REVIEWS_TIMEOUT` (150s). Neither ever lowers a
 longer client timeout.
 
 ### [Mercado Libre](https://scavio.dev/docs/mercadolibre-search?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme)

package/dist/index.cjs

@@ -76,8 +76,12 @@ __export(index_exports, {
   MetaAdsNamespace: () => MetaAdsNamespace,
   MicroCenterNamespace: () => MicroCenterNamespace,
   MissingAPIKeyError: () => MissingAPIKeyError,
+  NORDSTROM_RACK_REVIEWS_TIMEOUT: () => NORDSTROM_RACK_REVIEWS_TIMEOUT,
+  NORDSTROM_RACK_TIMEOUT: () => NORDSTROM_RACK_TIMEOUT,
+  NORDSTROM_REVIEWS_TIMEOUT: () => NORDSTROM_REVIEWS_TIMEOUT,
   NORDSTROM_TIMEOUT: () => NORDSTROM_TIMEOUT,
   NordstromNamespace: () => NordstromNamespace,
+  NordstromRackNamespace: () => NordstromRackNamespace,
   NotFoundError: () => NotFoundError,
   PETCO_SLOW_TIMEOUT: () => PETCO_SLOW_TIMEOUT,
   PetcoNamespace: () => PetcoNamespace,
@@ -261,7 +265,7 @@ function parseRetryAfter(header) {
 var BASE_URL = "https://api.scavio.dev";
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
-var SDK_VERSION = true ? "0.36.0" : "0.0.0";
+var SDK_VERSION = true ? "0.38.0" : "0.0.0";
 var USER_AGENT = `scavio-js/${SDK_VERSION}`;
 function isServerRuntime() {
   const g = globalThis;
@@ -3906,6 +3910,7 @@ var MenardsNamespace = class {
 
 // src/namespaces/nordstrom.ts
 var NORDSTROM_TIMEOUT = 12e4;
+var NORDSTROM_REVIEWS_TIMEOUT = 15e4;
 var NordstromNamespace = class {
   constructor(client) {
     this.client = client;
@@ -3940,8 +3945,9 @@ var NordstromNamespace = class {
    * a store reads in stock with quantity 0 (availability() lists its pickup
    * stores). Includes the reviews shown on the product page (up to about 13),
    * with the total review count; each review has title, text, rating, size
-   * rating, author, date, helpful votes and verified-purchase flag. Pass url
-   * or style_id. An unknown style id is a 404.
+   * rating, author, date, helpful votes and verified-purchase flag
+   * (reviews() pages the full review history). Pass url or style_id. An
+   * unknown style id is a 404.
    *
    * Costs 5 credits.
    */
@@ -4018,6 +4024,173 @@ var NordstromNamespace = class {
   async suggestions(options) {
     return this.client._post("/api/v1/nordstrom/suggestions", options, void 0, NORDSTROM_TIMEOUT);
   }
+  /**
+   * Customer reviews of one nordstrom.com (US) product by URL or style id, up
+   * to 200 per call (default 60), sorted most helpful (default), most recent,
+   * highest rated or lowest rated, optionally filtered to star ratings,
+   * verified purchases, reviews with photos, or a text search. Returns the
+   * product's review summary (average rating, total reviews, star histogram,
+   * size rating 1 runs small to 5 runs big, width rating where the site has
+   * one, the most mentioned praised and criticized features with a quote each,
+   * and the count of rating-only reviews), the AI review summary when the site
+   * shows one, the number of reviews matching the filters (total_results),
+   * returned and has_more. Each review has id, title, text, star rating, size
+   * rating, author, date, helpful votes, verified-purchase flag, reviewer
+   * badges (verified_purchaser, top_250, top_1000), size and color purchased,
+   * the reviewer's height, weight, body type and usual sizes when given,
+   * secondary ratings (Size, with its scale), the site it was syndicated from
+   * (e.g. nordstromrack.com) and photos with thumbnails. Rating-only reviews
+   * are included with title and text null. Takes 20-60s, up to about 100s at
+   * max_reviews 200, so the request timeout is raised to
+   * NORDSTROM_REVIEWS_TIMEOUT. A product with no reviews returns an empty
+   * list; an unknown style id is a 404.
+   *
+   * Costs 10 credits.
+   */
+  async reviews(options) {
+    return this.client._post("/api/v1/nordstrom/reviews", options, void 0, NORDSTROM_REVIEWS_TIMEOUT);
+  }
+};
+
+// src/namespaces/nordstrom-rack.ts
+var NORDSTROM_RACK_TIMEOUT = 12e4;
+var NORDSTROM_RACK_REVIEWS_TIMEOUT = 15e4;
+var NordstromRackNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search nordstromrack.com (US) products, 24 per page, sorted by relevance,
+   * rating, price, newest or percent off. Each result has style id, URL,
+   * name, brand, image, current price and price range in dollars, the
+   * compare-at price range Rack strikes through (original_price_range),
+   * percent off and on-sale flag, the clearance price range, any promotion on
+   * top (promotion_price_range, and promotion_percent_off: the extra percent
+   * off the clearance price during Clear the Rack, otherwise off Rack's
+   * regular price), rating, review count (Rack's own reviews), badges such as
+   * new_markdown or final_sale, a low-inventory flag, marketplace seller and
+   * every color. Also returns the total result count and page count. Use a
+   * result's url or style_id with product().
+   *
+   * Costs 5 credits.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/nordstromrack/search", options, void 0, NORDSTROM_RACK_TIMEOUT);
+  }
+  /**
+   * One nordstromrack.com (US) product by URL or style id: name, brand, brand
+   * page URL, description, feature bullets, fit notes, final-sale flag,
+   * current, compare-at and clearance price ranges, percent off, any promotion
+   * on top (promotion_price_range and promotion_percent_off, e.g. Clear the
+   * Rack's extra 25% off clearance), rating, review count, the star
+   * histogram, the size-fit distribution, the AI review summary when the site
+   * shows one, praised and criticized features, breadcrumbs and images. Every
+   * color lists every size as a sku with sku id, size, UPC, price, compare-at
+   * price, percent off, price type (regular, clearance, promotion), in_stock
+   * and the quantity available to ship. Includes the reviews shown on the
+   * product page (up to about 13), with the total review count (reviews()
+   * pages the full history). Ratings and reviews are Rack's own, separate
+   * from nordstrom.com's. Pass url or style_id. An unknown style id is a 404.
+   *
+   * Costs 5 credits.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/nordstromrack/product", options, void 0, NORDSTROM_RACK_TIMEOUT);
+  }
+  /**
+   * Browse a nordstromrack.com (US) category page, 24 products per page,
+   * sorted by relevance, rating, price, newest or percent off. Works on every
+   * /shop and /clearance listing: departments (/shop/women), deals
+   * (/shop/deals/black-friday), new arrivals (/shop/new-arrivals), Clear the
+   * Rack (/clearance, /clearance/women/clothing) and flash events: /shop/flash
+   * lists the live events as subcategories (it has no products of its own),
+   * and each event (/shop/flash/event-7) is a listing whose first page shows
+   * the event's featured products first. Returns the category's name, page
+   * title, path, URL, breadcrumbs and subcategories, products with the same
+   * fields as a search result, the total result count, page count and the
+   * filter sidebar with option counts. An unknown category is a 404.
+   *
+   * Costs 5 credits.
+   */
+  async category(options) {
+    return this.client._post("/api/v1/nordstromrack/category", options, void 0, NORDSTROM_RACK_TIMEOUT);
+  }
+  /**
+   * List a brand's products on nordstromrack.com (US) from its brand page
+   * (/brands/adidas), 24 per page, sorted by relevance, rating, price, newest
+   * or percent off. Returns the brand's name, path, URL and breadcrumbs,
+   * products with the same fields as a search result, the total result count,
+   * page count and the filter sidebar with option counts. An unknown brand is
+   * a 404.
+   *
+   * Costs 5 credits.
+   */
+  async brand(options) {
+    return this.client._post("/api/v1/nordstromrack/brand", options, void 0, NORDSTROM_RACK_TIMEOUT);
+  }
+  /**
+   * Find Nordstrom Rack stores near a US ZIP code or latitude/longitude
+   * within up to 100 miles, nearest first, or look Rack stores up by store
+   * number. Each store has store number, name, type (rack), address, phone,
+   * weekly hours, holiday hours when posted, open and close times for the
+   * next 8 days, time zone, distance in miles, coordinates, whether it offers
+   * buy-online pickup and curbside pickup, its amenities and its store page
+   * URL. A ZIP with no store in range returns an empty list.
+   *
+   * Costs 5 credits.
+   */
+  async stores(options) {
+    return this.client._post("/api/v1/nordstromrack/stores", options, void 0, NORDSTROM_RACK_TIMEOUT);
+  }
+  /**
+   * Online and Rack store-pickup availability for every size and color of
+   * one nordstromrack.com (US) product, by URL or style id, optionally one
+   * sku. Each sku has sku id, size, color, UPC, in_stock, whether it ships
+   * and the quantity available to ship, the quantity available for pickup,
+   * and the Rack stores where it can be picked up (store number, name,
+   * address, city, state, ZIP, phone). Quantities are chain-wide: per store
+   * the site only says whether pickup is available, not how many. An unknown
+   * style id or sku id is a 404.
+   *
+   * Costs 10 credits (the product page plus the store lookup).
+   */
+  async availability(options) {
+    return this.client._post("/api/v1/nordstromrack/availability", options, void 0, NORDSTROM_RACK_TIMEOUT);
+  }
+  /**
+   * The search-box autocomplete of nordstromrack.com: the queries Nordstrom
+   * Rack suggests for a partial search term, most likely first. Useful for
+   * keyword research and for building queries for search().
+   *
+   * Costs 5 credits.
+   */
+  async suggestions(options) {
+    return this.client._post("/api/v1/nordstromrack/suggestions", options, void 0, NORDSTROM_RACK_TIMEOUT);
+  }
+  /**
+   * Customer reviews of one nordstromrack.com (US) product by URL or style
+   * id, up to 200 per call (default 60), sorted most helpful (default), most
+   * recent, highest rated or lowest rated, optionally filtered to star
+   * ratings, verified purchases, reviews with photos, or a text search. Rack
+   * has its own review pool, separate from nordstrom.com's. Returns the review
+   * summary (average rating, total reviews, star histogram, size and width
+   * rating, praised and criticized features, rating-only count), the AI
+   * review summary when the site shows one, total_results, returned and
+   * has_more. Each review has id, title, text, star rating, size rating,
+   * author, date, helpful votes, verified-purchase flag, reviewer badges,
+   * size and color purchased, reviewer body details when given, secondary
+   * ratings, the site it was syndicated from and photos. Rating-only reviews
+   * are included with title and text null. Takes 15-60s, up to about 100s at
+   * max_reviews 200, so the request timeout is raised to
+   * NORDSTROM_RACK_REVIEWS_TIMEOUT. A product with no reviews returns an
+   * empty list; an unknown style id is a 404.
+   *
+   * Costs 10 credits.
+   */
+  async reviews(options) {
+    return this.client._post("/api/v1/nordstromrack/reviews", options, void 0, NORDSTROM_RACK_REVIEWS_TIMEOUT);
+  }
 };
 
 // src/namespaces/trustpilot.ts
@@ -4553,6 +4726,7 @@ var Scavio = class extends ScavioCore {
   chewy;
   menards;
   nordstrom;
+  nordstromRack;
   trustpilot;
   chatgpt;
   gemini;
@@ -4634,6 +4808,7 @@ var Scavio = class extends ScavioCore {
     this.chewy = new ChewyNamespace(this);
     this.menards = new MenardsNamespace(this);
     this.nordstrom = new NordstromNamespace(this);
+    this.nordstromRack = new NordstromRackNamespace(this);
     this.trustpilot = new TrustpilotNamespace(this);
     this.chatgpt = new ChatgptNamespace(this);
     this.gemini = new GeminiNamespace(this);
@@ -4789,8 +4964,12 @@ async function getSubtle() {
   MetaAdsNamespace,
   MicroCenterNamespace,
   MissingAPIKeyError,
+  NORDSTROM_RACK_REVIEWS_TIMEOUT,
+  NORDSTROM_RACK_TIMEOUT,
+  NORDSTROM_REVIEWS_TIMEOUT,
   NORDSTROM_TIMEOUT,
   NordstromNamespace,
+  NordstromRackNamespace,
   NotFoundError,
   PETCO_SLOW_TIMEOUT,
   PetcoNamespace,