scavio 0.31.0 → 0.32.1

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 42 platforms on one API key, plus `extract()` to read
+data across 52 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, 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, 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
@@ -553,6 +553,59 @@ Sam's Club, Canadian Tire and Dollar General call costs 1. Sam's Club caps
 carry the current price only, with no was-price. Canadian Tire and Dollar
 General return a rating and review count but no review text.
 
+### Sephora, Ulta Beauty, ALDI, Micro Center, Walgreens and CVS
+
+Six US retailers, new in 0.32.0. Where prices or stock are per store, pass the
+store number on the call (`aldi.stores`, `microCenter.stores`,
+`walgreens.stores`; CVS has no locator).
+
+```typescript
+// Sephora: 60 products per page. product() takes a result's url (faster)
+// or its product_id, and returns a review summary with pro and con
+// sentiment counts - no review text.
+await client.sephora.search({ query: "lipstick", sort: "best_selling", zip: "10001" }); // + same_day_eligible
+await client.sephora.category({ category: "lipstick" });
+await client.sephora.product({ product_id: "P510799" });
+
+// Ulta Beauty: stores() is in stock / out of stock for one shade or size at
+// the 10 stores nearest a ZIP (no unit counts).
+await client.ulta.search({ query: "lipstick" });
+await client.ulta.category({ category: "/shop/makeup/lips/lipstick" });
+await client.ulta.product({ url: "https://www.ulta.com/p/serum-lipstick-pimprod2057119", sku: "2648428" });
+await client.ulta.stores({ product_id: "pimprod2057119", sku_id: "2648428", zip: "10001" });
+
+// ALDI: prices are per store AND per service_type - instore (default, the
+// shelf price), pickup or delivery (online prices, often higher).
+await client.aldi.stores({ zip: "33131" });
+await client.aldi.search({ query: "milk", store_id: "151248", service_type: "pickup" });
+await client.aldi.product({ product_id: "16902710", store_id: "151248" });
+
+// Micro Center: stock is per 3-digit store_id (web store 029 when omitted);
+// counts are capped at 25+ (quantity_capped).
+await client.microCenter.stores({ state: "TX" });
+await client.microCenter.search({ query: "rtx 5070", store_id: "131" });
+await client.microCenter.product({ product_id: "691231", store_id: "131" }); // open-box units, stores_in_stock
+
+// Walgreens: prices are national; stock() checks up to 20 stores per call.
+const wg = await client.walgreens.stores({ zip: "60614" });
+const storeNumber = (wg.data as any).stores[0].store_number; // "15350"
+await client.walgreens.search({ query: "shampoo", store_id: storeNumber });
+await client.walgreens.product({ product_id: "300452904" });
+await client.walgreens.stock({ product_id: "300452904", store_ids: [storeNumber] });
+
+// CVS: no store locator - the store number is on every cvs.com store page
+// ("Store ID: #7019"). search() defaults to store 7019 (New York).
+await client.cvs.search({ query: "toothpaste", store_id: "7019" });
+await client.cvs.product({ product_id: "832677" });
+await client.cvs.stock({ sku_ids: ["832677"], store_id: "7019" });
+```
+
+Sephora, Ulta Beauty, ALDI and CVS calls cost 1 credit each. Micro Center
+`search` and `product` cost 2 and `stores` 1. Walgreens `search`, `product` and
+`stores` cost 2 and `stock` 4. CVS `product` can take 10-30+ seconds, so it
+raises the request timeout to `CVS_PRODUCT_TIMEOUT` (120s) when the client's is
+shorter; it never lowers it.
+
 ### [Mercado Libre](https://scavio.dev/docs/mercadolibre-search?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme)
 
 Five endpoints, new in 0.21.0: `reviews` costs 1 credit, the other four 2. The

package/dist/index.cjs

@@ -32,15 +32,18 @@ var index_exports = {};
 __export(index_exports, {
   AI_PROMPT_TIMEOUT: () => AI_PROMPT_TIMEOUT,
   AirbnbNamespace: () => AirbnbNamespace,
+  AldiNamespace: () => AldiNamespace,
   AmazonNamespace: () => AmazonNamespace,
   AppStoreNamespace: () => AppStoreNamespace,
   BadRequestError: () => BadRequestError,
   BookingNamespace: () => BookingNamespace,
+  CVS_PRODUCT_TIMEOUT: () => CVS_PRODUCT_TIMEOUT,
   CanadianTireNamespace: () => CanadianTireNamespace,
   CapterraNamespace: () => CapterraNamespace,
   ChatgptNamespace: () => ChatgptNamespace,
   CompaniesHouseNamespace: () => CompaniesHouseNamespace,
   CostcoNamespace: () => CostcoNamespace,
+  CvsNamespace: () => CvsNamespace,
   DEFAULT_MAX_REQUESTS_PER_SECOND: () => DEFAULT_MAX_REQUESTS_PER_SECOND,
   DollarGeneralNamespace: () => DollarGeneralNamespace,
   EbayNamespace: () => EbayNamespace,
@@ -64,6 +67,7 @@ __export(index_exports, {
   MAX_REQUESTS_PER_SECOND: () => MAX_REQUESTS_PER_SECOND,
   MercadoLibreNamespace: () => MercadoLibreNamespace,
   MetaAdsNamespace: () => MetaAdsNamespace,
+  MicroCenterNamespace: () => MicroCenterNamespace,
   MissingAPIKeyError: () => MissingAPIKeyError,
   NotFoundError: () => NotFoundError,
   RateLimitError: () => RateLimitError,
@@ -79,12 +83,15 @@ __export(index_exports, {
   ScavioError: () => ScavioError,
   ScavioJobTimeoutError: () => ScavioJobTimeoutError,
   ScavioTimeoutError: () => ScavioTimeoutError,
+  SephoraNamespace: () => SephoraNamespace,
   TargetNamespace: () => TargetNamespace,
   ThreadsNamespace: () => ThreadsNamespace,
   TikTokNamespace: () => TikTokNamespace,
   TikTokShopNamespace: () => TikTokShopNamespace,
   TripadvisorNamespace: () => TripadvisorNamespace,
   TrustpilotNamespace: () => TrustpilotNamespace,
+  UltaNamespace: () => UltaNamespace,
+  WalgreensNamespace: () => WalgreensNamespace,
   WalmartNamespace: () => WalmartNamespace,
   XNamespace: () => XNamespace,
   YelpNamespace: () => YelpNamespace,
@@ -241,7 +248,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.31.0" : "0.0.0";
+var SDK_VERSION = true ? "0.32.1" : "0.0.0";
 var USER_AGENT = `scavio-js/${SDK_VERSION}`;
 function isServerRuntime() {
   const g = globalThis;
@@ -3148,6 +3155,287 @@ var DollarGeneralNamespace = class {
   }
 };
 
+// src/namespaces/sephora.ts
+var SephoraNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search sephora.com products, 60 per page: product id, sku id, brand, name,
+   * URL, image, price, list and sale price (with a price range when sizes are
+   * priced differently), value price for sets, rating, review count, extra
+   * colors, and bestseller, new, exclusive, online-only, limited-edition and
+   * sponsored flags. Pass zip for same-day delivery eligibility. Also returns
+   * category facets and related searches.
+   *
+   * Costs 1 credit.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/sephora/search", options);
+  }
+  /**
+   * Products in a sephora.com category, 60 per page, in the same shape as
+   * search(), plus the category's id, name and URL, total product count,
+   * parent category, subcategories with product counts and breadcrumbs. An
+   * unknown category is a 404.
+   *
+   * Costs 1 credit.
+   */
+  async category(options) {
+    return this.client._post("/api/v1/sephora/category", options);
+  }
+  /**
+   * One sephora.com product: rating, review count, loves count, price range,
+   * description, suggested usage, breadcrumbs, a summary of what reviews say
+   * with pro and con sentiment counts (no review text), and every shade or
+   * size as a sku with price, list and sale price, in_stock, only_few_left,
+   * ingredients, images, and pickup and same-day eligibility. An unknown
+   * product is a 404.
+   *
+   * Costs 1 credit.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/sephora/product", options);
+  }
+};
+
+// src/namespaces/ulta.ts
+var UltaNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search Ulta Beauty by keyword, 64 products per page plus sponsored
+   * placements: product_id, sku_id, brand, name, URL, image, list and sale
+   * price (low end and range when shades are priced differently), discount,
+   * promo text, rating, review count, badge, variant label, limited-stock and
+   * sponsored flags.
+   *
+   * Costs 1 credit.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/ulta/search", options);
+  }
+  /**
+   * Products in an Ulta Beauty category, 64 per page plus sponsored
+   * placements, with the category title and total_results and the same
+   * product fields as search().
+   *
+   * Costs 1 credit.
+   */
+  async category(options) {
+    return this.client._post("/api/v1/ulta/category", options);
+  }
+  /**
+   * One Ulta Beauty product for the selected shade or size: list and sale
+   * price, discount, availability, GTIN, rating, review count, badges,
+   * description, usage, ingredients, breadcrumbs, images, every shade or size
+   * variant, ship / pickup / same-day eligibility and the five most recent
+   * customer reviews. An unknown product is a 404.
+   *
+   * Costs 1 credit.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/ulta/product", options);
+  }
+  /**
+   * In-store pickup availability of one shade or size at the 10 Ulta Beauty
+   * stores nearest a US ZIP: store id, name, address, distance in miles, open
+   * now and hours label, curbside label, in_stock and the availability label.
+   * In stock / out of stock per store, not unit counts.
+   *
+   * Costs 1 credit.
+   */
+  async stores(options) {
+    return this.client._post("/api/v1/ulta/stores", options);
+  }
+};
+
+// src/namespaces/aldi.ts
+var AldiNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search ALDI US at one store (store_id, or the nearest store to a zip):
+   * product_id, name, brand, size, price and was_price for that store and
+   * service_type, discount label, unit price, in_stock and stock_level,
+   * category, in-store aisle location, ALDI exclusive-brand flag, dietary
+   * labels, image and URL. Exact matches only unless include_related is set.
+   *
+   * Costs 1 credit.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/aldi/search", options);
+  }
+  /**
+   * One ALDI US product by id or aldi.us URL at one store: price and
+   * was_price for that store and service_type, unit price, stock, category,
+   * brand, size, description, ingredients, allergen warnings, dietary labels
+   * and images. An unknown product id is a 404.
+   *
+   * Costs 1 credit.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/aldi/product", options);
+  }
+  /**
+   * ALDI US stores near a ZIP code, nearest first: store_id (for search and
+   * product), name, street address, city, state, ZIP, coordinates and
+   * distance in miles.
+   *
+   * Costs 1 credit.
+   */
+  async stores(options) {
+    return this.client._post("/api/v1/aldi/stores", options);
+  }
+};
+
+// src/namespaces/micro-center.ts
+var MicroCenterNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search Micro Center by keyword or category at one store, up to 96 per
+   * page: product_id, SKU, name, brand, category, price and original price,
+   * image, URL, highlights, and that store's stock (label as printed,
+   * quantity, quantity_capped at 25+, in_stock, not_carried). Open-box count
+   * and lowest price, rebate text and an in_store_only flag where shown.
+   *
+   * Costs 2 credits.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/microcenter/search", options);
+  }
+  /**
+   * One product by id or URL: SKU, MPN, UPC, description, price, original
+   * price, ship and pickup flags, images, rating, up to 10 recent reviews,
+   * breadcrumbs and the full spec table. selected_store carries the store's
+   * stock and each open-box unit (condition, warranty, price); stores_in_stock
+   * is a yes/no per Micro Center store, not a unit count. An unknown product
+   * id is a 404.
+   *
+   * Costs 2 credits.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/microcenter/product", options);
+  }
+  /**
+   * Every Micro Center store with its 3-digit store_id, name, city, state and
+   * store page URL; street address and ZIP where known. Optionally filtered by
+   * state. The web store 029 is not listed but is accepted as a store_id.
+   *
+   * Costs 1 credit.
+   */
+  async stores(options = {}) {
+    return this.client._post("/api/v1/microcenter/stores", options);
+  }
+};
+
+// src/namespaces/walgreens.ts
+var WalgreensNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search Walgreens retail products, up to 70 per page: product id, SKU, UPC,
+   * name, brand, size, regular and sale price, unit price, promotion, coupon,
+   * loyalty and rebate messages, rating, review count, image, URL,
+   * ship/pickup/delivery availability, online stock status and clearance flag.
+   * Prices are national. Pass store_id for that store's availability text.
+   *
+   * Costs 2 credits.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/walgreens/search", options);
+  }
+  /**
+   * One Walgreens retail product by id or URL: SKU, UPC, GTIN, brand, size,
+   * regular and sale price, savings, unit price, rewards and rebate offers,
+   * description, ingredients, warnings, rating, review count, category path,
+   * images, ship and pickup availability and clearance flag. Prices are
+   * national. An unknown id is a 404.
+   *
+   * Costs 2 credits.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/walgreens/product", options);
+  }
+  /**
+   * Walgreens and Duane Reade stores near a US ZIP or coordinates, nearest
+   * first: store_number, name, brand, address, phone, coordinates, distance in
+   * miles, opening and closing time, time zone and store page URL. Paged with
+   * total_results, total_pages and has_more.
+   *
+   * Costs 2 credits.
+   */
+  async stores(options) {
+    return this.client._post("/api/v1/walgreens/stores", options);
+  }
+  /**
+   * Live in-store stock of one product at up to 20 stores: per store the
+   * status (In Stock, Out of Stock, or Not Available when the store does not
+   * carry it), the unit count and in_stock. Store numbers Walgreens does not
+   * recognise are listed in unknown_store_ids. An unknown product is a 404.
+   *
+   * Costs 4 credits.
+   */
+  async stock(options) {
+    return this.client._post("/api/v1/walgreens/stock", options);
+  }
+};
+
+// src/namespaces/cvs.ts
+var CVS_PRODUCT_TIMEOUT = 12e4;
+var CvsNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search CVS front-store products: product_id and sku_id, name, brand, URL,
+   * regular and sale price, unit price, promotion text, rating, review count,
+   * size, image, coupons (ExtraBucks rewards and manufacturer coupons) and
+   * stock at one store (in store, pickup) plus online ship stock;
+   * same_day_delivery is always null. Sponsored placements are excluded. Includes brand,
+   * price-range and rating facets.
+   *
+   * Costs 1 credit.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/cvs/search", options);
+  }
+  /**
+   * One CVS product by URL or id: regular and sale price, unit price,
+   * promotion and its end date, rating, review count, UPC, size, description,
+   * highlights, ingredients, directions, warnings, attributes, breadcrumbs,
+   * images and every variant (SKU id, UPC, size, price, rating). An unknown
+   * product is a 404. Can take 10-30+ seconds.
+   *
+   * Costs 1 credit.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/cvs/product", options, void 0, CVS_PRODUCT_TIMEOUT);
+  }
+  /**
+   * Units available at one CVS store for up to 20 SKUs: in_store (on the
+   * shelf), pickup and ship (online stock, chain-wide). same_day_delivery is
+   * always null (CVS does not report it per store). An unknown SKU or store
+   * number reads as 0.
+   *
+   * Costs 1 credit.
+   */
+  async stock(options) {
+    return this.client._post("/api/v1/cvs/stock", options);
+  }
+};
+
 // src/namespaces/trustpilot.ts
 var TrustpilotNamespace = class {
   constructor(client) {
@@ -3667,6 +3955,12 @@ var Scavio = class extends ScavioCore {
   samsClub;
   canadianTire;
   dollarGeneral;
+  sephora;
+  ulta;
+  aldi;
+  microCenter;
+  walgreens;
+  cvs;
   trustpilot;
   chatgpt;
   gemini;
@@ -3734,6 +4028,12 @@ var Scavio = class extends ScavioCore {
     this.samsClub = new SamsClubNamespace(this);
     this.canadianTire = new CanadianTireNamespace(this);
     this.dollarGeneral = new DollarGeneralNamespace(this);
+    this.sephora = new SephoraNamespace(this);
+    this.ulta = new UltaNamespace(this);
+    this.aldi = new AldiNamespace(this);
+    this.microCenter = new MicroCenterNamespace(this);
+    this.walgreens = new WalgreensNamespace(this);
+    this.cvs = new CvsNamespace(this);
     this.trustpilot = new TrustpilotNamespace(this);
     this.chatgpt = new ChatgptNamespace(this);
     this.gemini = new GeminiNamespace(this);
@@ -3845,15 +4145,18 @@ async function getSubtle() {
 0 && (module.exports = {
   AI_PROMPT_TIMEOUT,
   AirbnbNamespace,
+  AldiNamespace,
   AmazonNamespace,
   AppStoreNamespace,
   BadRequestError,
   BookingNamespace,
+  CVS_PRODUCT_TIMEOUT,
   CanadianTireNamespace,
   CapterraNamespace,
   ChatgptNamespace,
   CompaniesHouseNamespace,
   CostcoNamespace,
+  CvsNamespace,
   DEFAULT_MAX_REQUESTS_PER_SECOND,
   DollarGeneralNamespace,
   EbayNamespace,
@@ -3877,6 +4180,7 @@ async function getSubtle() {
   MAX_REQUESTS_PER_SECOND,
   MercadoLibreNamespace,
   MetaAdsNamespace,
+  MicroCenterNamespace,
   MissingAPIKeyError,
   NotFoundError,
   RateLimitError,
@@ -3892,12 +4196,15 @@ async function getSubtle() {
   ScavioError,
   ScavioJobTimeoutError,
   ScavioTimeoutError,
+  SephoraNamespace,
   TargetNamespace,
   ThreadsNamespace,
   TikTokNamespace,
   TikTokShopNamespace,
   TripadvisorNamespace,
   TrustpilotNamespace,
+  UltaNamespace,
+  WalgreensNamespace,
   WalmartNamespace,
   XNamespace,
   YelpNamespace,