scavio 0.16.0 → 0.18.1

package/dist/index.d.ts

@@ -912,11 +912,90 @@ interface WalmartSearchOptions {
     fulfillment_speed?: "today" | "tomorrow";
     /** Fulfillment type filter. */
     fulfillment_type?: "in_store";
+    /**
+     * Shopper's postal code for store targeting: a 5-digit US ZIP, or a Canadian
+     * postal code ("M5V 2T6") with domain "ca". Must be sent together with
+     * `store_id`. Store-targeted calls cost 2 credits.
+     */
+    delivery_zip?: string;
+    /**
+     * Walmart store to target, from `stores()` on the same domain. Must be sent
+     * together with `delivery_zip`. Supported on domain "com" and "ca".
+     */
+    store_id?: string | number;
     [key: string]: unknown;
 }
 interface WalmartProductOptions {
     /** Walmart item id (usItemId), e.g. "13544111159". */
     product_id: string;
+    /**
+     * Walmart storefront, "com" (default) or "ca". "ca" is only available
+     * together with `delivery_zip` + `store_id`.
+     */
+    domain?: "com" | "ca";
+    /**
+     * Shopper's postal code for store targeting: a 5-digit US ZIP, or a Canadian
+     * postal code with domain "ca". Must be sent together with `store_id`.
+     */
+    delivery_zip?: string;
+    /**
+     * Walmart store to target, from `stores()` on the same domain. Must be sent
+     * together with `delivery_zip`.
+     */
+    store_id?: string | number;
+    [key: string]: unknown;
+}
+interface WalmartStoresOptions {
+    /**
+     * A 5-digit US ZIP, or a Canadian postal code ("M5V 2T6" or "M5V2T6") with
+     * domain "ca".
+     */
+    zipcode: string;
+    /** "com" (walmart.com, default) or "ca" (walmart.ca). */
+    domain?: "com" | "ca";
+    [key: string]: unknown;
+}
+/** One store returned by `stores()`. */
+interface WalmartStore {
+    store_id: string | null;
+    name: string | null;
+    type: string | null;
+    node_type: string | null;
+    distance_miles: number | null;
+    address: {
+        line1: string | null;
+        line2: string | null;
+        city: string | null;
+        state: string | null;
+        zipcode: string | null;
+        country: string | null;
+    };
+    latitude: number | null;
+    longitude: number | null;
+    open_24_hours: boolean | null;
+    hours: {
+        day: string | null;
+        start: string | null;
+        end: string | null;
+        closed: boolean | null;
+    }[];
+    pickup_types: string[];
+}
+/** The `data` object of a `stores()` response. */
+interface WalmartStoresData {
+    /** The ZIP or postal code searched, normalized ("M5V 2T6"). */
+    zipcode: string;
+    domain: "com" | "ca";
+    count: number;
+    /** Nearest first. */
+    stores: WalmartStore[];
+}
+interface WalmartStoresResponse {
+    data: WalmartStoresData;
+    response_time: number;
+    credits_used: number;
+    credits_remaining: number;
+    warnings?: string[];
     [key: string]: unknown;
 }
 interface WalmartReviewsOptions {
@@ -983,15 +1062,22 @@ declare class WalmartNamespace {
      * 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.
      */
     search(options: WalmartSearchOptions): Promise<Record<string, unknown>>;
     /**
      * 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.
      */
     product(options: WalmartProductOptions): Promise<Record<string, unknown>>;
     /**
@@ -1030,6 +1116,15 @@ declare class WalmartNamespace {
      * Costs 1 credit. `seller_id` must be the numeric catalog seller id.
      */
     sellerProducts(options: WalmartSellerProductsOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    stores(options: WalmartStoresOptions): Promise<WalmartStoresResponse>;
 }
 
 interface YouTubeSearchOptions {
@@ -4055,6 +4150,270 @@ declare class MetaAdsNamespace {
     ad(options: MetaAdsAdOptions): Promise<Record<string, unknown>>;
 }
 
+/** costco.com ("us", default) or costco.ca ("ca"). */
+type CostcoNaCountry = "us" | "ca";
+/**
+ * Costco site. "us" (default) and "ca" support every filter; the other six
+ * support keyword, sort and paging only.
+ */
+type CostcoCountry = CostcoNaCountry | "uk" | "au" | "mx" | "jp" | "kr" | "tw";
+type CostcoSortBy = "best_match" | "price_low" | "price_high" | "top_rated" | "newest";
+type CostcoDealType = "new" | "while_supplies_last" | "treasure_hunt" | "member_favorites" | "online_only" | "on_sale";
+type CostcoPriceCode = "clearance" | "manager_markdown" | "special_buy";
+/** Filters shared by search, category and deals (us and ca). */
+interface CostcoListingFilters {
+    /**
+     * Costco warehouse number (e.g. "1062"). Adds that warehouse's in-store
+     * price, stock status and price code to every result; omit for online
+     * prices only.
+     */
+    warehouse_id?: string;
+    /** Result order (default "best_match"). Costco broadens matching under any other sort. */
+    sort_by?: CostcoSortBy;
+    /** Brand names to keep, up to 20 (e.g. ["Kirkland Signature"]). */
+    brands?: string[];
+    /** Minimum online price, inclusive. */
+    min_price?: number;
+    /** Maximum online price, inclusive. */
+    max_price?: number;
+    /** Minimum average star rating (1-5). */
+    min_rating?: number;
+    /** Only items with an active discount. */
+    on_sale?: boolean;
+    /** Hide out-of-stock items. */
+    in_stock?: boolean;
+    /** Only items sold and in stock at warehouse_id (requires warehouse_id). */
+    in_warehouse?: boolean;
+    /** Results page, 1-based (1-500). */
+    page?: number;
+    /** Results per page (1-120, default 24). */
+    page_size?: number;
+}
+interface CostcoSearchOptions extends CostcoListingFilters {
+    /** Keywords, or a Costco item number (1-200 characters). */
+    query: string;
+    country?: CostcoCountry;
+    [key: string]: unknown;
+}
+interface CostcoCategoryOptions extends CostcoListingFilters {
+    /** Category slug from categories() (e.g. "televisions"), or a costco.com category URL. */
+    category: string;
+    country?: CostcoNaCountry;
+    [key: string]: unknown;
+}
+interface CostcoCategoriesOptions {
+    /**
+     * Numeric Costco category id (e.g. "30001"). Omit for the top-level
+     * departments; pass one for its full subcategory tree.
+     */
+    category_id?: string;
+    country?: CostcoNaCountry;
+    [key: string]: unknown;
+}
+interface CostcoProductOptions {
+    /** Costco item number or product id, or a costco.com product URL. Pass this or item_ids. */
+    item_id?: string;
+    /** Up to 20 ids in one call (us and ca only). */
+    item_ids?: string[];
+    country?: CostcoCountry;
+    [key: string]: unknown;
+}
+interface CostcoPricesOptions {
+    /** Costco item number or product id. Pass this or item_ids. */
+    item_id?: string;
+    /** Up to 20 ids in one call. */
+    item_ids?: string[];
+    /**
+     * Warehouses to price (1-10, e.g. ["1062", "1107"]). The online price is
+     * always included.
+     */
+    warehouse_ids: string[];
+    country?: CostcoNaCountry;
+    [key: string]: unknown;
+}
+interface CostcoAvailabilityOptions {
+    /** Costco item number or product id, or a costco.com product URL. */
+    item_number: string;
+    /** Warehouses to check (1-10). 1 credit per 5 warehouses. */
+    warehouse_ids: string[];
+    country?: CostcoNaCountry;
+    [key: string]: unknown;
+}
+interface CostcoReviewsOptions {
+    /** Costco product id (the product_id field from search or product). */
+    product_id: string;
+    /** Review order (default "newest"). */
+    sort_by?: "newest" | "oldest" | "highest_rating" | "lowest_rating" | "most_helpful";
+    /** Only reviews with this star rating (1-5). */
+    rating?: number;
+    /** Results page, 1-based (1-500). */
+    page?: number;
+    /** Reviews per page (1-100, default 25). */
+    limit?: number;
+    [key: string]: unknown;
+}
+interface CostcoWarehousesOptions {
+    /** US zip code. Pass zip, or latitude and longitude. */
+    zip?: string;
+    latitude?: number;
+    longitude?: number;
+    country?: CostcoCountry;
+    /** Nearest warehouses to return (1-50, default 10). */
+    limit?: number;
+    [key: string]: unknown;
+}
+interface CostcoGasOptions {
+    /** US zip code. Pass zip, latitude and longitude, or warehouse_ids. */
+    zip?: string;
+    latitude?: number;
+    longitude?: number;
+    /** Specific warehouses instead of a location (1-10). */
+    warehouse_ids?: string[];
+    country?: CostcoNaCountry;
+    /** Nearest stations to return (1-50). */
+    limit?: number;
+    [key: string]: unknown;
+}
+/** coupons takes no parameters. */
+interface CostcoCouponsOptions {
+    [key: string]: unknown;
+}
+interface CostcoDealsOptions extends CostcoListingFilters {
+    /** Deal feed. */
+    type: CostcoDealType;
+    country?: CostcoNaCountry;
+    [key: string]: unknown;
+}
+interface CostcoClearanceOptions {
+    /** Costco warehouse number to scan, from warehouses() (e.g. "1062"). */
+    warehouse_id: string;
+    /** Keywords to scan. Pass query or category. */
+    query?: string;
+    /** Category slug to scan instead of a query. */
+    category?: string;
+    /** Result pages of 120 to scan (1-5, default 3). */
+    pages?: number;
+    /**
+     * Markdown codes to keep. Default clearance (.97) and manager_markdown
+     * (.00/.88); add special_buy for .49/.79/.89 endings, which are common on
+     * regular grocery prices.
+     */
+    price_codes?: CostcoPriceCode[];
+    country?: CostcoNaCountry;
+    [key: string]: unknown;
+}
+interface CostcoAutocompleteOptions {
+    /** Partial search text (1-100 characters). */
+    query: string;
+    country?: CostcoNaCountry;
+    [key: string]: unknown;
+}
+declare class CostcoNamespace {
+    private client;
+    constructor(client: Scavio);
+    /**
+     * 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.
+     */
+    search(options: CostcoSearchOptions): Promise<Record<string, unknown>>;
+    /**
+     * Products in a Costco category, with the same sort, filters and
+     * per-warehouse pricing as search().
+     *
+     * Costs 1 credit.
+     */
+    category(options: CostcoCategoryOptions): Promise<Record<string, unknown>>;
+    /**
+     * The Costco department list, or the full subcategory tree under one
+     * department when `category_id` is set.
+     *
+     * Costs 1 credit.
+     */
+    categories(options?: CostcoCategoriesOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    product(options: CostcoProductOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    prices(options: CostcoPricesOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    availability(options: CostcoAvailabilityOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    reviews(options: CostcoReviewsOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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".
+     */
+    warehouses(options: CostcoWarehousesOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    gas(options: CostcoGasOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    coupons(options?: CostcoCouponsOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    deals(options: CostcoDealsOptions): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    clearance(options: CostcoClearanceOptions): Promise<Record<string, unknown>>;
+    /**
+     * Costco search-box suggestions for a partial query.
+     *
+     * Costs 1 credit.
+     */
+    autocomplete(options: CostcoAutocompleteOptions): Promise<Record<string, unknown>>;
+}
+
 /**
  * Default client-side rate limit, safe on every plan including free.
  */
@@ -4138,6 +4497,7 @@ declare class Scavio {
     readonly companiesHouse: CompaniesHouseNamespace;
     readonly googleAds: GoogleAdsNamespace;
     readonly metaAds: MetaAdsNamespace;
+    readonly costco: CostcoNamespace;
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
@@ -4224,4 +4584,4 @@ declare class ScavioAPIError extends ScavioError {
     constructor(statusCode: number, message: string, responseBody?: Record<string, unknown>);
 }
 
-export { type AirbnbListingOptions, AirbnbNamespace, type AirbnbReviewsOptions, type AirbnbSearchOptions, AmazonNamespace, type AmazonOffersOptions, type AmazonProductOptions, type AmazonSearchOptions, type AppStoreAppOptions, AppStoreNamespace, type AppStoreReviewsOptions, type AppStoreSearchOptions, BadRequestError, type BookingHotelOptions, BookingNamespace, type BookingReviewsOptions, type BookingSearchOptions, CapterraNamespace, type CapterraProductOptions, type CapterraReviewsOptions, type CapterraSearchOptions, type CompaniesHouseCompanyOptions, type CompaniesHouseFilingHistoryOptions, CompaniesHouseNamespace, type CompaniesHouseOfficersOptions, type CompaniesHouseSearchOptions, DEFAULT_MAX_REQUESTS_PER_SECOND, EbayNamespace, type EbayProductOptions, type EbaySearchOptions, type EbaySellerOptions, type ExtractOptions, G2Namespace, type G2ProductOptions, type G2ReviewsOptions, type G2SearchOptions, type GlassdoorCompaniesOptions, type GlassdoorCompanyOptions, GlassdoorNamespace, type GlassdoorReviewsOptions, type GlassdoorSalariesOptions, type GoogleAdsAdvertisersOptions, type GoogleAdsCreativeOptions, GoogleAdsNamespace, type GoogleAdsSearchOptions, type GoogleAiModeOptions, type GoogleFlightsOptions, type GoogleHotelsDetailOptions, type GoogleHotelsOptions, type GoogleMapsPlaceOptions, type GoogleMapsReviewsOptions, type GoogleMapsSearchOptions, GoogleNamespace, type GoogleNewsOptions, type GooglePlayAppOptions, GooglePlayNamespace, type GooglePlayReviewsOptions, type GooglePlaySearchOptions, type GoogleSearchOptions, type GoogleShoppingOptions, type GoogleShoppingProductOptions, type GoogleShoppingStoresOptions, type GoogleTrendingOptions, type GoogleTrendsOptions, HomeDepotNamespace, type HomeDepotProductOptions, type HomeDepotReviewsOptions, type HomeDepotSearchOptions, type IndeedCompanyOptions, type IndeedCompanyReviewsOptions, type IndeedJobOptions, IndeedNamespace, type IndeedSearchOptions, type InstagramCommentRepliesOptions, type InstagramFollowOptions, InstagramNamespace, type InstagramPostCommentsOptions, type InstagramPostOptions, type InstagramProfileOptions, type InstagramSearchOptions, type InstagramStoriesOptions, type InstagramUserFeedOptions, InsufficientCreditsError, InvalidAPIKeyError, type KuaishouCommentRepliesOptions, KuaishouNamespace, type KuaishouProfileOptions, type KuaishouSearchLiveOptions, type KuaishouSearchOptions, type KuaishouSearchUsersOptions, type KuaishouSearchVideosOptions, type KuaishouTagFeedOptions, type KuaishouTrendingOptions, type KuaishouUserLiveOptions, type KuaishouUserPostsOptions, type KuaishouUserResolveOptions, type KuaishouVideoCommentsOptions, type KuaishouVideoOptions, type KuaishouVideosBatchOptions, type LinkedInCompanyOptions, type LinkedInCompanyPostsOptions, type LinkedInCompanyPostsRequest, type LinkedInCompanyRefOptions, type LinkedInJobOptions, LinkedInNamespace, type LinkedInPersonContactOptions, type LinkedInPersonOptions, type LinkedInPersonPostsOptions, type LinkedInPersonPostsRequest, type LinkedInPersonRefOptions, type LinkedInPostCommentsOptions, type LinkedInPostOptions, type LinkedInSearchJobsOptions, type LinkedInSearchPeopleOptions, type LinkedInSearchPostsOptions, MAX_REQUESTS_PER_SECOND, type MetaAdsAdOptions, type MetaAdsAdvertiserOptions, MetaAdsNamespace, type MetaAdsSearchOptions, MissingAPIKeyError, NotFoundError, RateLimitError, type RedditCommentRepliesOptions, type RedditFeedSort, RedditNamespace, type RedditPopularOptions, type RedditPostCommentsOptions, type RedditPostOptions, type RedditSearchOptions, type RedditSearchSuggestionsOptions, type RedditSort, type RedditSubredditOptions, type RedditSubredditPostsOptions, type RedditUserFeedOptions, type RedditUserOptions, type RedfinMarketOptions, RedfinNamespace, type RedfinPropertyOptions, type RedfinSearchOptions, type SECCompanyOptions, type SECConceptOptions, type SECFactsOptions, type SECFilingsOptions, type SECLookupOptions, SECNamespace, type SECSearchOptions, Scavio, ScavioAPIError, type ScavioConfig, ScavioConnectionError, ScavioError, ScavioTimeoutError, type TargetCategoryOptions, TargetNamespace, type TargetProductOptions, type TargetReviewsOptions, type TargetSearchOptions, ThreadsNamespace, type ThreadsPostCommentsOptions, type ThreadsPostOptions, type ThreadsProfileOptions, type ThreadsSearchUsersOptions, type ThreadsUserPostsOptions, type ThreadsUserRepliesOptions, type TikTokCommentRepliesOptions, type TikTokHashtagOptions, type TikTokHashtagVideosOptions, TikTokNamespace, type TikTokProfileOptions, type TikTokSearchUsersOptions, type TikTokSearchVideosOptions, type TikTokShopCategoryProductsOptions, type TikTokShopListingRegion, TikTokShopNamespace, type TikTokShopProductOptions, type TikTokShopProductReviewsOptions, type TikTokShopRegion, type TikTokShopResolveOptions, type TikTokShopReviewSort, type TikTokShopSearchOptions, type TikTokShopShopProductsOptions, type TikTokShopSuggestionsOptions, type TikTokUserFollowersOptions, type TikTokUserFollowingsOptions, type TikTokUserPostsOptions, type TikTokVideoCommentsOptions, type TikTokVideoOptions, type TripadvisorLocationOptions, type TripadvisorLocationsOptions, TripadvisorNamespace, type TripadvisorReviewsOptions, type TripadvisorSearchOptions, type WalmartCategoryOptions, WalmartNamespace, type WalmartOffersOptions, type WalmartProductOptions, type WalmartReviewsOptions, type WalmartSearchOptions, type WalmartSellerOptions, type WalmartSellerProductsOptions, XNamespace, type XSearchOptions, type XTrendingOptions, type XTweetCommentsOptions, type XTweetOptions, type XTweetRetweetersOptions, type XUserFeedOptions, type XUserOptions, type YelpBusinessOptions, YelpNamespace, type YelpReviewsOptions, type YelpSearchOptions, type YouTubeChannelCommunityOptions, type YouTubeChannelOptions, type YouTubeChannelResolveOptions, type YouTubeChannelSearchOptions, type YouTubeChannelShortsOptions, type YouTubeChannelVideosOptions, type YouTubeCommentRepliesOptions, type YouTubeCommentsOptions, type YouTubeMetadataOptions, YouTubeNamespace, type YouTubeRelatedOptions, type YouTubeSearchOptions, type YouTubeShortsOptions, type YouTubeStreamsOptions, type YouTubeSuggestionsOptions, type YouTubeTranscriptOptions, type YouTubeVideoOptions, type ZillowAgentReviewsOptions, ZillowNamespace, type ZillowPropertyOptions, type ZillowSearchOptions };
+export { type AirbnbListingOptions, AirbnbNamespace, type AirbnbReviewsOptions, type AirbnbSearchOptions, AmazonNamespace, type AmazonOffersOptions, type AmazonProductOptions, type AmazonSearchOptions, type AppStoreAppOptions, AppStoreNamespace, type AppStoreReviewsOptions, type AppStoreSearchOptions, BadRequestError, type BookingHotelOptions, BookingNamespace, type BookingReviewsOptions, type BookingSearchOptions, CapterraNamespace, type CapterraProductOptions, type CapterraReviewsOptions, type CapterraSearchOptions, type CompaniesHouseCompanyOptions, type CompaniesHouseFilingHistoryOptions, CompaniesHouseNamespace, type CompaniesHouseOfficersOptions, type CompaniesHouseSearchOptions, type CostcoAutocompleteOptions, type CostcoAvailabilityOptions, type CostcoCategoriesOptions, type CostcoCategoryOptions, type CostcoClearanceOptions, type CostcoCountry, type CostcoCouponsOptions, type CostcoDealType, type CostcoDealsOptions, type CostcoGasOptions, type CostcoListingFilters, type CostcoNaCountry, CostcoNamespace, type CostcoPriceCode, type CostcoPricesOptions, type CostcoProductOptions, type CostcoReviewsOptions, type CostcoSearchOptions, type CostcoSortBy, type CostcoWarehousesOptions, DEFAULT_MAX_REQUESTS_PER_SECOND, EbayNamespace, type EbayProductOptions, type EbaySearchOptions, type EbaySellerOptions, type ExtractOptions, G2Namespace, type G2ProductOptions, type G2ReviewsOptions, type G2SearchOptions, type GlassdoorCompaniesOptions, type GlassdoorCompanyOptions, GlassdoorNamespace, type GlassdoorReviewsOptions, type GlassdoorSalariesOptions, type GoogleAdsAdvertisersOptions, type GoogleAdsCreativeOptions, GoogleAdsNamespace, type GoogleAdsSearchOptions, type GoogleAiModeOptions, type GoogleFlightsOptions, type GoogleHotelsDetailOptions, type GoogleHotelsOptions, type GoogleMapsPlaceOptions, type GoogleMapsReviewsOptions, type GoogleMapsSearchOptions, GoogleNamespace, type GoogleNewsOptions, type GooglePlayAppOptions, GooglePlayNamespace, type GooglePlayReviewsOptions, type GooglePlaySearchOptions, type GoogleSearchOptions, type GoogleShoppingOptions, type GoogleShoppingProductOptions, type GoogleShoppingStoresOptions, type GoogleTrendingOptions, type GoogleTrendsOptions, HomeDepotNamespace, type HomeDepotProductOptions, type HomeDepotReviewsOptions, type HomeDepotSearchOptions, type IndeedCompanyOptions, type IndeedCompanyReviewsOptions, type IndeedJobOptions, IndeedNamespace, type IndeedSearchOptions, type InstagramCommentRepliesOptions, type InstagramFollowOptions, InstagramNamespace, type InstagramPostCommentsOptions, type InstagramPostOptions, type InstagramProfileOptions, type InstagramSearchOptions, type InstagramStoriesOptions, type InstagramUserFeedOptions, InsufficientCreditsError, InvalidAPIKeyError, type KuaishouCommentRepliesOptions, KuaishouNamespace, type KuaishouProfileOptions, type KuaishouSearchLiveOptions, type KuaishouSearchOptions, type KuaishouSearchUsersOptions, type KuaishouSearchVideosOptions, type KuaishouTagFeedOptions, type KuaishouTrendingOptions, type KuaishouUserLiveOptions, type KuaishouUserPostsOptions, type KuaishouUserResolveOptions, type KuaishouVideoCommentsOptions, type KuaishouVideoOptions, type KuaishouVideosBatchOptions, type LinkedInCompanyOptions, type LinkedInCompanyPostsOptions, type LinkedInCompanyPostsRequest, type LinkedInCompanyRefOptions, type LinkedInJobOptions, LinkedInNamespace, type LinkedInPersonContactOptions, type LinkedInPersonOptions, type LinkedInPersonPostsOptions, type LinkedInPersonPostsRequest, type LinkedInPersonRefOptions, type LinkedInPostCommentsOptions, type LinkedInPostOptions, type LinkedInSearchJobsOptions, type LinkedInSearchPeopleOptions, type LinkedInSearchPostsOptions, MAX_REQUESTS_PER_SECOND, type MetaAdsAdOptions, type MetaAdsAdvertiserOptions, MetaAdsNamespace, type MetaAdsSearchOptions, MissingAPIKeyError, NotFoundError, RateLimitError, type RedditCommentRepliesOptions, type RedditFeedSort, RedditNamespace, type RedditPopularOptions, type RedditPostCommentsOptions, type RedditPostOptions, type RedditSearchOptions, type RedditSearchSuggestionsOptions, type RedditSort, type RedditSubredditOptions, type RedditSubredditPostsOptions, type RedditUserFeedOptions, type RedditUserOptions, type RedfinMarketOptions, RedfinNamespace, type RedfinPropertyOptions, type RedfinSearchOptions, type SECCompanyOptions, type SECConceptOptions, type SECFactsOptions, type SECFilingsOptions, type SECLookupOptions, SECNamespace, type SECSearchOptions, Scavio, ScavioAPIError, type ScavioConfig, ScavioConnectionError, ScavioError, ScavioTimeoutError, type TargetCategoryOptions, TargetNamespace, type TargetProductOptions, type TargetReviewsOptions, type TargetSearchOptions, ThreadsNamespace, type ThreadsPostCommentsOptions, type ThreadsPostOptions, type ThreadsProfileOptions, type ThreadsSearchUsersOptions, type ThreadsUserPostsOptions, type ThreadsUserRepliesOptions, type TikTokCommentRepliesOptions, type TikTokHashtagOptions, type TikTokHashtagVideosOptions, TikTokNamespace, type TikTokProfileOptions, type TikTokSearchUsersOptions, type TikTokSearchVideosOptions, type TikTokShopCategoryProductsOptions, type TikTokShopListingRegion, TikTokShopNamespace, type TikTokShopProductOptions, type TikTokShopProductReviewsOptions, type TikTokShopRegion, type TikTokShopResolveOptions, type TikTokShopReviewSort, type TikTokShopSearchOptions, type TikTokShopShopProductsOptions, type TikTokShopSuggestionsOptions, type TikTokUserFollowersOptions, type TikTokUserFollowingsOptions, type TikTokUserPostsOptions, type TikTokVideoCommentsOptions, type TikTokVideoOptions, type TripadvisorLocationOptions, type TripadvisorLocationsOptions, TripadvisorNamespace, type TripadvisorReviewsOptions, type TripadvisorSearchOptions, type WalmartCategoryOptions, WalmartNamespace, type WalmartOffersOptions, type WalmartProductOptions, type WalmartReviewsOptions, type WalmartSearchOptions, type WalmartSellerOptions, type WalmartSellerProductsOptions, type WalmartStore, type WalmartStoresData, type WalmartStoresOptions, type WalmartStoresResponse, XNamespace, type XSearchOptions, type XTrendingOptions, type XTweetCommentsOptions, type XTweetOptions, type XTweetRetweetersOptions, type XUserFeedOptions, type XUserOptions, type YelpBusinessOptions, YelpNamespace, type YelpReviewsOptions, type YelpSearchOptions, type YouTubeChannelCommunityOptions, type YouTubeChannelOptions, type YouTubeChannelResolveOptions, type YouTubeChannelSearchOptions, type YouTubeChannelShortsOptions, type YouTubeChannelVideosOptions, type YouTubeCommentRepliesOptions, type YouTubeCommentsOptions, type YouTubeMetadataOptions, YouTubeNamespace, type YouTubeRelatedOptions, type YouTubeSearchOptions, type YouTubeShortsOptions, type YouTubeStreamsOptions, type YouTubeSuggestionsOptions, type YouTubeTranscriptOptions, type YouTubeVideoOptions, type ZillowAgentReviewsOptions, ZillowNamespace, type ZillowPropertyOptions, type ZillowSearchOptions };

package/dist/index.js

@@ -129,12 +129,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 = {};
@@ -611,7 +624,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);
@@ -620,8 +637,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);
@@ -672,6 +692,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
@@ -2236,6 +2270,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;
@@ -2271,6 +2440,7 @@ var Scavio = class {
   companiesHouse;
   googleAds;
   metaAds;
+  costco;
   apiKey;
   baseUrl;
   timeout;
@@ -2322,6 +2492,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) {
@@ -2386,6 +2557,7 @@ export {
   BookingNamespace,
   CapterraNamespace,
   CompaniesHouseNamespace,
+  CostcoNamespace,
   DEFAULT_MAX_REQUESTS_PER_SECOND,
   EbayNamespace,
   G2Namespace,