scavio 0.16.0 → 0.18.1

package/README.md

@@ -1,14 +1,14 @@
 # Scavio
 
-TypeScript SDK for the [Scavio API](https://scavio.dev) — real-time web scraping
-and data extraction across 31 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 32 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
 per-site parsers to maintain.
 
 - **Search and SERP** — Google (organic, news, maps, shopping, flights, hotels, trends, AI Mode)
-- **E-commerce** — Amazon, Walmart, eBay, Target, Home Depot, TikTok Shop
+- **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
 - **Jobs and companies** — Indeed, Glassdoor, SEC EDGAR, Companies House
@@ -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)
@@ -178,8 +182,8 @@ instead of the previous raw provider payload.
 
 ### Walmart
 
-Seven endpoints. `search` and `product` changed shape in 0.15.0 and the other
-five are new.
+Eight endpoints. `stores` and store targeting on `search` / `product` are new in
+0.17.0.
 
 ```typescript
 await client.walmart.search({
@@ -197,18 +201,49 @@ await client.walmart.category({ category_id: "3944_133251_1095191" });
 await client.walmart.offers({ product_id: "13544111159" });
 await client.walmart.seller({ seller_id: "101138578" });
 await client.walmart.sellerProducts({ seller_id: "101138578" });
+
+// Store targeting: find stores for a ZIP, then pass one with the ZIP.
+const { data } = await client.walmart.stores({ zipcode: "50036" });
+await client.walmart.search({
+  query: "whole milk",
+  delivery_zip: "50036",
+  store_id: data.stores[0].store_id!, // "1389", Boone Supercenter
+});
+
+// walmart.ca works the same way with a postal code and domain "ca".
+await client.walmart.stores({ zipcode: "M5V 2T6", domain: "ca" });
+await client.walmart.product({
+  product_id: "10220526",
+  domain: "ca",
+  delivery_zip: "M5V 2T6",
+  store_id: "3106",
+});
 ```
 
-Credits are a function of the body on `search` and `category`: `domain` "com" and
-"ca" cost 1 credit, "com.mx" costs 2. The other five endpoints always cost 1.
+Credits are a function of the body: `search` and `category` cost 1 credit on
+`domain` "com" or "ca" and 2 on "com.mx"; a store-targeted `search` or `product`
+costs 2. `stores` and the other endpoints cost 1.
+
+#### Walmart store targeting (0.17.0)
+
+- `delivery_zip` and `store_id` must be sent **together**, on `search` or
+  `product`. They work on walmart.com and walmart.ca (`domain: "ca"` with a
+  Canadian postal code); walmart.com.mx does not support store targeting.
+- Get `store_id` from `stores()` on the same domain. `store_id` decides the
+  store; `data.location` in the response confirms which store was used.
+- Store-targeted calls take 10-60 seconds — set a generous timeout. A
+  `store_id` that does not exist returns 400, and a product the store does not
+  carry returns 404.
+- `product` accepts `domain: "ca"` only together with a store target.
 
 #### Walmart changed in 0.15.0 (breaking)
 
-- `device`, `delivery_zip` and `store_id` are retired. Sending one still returns
-  200, with a top-level `warnings` array naming what was ignored.
+- `device` is retired. Sending it still returns 200, with a top-level `warnings`
+  array naming what was ignored. (`delivery_zip` and `store_id` were retired in
+  0.15.0 and came back in 0.17.0 as store targeting.)
 - `domain` is **not** retired — it is the price-bearing param, and it is accepted
-  on `search` and `category` only. Walmart.ca product pages cannot be fetched, so
-  every product-keyed endpoint is walmart.com only.
+  on `search` and `category`. Product-keyed endpoints are walmart.com only,
+  except `product` with a store target (0.17.0).
 - `page` (1-indexed) is the paging param; `start_page` remains a deprecated alias.
 - `sort_by` gained `rating_high` and `new`.
 - `fulfillment_speed` is `today` or `tomorrow` only. There is deliberately no
@@ -219,6 +254,60 @@ Credits are a function of the body on `search` and `category`: `domain` "com" an
 - `sellerProducts` has **no pagination** — roughly the first 40 server-rendered
   items. `total_count` reports the seller's real catalog size.
 
+### Costco
+
+Thirteen endpoints, new in 0.18.0. `country` is `"us"` (costco.com, default) or
+`"ca"` (costco.ca); `search`, `product` and `warehouses` also take `"uk"`,
+`"au"`, `"mx"`, `"jp"`, `"kr"` and `"tw"` (keyword, sort and paging only).
+
+```typescript
+// Warehouse numbers come from warehouses().
+await client.costco.warehouses({ zip: "10025", limit: 3 });
+
+// warehouse_id adds that warehouse's in-store price, stock and price code to
+// every result on search, category and deals.
+await client.costco.search({ query: "olive oil", warehouse_id: "1062", page_size: 5 });
+await client.costco.category({ category: "televisions", sort_by: "price_low" });
+await client.costco.categories();                         // departments
+await client.costco.categories({ category_id: "30001" }); // one department's tree
+await client.costco.product({ item_ids: ["100334960", "1492456"] }); // up to 20
+await client.costco.reviews({ product_id: "100334960", sort_by: "most_helpful" });
+await client.costco.autocomplete({ query: "kirk" });
+
+// Online vs in-warehouse price at up to 10 warehouses, with discount, final
+// price, promotion dates and price code.
+await client.costco.prices({ item_id: "1492456", warehouse_ids: ["1062", "1107"] });
+
+// In-warehouse stock status (never a quantity), pickup and same-day delivery.
+await client.costco.availability({ item_number: "1492456", warehouse_ids: ["1062"] });
+
+// Regular, premium and diesel prices near a location, or at given warehouses.
+await client.costco.gas({ zip: "90001" });
+await client.costco.gas({ warehouse_ids: ["1062", "1107"] });
+
+// The current member coupon book (US only, no parameters).
+await client.costco.coupons();
+
+// Deal feeds: new, while_supplies_last, treasure_hunt, member_favorites,
+// online_only, on_sale.
+await client.costco.deals({ type: "treasure_hunt", warehouse_id: "1062" });
+
+// Markdown finder at one warehouse: .97 clearance and .00/.88 manager
+// markdowns by default; add special_buy for .49/.79/.89 endings.
+await client.costco.clearance({
+  warehouse_id: "1062",
+  query: "snacks",
+  price_codes: ["clearance", "manager_markdown", "special_buy"],
+});
+```
+
+1 credit per call except where the body scales the work: `prices` costs 2 at 10
+warehouses, `availability` 1 per 5 warehouses, `warehouses` 2 with
+`country: "ca"`, and `gas` 2 by location on ca (by `warehouse_ids`, 1 per 5
+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.
+
 ### YouTube
 
 Credit cost varies by endpoint: `transcript` costs 8; `streams` costs 3;
@@ -951,24 +1040,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
 - **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

@@ -27,6 +27,7 @@ __export(index_exports, {
   BookingNamespace: () => BookingNamespace,
   CapterraNamespace: () => CapterraNamespace,
   CompaniesHouseNamespace: () => CompaniesHouseNamespace,
+  CostcoNamespace: () => CostcoNamespace,
   DEFAULT_MAX_REQUESTS_PER_SECOND: () => DEFAULT_MAX_REQUESTS_PER_SECOND,
   EbayNamespace: () => EbayNamespace,
   G2Namespace: () => G2Namespace,
@@ -198,12 +199,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.18.1" : "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 = {};
@@ -680,7 +694,11 @@ var WalmartNamespace = class {
    * Structured Walmart search results: `products[]`, `products_count` and the
    * resolved `location`. Page through with `page` (1-indexed).
    *
-   * Costs 1 credit for `domain` "com" or "ca", 2 credits for "com.mx".
+   * Pass `delivery_zip` + `store_id` to get one store's results (walmart.com
+   * and walmart.ca); `data.location` confirms the store.
+   *
+   * Costs 1 credit for `domain` "com" or "ca", 2 credits for "com.mx", and 2
+   * credits when store-targeted.
    */
   async search(options) {
     return this.client._post("/api/v1/walmart/search", options);
@@ -689,8 +707,11 @@ var WalmartNamespace = class {
    * Full product detail: price, rating, images, specifications, availability
    * and seller.
    *
-   * Costs 1 credit. Walmart.ca product pages are not fetchable, so this is
-   * walmart.com only.
+   * Pass `delivery_zip` + `store_id` for one store's price and availability.
+   * `domain: "ca"` is available only together with a store target.
+   *
+   * Costs 1 credit, or 2 when store-targeted. A store that does not carry the
+   * item returns 404.
    */
   async product(options) {
     return this.client._post("/api/v1/walmart/product", options);
@@ -741,6 +762,20 @@ var WalmartNamespace = class {
   async sellerProducts(options) {
     return this.client._post("/api/v1/walmart/seller-products", options);
   }
+  /**
+   * Walmart stores near a US ZIP (or a Canadian postal code with `domain: "ca"`),
+   * nearest first, with `store_id`, address, distance, coordinates and hours.
+   * Use a `store_id` with `delivery_zip` on `search()` or `product()`, on the
+   * same domain, to target that store.
+   *
+   * Costs 1 credit.
+   */
+  async stores(options) {
+    return await this.client._post(
+      "/api/v1/walmart/stores",
+      options
+    );
+  }
 };
 
 // src/namespaces/youtube.ts
@@ -2305,6 +2340,141 @@ var MetaAdsNamespace = class {
   }
 };
 
+// src/namespaces/costco.ts
+var CostcoNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Search Costco by keyword or item number: online price and original price,
+   * ratings, member-only and stock flags, promotions and facets. Pass
+   * `warehouse_id` to add that warehouse's in-store price and stock to every
+   * result.
+   *
+   * Costs 1 credit.
+   */
+  async search(options) {
+    return this.client._post("/api/v1/costco/search", options);
+  }
+  /**
+   * Products in a Costco category, with the same sort, filters and
+   * per-warehouse pricing as search().
+   *
+   * Costs 1 credit.
+   */
+  async category(options) {
+    return this.client._post("/api/v1/costco/category", options);
+  }
+  /**
+   * The Costco department list, or the full subcategory tree under one
+   * department when `category_id` is set.
+   *
+   * Costs 1 credit.
+   */
+  async categories(options = {}) {
+    return this.client._post("/api/v1/costco/categories", options);
+  }
+  /**
+   * Full details for up to 20 items: description, features, specifications,
+   * variants, member-only and purchase limits, delivery fee, and promotions
+   * with start and end dates. Pass `item_id` or `item_ids`.
+   *
+   * Costs 1 credit.
+   */
+  async product(options) {
+    return this.client._post("/api/v1/costco/product", options);
+  }
+  /**
+   * Online price versus in-warehouse price for up to 20 items across up to 10
+   * warehouses, with each location's discount, final price, promotion dates
+   * and price code.
+   *
+   * Costs 1 credit for up to 9 warehouses and 2 credits for 10.
+   */
+  async prices(options) {
+    return this.client._post("/api/v1/costco/prices", options);
+  }
+  /**
+   * In-warehouse stock status for one item at up to 10 warehouses, plus
+   * pickup and same-day delivery availability. A status, never a quantity.
+   *
+   * Costs 1 credit per 5 warehouses.
+   */
+  async availability(options) {
+    return this.client._post("/api/v1/costco/availability", options);
+  }
+  /**
+   * Customer reviews for a Costco product with the rating distribution and
+   * recommend count; sort, star filter and up to 100 reviews per page.
+   *
+   * Costs 1 credit.
+   */
+  async reviews(options) {
+    return this.client._post("/api/v1/costco/reviews", options);
+  }
+  /**
+   * Costco warehouses near a US zip code or coordinates, nearest first:
+   * warehouse_id, address, hours, departments, services, and gas station hours
+   * and prices.
+   *
+   * Costs 1 credit, or 2 with country "ca".
+   */
+  async warehouses(options) {
+    return this.client._post("/api/v1/costco/warehouses", options);
+  }
+  /**
+   * Current regular, premium and diesel prices at Costco gas stations near a
+   * location, or at specific warehouses.
+   *
+   * Costs 1 credit by location (2 with country "ca"); by `warehouse_ids`,
+   * 1 credit per 5 warehouses on us and 2 credits per warehouse on ca.
+   */
+  async gas(options) {
+    return this.client._post("/api/v1/costco/gas", options);
+  }
+  /**
+   * The current Costco member coupon book (US): every offer with its item
+   * number, discount, final price, warehouse/online scope, limits and the
+   * book's valid dates. Takes no parameters.
+   *
+   * Costs 1 credit.
+   */
+  async coupons(options = {}) {
+    return this.client._post("/api/v1/costco/coupons", options);
+  }
+  /**
+   * Costco deal feeds: new items, while supplies last, treasure hunt, member
+   * favorites, online-only and everything on sale, with the same filters and
+   * optional per-warehouse pricing as search().
+   *
+   * Costs 1 credit.
+   */
+  async deals(options) {
+    return this.client._post("/api/v1/costco/deals", options);
+  }
+  /**
+   * Markdown finder for one warehouse: scans a query or category and keeps
+   * the items whose in-warehouse price ends in a markdown code - .97
+   * clearance and .00/.88 manager markdown by default, .49/.79/.89 special
+   * buys on request. The codes are the member-community decode; Costco does
+   * not publish them. Only items Costco lists online are covered.
+   *
+   * Costs 1 credit.
+   */
+  async clearance(options) {
+    return this.client._post("/api/v1/costco/clearance", options);
+  }
+  /**
+   * Costco search-box suggestions for a partial query.
+   *
+   * Costs 1 credit.
+   */
+  async autocomplete(options) {
+    return this.client._post("/api/v1/costco/autocomplete", options);
+  }
+};
+
 // src/client.ts
 var DEFAULT_MAX_REQUESTS_PER_SECOND = 1;
 var MAX_REQUESTS_PER_SECOND = 50;
@@ -2340,6 +2510,7 @@ var Scavio = class {
   companiesHouse;
   googleAds;
   metaAds;
+  costco;
   apiKey;
   baseUrl;
   timeout;
@@ -2391,6 +2562,7 @@ var Scavio = class {
     this.companiesHouse = new CompaniesHouseNamespace(this);
     this.googleAds = new GoogleAdsNamespace(this);
     this.metaAds = new MetaAdsNamespace(this);
+    this.costco = new CostcoNamespace(this);
   }
   /** @internal */
   async _post(path, body) {
@@ -2456,6 +2628,7 @@ var Scavio = class {
   BookingNamespace,
   CapterraNamespace,
   CompaniesHouseNamespace,
+  CostcoNamespace,
   DEFAULT_MAX_REQUESTS_PER_SECOND,
   EbayNamespace,
   G2Namespace,