serpkite 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -156,7 +156,17 @@ interface paths {
         };
         get?: never;
         put?: never;
-        /** Google Maps search (places with coordinates). Accepts `ll` ("@lat,lng,zoomz") to search around a point */
+        /**
+         * Google Maps search (places with coordinates). Accepts `ll` ("@lat,lng,zoomz") to search around a point
+         * @description Google Maps search results: name, full address, coordinates, categories, rating, website,
+         *     phone, opening hours and the place's identifiers (`place_id`, `cid`, `fid`) for
+         *     `/v1/place` and `/v1/reviews`. Categories, addresses and hours are in `language`.
+         *
+         *     **Where:** `ll` ("@lat,lng,zoomz") searches the map at that point and zoom; `location`
+         *     (or `uule`) searches the named place. Without either, Google picks the area from the
+         *     query (an exact name or address) or from where the request comes from, so local queries
+         *     such as "coffee" need `location` or `ll`.
+         */
         post: operations["maps"];
         delete?: never;
         options?: never;
@@ -173,7 +183,10 @@ interface paths {
         };
         get?: never;
         put?: never;
-        /** Google local results (places) */
+        /**
+         * Google local results (places)
+         * @description Same results as `/v1/maps` (Google Maps search), with the same fields and location rules.
+         */
         post: operations["places"];
         delete?: never;
         options?: never;
@@ -181,6 +194,29 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/place": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Details of one place (by `place_id`, `cid` or `fid`); 1 credit
+         * @description The full Google Maps listing of one place: address, country, coordinates, time zone,
+         *     categories, opening hours (as text and as structured `weekly_hours`), website, phone,
+         *     rating, description and photos, in `language`. `results` holds the place, or is empty
+         *     (not charged) when no place has that identifier.
+         */
+        post: operations["place"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/reviews": {
         parameters: {
             query?: never;
@@ -639,7 +675,15 @@ interface paths {
         };
         get?: never;
         put?: never;
-        /** Remote MCP server (streamable HTTP, JSON-RPC 2.0). Tools search, news, maps, scholar, webpage */
+        /**
+         * Remote MCP server (streamable HTTP, JSON-RPC 2.0). Tools search, news, maps, place, scholar, webpage
+         * @description Authenticates with an API key (`Authorization: Bearer skt_live_…`) or an
+         *     OAuth 2.1 access token (`skt_oat_…`) issued by app-api.serpkite.com for
+         *     this resource (MCP authorization spec). Without a valid credential the
+         *     401 carries `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/v1/mcp", scope="mcp"`
+         *     (plus `error="invalid_token"` when a credential was rejected). OAuth
+         *     access tokens are only accepted here, not on the REST endpoints.
+         */
         post: operations["mcp"];
         delete?: never;
         options?: never;
@@ -647,6 +691,40 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/.well-known/oauth-protected-resource/v1/mcp": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** OAuth protected resource metadata for the MCP server (RFC 9728) */
+        get: operations["mcpProtectedResourceMetadata"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/.well-known/oauth-protected-resource": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** OAuth protected resource metadata (root form; same document) */
+        get: operations["protectedResourceMetadata"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 interface components {
     schemas: {
@@ -675,6 +753,25 @@ interface components {
                 request_id?: string;
             };
         };
+        /** @description RFC 9728 protected resource metadata */
+        ProtectedResourceMetadata: {
+            /**
+             * Format: uri
+             * @example https://api.serpkite.com/v1/mcp
+             */
+            resource: string;
+            /**
+             * @example [
+             *       "https://app-api.serpkite.com"
+             *     ]
+             */
+            authorization_servers: string[];
+            scopes_supported?: string[];
+            bearer_methods_supported?: string[];
+            resource_name?: string;
+            /** Format: uri */
+            resource_documentation?: string;
+        };
         SearchRequest: {
             q: string;
             /**
@@ -691,7 +788,7 @@ interface components {
             location?: string;
             /** @description Pre-encoded Google location (overrides ll and location; percent-encoded values are decoded) */
             uule?: string;
-            /** @description Map point "@lat,lng,14z" (maps and places only; zoom optional): the search runs as a searcher at that point. Overrides location */
+            /** @description Map point "@lat,lng,14z" (maps and places only; zoom optional, default 14z): the map is searched around that point at that zoom, wherever the request comes from. Overrides location */
             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
@@ -779,14 +876,15 @@ interface components {
             country?: string;
             language?: string;
             /**
+             * @description Only `most_relevant` is served: Google Maps shows other review orders only to signed-in visitors, so `newest`, `highest_rating` and `lowest_rating` return 400 (not charged).
              * @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. */
+            /** @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 10 reviews of a place, all Google Maps shows a logged-out visitor. */
             page_token?: string;
             /**
-             * @description Reviews per page (a page can be shorter when Google stops loading early; `next_page_token` then resumes after it)
+             * @description Reviews per page; a page holds at most 10 (the first 10 reviews of a place). A page can be shorter when Google stops loading early; `next_page_token` then resumes after it
              * @default 10
              */
             num?: number;
@@ -795,6 +893,34 @@ interface components {
             fields?: string;
             max_age?: number;
         };
+        /** @description One of place_id, cid or fid is required (place_id wins, then fid, then cid) */
+        PlaceRequest: {
+            /** @description Google place id ("ChIJ…"), e.g. `place_id` of a /v1/maps result */
+            place_id?: string;
+            /** @description Decimal customer id (`cid` of a result) */
+            cid?: string;
+            /** @description Feature id "0x…:0x…" (`fid` of a result) */
+            fid?: string;
+            /**
+             * @description Country code (ISO 3166-1 alpha-2); Google's regional view of the listing
+             * @default us
+             */
+            country?: string;
+            /**
+             * @description Language of the address, categories, hours and description (e.g. en, ru, de)
+             * @default en
+             */
+            language?: string;
+            /**
+             * @default json
+             * @enum {string}
+             */
+            format?: "json" | "markdown" | "compact";
+            fields?: string;
+            /** @description Accept a cached result up to this many seconds old (50% of credits on a hit) */
+            max_age?: number;
+            engine?: components["schemas"]["EngineParam"];
+        };
         WebpageRequest: {
             /**
              * Format: uri
@@ -1351,14 +1477,63 @@ interface components {
             types?: string[];
             website?: string;
             phone_number?: string;
+            /** @example +44 20 7232 3010 */
+            international_phone_number?: string;
+            /** @description Hours as Google displays them, keyed by English weekday (Monday … Sunday), in `language`, e.g. {"Monday": "7:30 am–6 pm", "Sunday": "Closed"} */
             opening_hours?: {
                 [key: string]: string;
             };
+            weekly_hours?: components["schemas"]["WeeklyHours"];
+            /** @description ISO 3166-1 alpha-2 country code of the place, upper case (RU, GB) */
+            country?: string;
+            /** @description IANA time zone of the place (Europe/Moscow) */
+            timezone?: string;
+            /** @description Google's short description of the place, or the owner's, when Google shows one */
+            description?: string;
+            /** @description Photos of the place (/v1/place; up to 10). The URLs are public and can be fetched server-side without cookies */
+            photos?: components["schemas"]["PlacePhoto"][];
+            /** @description The place on Google Maps */
+            google_maps_url?: string;
             thumbnail_url?: string;
             place_id?: string;
             cid?: string;
             fid?: string;
         };
+        /**
+         * @description Opening hours per weekday, from Google's listing, as local times (`timezone`) in 24-hour HH:MM.
+         *     A day that is closed is an empty list; a day open 24 hours is `[{"open": "00:00", "close": "24:00"}]`;
+         *     a day with a break has several intervals. `close` is "24:00" at midnight, and an interval that
+         *     ends after midnight has `next_day: true` (e.g. 17:30–03:00). Days Google doesn't list are absent.
+         */
+        WeeklyHours: {
+            monday?: components["schemas"]["HoursIntervals"];
+            tuesday?: components["schemas"]["HoursIntervals"];
+            wednesday?: components["schemas"]["HoursIntervals"];
+            thursday?: components["schemas"]["HoursIntervals"];
+            friday?: components["schemas"]["HoursIntervals"];
+            saturday?: components["schemas"]["HoursIntervals"];
+            sunday?: components["schemas"]["HoursIntervals"];
+        };
+        HoursIntervals: components["schemas"]["HoursInterval"][];
+        HoursInterval: {
+            /** @example 08:00 */
+            open: string;
+            /** @example 22:00 */
+            close: string;
+            /** @description The interval closes after midnight, on the next day */
+            next_day?: boolean;
+        };
+        PlacePhoto: {
+            /** @description Image URL (at most 1600 px on the long side) */
+            url: string;
+            width?: number;
+            height?: number;
+            /**
+             * @description Who uploaded it, when Google says (Google shows no contributor names to logged-out visitors)
+             * @enum {string}
+             */
+            source?: "business" | "visitor";
+        };
         PlacesResponse: {
             request: components["schemas"]["RequestEcho"];
             results: components["schemas"]["PlaceResult"][];
@@ -1567,13 +1742,15 @@ interface components {
                 requests: number;
                 /** @description Share of requests without a 5xx (0-1) */
                 success_rate: number;
+                /** @description Median latency of successful (non-error) responses; 0 when none succeeded */
                 p50_ms: number;
+                /** @description 95th-percentile latency of successful (non-error) responses; 0 when none succeeded */
                 p95_ms: number;
             }[];
         };
         BatchCreateRequest: {
             /** @enum {string} */
-            endpoint: "search" | "images" | "videos" | "news" | "maps" | "places" | "reviews" | "shopping" | "scholar" | "patents" | "autocomplete" | "webpage";
+            endpoint: "search" | "images" | "videos" | "news" | "maps" | "places" | "place" | "reviews" | "shopping" | "scholar" | "patents" | "autocomplete" | "webpage";
             /** @description Request bodies for `endpoint` (same fields as the realtime endpoint) */
             requests: {
                 [key: string]: unknown;
@@ -2393,6 +2570,28 @@ interface operations {
             503: components["responses"]["Unavailable"];
         };
     };
+    place: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PlaceRequest"];
+            };
+        };
+        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;
@@ -3096,7 +3295,57 @@ interface operations {
                 };
                 content?: never;
             };
-            401: components["responses"]["Error"];
+            /** @description Missing, invalid, expired or revoked credential */
+            401: {
+                headers: {
+                    /** @description RFC 9728 challenge pointing at the protected resource metadata */
+                    "WWW-Authenticate"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    mcpProtectedResourceMetadata: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Metadata */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProtectedResourceMetadata"];
+                };
+            };
+        };
+    };
+    protectedResourceMetadata: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Metadata */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProtectedResourceMetadata"];
+                };
+            };
         };
     };
     crawlCompletedWebhook: {
@@ -3171,6 +3420,11 @@ type SearchParams = Omit<Schemas["SearchRequest"], "engine"> & {
     engine?: Engine;
 };
 type ReviewsParams = Schemas["ReviewsRequest"];
+/** Parameters of `place`: one of `place_id`, `cid` or `fid` (place_id wins, then fid, then cid). */
+type PlaceParams = Omit<Schemas["PlaceRequest"], "engine"> & {
+    /** Search providers allowed to answer. Default `"google"`. See {@link Engine}. */
+    engine?: Engine;
+};
 type WebpageParams = Schemas["WebpageRequest"];
 type RankParams = Schemas["RankRequest"];
 type MapParams = Schemas["MapRequest"];
@@ -3190,6 +3444,16 @@ type ImageResult = Schemas["ImageResult"];
 type VideoResult = Schemas["VideoResult"];
 type NewsResult = Schemas["NewsResult"];
 type PlaceResult = Schemas["PlaceResult"];
+/**
+ * Opening hours per weekday (`monday` … `sunday`) as local 24-hour `HH:MM` intervals: a closed
+ * day is `[]`, a day open 24 hours `[{ open: "00:00", close: "24:00" }]`. Days Google doesn't
+ * list are absent.
+ */
+type WeeklyHours = Schemas["WeeklyHours"];
+/** One opening interval; `next_day` when it closes after midnight. */
+type HoursInterval = Schemas["HoursInterval"];
+/** A photo of a place (`place`; up to 10). */
+type PlacePhoto = Schemas["PlacePhoto"];
 type ReviewResult = Schemas["ReviewResult"];
 type ShoppingResult = Schemas["ShoppingResult"];
 type ScholarResult = Schemas["ScholarResult"];
@@ -3210,7 +3474,7 @@ type SearchResponse = Schemas["SearchResponse"];
 type ImagesResponse = Schemas["ImagesResponse"];
 type VideosResponse = Schemas["VideosResponse"];
 type NewsResponse = Schemas["NewsResponse"];
-/** Returned by both `maps` and `places`. */
+/** Returned by `maps`, `places` and `place`. */
 type PlacesResponse = Schemas["PlacesResponse"];
 type MapsResponse = PlacesResponse;
 type ReviewsResponse = Schemas["ReviewsResponse"];
@@ -3253,6 +3517,7 @@ type BatchRequestMap = {
     news: SearchParams;
     maps: SearchParams;
     places: SearchParams;
+    place: PlaceParams;
     reviews: ReviewsParams;
     shopping: SearchParams;
     scholar: SearchParams;
@@ -3365,7 +3630,7 @@ type WebhookEvent = {
     data: MonitorResultsEvent;
 };
 
-declare const VERSION = "0.4.0";
+declare const VERSION = "0.5.0";
 declare const DEFAULT_BASE_URL = "https://api.serpkite.com";
 interface SerpKiteOptions {
     /** API key (`skt_live_…`). Defaults to the `SERPKITE_API_KEY` environment variable. */
@@ -3498,6 +3763,16 @@ declare class SerpKite {
         results: components["schemas"]["PlaceResult"][];
         meta: components["schemas"]["Meta"];
     }>;
+    /**
+     * Details of one place by `place_id`, `cid` or `fid`: address, country, time zone, hours
+     * (`opening_hours` text and structured `weekly_hours`), phones, description and photos.
+     * `results` holds the place, or is empty (not charged) when no place has that id. 1 credit.
+     */
+    readonly place: VerticalMethod<PlaceParams, {
+        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;
@@ -3744,4 +4019,4 @@ declare function verifyWebhook(secret: string, payload: string | Uint8Array, hea
  */
 declare function parseWebhook(secret: string, payload: string | Uint8Array, headers: HeaderSource, options?: VerifyWebhookOptions): Promise<WebhookEvent>;
 
-export { type Account, type AnswerBox, type AutocompleteResponse, type Batch, type BatchCompletedEvent, type BatchCreateEntry, type BatchCreateError, type BatchCreateOptions, type BatchCreateParams, type BatchCreateResponse, type BatchEndpoint, type BatchStatus, type CompactResponse, type CrawlPage, type CrawlParams, type CrawlResult, type CrawlSitemapMode, type CrawlStats, type CrawlStopReason, type CrawlTask, DEFAULT_BASE_URL, type DomainList, type Engine, type ErrorBody, type ExtractFailure, type ExtractParams, type ExtractResponse, type ExtractResult, type Format, type Highlight, type ImageResult, type ImagesResponse, type KnowledgeGraph, type MapParams, type MapResponse, type MapURL, type MapsResponse, type Meta, type Monitor, type MonitorCreateParams, type MonitorEndpoint, type MonitorList, type MonitorMetadata, type MonitorPageChange, type MonitorResultsEvent, type MonitorRun, type MonitorRunList, type MonitorRunsParams, type MonitorSearch, type MonitorStatus, type MonitorUpdateParams, type NewsResponse, type NewsResult, type OrganicResult, type PageLink, 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, type TaskCancelResponse, type TaskCompletedEvent, type TaskCreated, type TaskError, type TaskStatus, VERSION, type VerifyWebhookOptions, type VerticalMethod, type VideoResult, type VideosResponse, type WaitOptions, type WebhookEvent, type WebhookEventType, type WebpageParams, type WebpageResponse, type components, isBatchError, type operations, parseRetryAfter, parseWebhook, type paths, verifyWebhook };
+export { type Account, type AnswerBox, type AutocompleteResponse, type Batch, type BatchCompletedEvent, type BatchCreateEntry, type BatchCreateError, type BatchCreateOptions, type BatchCreateParams, type BatchCreateResponse, type BatchEndpoint, type BatchStatus, type CompactResponse, type CrawlPage, type CrawlParams, type CrawlResult, type CrawlSitemapMode, type CrawlStats, type CrawlStopReason, type CrawlTask, DEFAULT_BASE_URL, type DomainList, type Engine, type ErrorBody, type ExtractFailure, type ExtractParams, type ExtractResponse, type ExtractResult, type Format, type Highlight, type HoursInterval, type ImageResult, type ImagesResponse, type KnowledgeGraph, type MapParams, type MapResponse, type MapURL, type MapsResponse, type Meta, type Monitor, type MonitorCreateParams, type MonitorEndpoint, type MonitorList, type MonitorMetadata, type MonitorPageChange, type MonitorResultsEvent, type MonitorRun, type MonitorRunList, type MonitorRunsParams, type MonitorSearch, type MonitorStatus, type MonitorUpdateParams, type NewsResponse, type NewsResult, type OrganicResult, type PageLink, type PageMetadata, type PatentResult, type PatentsResponse, type PeopleAlsoAsk, type PlaceParams, type PlacePhoto, 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, type TaskCancelResponse, type TaskCompletedEvent, type TaskCreated, type TaskError, type TaskStatus, VERSION, type VerifyWebhookOptions, type VerticalMethod, type VideoResult, type VideosResponse, type WaitOptions, type WebhookEvent, type WebhookEventType, type WebpageParams, type WebpageResponse, type WeeklyHours, type components, isBatchError, type operations, parseRetryAfter, parseWebhook, type paths, verifyWebhook };