googlemaps-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kumar Vandit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# googlemaps-kit
+
+> TypeScript SDK for programmatic access to Google Maps consumer surfaces.
+
+[![npm version](https://img.shields.io/npm/v/googlemaps-kit.svg)](https://www.npmjs.com/package/googlemaps-kit)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](./package.json)
+
+## Overview
+
+Service-based client for search, places, reviews, directions, photos, geocoding, tiles,
+and more. Calls the same HTTP endpoints the Maps web app uses. **No Maps Platform API
+key. No browser or Playwright dependency** — plain `fetch` via Node (`undici`) with
+browser-like headers and an automatically warmed anonymous cookie jar.
+
+## Disclaimer
+
+Not an official Google product. Endpoints are undocumented and can change, throttle, or
+block without notice. Intended for research and personal tooling, not bulk scraping.
+
+## How it works
+
+1. **Session bootstrap** — On first use, the client fetches Google/Maps HTML over HTTP and
+   stores anonymous cookies (for example `NID`, `AEC`). See `src/auth/session.ts`.
+2. **API calls** — Services build request URLs and protobuf payloads, then parse JSON
+   responses into typed results.
+3. **No headless browser** — Chromium/Playwright is not used at runtime. The only
+   exception is `passiveAssist`, which needs a viewport `psi` token you obtain outside
+   the SDK (for example from a browser session you control).
+
+## Features
+
+### Search and places
+
+| Feature | Method | Example |
+|---------|--------|---------|
+| Text search | `maps.search.searchText()` | [search-text.ts](examples/search-text.ts) |
+| Search (full rows) | `maps.search.search()` | [search-text.ts](examples/search-text.ts) |
+| Search pagination | `maps.search.searchPage()` | [search-pagination.ts](examples/search-pagination.ts) |
+| Place details | `maps.places.get()` | [place-get.ts](examples/place-get.ts) |
+| Place + reviews | `maps.getPlaceFull()` | [place-full.ts](examples/place-full.ts) |
+| Reviews (Boq, paginated) | `maps.reviews.listAll()` | [reviews-list.ts](examples/reviews-list.ts) |
+| Autocomplete | `maps.suggest.suggest()` | [suggest.ts](examples/suggest.ts) |
+| Map-click POI | `maps.reveal.revealAtClick()` | — |
+
+`reviews.list()` tries Boq first, then embedded snippets from the place preview.
+
+### Directions and location
+
+| Feature | Method | Example |
+|---------|--------|---------|
+| Directions | `maps.directions.get()` | [directions-get.ts](examples/directions-get.ts) |
+| Geocode | `maps.geocode.geocode()` | [geocode.ts](examples/geocode.ts) |
+| Reverse geocode | `maps.geocode.reverseGeocode()` | [geocode.ts](examples/geocode.ts) |
+| Timezone | `maps.timezone.get()` | — |
+| Distance matrix | `maps.distanceMatrix.getMatrix()` | — |
+| Elevation | `maps.elevation.getAtPoint()` | — |
+
+Distance matrix and elevation are **derived** by fanning out directions requests, not a
+single Google matrix/elevation API.
+
+### Media and maps
+
+| Feature | Method | Notes |
+|---------|--------|-------|
+| Place photos | `maps.photos.list()` | `batchexecute` when `lat`/`lng` set; else `place_preview` |
+| Street View nearby | `maps.panorama.findNearby()` | Coverage tiles first |
+| Map tiles | `maps.tiles.getTileByLatLng()` | 256px roadmap verified |
+| Static map PNG | `maps.staticMap.getStaticMap()` | Stitched from `vt/proto` tiles |
+
+### Links and lists
+
+| Feature | Method | Example |
+|---------|--------|---------|
+| Short link resolve | `maps.links.resolve()` | — |
+| Parse Maps URL | `parseMapsUrl()` | [maps-url.ts](examples/maps-url.ts) |
+| Build share link | `buildPlaceLink()`, … | [maps-url.ts](examples/maps-url.ts) |
+| Public place lists | `maps.lists.get()` | — |
+
+### batchexecute
+
+| Feature | Method |
+|---------|--------|
+| Area traffic | `maps.traffic.getAreaTraffic()` |
+| Category taxonomy | `maps.categories.getHierarchy()` |
+| Category suggestions | `maps.categories.suggest()` |
+| Rating histogram | `maps.ugcAggregates.getPlaceAggregates()` |
+| URL decode | `maps.batchUrl.decode()` |
+| Short URL create | `maps.batchUrl.createShortUrl()` |
+| Transit departures | `maps.transit.getStationDepartures()` |
+
+Traffic, UGC aggregates, and batchexecute photo galleries resolve a Maps session `psi`
+from the warmed HTTP session when you do not pass one.
+
+Low-level RPC builders and parsers: `import from 'googlemaps-kit/internal'`.
+
+## Installation
+
+```bash
+npm install googlemaps-kit
+```
+
+**Requirements:** Node.js >= 18
+
+**From source:**
+
+```bash
+git clone https://github.com/KumarVandit/googlemaps-kit.git
+cd googlemaps-kit
+npm install && npm run build
+```
+
+## Quick start
+
+```typescript
+import { createGMapsClient } from 'googlemaps-kit';
+
+const maps = createGMapsClient({ hl: 'en', gl: 'in' });
+
+const { places } = await maps.search.searchText({
+  query: 'cafes in indiranagar',
+  location: { lat: 12.98, lng: 77.64 },
+  limit: 5,
+});
+
+const top = places[0]!;
+const place = await maps.places.get({
+  hexId: top.hexId!,
+  name: top.name,
+  lat: top.latitude ?? 12.98,
+  lng: top.longitude ?? 77.64,
+  mode: 'rich',
+});
+
+const reviews = await maps.reviews.listAll({
+  hexId: place.hexId!,
+  limit: 10,
+  maxPages: 1,
+});
+
+console.log(place.name, place.rating, reviews.reviews.length, 'reviews');
+```
+
+From a git checkout:
+
+```bash
+npm run example:quick-start
+```
+
+## Configuration
+
+`createGMapsClient()` loads `.env.local` then `.env` from the working directory
+(see `loadProjectEnv()`). Existing `process.env` values are not overwritten.
+
+| Option | Env var | Default | Description |
+|--------|---------|---------|-------------|
+| `hl` | `GMAPS_HL` | `en` | Language |
+| `gl` | `GMAPS_GL` | `us` | Region |
+| `requestDelayMs` | `GMAPS_REQUEST_DELAY_MS` | `0` | Min delay between request starts |
+| `concurrency` | `GMAPS_CONCURRENCY` | `6` | Max parallel in-flight requests |
+| `debug` | — | `false` | Log requests/responses (pass in config, not an env var) |
+| `maxRetries` | — | `2` | Retries on transient failures |
+| `retryDelay` | — | `500` | Base retry delay (ms) |
+
+Copy [`.env.example`](./.env.example) to `.env.local` for local overrides.
+
+## Client
+
+`createGMapsClient()` exposes **24 services**:
+
+`search`, `places`, `reviews`, `directions`, `geocode`, `distanceMatrix`, `elevation`,
+`timezone`, `staticMap`, `suggest`, `panorama`, `tiles`, `lists`, `photos`, `links`,
+`traffic`, `transit`, `categories`, `ugcAggregates`, `batchUrl`, `knowledge`,
+`localPosts`, `reveal`, `passiveAssist`
+
+**Convenience methods on the client:** `getPlaceFull`, `getPlaceComplete`, `getDirections`,
+`searchEnriched`, `getHttpStats()`
+
+**Advanced (lazy-loaded):** `rpc()`, `features()`, `runtime()`
+
+**Standalone exports:** `parseMapsUrl`, `buildPlaceLink`, `encodePolyline`,
+`decodeEncodedPolyline`, error classes, and domain types.
+
+## Error handling
+
+```typescript
+import {
+  createGMapsClient,
+  GMapsThrottleError,
+  GMapsPhotosBlockedError,
+  GMapsEmptyPayloadError,
+} from 'googlemaps-kit';
+
+const maps = createGMapsClient();
+
+try {
+  await maps.photos.list({
+    hexId: '0x…',
+    lat: 12.91,
+    lng: 77.65,
+    source: 'listentityphotos', // GET RPC; often blocked
+  });
+} catch (error) {
+  if (error instanceof GMapsThrottleError) {
+    // Back off (client also retries with jitter)
+  } else if (error instanceof GMapsPhotosBlockedError) {
+    // Prefer default source or `source: 'batchexecute'`
+  } else if (error instanceof GMapsEmptyPayloadError) {
+    // HTTP 200 but empty/stub body
+  }
+}
+```
+
+## Best practices
+
+- Set `requestDelayMs` and `concurrency` for scheduled or high-volume jobs.
+- Under load, Google may return **HTTP 200 with truncated payloads** (fewer photos, missing
+  `reviewCount`). Check field presence, not status codes alone.
+- Pass `lat` and `lng` to `maps.photos.list()` for batchexecute galleries with metadata;
+  without coordinates it uses place preview URLs only.
+- Avoid `source: 'listentityphotos'`; many IPs get an abuse block (`GMapsPhotosBlockedError`).
+- `distanceMatrix.getMatrix()` costs **N×M directions requests** (deduped, bounded concurrency).
+- First batchexecute call may warm the session; empty 200 responses often mean the jar was
+  not warmed yet, not that the place has no data.
+
+## Limitations
+
+- Unofficial reverse-engineered surfaces; no stability guarantee.
+- No logged-in Google account support in the public API.
+- `knowledge.get()` uses place-preview fields as fallback (not a live knowledge-graph RPC).
+- `localPosts.list()` is unverified (sampled businesses returned empty payloads).
+- `passiveAssist.getViewportChips()` requires a viewport `psi` you supply; the SDK does not
+  open a browser.
+- Map tiles: 256px roadmap layer verified; other layers/sizes may return HTTP 400.
+- Bicycling directions are sparse in some regions.
+
+## Development
+
+```bash
+npm test
+npm run build
+npm run examples:all  # build + run every public example (live network)
+npm run verify:all    # live HTTP checks against Google
+```
+
+## License
+
+MIT

package/dist/auth/auth-status.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Signed-in session detection for googlemaps-kit.
+ *
+ * Never logs or returns cookie/token values — only names and lengths.
+ */
+import type { HttpClient } from '../client/http-client.js';
+import { type AuthStatus } from '../types/common.js';
+export interface AuthStatusOptions {
+    liveCheck?: boolean;
+    hl?: string;
+    gl?: string;
+}
+export declare class AuthService {
+    private http;
+    private configuredCookies?;
+    private configuredAuthToken?;
+    private lastStatus;
+    private lastCheckedAt;
+    private readonly statusTtlMs;
+    constructor(http: HttpClient, options?: {
+        cookies?: string;
+        authToken?: string;
+    });
+    getStatus(options?: AuthStatusOptions): Promise<AuthStatus>;
+    assertSignedIn(options?: AuthStatusOptions): Promise<AuthStatus>;
+    private cacheStatus;
+    private probeListUgc;
+}
+export declare function summarizeAuthStatus(status: AuthStatus): string;
+//# sourceMappingURL=auth-status.d.ts.map

package/dist/auth/auth-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-status.d.ts","sourceRoot":"","sources":["../../src/auth/auth-status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAA4B,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAM/E,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAUD,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,iBAAiB,CAAC,CAAS;IACnC,OAAO,CAAC,mBAAmB,CAAC,CAAS;IACrC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;gBAG3C,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAOlD,SAAS,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC;IAsF/D,cAAc,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC;IAW1E,OAAO,CAAC,WAAW;YAKL,YAAY;CA0C3B;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAQ9D"}

package/dist/auth/auth-status.js

@@ -0,0 +1,169 @@
+/**
+ * Signed-in session detection for googlemaps-kit.
+ *
+ * Never logs or returns cookie/token values — only names and lengths.
+ */
+import { buildGoogleAuthorization, buildAuthenticatedHeaders } from './google-auth.js';
+import { extractMapsPageTokens } from './maps-tokens.js';
+import { cookiesToHeader, randomUserAgent } from './session.js';
+import { GMapsCookiesExpiredError } from '../types/common.js';
+import { buildReviewsUrl } from '../rpc/pb-builders.js';
+import { isListUgcUnauthenticatedStub } from '../utils/throttle-detection.js';
+import { parseGoogleResponse } from '../utils/response-parser.js';
+function redactCookieNames(jar) {
+    return Object.keys(jar);
+}
+function hasSapisidFamily(jar) {
+    return Boolean(jar.SAPISID || jar['__Secure-1PAPISID'] || jar['__Secure-3PAPISID']);
+}
+export class AuthService {
+    http;
+    configuredCookies;
+    configuredAuthToken;
+    lastStatus = null;
+    lastCheckedAt = 0;
+    statusTtlMs = 5 * 60 * 1000;
+    constructor(http, options = {}) {
+        this.http = http;
+        this.configuredCookies = options.cookies;
+        this.configuredAuthToken = options.authToken;
+    }
+    async getStatus(options = {}) {
+        const runLive = options.liveCheck !== false;
+        if (!runLive &&
+            this.lastStatus &&
+            Date.now() - this.lastCheckedAt < this.statusTtlMs) {
+            return this.lastStatus;
+        }
+        const jar = this.http.getCookieJar();
+        const cookieNames = redactCookieNames(jar);
+        const cookiesPresent = cookieNames.length > 0 || Boolean(this.configuredCookies);
+        const authToken = this.configuredAuthToken ?? this.http.getConfiguredAuthToken() ?? '';
+        const authTokenPresent = authToken.length > 0;
+        const sapisidHash = hasSapisidFamily(jar) && Boolean(buildGoogleAuthorization(jar));
+        const batchexecuteXsrf = authTokenPresent;
+        const base = {
+            signedIn: false,
+            cookiesPresent,
+            cookieNames,
+            authTokenPresent,
+            authTokenLength: authToken.length,
+            capabilities: {
+                sapisidHash,
+                batchexecuteXsrf,
+                batchUgcPosts: sapisidHash && batchexecuteXsrf,
+            },
+        };
+        if (!cookiesPresent) {
+            base.message =
+                'No signed-in cookies configured. Anonymous mode is active — run `npm run auth:login` to upgrade.';
+            this.cacheStatus(base);
+            return base;
+        }
+        if (!runLive) {
+            base.signedIn = sapisidHash;
+            base.message = sapisidHash
+                ? 'Auth cookies present (live check skipped).'
+                : 'Cookies present but no SAPISID — listugcposts will not work.';
+            this.cacheStatus(base);
+            return base;
+        }
+        try {
+            const tokens = await extractMapsPageTokens(jar, this.http.getUserAgent());
+            if (tokens.authToken && tokens.authToken.length > 0 && !authTokenPresent) {
+                base.authTokenPresent = true;
+                base.authTokenLength = tokens.authToken.length;
+                base.capabilities.batchexecuteXsrf = true;
+                base.capabilities.batchUgcPosts = sapisidHash;
+            }
+            const listUgc = await this.probeListUgc(options);
+            if (listUgc === 'valid') {
+                base.signedIn = true;
+                base.liveCheck = 'valid';
+                base.message = 'Signed-in session is valid.';
+            }
+            else if (listUgc === 'expired') {
+                base.signedIn = false;
+                base.liveCheck = 'expired';
+                base.message =
+                    'Cookies expired or rejected — re-run: npm run auth:login';
+            }
+            else if (sapisidHash && tokens.authToken.length > 0) {
+                base.signedIn = true;
+                base.liveCheck = 'valid';
+                base.message = 'Signed-in (SAPISID + SNlM0e present; listugcposts stub not re-probed).';
+            }
+            else {
+                base.signedIn = false;
+                base.liveCheck = 'anonymous';
+                base.message =
+                    'Cookies present but session behaves as anonymous — re-run: npm run auth:login';
+            }
+        }
+        catch {
+            base.liveCheck = 'error';
+            base.message = 'Live auth check failed — cookies may be stale.';
+        }
+        this.cacheStatus(base);
+        return base;
+    }
+    async assertSignedIn(options = {}) {
+        const status = await this.getStatus(options);
+        if (!this.configuredCookies && !status.cookiesPresent) {
+            return status;
+        }
+        if (status.liveCheck === 'expired' || (status.cookiesPresent && !status.signedIn)) {
+            throw new GMapsCookiesExpiredError(status.message);
+        }
+        return status;
+    }
+    cacheStatus(status) {
+        this.lastStatus = status;
+        this.lastCheckedAt = Date.now();
+    }
+    async probeListUgc(options) {
+        if (!hasSapisidFamily(this.http.getCookieJar())) {
+            return 'anonymous';
+        }
+        const url = buildReviewsUrl({
+            hexId: '0x3bae1500315fdff7:0x9fe54cd44a84f1c7',
+            limit: 3,
+            hl: options.hl ?? 'en',
+            gl: options.gl ?? 'in',
+        });
+        const jar = this.http.getCookieJar();
+        const response = await fetch(url, {
+            headers: {
+                'User-Agent': this.http.getUserAgent() || randomUserAgent(),
+                Cookie: cookiesToHeader(jar),
+                Accept: '*/*',
+                ...buildAuthenticatedHeaders(jar, { referer: 'https://www.google.com/' }),
+            },
+            redirect: 'follow',
+        });
+        const body = await response.text();
+        if (response.url.includes('accounts.google.com')) {
+            return 'expired';
+        }
+        const parsed = parseGoogleResponse(body);
+        const root = Array.isArray(parsed) && Array.isArray(parsed[0]) ? parsed[0] : parsed;
+        if (isListUgcUnauthenticatedStub(root)) {
+            return 'expired';
+        }
+        if (Array.isArray(root) && JSON.stringify(root).length > 40) {
+            return 'valid';
+        }
+        return 'anonymous';
+    }
+}
+export function summarizeAuthStatus(status) {
+    const parts = [
+        status.signedIn ? 'signed-in' : 'anonymous',
+        `cookies=${status.cookieNames.length}`,
+        `authTokenLen=${status.authTokenLength}`,
+    ];
+    if (status.liveCheck)
+        parts.push(`live=${status.liveCheck}`);
+    return parts.join(', ');
+}
+//# sourceMappingURL=auth-status.js.map

package/dist/auth/auth-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-status.js","sourceRoot":"","sources":["../../src/auth/auth-status.ts"],"names":[],"mappings":"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"}

package/dist/auth/google-auth.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Build Google SAPISIDHASH Authorization header required by /maps/rpc/listugcposts.
+ */
+export declare function buildGoogleAuthorization(cookies: Record<string, string>, now?: number): string | undefined;
+export declare function buildAuthenticatedHeaders(cookies: Record<string, string>, options?: {
+    referer?: string;
+    now?: number;
+}): Record<string, string>;
+//# sourceMappingURL=google-auth.d.ts.map

package/dist/auth/google-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-auth.d.ts","sourceRoot":"","sources":["../../src/auth/google-auth.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,GAAG,SAAa,GACf,MAAM,GAAG,SAAS,CAUpB;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAexB"}

package/dist/auth/google-auth.js

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto';
+const GOOGLE_ORIGIN = 'https://www.google.com';
+const SAPISID_COOKIES = [
+    { name: 'SAPISID', label: 'SAPISIDHASH' },
+    { name: '__Secure-1PAPISID', label: 'SAPISID1PHASH' },
+    { name: '__Secure-3PAPISID', label: 'SAPISID3PHASH' },
+];
+function sapisidHash(timestampMs, sapisid, origin) {
+    const payload = `${timestampMs} ${sapisid} ${origin}`;
+    const digest = createHash('sha1').update(payload).digest('hex');
+    return `${timestampMs}_${digest}`;
+}
+/**
+ * Build Google SAPISIDHASH Authorization header required by /maps/rpc/listugcposts.
+ */
+export function buildGoogleAuthorization(cookies, now = Date.now()) {
+    const parts = [];
+    for (const { name, label } of SAPISID_COOKIES) {
+        const value = cookies[name];
+        if (!value)
+            continue;
+        parts.push(`${label} ${sapisidHash(now, value, GOOGLE_ORIGIN)}`);
+    }
+    return parts.length > 0 ? parts.join(' ') : undefined;
+}
+export function buildAuthenticatedHeaders(cookies, options) {
+    const headers = {
+        Origin: GOOGLE_ORIGIN,
+        Referer: options?.referer ?? `${GOOGLE_ORIGIN}/maps/`,
+        'X-Goog-AuthUser': '0',
+        'X-Same-Domain': '1',
+        'x-maps-diversion-context-bin': 'CAE=',
+    };
+    const auth = buildGoogleAuthorization(cookies, options?.now);
+    if (auth) {
+        headers.Authorization = auth;
+    }
+    return headers;
+}
+//# sourceMappingURL=google-auth.js.map

package/dist/auth/google-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-auth.js","sourceRoot":"","sources":["../../src/auth/google-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,aAAa,GAAG,wBAAwB,CAAC;AAE/C,MAAM,eAAe,GAA2C;IAC9D,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE;IACzC,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,eAAe,EAAE;IACrD,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,eAAe,EAAE;CACtD,CAAC;AAEF,SAAS,WAAW,CAAC,WAAmB,EAAE,OAAe,EAAE,MAAc;IACvE,MAAM,OAAO,GAAG,GAAG,WAAW,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;IACtD,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChE,OAAO,GAAG,WAAW,IAAI,MAAM,EAAE,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA+B,EAC/B,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAEhB,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,eAAe,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,OAA+B,EAC/B,OAA4C;IAE5C,MAAM,OAAO,GAA2B;QACtC,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,GAAG,aAAa,QAAQ;QACrD,iBAAiB,EAAE,GAAG;QACtB,eAAe,EAAE,GAAG;QACpB,8BAA8B,EAAE,MAAM;KACvC,CAAC;IAEF,MAAM,IAAI,GAAG,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAC7D,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAC/B,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/auth/maps-tokens.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Extract batchexecute tokens from a Maps HTML bootstrap page.
+ */
+import type { MapsPageTokens } from '../types/common.js';
+export declare function extractMapsPageTokens(cookies: Record<string, string>, userAgent: string, fetchImpl?: typeof fetch): Promise<MapsPageTokens>;
+//# sourceMappingURL=maps-tokens.d.ts.map

package/dist/auth/maps-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maps-tokens.d.ts","sourceRoot":"","sources":["../../src/auth/maps-tokens.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,cAAc,CAAC,CAYzB"}

package/dist/auth/maps-tokens.js

@@ -0,0 +1,18 @@
+/**
+ * Extract batchexecute tokens from a Maps HTML bootstrap page.
+ */
+import { buildBrowserHeaders } from './session.js';
+import { parseMapsPageTokens } from '../rpc/app-options.js';
+export async function extractMapsPageTokens(cookies, userAgent, fetchImpl = fetch) {
+    const response = await fetchImpl('https://www.google.com/maps', {
+        headers: buildBrowserHeaders({
+            userAgent,
+            cookies,
+            mode: 'document',
+        }),
+        redirect: 'follow',
+    });
+    const html = await response.text();
+    return parseMapsPageTokens(html);
+}
+//# sourceMappingURL=maps-tokens.js.map

package/dist/auth/maps-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maps-tokens.js","sourceRoot":"","sources":["../../src/auth/maps-tokens.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG5D,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAA+B,EAC/B,SAAiB,EACjB,YAA0B,KAAK;IAE/B,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,6BAA6B,EAAE;QAC9D,OAAO,EAAE,mBAAmB,CAAC;YAC3B,SAAS;YACT,OAAO;YACP,IAAI,EAAE,UAAU;SACjB,CAAC;QACF,QAAQ,EAAE,QAAQ;KACnB,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/auth/session.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Session bootstrap for Google Maps internal APIs (raw HTTP, no browser).
+ *
+ * Follows the google.com → consent.google.com → maps cookie chain used by
+ * production scrapers to obtain NID/AEC session cookies.
+ */
+export declare function randomUserAgent(): string;
+export interface CookieJarState {
+    cookies: Record<string, string>;
+    userAgent: string;
+    fetchedAt: number;
+}
+export declare function cookiesToHeader(jar: Record<string, string>): string;
+export declare function buildBrowserHeaders(options?: {
+    userAgent?: string;
+    referer?: string;
+    cookies?: Record<string, string> | string;
+    mode?: 'document' | 'cors';
+}): Record<string, string>;
+/** Default SOCS consent cookie for anonymous Maps sessions. */
+export declare const DEFAULT_SOCS = "CAISNQgEEitib3FfaWRlbnRpdHlmcm9udGVuZHVpc2VydmVyXzIwMjYwMTE4LjA5X3AwGgJlbiACGgYIgIu7ywY";
+/**
+ * Bootstrap cookies via the 3-step chain. Returns a cookie jar with NID when successful.
+ */
+export declare function bootstrapSession(force?: boolean, fetchImpl?: typeof fetch): Promise<CookieJarState>;
+export declare function clearSessionCache(): void;
+export declare function getCachedSession(): CookieJarState | null;
+//# sourceMappingURL=session.d.ts.map

package/dist/auth/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/auth/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAmBD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAInE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;IAC1C,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAC5B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8BzB;AAED,+DAA+D;AAC/D,eAAO,MAAM,YAAY,4FACkE,CAAC;AAE5F;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,UAAQ,EACb,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,cAAc,CAAC,CAgCzB;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,wBAAgB,gBAAgB,IAAI,cAAc,GAAG,IAAI,CAExD"}