scavio 0.15.0 → 0.18.0

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
+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
@@ -49,7 +49,7 @@ const client = new Scavio({
   apiKey: "sk_...",               // or set SCAVIO_API_KEY env var
   baseUrl: "https://api.scavio.dev", // default
   timeout: 30_000,                   // ms, default
-  maxRequestsPerSecond: 1,           // 1-10, default 1
+  maxRequestsPerSecond: 1,           // 1-50, default 1
   maxRetries: 2,                     // default 2, set 0 to disable
 });
 ```
@@ -62,8 +62,9 @@ errors. Backoff is exponential with full jitter, capped at 8s, and a
 
 `maxRequestsPerSecond` throttles the client so it never sends more than N
 requests in any one-second window. Your plan also has a server-side concurrency
-limit on simultaneous in-flight requests: 1 on free and pay-as-you-go, 2 on
-Project, 3 on Bootstrap, 5 on Startup, 10 on Growth.
+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.
 
 ## API Reference
 
@@ -177,8 +178,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({
@@ -196,18 +197,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
@@ -218,6 +250,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;

package/dist/index.cjs

@@ -27,6 +27,8 @@ __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,
   GlassdoorNamespace: () => GlassdoorNamespace,
@@ -40,6 +42,7 @@ __export(index_exports, {
   InvalidAPIKeyError: () => InvalidAPIKeyError,
   KuaishouNamespace: () => KuaishouNamespace,
   LinkedInNamespace: () => LinkedInNamespace,
+  MAX_REQUESTS_PER_SECOND: () => MAX_REQUESTS_PER_SECOND,
   MetaAdsNamespace: () => MetaAdsNamespace,
   MissingAPIKeyError: () => MissingAPIKeyError,
   NotFoundError: () => NotFoundError,
@@ -678,7 +681,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);
@@ -687,8 +694,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);
@@ -739,6 +749,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
@@ -2303,7 +2327,144 @@ 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;
 var Scavio = class {
   google;
   amazon;
@@ -2336,6 +2497,7 @@ var Scavio = class {
   companiesHouse;
   googleAds;
   metaAds;
+  costco;
   apiKey;
   baseUrl;
   timeout;
@@ -2349,9 +2511,11 @@ var Scavio = class {
     this.baseUrl = (config?.baseUrl ?? BASE_URL).replace(/\/+$/, "");
     this.timeout = config?.timeout ?? DEFAULT_TIMEOUT;
     this.maxRetries = config?.maxRetries ?? DEFAULT_MAX_RETRIES;
-    const rps = config?.maxRequestsPerSecond ?? 1;
-    if (rps < 1 || rps > 10) {
-      throw new ScavioError("maxRequestsPerSecond must be between 1 and 10");
+    const rps = config?.maxRequestsPerSecond ?? DEFAULT_MAX_REQUESTS_PER_SECOND;
+    if (rps < 1 || rps > MAX_REQUESTS_PER_SECOND) {
+      throw new ScavioError(
+        `maxRequestsPerSecond must be between 1 and ${MAX_REQUESTS_PER_SECOND}`
+      );
     }
     this.rateLimiter = new RateLimiter(rps);
     this.google = new GoogleNamespace(this);
@@ -2385,6 +2549,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) {
@@ -2450,6 +2615,8 @@ var Scavio = class {
   BookingNamespace,
   CapterraNamespace,
   CompaniesHouseNamespace,
+  CostcoNamespace,
+  DEFAULT_MAX_REQUESTS_PER_SECOND,
   EbayNamespace,
   G2Namespace,
   GlassdoorNamespace,
@@ -2463,6 +2630,7 @@ var Scavio = class {
   InvalidAPIKeyError,
   KuaishouNamespace,
   LinkedInNamespace,
+  MAX_REQUESTS_PER_SECOND,
   MetaAdsNamespace,
   MissingAPIKeyError,
   NotFoundError,