scavio 0.30.0 → 0.31.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 38 platforms on one API key, plus `extract()` to read
+data across 42 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, Mercado Libre, eBay, Target, Home Depot, TikTok Shop
+- **E-commerce** — Amazon, Walmart, Costco, Lowe's, Sam's Club, Canadian Tire, Dollar General, 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
@@ -504,6 +504,55 @@ warehouses on us and 2 per warehouse on ca). The clearance price codes are the
 member-community decode of Costco shelf prices; Costco does not publish them,
 and only items Costco lists online are covered.
 
+### Lowe's, Sam's Club, Canadian Tire and Dollar General
+
+Four store-level retailers, new in 0.31.0. Each call answers for ONE store you
+choose: get its number from the locator (`lowes.stores`, `samsClub.clubs`,
+`canadianTire.stores`, `dollarGeneral.stores`) and pass it on every call.
+
+```typescript
+// Lowe's: store_id AND that store's own ZIP are required on search/product.
+const lowesStores = await client.lowes.stores({ zip: "28117", limit: 1 });
+const store = (lowesStores.data as any).stores[0];
+const sid = store.store_id;                  // "0595"
+const zip = store.address.postal_code;       // "28117"
+await client.lowes.search({ query: "cordless drill", store_id: sid, zip });
+await client.lowes.search({ query: "cordless drill", store_id: sid, zip, on_sale: true }); // that store's deals
+await client.lowes.product({ item_id: "5016412045", store_id: sid, zip }); // stock, aisle_locations, nearby stores
+await client.lowes.reviews({ item_id: "5016412045", sort: "most_helpful" });
+
+// Sam's Club: search, savings and category answer for a club picked by
+// location (echoed in data.club). product({ club_id }) targets one club.
+await client.samsClub.clubs({ zip: "75201", limit: 5 });
+await client.samsClub.search({ query: "paper towels", sort: "price_low" });
+await client.samsClub.product({ item_id: "15325822107", club_id: "6372" }); // club_price, in_stock_at_club
+await client.samsClub.savings({ sort: "top_selling" });   // Instant Savings
+await client.samsClub.category({ category_id: "1150109" }); // clearance
+await client.samsClub.reviews({ item_id: "15325822107", sort: "lowest" });
+
+// Canadian Tire: prices in CAD, per store and province.
+await client.canadianTire.stores({ postal_code: "M5V 2T6", sku: "0438858" }); // + quantity and aisle per store
+await client.canadianTire.search({ query: "dewalt drill", store_id: "600" });
+await client.canadianTire.product({ product_code: "0547273P", store_id: "600" });
+await client.canadianTire.availability({ store_id: "600", skus: ["0438858", "0547273"] }); // up to 50
+await client.canadianTire.clearance({ store_id: "600" }); // in-stock only by default
+await client.canadianTire.deals({ store_id: "600", type: "sale" }); // or instant_rebate, special_buy, loyalty
+
+// Dollar General: one stores() call with a upc gives that product's unit
+// count at up to 25 nearby stores.
+await client.dollarGeneral.stores({ zip: "75203", upc: "030772156629" });
+await client.dollarGeneral.search({ query: "paper towels", store_id: "12629", in_stock_only: true });
+await client.dollarGeneral.product({ upc: "030772156629", store_id: "12629" });
+await client.dollarGeneral.deals({ store_id: "12629", type: "clearance" }); // or on_sale
+await client.dollarGeneral.coupons();
+```
+
+Lowe's `search`, `product` and `stores` cost 2 credits and `reviews` 1; every
+Sam's Club, Canadian Tire and Dollar General call costs 1. Sam's Club caps
+`available_quantity` at 8 (8 means 8 or more). Dollar General clearance items
+carry the current price only, with no was-price. Canadian Tire and Dollar
+General return a rating and review count but no review text.
+
 ### [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
@@ -1215,7 +1264,7 @@ await client.glassdoor.reviews({ url: company.reviews_url as string });
 await client.glassdoor.salaries({ url: company.salaries_url as string });
 ```
 
-1 credit per call. Glassdoor's login wall caps `reviews` at **three reviews per
+2 credits per call. Glassdoor's login wall caps `reviews` at **three reviews per
 response** — there is deliberately no `page` param; move the window with
 `category` and `employment_status` and read `filtered_review_count` to see how
 many match. Addressing `reviews` or `salaries` by `employer_id` needs an

package/dist/index.cjs

@@ -36,11 +36,13 @@ __export(index_exports, {
   AppStoreNamespace: () => AppStoreNamespace,
   BadRequestError: () => BadRequestError,
   BookingNamespace: () => BookingNamespace,
+  CanadianTireNamespace: () => CanadianTireNamespace,
   CapterraNamespace: () => CapterraNamespace,
   ChatgptNamespace: () => ChatgptNamespace,
   CompaniesHouseNamespace: () => CompaniesHouseNamespace,
   CostcoNamespace: () => CostcoNamespace,
   DEFAULT_MAX_REQUESTS_PER_SECOND: () => DEFAULT_MAX_REQUESTS_PER_SECOND,
+  DollarGeneralNamespace: () => DollarGeneralNamespace,
   EbayNamespace: () => EbayNamespace,
   ExtractNamespace: () => ExtractNamespace,
   G2Namespace: () => G2Namespace,
@@ -58,6 +60,7 @@ __export(index_exports, {
   KrogerNamespace: () => KrogerNamespace,
   KuaishouNamespace: () => KuaishouNamespace,
   LinkedInNamespace: () => LinkedInNamespace,
+  LowesNamespace: () => LowesNamespace,
   MAX_REQUESTS_PER_SECOND: () => MAX_REQUESTS_PER_SECOND,
   MercadoLibreNamespace: () => MercadoLibreNamespace,
   MetaAdsNamespace: () => MetaAdsNamespace,
@@ -69,6 +72,7 @@ __export(index_exports, {
   RedfinNamespace: () => RedfinNamespace,
   RightmoveNamespace: () => RightmoveNamespace,
   SECNamespace: () => SECNamespace,
+  SamsClubNamespace: () => SamsClubNamespace,
   Scavio: () => Scavio,
   ScavioAPIError: () => ScavioAPIError,
   ScavioConnectionError: () => ScavioConnectionError,
@@ -237,7 +241,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.30.0" : "0.0.0";
+var SDK_VERSION = true ? "0.31.0" : "0.0.0";
 var USER_AGENT = `scavio-js/${SDK_VERSION}`;
 function isServerRuntime() {
   const g = globalThis;
@@ -2037,7 +2041,7 @@ var GlassdoorNamespace = class {
    * only inside Glassdoor's /Overview/ URLs, so this lookup is the entry
    * point.
    *
-   * Costs 1 credit. Single response, no pagination.
+   * Costs 2 credits. Single response, no pagination.
    */
   async companies(options) {
     return this.client._post("/api/v1/glassdoor/companies", options);
@@ -2052,7 +2056,7 @@ var GlassdoorNamespace = class {
    * reviews() and salaries() to halve the lookups. `employer_id` or
    * `url` is required - `company` is cosmetic and does not satisfy it.
    *
-   * Costs 1 credit. Single response, no pagination. Typically ~3-47s.
+   * Costs 2 credits. Single response, no pagination. Typically a few seconds.
    */
   async company(options) {
     return this.client._post("/api/v1/glassdoor/company", options);
@@ -2069,7 +2073,7 @@ var GlassdoorNamespace = class {
    * filtered_review_count to see how many match; the aggregate statistics are
    * the full-population signal here, not the bodies.
    *
-   * `employer_id` or `url` is required. Costs 1 credit. Typically ~75s.
+   * `employer_id` or `url` is required. Costs 2 credits. Typically a few seconds.
    */
   async reviews(options) {
     return this.client._post("/api/v1/glassdoor/reviews", options);
@@ -2083,7 +2087,7 @@ var GlassdoorNamespace = class {
    * salaries. Paged with `page` at 10 job titles per page; `page_count` on the
    * response is how many pages exist.
    *
-   * `employer_id` or `url` is required. Costs 1 credit. Typically ~41s.
+   * `employer_id` or `url` is required. Costs 2 credits. Typically a few seconds.
    */
   async salaries(options) {
     return this.client._post("/api/v1/glassdoor/salaries", options);
@@ -2891,6 +2895,259 @@ var SpecsNamespace = class {
   }
 };
 
+// src/namespaces/lowes.ts
+var LowesNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search Lowe's by keyword or category at one store: the store's price,
+   * was-price and savings with the sale end date, brand, model number, rating,
+   * review count, and stock for pickup, truck delivery, parcel shipping and
+   * same-day delivery. Pass query or category_id; on_sale returns that
+   * store's deals.
+   *
+   * Costs 2 credits.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/lowes/search", options);
+  }
+  /**
+   * One Lowe's item at one store: price, was-price and savings, on-hand stock
+   * with lead time per fulfillment method, stock at nearby stores, aisle and
+   * bay, grouped specifications, UPC, dimensions, weight, rating, images, and
+   * the store's hours.
+   *
+   * Costs 2 credits.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/lowes/product", options);
+  }
+  /**
+   * Lowe's stores near a ZIP code, nearest first: store_id, name, address,
+   * phone, coordinates, distance, time zone, opening hours and features.
+   *
+   * Costs 2 credits.
+   */
+  async stores(options) {
+    return this.client._post("/api/v1/lowes/stores", options);
+  }
+  /**
+   * One page of an item's customer reviews (10 per page): rating, title, text,
+   * date, reviewer, recommended, helpful votes, verified and incentivized
+   * flags, photos and brand replies, plus the average rating and count per star.
+   *
+   * Costs 1 credit.
+   */
+  async reviews(options) {
+    return this.client._post("/api/v1/lowes/reviews", options);
+  }
+};
+
+// src/namespaces/sams-club.ts
+var SamsClubNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search Sam's Club: item_id, price, was_price, savings_amount, unit price,
+   * Instant Savings (amount, end date, purchase limit), rating, review count,
+   * stock, pickup/delivery/shipping availability and aisle. The club is picked
+   * by location and returned in data.club.
+   *
+   * Costs 1 credit.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/samsclub/search", options);
+  }
+  /**
+   * One Sam's Club item: online price and the club shelf price (club_price)
+   * with was price, savings and unit price, Instant Savings, rating histogram,
+   * UPC, model, specifications, and per-method fulfillment with stock and
+   * aisle. Pass club_id to price and stock a specific club.
+   *
+   * Costs 1 credit.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/samsclub/product", options);
+  }
+  /**
+   * Sam's Club clubs near a US ZIP, nearest first: club_id, name, address,
+   * coordinates, distance in miles, phone, opening hours, services and whether
+   * the club is temporarily closed.
+   *
+   * Costs 1 credit.
+   */
+  async clubs(options) {
+    return this.client._post("/api/v1/samsclub/clubs", options);
+  }
+  /**
+   * Every item on Sam's Club Instant Savings, paged: price, was price and
+   * savings amount, plus each offer's amount, end date, purchase limit and
+   * channels.
+   *
+   * Costs 1 credit.
+   */
+  async savings(options = {}) {
+    return this.client._post("/api/v1/samsclub/savings", options);
+  }
+  /**
+   * Products in a Sam's Club category, paged, with the same fields as
+   * search(). Clearance is category "1150109".
+   *
+   * Costs 1 credit.
+   */
+  async category(options) {
+    return this.client._post("/api/v1/samsclub/category", options);
+  }
+  /**
+   * Customer reviews for a Sam's Club item, 10 per page: rating, title, text,
+   * author, date, verified purchase and helpful votes, plus the average rating,
+   * total count and 1-5 star breakdown.
+   *
+   * Costs 1 credit.
+   */
+  async reviews(options) {
+    return this.client._post("/api/v1/samsclub/reviews", options);
+  }
+};
+
+// src/namespaces/canadian-tire.ts
+var CanadianTireNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search Canadian Tire by keyword or category at one store: the store's
+   * price and regular price (CAD), price range for multi-variant items,
+   * savings, badges (clearance, sale, rebate), rating, review count, brand,
+   * part number, SKU, and stock at the store and online.
+   *
+   * Costs 1 credit.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/canadiantire/search", options);
+  }
+  /**
+   * One product by code at one store: breadcrumb, images, rating, review
+   * count, descriptions, features, specifications, price and regular price,
+   * warranty, manuals, variants with their SKUs, and the store's price, stock,
+   * and pickup and ship-to-home dates.
+   *
+   * Costs 1 credit.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/canadiantire/product", options);
+  }
+  /**
+   * Canadian Tire stores near a postal code or coordinates, nearest first:
+   * store_id, name, address, phone, coordinates, distance, weekly hours and
+   * services. Pass sku to get each store's stock quantity and aisle for it.
+   *
+   * Costs 1 credit.
+   */
+  async stores(options) {
+    return this.client._post("/api/v1/canadiantire/stores", options);
+  }
+  /**
+   * Up to 50 SKUs at one store in one call: the store's price and regular
+   * price, clearance and sale flags, price valid-until date, stock quantity,
+   * aisle, online stock, and pickup and delivery dates. Unknown SKUs are
+   * listed in not_found.
+   *
+   * Costs 1 credit.
+   */
+  async availability(options) {
+    return this.client._post("/api/v1/canadiantire/availability", options);
+  }
+  /**
+   * Every clearance item at one store, 100 per page, with clearance price,
+   * regular price, stock at the store and the same fields as search().
+   * In-stock items only by default.
+   *
+   * Costs 1 credit.
+   */
+  async clearance(options) {
+    return this.client._post("/api/v1/canadiantire/clearance", options);
+  }
+  /**
+   * Items on a deal at one store, 100 per page: sale prices, instant rebates,
+   * special buys or Triangle Rewards loyalty offers, with the same fields as
+   * search().
+   *
+   * Costs 1 credit.
+   */
+  async deals(options) {
+    return this.client._post("/api/v1/canadiantire/deals", options);
+  }
+};
+
+// src/namespaces/dollar-general.ts
+var DollarGeneralNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search Dollar General at one store: that store's price and original price,
+   * available_quantity (units on hand at that store), inventory_status,
+   * rating, review count, categories, digital coupons and promotions, UPC and
+   * product URL.
+   *
+   * Costs 1 credit.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/dollargeneral/search", options);
+  }
+  /**
+   * One product by UPC at one store: price, original price,
+   * available_quantity, stock_status, nearby_stores_with_stock, rating, review
+   * count, SKU, brand, description, highlights, images, categories, digital
+   * coupons and promotions. An unknown UPC or store number is a 404.
+   *
+   * Costs 1 credit.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/dollargeneral/product", options);
+  }
+  /**
+   * Dollar General stores near a US ZIP code or coordinates, nearest first (up
+   * to 25): store_id, address, phone, coordinates, distance in miles, opening
+   * hours and services. Pass upc and each store also carries its unit count of
+   * that product.
+   *
+   * Costs 1 credit.
+   */
+  async stores(options) {
+    return this.client._post("/api/v1/dollargeneral/stores", options);
+  }
+  /**
+   * Products on sale or on clearance, priced and stocked at one store, 24 per
+   * page. available_quantity > 0 means in stock at that store; the listing
+   * covers the whole chain. Clearance items carry the current price only (no
+   * was-price).
+   *
+   * Costs 1 credit.
+   */
+  async deals(options) {
+    return this.client._post("/api/v1/dollargeneral/deals", options);
+  }
+  /**
+   * Dollar General's current digital coupons, 30 per page: offer id and code,
+   * summary, description, brand, company, value, offer type, category, minimum
+   * quantity, start and expiration dates, and whether it is a manufacturer
+   * coupon.
+   *
+   * Costs 1 credit.
+   */
+  async coupons(options = {}) {
+    return this.client._post("/api/v1/dollargeneral/coupons", options);
+  }
+};
+
 // src/namespaces/trustpilot.ts
 var TrustpilotNamespace = class {
   constructor(client) {
@@ -3406,6 +3663,10 @@ var Scavio = class extends ScavioCore {
   kroger;
   decathlon;
   specs;
+  lowes;
+  samsClub;
+  canadianTire;
+  dollarGeneral;
   trustpilot;
   chatgpt;
   gemini;
@@ -3469,6 +3730,10 @@ var Scavio = class extends ScavioCore {
     this.kroger = new KrogerNamespace(this);
     this.decathlon = new DecathlonNamespace(this);
     this.specs = new SpecsNamespace(this);
+    this.lowes = new LowesNamespace(this);
+    this.samsClub = new SamsClubNamespace(this);
+    this.canadianTire = new CanadianTireNamespace(this);
+    this.dollarGeneral = new DollarGeneralNamespace(this);
     this.trustpilot = new TrustpilotNamespace(this);
     this.chatgpt = new ChatgptNamespace(this);
     this.gemini = new GeminiNamespace(this);
@@ -3584,11 +3849,13 @@ async function getSubtle() {
   AppStoreNamespace,
   BadRequestError,
   BookingNamespace,
+  CanadianTireNamespace,
   CapterraNamespace,
   ChatgptNamespace,
   CompaniesHouseNamespace,
   CostcoNamespace,
   DEFAULT_MAX_REQUESTS_PER_SECOND,
+  DollarGeneralNamespace,
   EbayNamespace,
   ExtractNamespace,
   G2Namespace,
@@ -3606,6 +3873,7 @@ async function getSubtle() {
   KrogerNamespace,
   KuaishouNamespace,
   LinkedInNamespace,
+  LowesNamespace,
   MAX_REQUESTS_PER_SECOND,
   MercadoLibreNamespace,
   MetaAdsNamespace,
@@ -3617,6 +3885,7 @@ async function getSubtle() {
   RedfinNamespace,
   RightmoveNamespace,
   SECNamespace,
+  SamsClubNamespace,
   Scavio,
   ScavioAPIError,
   ScavioConnectionError,