serpkite 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,2259 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+interface paths {
+    "/healthz": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Readiness (DB, Valkey) */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description OK */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description A dependency is down */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/livez": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Liveness only */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description OK */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Same as POST /v1/search with query-string parameters */
+        get: operations["searchGet"];
+        put?: never;
+        /** Google web search (organic results, knowledge graph, answer box, people also ask, top stories, local pack…) */
+        post: operations["search"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/images": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google Images */
+        post: operations["images"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/videos": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google Videos */
+        post: operations["videos"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/news": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google News */
+        post: operations["news"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/maps": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google Maps search (places with coordinates). Accepts `ll` ("@lat,lng,zoomz") */
+        post: operations["maps"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/places": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google local results (places) */
+        post: operations["places"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/reviews": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reviews of a place (by `place_id`, `cid` or `fid`); 1 credit per 10 reviews */
+        post: operations["reviews"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/shopping": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google Shopping */
+        post: operations["shopping"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/scholar": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google Scholar */
+        post: operations["scholar"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/patents": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google Patents */
+        post: operations["patents"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/autocomplete": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google autocomplete suggestions (0.5 credit) */
+        post: operations["autocomplete"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/lens": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Google Lens visual matches for an image URL (2 credits) */
+        post: operations["lens"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/webpage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Fetch any public URL and return clean Markdown + metadata (1 credit) */
+        post: operations["webpage"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/customsearch/v1": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Google Custom Search JSON API–compatible endpoint (for apps moving off CSE) */
+        get: operations["customSearch"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/rank": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Position of a domain for a keyword in the top N (default 100; priced like /v1/search depth, 7 credits for 100) */
+        post: operations["rank"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Public live status — requests, success rate, p50/p95 latency per endpoint over the last hour */
+        get: operations["status"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/batches": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Queue up to 100 requests for one endpoint at half price. Each request becomes one batch job
+         * @description Credits for the whole batch are reserved together: if the balance, spend cap, key limit or
+         *     free daily cap can't cover every valid request, none is queued and each gets the error
+         *     (invalid requests get their own 400 entry either way). Each job is settled and refunded on
+         *     its own once it runs.
+         *
+         *     **Retries.** Send an `Idempotency-Key` to make the call safe to retry: for 24 hours a
+         *     repeat with the same key and the same body returns the first response (with
+         *     `Idempotent-Replayed: true`) without queueing or billing again. The same key with a
+         *     different body is rejected with 422 `idempotency_key_reused`; a repeat while the first
+         *     call is still running gets 409.
+         *
+         *     **Webhooks.** Every delivery is a `POST` with `X-SerpKite-Event: batch.completed`,
+         *     `X-SerpKite-Delivery` (the job id), `X-SerpKite-Timestamp` (Unix seconds) and
+         *     `X-SerpKite-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>`. Deliveries
+         *     are always signed; the account's secret is created with its first webhook and revealed by
+         *     rotating it (dashboard Settings → Webhooks). Verify by recomputing the HMAC over the raw
+         *     body, comparing in constant time, and rejecting timestamps older than 5 minutes. The SDKs
+         *     ship `verifyWebhook` / `verify_webhook` / `VerifyWebhook`.
+         */
+        post: operations["createBatches"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/batches/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Poll a batch job */
+        get: operations["getBatch"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/account": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Balance, limits and this month's usage for the calling key's account */
+        get: operations["account"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/playground/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** No-login demo of /v1/search (and news, images, autocomplete via `endpoint`). Per-IP rate limited (IPv6 per /64), not billed. Browser calls only from serpkite.com and app.serpkite.com */
+        post: operations["playground"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/mcp": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Remote MCP server (streamable HTTP, JSON-RPC 2.0). Tools search, news, maps, scholar, webpage */
+        post: operations["mcp"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        Error: {
+            error: {
+                /**
+                 * @description 403: spend_cap_reached, key_limit_reached, forbidden. 409/422: idempotency_key_reused. 429: rate_limited, daily_limit_reached. 503: upstream_error, upstream_blocked, upstream_timeout, unavailable (the API never sends 502 or 504)
+                 * @example unauthorized
+                 * @example invalid_request
+                 * @example insufficient_credits
+                 * @example rate_limited
+                 * @example daily_limit_reached
+                 * @example spend_cap_reached
+                 * @example key_limit_reached
+                 * @example idempotency_key_reused
+                 * @example forbidden
+                 * @example not_found
+                 * @example upstream_error
+                 * @example upstream_blocked
+                 * @example upstream_timeout
+                 * @example unavailable
+                 * @example internal
+                 */
+                code: string;
+                message: string;
+                request_id?: string;
+            };
+        };
+        SearchRequest: {
+            q: string;
+            /**
+             * @description Country code (ISO 3166-1 alpha-2)
+             * @default us
+             */
+            country?: string;
+            /**
+             * @description Interface language (e.g. en
+             * @default en
+             */
+            language?: string;
+            /** @description Free-text location, e.g. "Austin, Texas, United States" */
+            location?: string;
+            /** @description Pre-encoded Google location (overrides location) */
+            uule?: string;
+            /** @description Maps viewport "@lat,lng,14z" (maps only) */
+            ll?: string;
+            /**
+             * @description 10, or up to 100 for the depth bundle on search and news (7 credits for 100; values between round up to whole pages). Other verticals return one page of 10
+             * @default 10
+             */
+            num?: number;
+            /** @default 1 */
+            page?: number;
+            /**
+             * @description Only results from the last hour/day/…
+             * @enum {string}
+             */
+            time?: "hour" | "day" | "week" | "month" | "year";
+            /** @description Advanced: raw Google tbs filter (e.g. qdr:d); overrides time */
+            tbs?: string;
+            /**
+             * @default desktop
+             * @enum {string}
+             */
+            device?: "desktop" | "mobile";
+            /**
+             * @default off
+             * @enum {string}
+             */
+            safe?: "active" | "off";
+            /** @default true */
+            autocorrect?: boolean;
+            /**
+             * @default json
+             * @enum {string}
+             */
+            format?: "json" | "markdown" | "compact";
+            /** @description Comma-separated projection, e.g. "results.title,results.link,knowledge_graph" */
+            fields?: string;
+            /**
+             * @description Also fetch the top N organic pages as Markdown (+1 credit each fetched page)
+             * @default 0
+             */
+            include_content?: number;
+            /**
+             * @description Include sponsored results
+             * @default false
+             */
+            ads?: boolean;
+            /** @description Accept a cached result up to this many seconds old (50% of credits on a hit) */
+            max_age?: number;
+            engine?: components["schemas"]["EngineParam"];
+        };
+        /** @description One of place_id, cid or fid is required */
+        ReviewsRequest: {
+            place_id?: string;
+            cid?: string;
+            fid?: string;
+            country?: string;
+            language?: string;
+            /**
+             * @default most_relevant
+             * @enum {string}
+             */
+            sort?: "most_relevant" | "newest" | "highest_rating" | "lowest_rating";
+            /** @description `next_page_token` from the previous page, unchanged. Opaque and bound to the place and `sort` it was issued for (anything else is a 400). Paging reaches the first 100 reviews of a place per sort order. */
+            page_token?: string;
+            /**
+             * @description Reviews per page (a page can be shorter when Google stops loading early; `next_page_token` then resumes after it)
+             * @default 10
+             */
+            num?: number;
+            /** @enum {string} */
+            format?: "json" | "markdown" | "compact";
+            fields?: string;
+            max_age?: number;
+        };
+        LensRequest: {
+            /**
+             * Format: uri
+             * @description Image URL
+             */
+            url: string;
+            country?: string;
+            language?: string;
+            /** @enum {string} */
+            format?: "json" | "markdown" | "compact";
+            fields?: string;
+            max_age?: number;
+        };
+        WebpageRequest: {
+            /** Format: uri */
+            url: string;
+            /**
+             * @default json
+             * @enum {string}
+             */
+            format?: "json" | "markdown" | "compact";
+            /** @default false */
+            include_html?: boolean;
+            max_age?: number;
+        };
+        /**
+         * @description A search provider (docs/providers). Which verticals each serves depends on the deployment.
+         * @enum {string}
+         */
+        Provider: "google" | "brave" | "bing" | "yahoo" | "duckduckgo" | "mojeek" | "wikipedia";
+        /** @description Which search providers may answer. `google` (the default) is Google only; within Google, SerpKite always fails over across its own proxy pools. `auto` allows falling back to other enabled providers, in route order, when Google is blocked or times out. A single other provider (`brave`) or a list (`["google","brave"]`, or `google,brave` in a query string) restricts the request to those providers. `meta.engine` always names the provider that answered and credits follow that provider's price. A key with "Allow fallback to other search engines" on treats a request without `engine` as `auto`. `consensus` (`/v1/search` only; 400 elsewhere, and it can't be combined with other names) queries several independent search indexes in parallel (at most one Bing-backed provider, so Yahoo or DuckDuckGo never count as agreeing with Bing), merges the results by URL and ranks them by how many providers returned each one. Each result lists its `sources`; `meta.engine` is `consensus` and `meta.route` lists every provider attempt. It stops once `num` unique results are in hand or after a few seconds, and costs the sum of one page at each provider that returned results (providers that failed, came back empty or were never started are free). */
+        EngineParam: string | components["schemas"]["Provider"][];
+        /** @description One provider attempt behind this answer. Proxy pools are internal and never listed. */
+        RouteStep: {
+            /**
+             * @example google
+             * @example brave
+             */
+            provider: string;
+            /** @enum {string} */
+            outcome: "ok" | "partial" | "empty" | "soft_empty" | "blocked" | "timeout" | "error" | "unsupported" | "bad_param" | "bad_target" | "canceled";
+            /** @description Duration of the attempt in milliseconds */
+            ms: number;
+        };
+        Meta: {
+            request_id: string;
+            credits_used: number;
+            /**
+             * @description The provider that produced the result (`consensus` for a merged engine=consensus answer)
+             * @example google
+             * @example brave
+             * @example consensus
+             * @example stub
+             */
+            engine?: string;
+            /** @description Provider attempts in order (fresh results only; absent on cache hits). With engine=consensus, every provider started; ones stopped early are `canceled`, ones cut off by the deadline `timeout` */
+            route?: components["schemas"]["RouteStep"][];
+            cached: boolean;
+            /** Format: date-time */
+            cached_at?: string;
+            resolved_urls?: boolean;
+            /** @enum {string} */
+            parse_quality?: "ok" | "partial" | "empty";
+            latency_ms?: number;
+        };
+        /** @description The normalised request that produced this response (defaults filled in) */
+        RequestEcho: {
+            /**
+             * @example search
+             * @example news
+             * @example lens
+             */
+            endpoint: string;
+            /** @description The engine policy as asked (google, auto, one provider or a list) */
+            engine: string | string[];
+            q?: string;
+            url?: string;
+            country?: string;
+            language?: string;
+            location?: string;
+            num?: number;
+            page?: number;
+            device?: string;
+            autocorrect?: boolean;
+            tbs?: string;
+            safe?: string;
+            place_id?: string;
+            cid?: string;
+            fid?: string;
+            sort?: string;
+            include_content?: number;
+            format?: string;
+        } & {
+            [key: string]: unknown;
+        };
+        Sitelink: {
+            title: string;
+            link: string;
+            snippet?: string;
+        };
+        OrganicResult: {
+            position: number;
+            title: string;
+            /** @description Resolved destination URL (never a google.com/url or /goto redirect) */
+            link: string;
+            /** @description Canonical host without www. */
+            domain: string;
+            displayed_link?: string;
+            snippet?: string;
+            date?: string;
+            sitelinks?: components["schemas"]["Sitelink"][];
+            attributes?: {
+                [key: string]: string;
+            };
+            rating?: number;
+            rating_count?: number;
+            /** @description Page Markdown when include_content covered this result */
+            content?: string;
+            /**
+             * @description engine=consensus only. The providers that returned this result, in route order; results are ranked by how many there are
+             * @example [
+             *       "google",
+             *       "brave",
+             *       "bing"
+             *     ]
+             */
+            sources?: components["schemas"]["Provider"][];
+        };
+        AnswerBox: {
+            title?: string;
+            answer?: string;
+            snippet?: string;
+            snippet_highlighted?: string[];
+            link?: string;
+        };
+        KnowledgeGraph: {
+            title?: string;
+            type?: string;
+            website?: string;
+            image_url?: string;
+            description?: string;
+            description_source?: string;
+            description_link?: string;
+            attributes?: {
+                [key: string]: string;
+            };
+        };
+        PeopleAlsoAsk: {
+            question: string;
+            snippet?: string;
+            title?: string;
+            link?: string;
+        };
+        RelatedSearch: {
+            query: string;
+        };
+        SearchResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["OrganicResult"][];
+            answer_box?: components["schemas"]["AnswerBox"];
+            knowledge_graph?: components["schemas"]["KnowledgeGraph"];
+            ads?: components["schemas"]["OrganicResult"][];
+            people_also_ask?: components["schemas"]["PeopleAlsoAsk"][];
+            related_searches: components["schemas"]["RelatedSearch"][];
+            top_stories?: components["schemas"]["NewsResult"][];
+            places?: components["schemas"]["PlaceResult"][];
+            meta: components["schemas"]["Meta"];
+        };
+        ImageResult: {
+            position: number;
+            title: string;
+            image_url: string;
+            image_width?: number;
+            image_height?: number;
+            thumbnail_url?: string;
+            source?: string;
+            domain?: string;
+            link?: string;
+        };
+        ImagesResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["ImageResult"][];
+            meta: components["schemas"]["Meta"];
+        };
+        VideoResult: {
+            position: number;
+            title: string;
+            link: string;
+            domain?: string;
+            snippet?: string;
+            image_url?: string;
+            duration?: string;
+            source?: string;
+            channel?: string;
+            date?: string;
+        };
+        VideosResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["VideoResult"][];
+            meta: components["schemas"]["Meta"];
+        };
+        NewsResult: {
+            position: number;
+            title: string;
+            link: string;
+            domain?: string;
+            snippet?: string;
+            date?: string;
+            source?: string;
+            image_url?: string;
+        };
+        NewsResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["NewsResult"][];
+            meta: components["schemas"]["Meta"];
+        };
+        PlaceResult: {
+            position: number;
+            title: string;
+            address?: string;
+            latitude?: number;
+            longitude?: number;
+            rating?: number;
+            rating_count?: number;
+            price_level?: string;
+            type?: string;
+            types?: string[];
+            website?: string;
+            phone_number?: string;
+            opening_hours?: {
+                [key: string]: string;
+            };
+            thumbnail_url?: string;
+            place_id?: string;
+            cid?: string;
+            fid?: string;
+        };
+        PlacesResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["PlaceResult"][];
+            meta: components["schemas"]["Meta"];
+        };
+        ReviewResult: {
+            rating?: number;
+            date?: string;
+            iso_date?: string;
+            snippet?: string;
+            likes?: number;
+            user?: {
+                name?: string;
+                thumbnail?: string;
+                reviews?: number;
+            };
+            response?: {
+                snippet?: string;
+                date?: string;
+            };
+        };
+        ReviewsResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["ReviewResult"][];
+            /** @description Pass as `page_token` for the next page. Absent on the last page and at the 100-review depth limit */
+            next_page_token?: string;
+            meta: components["schemas"]["Meta"];
+        };
+        ShoppingResult: {
+            position: number;
+            title: string;
+            source?: string;
+            link?: string;
+            price?: string;
+            price_value?: number;
+            currency?: string;
+            delivery?: string;
+            image_url?: string;
+            rating?: number;
+            rating_count?: number;
+            offers?: string;
+            product_id?: string;
+        };
+        ShoppingResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["ShoppingResult"][];
+            meta: components["schemas"]["Meta"];
+        };
+        ScholarResult: {
+            position: number;
+            title: string;
+            link: string;
+            domain?: string;
+            publication_info?: string;
+            snippet?: string;
+            year?: number;
+            cited_by?: number;
+            pdf_url?: string;
+            id?: string;
+        };
+        ScholarResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["ScholarResult"][];
+            meta: components["schemas"]["Meta"];
+        };
+        PatentResult: {
+            position: number;
+            title: string;
+            snippet?: string;
+            link: string;
+            publication_number?: string;
+            priority_date?: string;
+            filing_date?: string;
+            grant_date?: string;
+            publication_date?: string;
+            inventor?: string;
+            assignee?: string;
+            language?: string;
+            pdf_url?: string;
+            thumbnail_url?: string;
+        };
+        PatentsResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["PatentResult"][];
+            meta: components["schemas"]["Meta"];
+        };
+        Suggestion: {
+            value: string;
+        };
+        AutocompleteResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["Suggestion"][];
+            meta: components["schemas"]["Meta"];
+        };
+        LensResult: {
+            position: number;
+            title: string;
+            source?: string;
+            link: string;
+            domain?: string;
+            image_url?: string;
+            thumbnail_url?: string;
+        };
+        LensResponse: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["LensResult"][];
+            meta: components["schemas"]["Meta"];
+        };
+        PageMetadata: {
+            title?: string;
+            description?: string;
+            language?: string;
+            canonical?: string;
+            site_name?: string;
+            image?: string;
+            published_time?: string;
+            author?: string;
+        };
+        WebpageResponse: {
+            request: components["schemas"]["RequestEcho"];
+            /** @description Final URL after redirects */
+            url: string;
+            status_code?: number;
+            markdown: string;
+            text?: string;
+            /** @description Only with include_html=true */
+            html?: string;
+            metadata: components["schemas"]["PageMetadata"];
+            meta: components["schemas"]["Meta"];
+        };
+        CSEResponse: {
+            /** @constant */
+            kind: "customsearch#search";
+            url?: Record<string, never>;
+            queries?: {
+                [key: string]: unknown;
+            };
+            context?: Record<string, never>;
+            searchInformation: {
+                searchTime?: number;
+                formattedSearchTime?: string;
+                totalResults?: string;
+                formattedTotalResults?: string;
+            };
+            items: {
+                /** @constant */
+                kind?: "customsearch#result";
+                title?: string;
+                htmlTitle?: string;
+                link?: string;
+                displayLink?: string;
+                snippet?: string;
+                htmlSnippet?: string;
+                formattedUrl?: string;
+                htmlFormattedUrl?: string;
+                pagemap?: {
+                    [key: string]: unknown;
+                };
+                image?: {
+                    [key: string]: unknown;
+                };
+            }[];
+        };
+        RankRequest: {
+            q: string;
+            /** @description Domain to find, e.g. "example.com" (subdomains match) */
+            domain: string;
+            /**
+             * @default 100
+             * @enum {integer}
+             */
+            num?: 10 | 20 | 30 | 50 | 100;
+            country?: string;
+            language?: string;
+            location?: string;
+            /** @enum {string} */
+            device?: "desktop" | "mobile";
+            max_age?: number;
+        };
+        RankResponse: {
+            request: components["schemas"]["RequestEcho"];
+            domain: string;
+            /** @description Best organic position */
+            position: number | null;
+            matches: {
+                position: number;
+                title: string;
+                link: string;
+            }[];
+            /** @description Organic results inspected */
+            checked: number;
+            meta: components["schemas"]["Meta"];
+        };
+        Status: {
+            /** @enum {string} */
+            status: "operational" | "degraded";
+            window_minutes: number;
+            /** Format: date-time */
+            updated_at: string;
+            endpoints: {
+                endpoint: string;
+                requests: number;
+                /** @description Share of requests without a 5xx (0-1) */
+                success_rate: number;
+                p50_ms: number;
+                p95_ms: number;
+            }[];
+        };
+        BatchCreateRequest: {
+            /** @enum {string} */
+            endpoint: "search" | "images" | "videos" | "news" | "maps" | "places" | "reviews" | "shopping" | "scholar" | "patents" | "autocomplete" | "lens" | "webpage";
+            /** @description Request bodies for `endpoint` (same fields as the realtime endpoint) */
+            requests: {
+                [key: string]: unknown;
+            }[];
+            /**
+             * Format: uri
+             * @description POSTed each job's result, always signed with X-SerpKite-Signature (v1=hex HMAC-SHA256 of `<timestamp>.<body>` with the account webhook secret; see createBatches). Defaults to the account webhook
+             */
+            webhook_url?: string;
+        };
+        BatchCreateResponse: {
+            batches: (components["schemas"]["Batch"] | components["schemas"]["Error"])[];
+        };
+        Batch: {
+            /** Format: uuid */
+            id: string;
+            /** @enum {string} */
+            status: "queued" | "running" | "done" | "failed";
+            /** @example /v1/search */
+            endpoint: string;
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            completed_at?: string | null;
+            credits_used?: number;
+            poll_url: string;
+            webhook_url?: string | null;
+            /** @enum {string|null} */
+            webhook_status?: "pending" | "delivered" | "failed" | null;
+            error?: {
+                code?: string;
+                message?: string;
+            } | null;
+            /** @description Present when done; kept 24h. The endpoint's response body, or {markdown, meta} for format=markdown jobs */
+            result?: {
+                [key: string]: unknown;
+            } | null;
+        };
+        Account: {
+            /** @description Negative after a refund of credits that were already spent; requests then get 402 insufficient_credits */
+            balance: number;
+            rate_limit_rps: number;
+            /** @enum {string} */
+            plan: "free" | "paid";
+            key?: {
+                id?: string;
+                name?: string;
+                credit_limit?: number | null;
+                credits_used_month?: number;
+            };
+            monthly_spend_cap?: number | null;
+            month: {
+                credits: number;
+                requests: number;
+            };
+        };
+    };
+    responses: {
+        /** @description Error */
+        Error: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /**
+         * @description Temporarily unavailable, not billed, safe to retry after `Retry-After`.
+         *     Codes: `upstream_error` (the upstream page couldn't be fetched or parsed),
+         *     `upstream_blocked` (the upstream is rate limiting us), `upstream_timeout`
+         *     (the search took too long), `unavailable` (endpoint or dependency down).
+         *     The API never sends 502 or 504.
+         */
+        Unavailable: {
+            headers: {
+                "Retry-After": components["headers"]["RetryAfter"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        SearchOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["SearchResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        ImagesOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ImagesResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        VideosOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["VideosResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        NewsOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["NewsResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        PlacesOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["PlacesResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        ReviewsOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ReviewsResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        ShoppingOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ShoppingResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        ScholarOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ScholarResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        PatentsOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["PatentsResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        AutocompleteOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["AutocompleteResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        LensOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["LensResponse"];
+                "text/markdown": string;
+            };
+        };
+        /** @description OK (text/markdown when format=markdown) */
+        WebpageOK: {
+            headers: {
+                "X-Credits-Used": components["headers"]["CreditsUsed"];
+                "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                "X-Cost-USD": components["headers"]["CostUSD"];
+                "X-Cache": components["headers"]["Cache"];
+                "X-Latency-Ms": components["headers"]["LatencyMs"];
+                "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["WebpageResponse"];
+                "text/markdown": string;
+            };
+        };
+    };
+    parameters: never;
+    requestBodies: {
+        Search: {
+            content: {
+                "application/json": components["schemas"]["SearchRequest"];
+            };
+        };
+    };
+    headers: {
+        CreditsUsed: number;
+        CreditsRemaining: number;
+        CostUSD: number;
+        Cache: "HIT" | "MISS";
+        LatencyMs: number;
+        TokensEstimate: number;
+        /** @description Seconds to wait before retrying */
+        RetryAfter: number;
+    };
+    pathItems: never;
+}
+interface operations {
+    searchGet: {
+        parameters: {
+            query: {
+                q: string;
+                country?: string;
+                language?: string;
+                location?: string;
+                num?: number;
+                page?: number;
+                uule?: string;
+                ll?: string;
+                time?: string;
+                tbs?: string;
+                device?: string;
+                safe?: string;
+                autocorrect?: boolean;
+                format?: string;
+                fields?: string;
+                include_content?: number;
+                ads?: boolean;
+                max_age?: number;
+                /** @description google (default), auto, consensus, one provider, or a comma-separated list (e.g. google,brave) */
+                engine?: string;
+                api_key?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: components["responses"]["SearchOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    search: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["SearchOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    images: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["ImagesOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    videos: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["VideosOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    news: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["NewsOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    maps: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["PlacesOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    places: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["PlacesOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    reviews: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ReviewsRequest"];
+            };
+        };
+        responses: {
+            200: components["responses"]["ReviewsOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    shopping: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["ShoppingOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    scholar: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["ScholarOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    patents: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["PatentsOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    autocomplete: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["Search"];
+        responses: {
+            200: components["responses"]["AutocompleteOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    lens: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["LensRequest"];
+            };
+        };
+        responses: {
+            200: components["responses"]["LensOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    webpage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["WebpageRequest"];
+            };
+        };
+        responses: {
+            200: components["responses"]["WebpageOK"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    customSearch: {
+        parameters: {
+            query: {
+                /** @description API key (or Authorization Bearer) */
+                key?: string;
+                /** @description Accepted and ignored */
+                cx?: string;
+                q: string;
+                start?: number;
+                num?: number;
+                gl?: string;
+                hl?: string;
+                lr?: string;
+                safe?: "active" | "off";
+                dateRestrict?: string;
+                siteSearch?: string;
+                searchType?: "image";
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description CSE-shaped response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CSEResponse"];
+                };
+            };
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    rank: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RankRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RankResponse"];
+                };
+            };
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    status: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Status"];
+                };
+            };
+        };
+    };
+    createBatches: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description 1-255 printable ASCII characters (e.g. a UUID). Retries with the same key and body replay the first response for 24 h */
+                "Idempotency-Key"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["BatchCreateRequest"];
+            };
+        };
+        responses: {
+            /** @description Queued. One entry per request, in order; an entry is a batch job or an error object */
+            202: {
+                headers: {
+                    /** @description `true` when this is the stored response of an earlier call with the same Idempotency-Key */
+                    "Idempotent-Replayed"?: "true";
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BatchCreateResponse"];
+                };
+            };
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            409: components["responses"]["Error"];
+            422: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    getBatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Batch"];
+                };
+            };
+            401: components["responses"]["Error"];
+            404: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+        };
+    };
+    account: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Account"];
+                };
+            };
+            401: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+        };
+    };
+    playground: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SearchRequest"] & {
+                    /**
+                     * @default search
+                     * @enum {string}
+                     */
+                    endpoint?: "search" | "news" | "images" | "autocomplete";
+                    /** @description Cloudflare Turnstile token, required when the server enforces Turnstile. Single-use: get a fresh one for every request */
+                    turnstile_token?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Same body as the corresponding endpoint */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            400: components["responses"]["Error"];
+            /** @description Bot check failed (missing, spent or foreign Turnstile token) or the Origin is not one of our sites */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            429: components["responses"]["Error"];
+        };
+    };
+    mcp: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    [key: string]: unknown;
+                };
+            };
+        };
+        responses: {
+            /** @description JSON-RPC response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Notification accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Error"];
+        };
+    };
+}
+
+type Schemas = components["schemas"];
+/** A search provider that can answer a request. `meta.engine` names the one that did. */
+type Provider = Schemas["Provider"];
+/**
+ * Which search providers may answer (`engine` param):
+ * - `"google"` (default): Google only.
+ * - `"auto"`: fall back to other enabled providers when Google is blocked or times out.
+ * - `"consensus"` (`search` only): several independent indexes in parallel, merged by URL and
+ *   ranked by agreement; each result lists its `sources`, `meta.engine` is `"consensus"`, and
+ *   it costs the sum of one page per provider that returned results.
+ * - a single provider (`"brave"`) or a list (`["google", "brave"]`): only those, in order.
+ *
+ * `auto` and `consensus` can't be combined with other names. Unknown names, or a provider
+ * that doesn't serve the endpoint, are a 400 `invalid_request`. Plain strings stay accepted
+ * so a provider added to the API before this SDK is updated still type-checks.
+ */
+type Engine = "google" | "auto" | "consensus" | Provider | Provider[] | (string & {});
+/** One provider attempt in `meta.route`. */
+type RouteStep = Schemas["RouteStep"];
+type RouteOutcome = RouteStep["outcome"];
+/** Parameters for search, images, videos, news, maps, places, shopping, scholar, patents and autocomplete. */
+type SearchParams = Omit<Schemas["SearchRequest"], "engine"> & {
+    /** Search providers allowed to answer. Default `"google"`. See {@link Engine}. */
+    engine?: Engine;
+};
+type ReviewsParams = Schemas["ReviewsRequest"];
+type LensParams = Schemas["LensRequest"];
+type WebpageParams = Schemas["WebpageRequest"];
+type RankParams = Schemas["RankRequest"];
+/** `format` values accepted by the verticals. */
+type Format = NonNullable<SearchParams["format"]>;
+type Meta = Schemas["Meta"];
+type RequestEcho = Schemas["RequestEcho"];
+type ErrorBody = Schemas["Error"];
+type OrganicResult = Schemas["OrganicResult"];
+type Sitelink = Schemas["Sitelink"];
+type AnswerBox = Schemas["AnswerBox"];
+type KnowledgeGraph = Schemas["KnowledgeGraph"];
+type PeopleAlsoAsk = Schemas["PeopleAlsoAsk"];
+type RelatedSearch = Schemas["RelatedSearch"];
+type ImageResult = Schemas["ImageResult"];
+type VideoResult = Schemas["VideoResult"];
+type NewsResult = Schemas["NewsResult"];
+type PlaceResult = Schemas["PlaceResult"];
+type ReviewResult = Schemas["ReviewResult"];
+type ShoppingResult = Schemas["ShoppingResult"];
+type ScholarResult = Schemas["ScholarResult"];
+type PatentResult = Schemas["PatentResult"];
+type Suggestion = Schemas["Suggestion"];
+type LensResult = Schemas["LensResult"];
+type PageMetadata = Schemas["PageMetadata"];
+type RankMatch = Schemas["RankResponse"]["matches"][number];
+type SearchResponse = Schemas["SearchResponse"];
+type ImagesResponse = Schemas["ImagesResponse"];
+type VideosResponse = Schemas["VideosResponse"];
+type NewsResponse = Schemas["NewsResponse"];
+/** Returned by both `maps` and `places`. */
+type PlacesResponse = Schemas["PlacesResponse"];
+type MapsResponse = PlacesResponse;
+type ReviewsResponse = Schemas["ReviewsResponse"];
+type ShoppingResponse = Schemas["ShoppingResponse"];
+type ScholarResponse = Schemas["ScholarResponse"];
+type PatentsResponse = Schemas["PatentsResponse"];
+type AutocompleteResponse = Schemas["AutocompleteResponse"];
+type LensResponse = Schemas["LensResponse"];
+type WebpageResponse = Schemas["WebpageResponse"];
+type RankResponse = Schemas["RankResponse"];
+type Account = Schemas["Account"];
+type Status = Schemas["Status"];
+/**
+ * `format: "compact"` returns a token-lean object: short snippets, no
+ * thumbnails or positions. Its keys depend on the vertical.
+ */
+interface CompactResponse {
+    results?: Record<string, unknown>[];
+    meta: Meta;
+    [key: string]: unknown;
+}
+type Batch = Schemas["Batch"];
+type BatchStatus = Batch["status"];
+type BatchEndpoint = Schemas["BatchCreateRequest"]["endpoint"];
+/** An entry of `batches.create` that could not be queued. */
+type BatchCreateError = ErrorBody & {
+    id?: never;
+    status?: never;
+};
+/** One entry per submitted request, in order: a queued job or an error. */
+type BatchCreateEntry = Batch | BatchCreateError;
+interface BatchCreateResponse {
+    batches: BatchCreateEntry[];
+}
+type BatchRequestMap = {
+    search: SearchParams;
+    images: SearchParams;
+    videos: SearchParams;
+    news: SearchParams;
+    maps: SearchParams;
+    places: SearchParams;
+    reviews: ReviewsParams;
+    shopping: SearchParams;
+    scholar: SearchParams;
+    patents: SearchParams;
+    autocomplete: SearchParams;
+    lens: LensParams;
+    webpage: WebpageParams;
+};
+/** Body of `POST /v1/batches`. `requests` takes the same fields as the realtime endpoint. */
+type BatchCreateParams = {
+    [E in BatchEndpoint]: {
+        endpoint: E;
+        /** 1-100 request bodies. */
+        requests: BatchRequestMap[E][];
+        /** Receives each job's result (signed with X-SerpKite-Signature). Defaults to the account webhook. */
+        webhook_url?: string;
+    };
+}[BatchEndpoint];
+
+declare const VERSION = "0.2.0";
+declare const DEFAULT_BASE_URL = "https://api.serpkite.com";
+interface SerpKiteOptions {
+    /** API key (`skt_live_…`). Defaults to the `SERPKITE_API_KEY` environment variable. */
+    apiKey?: string;
+    /** Defaults to `SERPKITE_BASE_URL` or https://api.serpkite.com. */
+    baseUrl?: string;
+    /** Per-attempt timeout in milliseconds. Default 60000. */
+    timeoutMs?: number;
+    /** Retries after the first attempt on 429, 5xx and network errors. Default 2. */
+    maxRetries?: number;
+    /** Base delay of the exponential backoff in milliseconds. Default 500. */
+    retryDelayMs?: number;
+    /** Custom fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+}
+/** Billing and tracing details from the response headers. */
+interface ResponseInfo {
+    status: number;
+    headers: Headers;
+    requestId: string | undefined;
+    creditsUsed: number | undefined;
+    creditsRemaining: number | undefined;
+    costUsd: number | undefined;
+    /** `HIT` when served from cache (`max_age`), else `MISS`. */
+    cache: "HIT" | "MISS" | undefined;
+    latencyMs: number | undefined;
+    tokensEstimate: number | undefined;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+    /** Overrides the client's per-attempt timeout. */
+    timeoutMs?: number;
+    /** Overrides the client's retry count. */
+    maxRetries?: number;
+    headers?: Record<string, string>;
+    /** Called with the final response's headers (credits used/remaining, cache, request id). */
+    onResponse?: (info: ResponseInfo) => void;
+}
+interface BatchCreateOptions extends RequestOptions {
+    /**
+     * Sent as `Idempotency-Key` (1-255 printable ASCII characters, e.g. a UUID).
+     * For 24 hours a retry with the same key and body returns the first response
+     * instead of queueing and billing the jobs again.
+     */
+    idempotencyKey?: string;
+}
+interface WaitOptions {
+    /** Give up after this many milliseconds. Default 600000 (10 minutes). */
+    timeoutMs?: number;
+    /** First delay between polls. Default 1000. Grows 1.5× per poll. */
+    pollIntervalMs?: number;
+    /** Upper bound of the delay between polls. Default 10000. */
+    maxPollIntervalMs?: number;
+    signal?: AbortSignal;
+}
+/** A vertical whose return type follows `format`: `"markdown"` → string, `"compact"` → CompactResponse. */
+interface VerticalMethod<P, R> {
+    (params: P & {
+        format: "markdown";
+    }, options?: RequestOptions): Promise<string>;
+    (params: P & {
+        format: "compact";
+    }, options?: RequestOptions): Promise<CompactResponse>;
+    (params: P & {
+        format?: "json";
+    }, options?: RequestOptions): Promise<R>;
+    (params: P, options?: RequestOptions): Promise<R | CompactResponse | string>;
+}
+type Method = "GET" | "POST";
+interface Call {
+    method: Method;
+    path: string;
+    body?: unknown;
+    options?: RequestOptions;
+    /** Which failures are safe to retry. `all` = 429, 5xx and network errors. */
+    retry?: "all" | "rate_limit";
+}
+declare class SerpKite {
+    #private;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly retryDelayMs: number;
+    constructor(options?: SerpKiteOptions);
+    /** Google web search: organic results, answer box, knowledge graph, people also ask… */
+    readonly search: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["OrganicResult"][];
+        answer_box?: components["schemas"]["AnswerBox"];
+        knowledge_graph?: components["schemas"]["KnowledgeGraph"];
+        ads?: components["schemas"]["OrganicResult"][];
+        people_also_ask?: components["schemas"]["PeopleAlsoAsk"][];
+        related_searches: components["schemas"]["RelatedSearch"][];
+        top_stories?: components["schemas"]["NewsResult"][];
+        places?: components["schemas"]["PlaceResult"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google Images. */
+    readonly images: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["ImageResult"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google Videos. */
+    readonly videos: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["VideoResult"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google News. */
+    readonly news: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["NewsResult"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google Maps search (places with coordinates). Accepts `ll` ("@lat,lng,14z"). */
+    readonly maps: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["PlaceResult"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google local results. */
+    readonly places: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["PlaceResult"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Reviews of a place by `place_id`, `cid` or `fid`. Page with `page_token` = `next_page_token`. */
+    readonly reviews: VerticalMethod<{
+        place_id?: string;
+        cid?: string;
+        fid?: string;
+        country?: string;
+        language?: string;
+        sort?: "most_relevant" | "newest" | "highest_rating" | "lowest_rating";
+        page_token?: string;
+        num?: number;
+        format?: "json" | "markdown" | "compact";
+        fields?: string;
+        max_age?: number;
+    }, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["ReviewResult"][];
+        next_page_token?: string;
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google Shopping. */
+    readonly shopping: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["ShoppingResult"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google Scholar. */
+    readonly scholar: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["ScholarResult"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google Patents. */
+    readonly patents: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["PatentResult"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google autocomplete suggestions. */
+    readonly autocomplete: VerticalMethod<SearchParams, {
+        request: components["schemas"]["RequestEcho"];
+        results: components["schemas"]["Suggestion"][];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Fetch any public URL as clean Markdown plus metadata. */
+    readonly webpage: VerticalMethod<{
+        url: string;
+        format?: "json" | "markdown" | "compact";
+        include_html?: boolean;
+        max_age?: number;
+    }, {
+        request: components["schemas"]["RequestEcho"];
+        url: string;
+        status_code?: number;
+        markdown: string;
+        text?: string;
+        html?: string;
+        metadata: components["schemas"]["PageMetadata"];
+        meta: components["schemas"]["Meta"];
+    }>;
+    /** Google Lens visual matches for an image URL. */
+    lens(params: LensParams, options?: RequestOptions): Promise<LensResponse>;
+    /** Position of `domain` for keyword `q` in the top `num` results (default 100). */
+    rank(params: RankParams, options?: RequestOptions): Promise<RankResponse>;
+    /** Balance, limits and this month's usage for the key's account. */
+    account(options?: RequestOptions): Promise<Account>;
+    readonly batches: {
+        /**
+         * Queue 1-100 requests for one endpoint at half price. Returns one entry per
+         * request, in order: a queued `Batch` or an error object. Without an
+         * `idempotencyKey` it is only retried on 429, so a lost response never queues
+         * (and bills) the same requests twice. With one, 5xx and network errors are
+         * retried too: the server replays the first response for the same key and body.
+         */
+        create: (params: BatchCreateParams, options?: BatchCreateOptions) => Promise<BatchCreateResponse>;
+        /** Poll one batch job. */
+        get: (id: string, options?: RequestOptions) => Promise<Batch>;
+        /**
+         * Poll until the job is `done` or `failed` and return it (a failed job is
+         * returned, not thrown; check `status` and `error`). Accepts an id or an
+         * entry from `create`; an entry that failed to queue throws its error.
+         */
+        wait: (idOrEntry: string | BatchCreateEntry | undefined, options?: WaitOptions) => Promise<{
+            id: string;
+            status: "queued" | "running" | "done" | "failed";
+            endpoint: string;
+            created_at: string;
+            completed_at?: string | null;
+            credits_used?: number;
+            poll_url: string;
+            webhook_url?: string | null;
+            webhook_status?: "pending" | "delivered" | "failed" | null;
+            error?: {
+                code?: string;
+                message?: string;
+            } | null;
+            result?: {
+                [key: string]: unknown;
+            } | null;
+        }>;
+    };
+    /** Low-level request: JSON body in, parsed JSON (or text for non-JSON responses) out. */
+    request<T>(call: Call): Promise<T>;
+}
+/** Parses Retry-After (seconds or an HTTP date) into milliseconds. */
+declare function parseRetryAfter(v: string | null): number | undefined;
+
+/**
+ * Every failure thrown by the SDK. API errors carry the fields of the
+ * `{"error":{"code","message","request_id"}}` envelope; network failures and
+ * timeouts use `status: 0` with code `connection_error` or `timeout`.
+ */
+declare class SerpKiteError extends Error {
+    /** HTTP status, or 0 when no response was received. */
+    readonly status: number;
+    /** Machine-readable code, e.g. `unauthorized`, `insufficient_credits`, `rate_limited`. */
+    readonly code: string;
+    /** `X-Request-Id` of the failed request, when the API returned one. */
+    readonly requestId: string | undefined;
+    /** Response headers, when the API responded. */
+    readonly headers: Headers | undefined;
+    constructor(status: number, code: string, message: string, requestId?: string, headers?: Headers, options?: {
+        cause?: unknown;
+    });
+}
+
+/** True when a `batches.create` entry was rejected instead of queued. */
+declare function isBatchError(entry: BatchCreateEntry): entry is BatchCreateError;
+
+/** Options for {@link verifyWebhook}. */
+interface VerifyWebhookOptions {
+    /** Reject deliveries whose timestamp is further than this from now. Default 300. */
+    toleranceSeconds?: number;
+    /** Current time in Unix seconds (tests). */
+    now?: number;
+}
+type HeaderSource = Headers | Record<string, string | string[] | undefined>;
+/**
+ * Checks a batch webhook delivery: `X-SerpKite-Signature` must be
+ * `v1=<hex HMAC-SHA256(secret, "<X-SerpKite-Timestamp>.<raw body>")>` and the
+ * timestamp recent. Pass the raw request body exactly as received (not
+ * re-serialised JSON). Uses Web Crypto (Node 18+, Deno, Bun, browsers).
+ *
+ * ```ts
+ * const ok = await verifyWebhook(process.env.SERPKITE_WEBHOOK_SECRET!, rawBody, req.headers);
+ * ```
+ */
+declare function verifyWebhook(secret: string, payload: string | Uint8Array, headers: HeaderSource, options?: VerifyWebhookOptions): Promise<boolean>;
+
+export { type Account, type AnswerBox, type AutocompleteResponse, type Batch, type BatchCreateEntry, type BatchCreateError, type BatchCreateOptions, type BatchCreateParams, type BatchCreateResponse, type BatchEndpoint, type BatchStatus, type CompactResponse, DEFAULT_BASE_URL, type Engine, type ErrorBody, type Format, type ImageResult, type ImagesResponse, type KnowledgeGraph, type LensParams, type LensResponse, type LensResult, type MapsResponse, type Meta, type NewsResponse, type NewsResult, type OrganicResult, type PageMetadata, type PatentResult, type PatentsResponse, type PeopleAlsoAsk, type PlaceResult, type PlacesResponse, type Provider, type RankMatch, type RankParams, type RankResponse, type RelatedSearch, type RequestEcho, type RequestOptions, type ResponseInfo, type ReviewResult, type ReviewsParams, type ReviewsResponse, type RouteOutcome, type RouteStep, type ScholarResponse, type ScholarResult, type SearchParams, type SearchResponse, SerpKite, SerpKiteError, type SerpKiteOptions, type ShoppingResponse, type ShoppingResult, type Sitelink, type Status, type Suggestion, VERSION, type VerifyWebhookOptions, type VerticalMethod, type VideoResult, type VideosResponse, type WaitOptions, type WebpageParams, type WebpageResponse, type components, isBatchError, type operations, parseRetryAfter, type paths, verifyWebhook };