scavio 0.2.1 → 0.5.0

package/dist/index.d.ts

@@ -1,59 +1,430 @@
 interface AmazonSearchOptions {
+    /** Product search query (1-500 characters). */
     query: string;
+    /** Amazon domain suffix (default 'com', e.g. 'co.uk'). */
     domain?: string;
+    /** Country code for localization. */
     country?: string;
+    /** Language code. */
     language?: string;
+    /** Currency code (ISO 4217, e.g. 'USD'). */
     currency?: string;
-    device?: string;
-    sort_by?: string;
+    /** Device to emulate. */
+    device?: "desktop" | "mobile" | "tablet";
+    /** Result sort order. */
+    sort_by?: "most_recent" | "price_low_to_high" | "price_high_to_low" | "featured" | "average_review" | "bestsellers";
+    /** Starting page (1-indexed). */
     start_page?: number;
+    /** Number of pages to fetch. */
     pages?: number;
+    /** Amazon category id. */
     category_id?: string;
+    /** Filter to a specific merchant. */
     merchant_id?: string;
+    /** ZIP/postal code for localized pricing. */
     zip_code?: string;
+    /** Auto-select the default variant. */
     autoselect_variant?: boolean;
+    [key: string]: unknown;
 }
 interface AmazonProductOptions {
+    /** Amazon ASIN (e.g. 'B09XS7JWHH'). Sent to the API as 'query'. */
     asin: string;
+    /** Amazon domain suffix (default 'com'). */
     domain?: string;
+    /** Country code for localization. */
     country?: string;
+    /** Language code. */
     language?: string;
+    /** Currency code (ISO 4217, e.g. 'USD'). */
     currency?: string;
-    device?: string;
+    /** Device to emulate. */
+    device?: "desktop" | "mobile" | "tablet";
+    /** ZIP/postal code for localized pricing. */
     zip_code?: string;
+    /** Auto-select the default variant. */
     autoselect_variant?: boolean;
+    [key: string]: unknown;
 }
 declare class AmazonNamespace {
     private client;
     constructor(client: Scavio);
     search(options: AmazonSearchOptions): Promise<Record<string, unknown>>;
     product(options: AmazonProductOptions): Promise<Record<string, unknown>>;
+    /** Supported Amazon domains, languages, currencies, and countries. */
+    options(): Promise<Record<string, unknown>>;
 }
 
+/**
+ * Google endpoints (scrape.do engine, /api/v2/google). A faithful passthrough
+ * that returns Google's full response. Every endpoint costs 1 credit. Any
+ * additional scrape.do parameter can be added to the options object.
+ * See https://scavio.dev/docs/search-api.
+ */
 interface GoogleSearchOptions {
+    /** Search query (1-500 characters). */
     query: string;
-    country_code?: string;
-    language?: string;
-    page?: number;
-    search_type?: string;
-    device?: string;
+    /** Device to emulate. */
+    device?: "desktop" | "mobile";
+    /** Result offset: 0 = page 1, 10 = page 2, ... up to 990. */
+    start?: number;
+    /** Include the raw Google HTML in the response. */
+    include_html?: boolean;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** Regional Google domain (e.g. 'google.co.uk'). */
+    google_domain?: string;
+    /** Canonical location name; auto-encoded to a UULE string. */
+    location?: string;
+    /** Pre-encoded UULE location string (takes priority over location). */
+    uule?: string;
+    /** Language restrict (e.g. 'lang_en'). */
+    lr?: string;
+    /** Country restrict (e.g. 'countryUS'). */
+    cr?: string;
+    /** SafeSearch filter. */
+    safe?: "active";
+    /** Disable spelling correction / auto-fixes when true. */
     nfpr?: boolean;
-    light_request?: boolean;
+    /** '0' disables the omitted/similar-results filter. */
+    filter?: "0" | "1";
+    /** Restrict results to a recent time window. */
+    time_period?: "last_hour" | "last_day" | "last_week" | "last_month" | "last_year";
+    /** Resolve a deferred AI Overview (server default true). */
+    resolve_ai_overview?: boolean;
+    [key: string]: unknown;
+}
+interface GoogleAiModeOptions {
+    /** Question or prompt (1-500 characters). */
+    query: string;
+    /** Device to emulate. */
+    device?: "desktop" | "mobile";
+    /** Include the raw Google HTML in the response. */
+    include_html?: boolean;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** Regional Google domain (e.g. 'google.co.uk'). */
+    google_domain?: string;
+    /** Canonical location name; auto-encoded to a UULE string. */
+    location?: string;
+    /** Pre-encoded UULE location string (takes priority over location). */
+    uule?: string;
+    /** SafeSearch filter. */
+    safe?: "active";
+    [key: string]: unknown;
+}
+interface GoogleMapsSearchOptions {
+    /** Search query (1-500 characters). */
+    query: string;
+    /** Result offset; must be a multiple of 20 (0, 20, 40, ...). */
+    start?: number;
+    /** Map center as '@lat,lng,zoomz'; controls where results come from. */
+    ll?: string;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** Regional Google domain (e.g. 'google.co.uk'). */
+    google_domain?: string;
+    [key: string]: unknown;
+}
+interface GoogleMapsPlaceOptions {
+    /** Place ID (ChIJ...). */
+    place_id?: string;
+    /** Numeric CID. */
+    data_cid?: string;
+    [key: string]: unknown;
+}
+interface GoogleMapsReviewsOptions {
+    /** Data ID (0xHEX:0xHEX). */
+    data_id?: string;
+    /** Place ID (ChIJ...). */
+    place_id?: string;
+    /** Reviews per page (1-20). */
+    num?: number;
+    /** Pagination cursor from a prior response. */
+    next_page_token?: string;
+    /** Sort order. */
+    sort_by?: "relevance" | "newest" | "highest_rating" | "lowest_rating";
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** Regional Google domain (e.g. 'google.co.uk'). */
+    google_domain?: string;
+    [key: string]: unknown;
+}
+interface GoogleShoppingOptions {
+    /** Product search query (1-500 characters). */
+    query: string;
+    /** Device to emulate. */
+    device?: "desktop" | "mobile";
+    /** Result offset. */
+    start?: number;
+    /** Minimum price filter. */
+    min_price?: number;
+    /** Maximum price filter. */
+    max_price?: number;
+    /** 0 = relevance, 1 = price ascending, 2 = price descending. */
+    sort_by?: number;
+    /** Only items with free shipping. */
+    free_shipping?: boolean;
+    /** Only items on sale. */
+    on_sale?: boolean;
+    /** Opaque Google Shopping filter token. */
+    shoprs?: string;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** Regional Google domain (e.g. 'google.co.uk'). */
+    google_domain?: string;
+    /** Canonical location name; auto-encoded to a UULE string. */
+    location?: string;
+    /** Pre-encoded UULE location string (takes priority over location). */
+    uule?: string;
+    [key: string]: unknown;
+}
+interface GoogleShoppingProductOptions {
+    /** Durable product catalog id. */
+    catalog_id?: string;
+    /** Product query; required when catalog_id is set. */
+    query?: string;
+    /** Immersive product page token. */
+    immersive_product_page_token?: string;
+    /** Alias for immersive_product_page_token. */
+    page_token?: string;
+    /** Product id. */
+    product_id?: string;
+    /** Device to emulate. */
+    device?: "desktop" | "mobile" | "tablet";
+    /** Regional Google domain (e.g. 'google.co.uk'). */
+    google_domain?: string;
+    /** Seller sort order. */
+    sort_by?: "base_price" | "total_price" | "promotion" | "seller_rating";
+    /** Load all available stores. */
+    load_all_stores?: boolean;
+    /** Fetch additional stores. */
+    more_stores?: boolean;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** Canonical location name; auto-encoded to a UULE string. */
+    location?: string;
+    /** Pre-encoded UULE location string (takes priority over location). */
+    uule?: string;
+    [key: string]: unknown;
+}
+interface GoogleShoppingStoresOptions {
+    /** Durable product catalog id. */
+    catalog_id: string;
+    /** Pagination cursor from shopping_product. */
+    next_page_token: string;
+    [key: string]: unknown;
+}
+interface GoogleFlightsOptions {
+    /** Departure IATA code(s); comma-separated allowed. */
+    departure_id: string;
+    /** Arrival IATA code(s); comma-separated allowed. */
+    arrival_id: string;
+    /** Outbound date (YYYY-MM-DD). */
+    outbound_date: string;
+    /** 1 = round trip, 2 = one way, 3 = multi-city. */
+    type?: number;
+    /** Return date (YYYY-MM-DD); required when type=1. */
+    return_date?: string;
+    /** Number of adults (1-9). */
+    adults?: number;
+    /** Number of children (0-9). */
+    children?: number;
+    /** Infants in seat (0-4). */
+    infants_in_seat?: number;
+    /** Infants on lap (0-4). */
+    infants_on_lap?: number;
+    /** 1 = economy, 2 = premium, 3 = business, 4 = first. */
+    travel_class?: number;
+    /** 0 = any, 1 = nonstop, 2 = <=1 stop, 3 = <=2 stops. */
+    stops?: number;
+    /** 1 = top, 2 = price, 3 = departure, 4 = arrival, 5 = duration, 6 = emissions. */
+    sort_by?: number;
+    /** Comma-separated airline codes/alliances to include. */
+    include_airlines?: string;
+    /** Comma-separated airline codes/alliances to exclude. */
+    exclude_airlines?: string;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** Currency code (ISO 4217, e.g. 'USD'). */
+    currency?: string;
+    [key: string]: unknown;
+}
+interface GoogleHotelsOptions {
+    /** Search query; use a '<City> hotels' form. */
+    query: string;
+    /** Check-in date (YYYY-MM-DD). */
+    check_in_date: string;
+    /** Check-out date (YYYY-MM-DD). */
+    check_out_date: string;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** Currency code (ISO 4217, e.g. 'USD'). */
+    currency?: string;
+    /** 3 = lowest price, 8 = highest rating, 13 = most reviewed. */
+    sort_by?: number;
+    /** Minimum nightly price. */
+    min_price?: number;
+    /** Maximum nightly price. */
+    max_price?: number;
+    /** 7 = 3.5+, 8 = 4.0+, 9 = 4.5+. */
+    rating?: number;
+    /** Comma-separated star ratings (2-5). */
+    hotel_class?: string;
+    /** Comma-separated amenity ids. */
+    amenities?: string;
+    /** Comma-separated property-type ids (e.g. '12' for vacation rentals). */
+    property_types?: string;
+    /** Only properties with free cancellation. */
+    free_cancellation?: boolean;
+    /** Only eco-certified properties. */
+    eco_certified?: boolean;
+    /** Only properties with special offers. */
+    special_offers?: boolean;
+    /** Pagination cursor from a prior response. */
+    next_page_token?: string;
+    /** Number of properties to return (1-20). */
+    limit?: number;
+    [key: string]: unknown;
+}
+interface GoogleHotelsDetailOptions {
+    /** Property detail token from a hotels listing. */
+    detail_token: string;
+    /** Check-in date (YYYY-MM-DD). */
+    check_in_date: string;
+    /** Check-out date (YYYY-MM-DD). */
+    check_out_date: string;
+    /** Currency code (ISO 4217, e.g. 'USD'). */
+    currency?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    [key: string]: unknown;
+}
+interface GoogleNewsOptions {
+    /** Keyword search. */
+    query?: string;
+    /** Browse a news topic. */
+    topic_token?: string;
+    /** Browse a topic section. */
+    section_token?: string;
+    /** Fetch full coverage of a story. */
+    story_token?: string;
+    /** Browse a publication. */
+    publication_token?: string;
+    /** Knowledge Graph entity id. */
+    kgmid?: string;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Country of the search (ISO 3166-1 alpha-2, e.g. 'us'). */
+    gl?: string;
+    /** Regional Google domain (e.g. 'google.co.uk'). */
+    google_domain?: string;
+    /** Sort order: 0 = relevance, 1 = date (only with query or kgmid). */
+    so?: number;
+    [key: string]: unknown;
+}
+interface GoogleTrendsOptions {
+    /** Search term(s); comma-separated for comparisons. */
+    query: string;
+    /** Location code (e.g. 'US', 'GB', 'US-CA'). */
+    geo?: string;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Time range (e.g. 'today 12-m', 'now 7-d'). */
+    date?: string;
+    /** Timezone offset in minutes. */
+    tz?: string;
+    /** Which trends dataset to return. */
+    data_type?: "TIMESERIES" | "GEO_MAP" | "GEO_MAP_0" | "RELATED_QUERIES" | "RELATED_TOPICS";
+    /** Category id. */
+    cat?: string;
+    /** Google property filter. */
+    gprop?: "images" | "news" | "youtube" | "froogle";
+    /** Resolution for GEO_MAP data. */
+    region?: "COUNTRY" | "REGION" | "DMA" | "CITY";
+    [key: string]: unknown;
+}
+interface GoogleTrendingOptions {
+    /** Country code (e.g. 'US'). */
+    geo: string;
+    /** UI language (ISO 639-1, e.g. 'en'). */
+    hl?: string;
+    /** Trending window: 4, 24, 48, or 168. */
+    hours?: number;
+    /** Category id (0-20). */
+    cat?: number;
+    /** Sort order. */
+    sort?: "relevance" | "search_volume" | "recency" | "title";
+    /** Filter by trend status. */
+    status?: "all" | "active";
+    [key: string]: unknown;
 }
 declare class GoogleNamespace {
     private client;
     constructor(client: Scavio);
+    /** Google SERP search (includes the AI Overview when Google returns one). */
     search(options: GoogleSearchOptions): Promise<Record<string, unknown>>;
+    /** Google AI Mode answer. */
+    aiMode(options: GoogleAiModeOptions): Promise<Record<string, unknown>>;
+    /** Google Maps local results. */
+    mapsSearch(options: GoogleMapsSearchOptions): Promise<Record<string, unknown>>;
+    /** Google Maps place details. Provide place_id or data_cid. */
+    mapsPlace(options: GoogleMapsPlaceOptions): Promise<Record<string, unknown>>;
+    /** Google Maps reviews. Provide data_id or place_id. */
+    mapsReviews(options: GoogleMapsReviewsOptions): Promise<Record<string, unknown>>;
+    /** Google Shopping search results. */
+    shopping(options: GoogleShoppingOptions): Promise<Record<string, unknown>>;
+    /** Google Shopping product. Pass catalog_id + query for full details and sellers. */
+    shoppingProduct(options: GoogleShoppingProductOptions): Promise<Record<string, unknown>>;
+    /** Google Shopping product sellers (continuation of shoppingProduct). */
+    shoppingStores(options: GoogleShoppingStoresOptions): Promise<Record<string, unknown>>;
+    /** Google Flights. */
+    flights(options: GoogleFlightsOptions): Promise<Record<string, unknown>>;
+    /** Google Hotels search. */
+    hotels(options: GoogleHotelsOptions): Promise<Record<string, unknown>>;
+    /** Google Hotels property details (from a hotels listing detail_token). */
+    hotelsDetail(options: GoogleHotelsDetailOptions): Promise<Record<string, unknown>>;
+    /** Google News. Provide query or a topic/story/publication token. */
+    news(options: GoogleNewsOptions): Promise<Record<string, unknown>>;
+    /** Google Trends data. */
+    trends(options: GoogleTrendsOptions): Promise<Record<string, unknown>>;
+    /** Google Trending Now for a country. */
+    trending(options: GoogleTrendingOptions): Promise<Record<string, unknown>>;
 }
 
 interface RedditSearchOptions {
+    /** Search query (1-500 characters). */
     query: string;
-    type?: string;
-    sort?: string;
+    /** Result type (server default 'posts'). */
+    type?: "posts" | "comments";
+    /** Sort order (server default 'new'). */
+    sort?: "new" | "relevance" | "hot" | "top" | "comments";
+    /** Pagination cursor from a prior response. */
     cursor?: string;
+    [key: string]: unknown;
 }
 interface RedditPostOptions {
+    /** Full Reddit post URL. */
     url: string;
+    [key: string]: unknown;
 }
 declare class RedditNamespace {
     private client;
@@ -63,61 +434,107 @@ declare class RedditNamespace {
 }
 
 interface TikTokProfileOptions {
+    /** TikTok @username (without the @). */
     username?: string;
+    /** TikTok sec_user_id. */
     sec_user_id?: string;
+    [key: string]: unknown;
 }
 interface TikTokUserPostsOptions {
+    /** TikTok sec_user_id. */
     sec_user_id: string;
+    /** Pagination cursor (default '0'). */
     cursor?: string;
+    /** Results per page (1-30). */
     count?: number;
-    sort_type?: string;
+    /** '0' = latest, '1' = popular. */
+    sort_type?: "0" | "1";
+    [key: string]: unknown;
 }
 interface TikTokVideoOptions {
+    /** TikTok video id. */
     video_id: string;
+    [key: string]: unknown;
 }
 interface TikTokVideoCommentsOptions {
+    /** TikTok video id. */
     video_id: string;
+    /** Pagination cursor (default '0'). */
     cursor?: string;
+    /** Results per page (1-50). */
     count?: number;
+    [key: string]: unknown;
 }
 interface TikTokCommentRepliesOptions {
+    /** TikTok video id. */
     video_id: string;
+    /** Parent comment id. */
     comment_id: string;
+    /** Pagination cursor (default '0'). */
     cursor?: string;
+    /** Results per page (1-50). */
     count?: number;
+    [key: string]: unknown;
 }
 interface TikTokSearchVideosOptions {
+    /** Search keyword (1-500 characters). */
     keyword: string;
+    /** Pagination cursor (default '0'). */
     cursor?: string;
+    /** Results per page (1-30). */
     count?: number;
-    sort_type?: string;
-    publish_time?: string;
+    /** '0' = relevance, '1' = most likes. */
+    sort_type?: "0" | "1";
+    /** Age filter in days: 0 = all time, 1, 7, 30, 90, 180. */
+    publish_time?: "0" | "1" | "7" | "30" | "90" | "180";
+    [key: string]: unknown;
 }
 interface TikTokSearchUsersOptions {
+    /** Search keyword (1-500 characters). */
     keyword: string;
+    /** Pagination cursor (default '0'). */
     cursor?: string;
+    /** Results per page (1-30). */
     count?: number;
+    [key: string]: unknown;
 }
 interface TikTokHashtagOptions {
+    /** Hashtag name (without the #). */
     hashtag_name?: string;
+    /** Hashtag id. */
     hashtag_id?: string;
+    [key: string]: unknown;
 }
 interface TikTokHashtagVideosOptions {
+    /** Hashtag id. */
     hashtag_id: string;
+    /** Pagination cursor (default '0'). */
     cursor?: string;
+    /** Results per page (1-30). */
     count?: number;
+    [key: string]: unknown;
 }
 interface TikTokUserFollowersOptions {
+    /** TikTok sec_user_id. */
     sec_user_id: string;
+    /** Results per page (1-20). */
     count?: number;
+    /** Pagination token from a prior response. */
     page_token?: string;
+    /** Minimum timestamp cursor. */
     min_time?: number;
+    [key: string]: unknown;
 }
 interface TikTokUserFollowingsOptions {
+    /** TikTok sec_user_id. */
     sec_user_id: string;
+    /** Results per page (1-20). */
     count?: number;
+    /** Pagination token from a prior response. */
     page_token?: string;
+    /** Minimum timestamp cursor. */
     min_time?: number;
+    [key: string]: unknown;
 }
 declare class TikTokNamespace {
     private client;
@@ -136,44 +553,76 @@ declare class TikTokNamespace {
 }
 
 interface InstagramProfileOptions {
+    /** Instagram username (without the @). */
     username?: string;
+    /** Instagram numeric user id. */
     user_id?: string;
+    [key: string]: unknown;
 }
 interface InstagramUserFeedOptions {
+    /** Instagram username (without the @). */
     username?: string;
+    /** Instagram numeric user id. */
     user_id?: string;
+    /** Results per page (1-50). */
     count?: number;
+    /** Pagination cursor from a prior response. */
     cursor?: string;
+    [key: string]: unknown;
 }
 interface InstagramStoriesOptions {
+    /** Instagram username (without the @). */
     username?: string;
+    /** Instagram numeric user id. */
     user_id?: string;
+    [key: string]: unknown;
 }
 interface InstagramPostOptions {
+    /** Full Instagram post URL. */
     url?: string;
+    /** Instagram media id. */
     media_id?: string;
+    /** Instagram shortcode (from the post URL). */
     shortcode?: string;
+    [key: string]: unknown;
 }
 interface InstagramPostCommentsOptions {
+    /** Instagram shortcode (from the post URL). */
     shortcode?: string;
+    /** Full Instagram post URL. */
     url?: string;
+    /** Pagination cursor from a prior response. */
     cursor?: string;
-    sort_order?: string;
+    /** Comment sort order. */
+    sort_order?: "popular" | "newest";
+    [key: string]: unknown;
 }
 interface InstagramCommentRepliesOptions {
+    /** Instagram media id. */
     media_id: string;
+    /** Parent comment id. */
     comment_id: string;
+    /** Pagination cursor from a prior response. */
     cursor?: string;
+    [key: string]: unknown;
 }
 interface InstagramSearchOptions {
+    /** Search keyword (1-500 characters). */
     keyword: string;
+    /** Pagination cursor from a prior response. */
     cursor?: string;
+    [key: string]: unknown;
 }
 interface InstagramFollowOptions {
+    /** Instagram username (without the @). */
     username?: string;
+    /** Instagram numeric user id. */
     user_id?: string;
+    /** Results per page (1-100). */
     count?: number;
+    /** Pagination cursor from a prior response. */
     cursor?: string;
+    [key: string]: unknown;
 }
 declare class InstagramNamespace {
     private client;
@@ -193,24 +642,42 @@ declare class InstagramNamespace {
 }
 
 interface WalmartSearchOptions {
+    /** Product search query (1-500 characters). */
     query: string;
+    /** Walmart domain. */
     domain?: string;
-    device?: string;
-    sort_by?: string;
+    /** Device to emulate. */
+    device?: "desktop" | "mobile" | "tablet";
+    /** Result sort order. */
+    sort_by?: "best_match" | "price_low" | "price_high" | "best_seller";
+    /** Starting page (1-indexed). */
     start_page?: number;
+    /** Minimum price filter (USD). */
     min_price?: number;
+    /** Maximum price filter (USD). */
     max_price?: number;
-    fulfillment_speed?: string;
-    fulfillment_type?: string;
+    /** Delivery speed filter. */
+    fulfillment_speed?: "today" | "tomorrow" | "2_days" | "anytime";
+    /** Fulfillment type filter. */
+    fulfillment_type?: "in_store";
+    /** ZIP code for localized results. */
     delivery_zip?: string;
+    /** Store id for in-store availability. */
     store_id?: string;
+    [key: string]: unknown;
 }
 interface WalmartProductOptions {
+    /** Walmart product id. */
     product_id: string;
+    /** Walmart domain. */
     domain?: string;
-    device?: string;
+    /** Device to emulate. */
+    device?: "desktop" | "mobile" | "tablet";
+    /** ZIP code for localized pricing. */
     delivery_zip?: string;
+    /** Store id for in-store availability. */
     store_id?: string;
+    [key: string]: unknown;
 }
 declare class WalmartNamespace {
     private client;
@@ -220,18 +687,42 @@ declare class WalmartNamespace {
 }
 
 interface YouTubeSearchOptions {
+    /** Search query (1-500 characters). Sent to the API as 'search'. */
     query: string;
-    upload_date?: string;
-    type?: string;
-    duration?: string;
-    sort_by?: string;
+    /** Filter by upload date. */
+    upload_date?: "last_hour" | "today" | "this_week" | "this_month" | "this_year";
+    /** Filter by result type. */
+    type?: "video" | "channel" | "playlist";
+    /** short (<4 min), medium (4-20 min), long (>20 min). */
+    duration?: "short" | "medium" | "long";
+    /** Sort order. */
+    sort_by?: "relevance" | "date" | "view_count" | "rating";
+    /** HD videos only. */
     hd?: boolean;
+    /** Videos with subtitles/CC only. */
     subtitles?: boolean;
+    /** Creative Commons licensed only. */
     creative_commons?: boolean;
+    /** Live videos only. */
     live?: boolean;
+    /** HDR videos only. */
+    hdr?: boolean;
+    /** Videos with location metadata only. */
+    location?: boolean;
+    /** VR180 videos only. */
+    vr180?: boolean;
+    /** 4K videos only. Sent to the API as '4k'. */
+    fourK?: boolean;
+    /** 360-degree videos only. Sent to the API as '360'. */
+    video_360?: boolean;
+    /** 3D videos only. Sent to the API as '3d'. */
+    video_3d?: boolean;
+    [key: string]: unknown;
 }
 interface YouTubeMetadataOptions {
+    /** YouTube video id (e.g. 'dQw4w9WgXcQ'). */
     video_id: string;
+    [key: string]: unknown;
 }
 declare class YouTubeNamespace {
     private client;
@@ -245,6 +736,12 @@ interface ScavioConfig {
     baseUrl?: string;
     timeout?: number;
     maxRequestsPerSecond?: number;
+    /**
+     * Additional retry attempts after the first request on transient failures
+     * (HTTP 429/500/502/503/504 and network/timeout errors). Defaults to 2.
+     * Set to 0 to disable retries.
+     */
+    maxRetries?: number;
 }
 declare class Scavio {
     readonly google: GoogleNamespace;
@@ -257,6 +754,7 @@ declare class Scavio {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly maxRetries;
     private readonly rateLimiter;
     constructor(config?: ScavioConfig);
     /** @internal */
@@ -273,21 +771,43 @@ declare class ScavioError extends Error {
 declare class MissingAPIKeyError extends ScavioError {
     constructor();
 }
-declare class InvalidAPIKeyError extends ScavioError {
+/** The request could not reach the API (DNS, connection reset, TLS, ...). */
+declare class ScavioConnectionError extends ScavioError {
     constructor(message?: string);
 }
-declare class InsufficientCreditsError extends ScavioError {
+/** The request did not complete within the configured timeout. */
+declare class ScavioTimeoutError extends ScavioError {
     constructor(message?: string);
 }
+declare class InvalidAPIKeyError extends ScavioError {
+    readonly statusCode = 401;
+    readonly responseBody?: Record<string, unknown>;
+    constructor(message?: string, responseBody?: Record<string, unknown>);
+}
+declare class InsufficientCreditsError extends ScavioError {
+    readonly statusCode = 402;
+    readonly responseBody?: Record<string, unknown>;
+    constructor(message?: string, responseBody?: Record<string, unknown>);
+}
 declare class BadRequestError extends ScavioError {
-    constructor(message?: string);
+    readonly statusCode = 400;
+    readonly responseBody?: Record<string, unknown>;
+    constructor(message?: string, responseBody?: Record<string, unknown>);
+}
+declare class NotFoundError extends ScavioError {
+    readonly statusCode = 404;
+    readonly responseBody?: Record<string, unknown>;
+    constructor(message?: string, responseBody?: Record<string, unknown>);
 }
 declare class RateLimitError extends ScavioError {
-    constructor(message?: string);
+    readonly statusCode = 429;
+    readonly responseBody?: Record<string, unknown>;
+    constructor(message?: string, responseBody?: Record<string, unknown>);
 }
 declare class ScavioAPIError extends ScavioError {
     readonly statusCode: number;
-    constructor(statusCode: number, message: string);
+    readonly responseBody?: Record<string, unknown>;
+    constructor(statusCode: number, message: string, responseBody?: Record<string, unknown>);
 }
 
-export { type AmazonProductOptions, type AmazonSearchOptions, BadRequestError, type GoogleSearchOptions, type InstagramCommentRepliesOptions, type InstagramFollowOptions, type InstagramPostCommentsOptions, type InstagramPostOptions, type InstagramProfileOptions, type InstagramSearchOptions, type InstagramStoriesOptions, type InstagramUserFeedOptions, InsufficientCreditsError, InvalidAPIKeyError, MissingAPIKeyError, RateLimitError, type RedditPostOptions, type RedditSearchOptions, Scavio, ScavioAPIError, type ScavioConfig, ScavioError, type TikTokCommentRepliesOptions, type TikTokHashtagOptions, type TikTokHashtagVideosOptions, type TikTokProfileOptions, type TikTokSearchUsersOptions, type TikTokSearchVideosOptions, type TikTokUserFollowersOptions, type TikTokUserFollowingsOptions, type TikTokUserPostsOptions, type TikTokVideoCommentsOptions, type TikTokVideoOptions, type WalmartProductOptions, type WalmartSearchOptions, type YouTubeMetadataOptions, type YouTubeSearchOptions };
+export { type AmazonProductOptions, type AmazonSearchOptions, BadRequestError, type GoogleAiModeOptions, type GoogleFlightsOptions, type GoogleHotelsDetailOptions, type GoogleHotelsOptions, type GoogleMapsPlaceOptions, type GoogleMapsReviewsOptions, type GoogleMapsSearchOptions, type GoogleNewsOptions, type GoogleSearchOptions, type GoogleShoppingOptions, type GoogleShoppingProductOptions, type GoogleShoppingStoresOptions, type GoogleTrendingOptions, type GoogleTrendsOptions, type InstagramCommentRepliesOptions, type InstagramFollowOptions, type InstagramPostCommentsOptions, type InstagramPostOptions, type InstagramProfileOptions, type InstagramSearchOptions, type InstagramStoriesOptions, type InstagramUserFeedOptions, InsufficientCreditsError, InvalidAPIKeyError, MissingAPIKeyError, NotFoundError, RateLimitError, type RedditPostOptions, type RedditSearchOptions, Scavio, ScavioAPIError, type ScavioConfig, ScavioConnectionError, ScavioError, ScavioTimeoutError, type TikTokCommentRepliesOptions, type TikTokHashtagOptions, type TikTokHashtagVideosOptions, type TikTokProfileOptions, type TikTokSearchUsersOptions, type TikTokSearchVideosOptions, type TikTokUserFollowersOptions, type TikTokUserFollowingsOptions, type TikTokUserPostsOptions, type TikTokVideoCommentsOptions, type TikTokVideoOptions, type WalmartProductOptions, type WalmartSearchOptions, type YouTubeMetadataOptions, type YouTubeSearchOptions };