@happyvertical/geo 0.74.8

package/AGENT.md

@@ -0,0 +1,33 @@
+# @happyvertical/geo
+
+<!-- BEGIN AGENT:GENERATED -->
+## Purpose
+Standardized geographical information interface supporting Google Maps and OpenStreetMap
+
+## Package Map
+- Package: `@happyvertical/geo`
+- Hierarchy path: `@happyvertical/sdk > packages > geo`
+- Workspace position: `12 of 30` local packages
+- Internal dependencies: `@happyvertical/cache`, `@happyvertical/utils`
+- Internal dependents: none
+- Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
+
+## Build & Test
+```bash
+pnpm --filter @happyvertical/geo build
+pnpm --filter @happyvertical/geo test
+pnpm --filter @happyvertical/geo clean
+```
+
+## Agent Correction Loops
+- If module resolution or export errors mention a workspace dependency, build the dependency first (`pnpm --filter @happyvertical/cache build`, `pnpm --filter @happyvertical/utils build`) and then rerun `pnpm --filter @happyvertical/geo build`.
+- If tests or exports fail after API, type, or bundle changes, run `pnpm --filter @happyvertical/geo clean` followed by `pnpm --filter @happyvertical/geo build` and `pnpm --filter @happyvertical/geo test`.
+- If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
+
+## Ecosystem Relationships
+- Provides: Standardized geographical information interface supporting Google Maps and OpenStreetMap
+- Implements: none
+- Requires: @happyvertical/cache, @happyvertical/utils, @googlemaps/google-maps-services-js
+- Stability: stable (Primary package surface is described as implemented and production-oriented.)
+<!-- END AGENT:GENERATED -->
+

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+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,194 @@
+---
+id: geo
+title: "@happyvertical/geo: Geographical Information"
+sidebar_label: "@happyvertical/geo"
+sidebar_position: 5
+---
+
+# @happyvertical/geo
+
+Geocoding, reverse geocoding, and static map generation with a unified adapter interface. Supports Google Maps and OpenStreetMap (Nominatim) for geocoding, and Mapbox and Google Maps for static map images. Results are cached in memory automatically.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/geo
+```
+
+Peer dependencies: `@happyvertical/cache`, `@happyvertical/utils`.
+
+## Usage
+
+### Geocoding
+
+```typescript
+import { getGeoAdapter } from '@happyvertical/geo';
+
+const adapter = await getGeoAdapter({
+  provider: 'google',
+  apiKey: process.env.GOOGLE_MAPS_API_KEY!,
+});
+
+const results = await adapter.lookup('Eiffel Tower, Paris');
+console.log(results[0].name);       // Formatted address
+console.log(results[0].latitude);   // 48.8583701
+console.log(results[0].countryCode); // FR
+
+const locations = await adapter.reverseGeocode(48.8584, 2.2945);
+```
+
+### OpenStreetMap (no API key required)
+
+```typescript
+const adapter = await getGeoAdapter({
+  provider: 'openstreetmap',
+  rateLimitDelay: 1000, // ms between requests (default)
+});
+
+const results = await adapter.lookup('Big Ben, London');
+```
+
+### POI (Point-of-Interest) search
+
+Both providers implement `findPoisNear(lat, lon, radiusMeters, options?)`
+for discovering businesses, landmarks, and amenities around a coordinate.
+It's an optional method on the adapter — feature-detect before calling:
+
+```typescript
+if (typeof adapter.findPoisNear === 'function') {
+  const cafes = await adapter.findPoisNear(48.8566, 2.3522, 300, {
+    types: ['cafe'],
+    limit: 10,
+  });
+  for (const cafe of cafes) {
+    console.log(cafe.name, '@', cafe.latitude, cafe.longitude);
+  }
+}
+```
+
+**Google** routes the request through the Places API (Nearby Search) so the
+API key needs the Places API enabled in Google Cloud in addition to
+Geocoding. The first entry of `options.types` becomes the request's `type`
+filter; additional entries fan out across separate requests and the results
+are deduped by `place_id`. Max radius 50 000 m per Places API.
+
+**OpenStreetMap** uses the public [Overpass API][overpass]. No key, but
+the same community use-policy as Nominatim applies — cache aggressively
+and reuse a `rateLimitDelay` that matches your traffic. When `types` is
+omitted, the query looks across `amenity`, `shop`, `tourism`, `leisure`,
+`office`, `historic`, and `craft` tag keys. When supplied, values are
+matched against each of those keys so you can pass `['cafe']` or
+`['supermarket']` without knowing the exact tag.
+
+[overpass]: https://wiki.openstreetmap.org/wiki/Overpass_API
+
+### Environment Variable Configuration
+
+Set `HAVE_GEO_PROVIDER`, `HAVE_GEO_TIMEOUT`, `HAVE_GEO_MAX_RESULTS`, `HAVE_GEO_RATE_LIMIT_DELAY`, `HAVE_GEO_USER_AGENT`, and `GOOGLE_MAPS_API_KEY` to configure without passing options:
+
+```typescript
+const adapter = await getGeoAdapter(); // reads from env
+```
+
+User-provided options always take precedence over environment variables.
+
+### Static Maps
+
+Generate static map URLs or fetch map images for embedding:
+
+```typescript
+import { getStaticMapUrl, fetchStaticMap, getOGMapUrl } from '@happyvertical/geo';
+
+// Mapbox URL (default provider)
+const url = getStaticMapUrl(53.5461, -113.4938, {
+  provider: 'mapbox',
+  zoom: 14,
+  width: 1200,
+  height: 630,
+});
+
+// Google Maps URL
+const googleUrl = getStaticMapUrl(53.5461, -113.4938, {
+  provider: 'google',
+  googleMapType: 'roadmap',
+});
+
+// Fetch image as Buffer
+const result = await fetchStaticMap(53.5461, -113.4938, { provider: 'mapbox' });
+await fs.writeFile('map.png', result.buffer);
+
+// OG-sized map (1200x630) convenience function
+const ogUrl = getOGMapUrl(53.5461, -113.4938);
+```
+
+## API
+
+### `getGeoAdapter(options?): Promise<GeoAdapter>`
+
+Factory function returning a geocoding adapter. Options are a discriminated union on `provider`:
+
+| Option | Google | OSM | Description |
+|--------|--------|-----|-------------|
+| `provider` | `'google'` | `'openstreetmap'` | Required (or set `HAVE_GEO_PROVIDER`) |
+| `apiKey` | required | — | Google Maps API key |
+| `timeout` | optional | optional | Request timeout ms (default: 10000) |
+| `maxResults` | optional | optional | Max results (default: 10) |
+| `userAgent` | — | optional | Custom User-Agent for Nominatim |
+| `rateLimitDelay` | — | optional | Delay between requests ms (default: 1000) |
+
+### `GeoAdapter` Interface
+
+```typescript
+interface GeoAdapter {
+  lookup(query: string): Promise<Location[]>;
+  reverseGeocode(latitude: number, longitude: number): Promise<Location[]>;
+}
+```
+
+### `Location`
+
+```typescript
+interface Location {
+  id: string;
+  type: 'country' | 'region' | 'city' | 'address' | 'point_of_interest' | 'unknown';
+  name: string;
+  latitude: number;
+  longitude: number;
+  addressComponents: {
+    streetNumber?: string; streetName?: string; city?: string;
+    region?: string; country?: string; postalCode?: string;
+  };
+  countryCode: string;
+  timezone?: string;
+  raw: any;
+}
+```
+
+### Static Map Functions
+
+- `getStaticMapUrl(lat, lng, options?): string` — Generate a Mapbox or Google static map URL.
+- `fetchStaticMap(lat, lng, options?): Promise<StaticMapResult>` — Fetch the map image as a Buffer.
+- `getOGMapUrl(lat, lng, options?): string` — Convenience for 1200x630 Open Graph maps.
+
+`StaticMapOptions` supports `provider` (`'mapbox'` | `'google'`), `width`, `height`, `zoom`, `markerColor`, `showMarker`, `mapboxToken`/`googleApiKey`, `mapboxStyle`, `googleMapType`, `scale`, and `markers`.
+
+### Error Classes
+
+All extend `GeoError`:
+
+- `GeoError` — Base error with `code` and `provider` fields
+- `InvalidQueryError` — Empty or malformed query
+- `RateLimitError` — Provider rate limit exceeded
+- `AuthenticationError` — Invalid API key
+- `NoResultsError` — No results for query
+
+### Utility Functions
+
+- `validateCoordinates(lat, lng)` — Returns `{ valid, error? }`
+- `isValidLatitude(lat)` / `isValidLongitude(lng)` — Bounds check
+- `normalizeCountryCode(code)` — Normalize to ISO 3166-1 alpha-2
+- `mapGooglePlaceType(types)` / `mapOSMPlaceType(type, addressType?)` — Map provider types to `Location['type']`
+
+## License
+
+ISC

package/dist/chunks/google-Ci3_ec7t.js

@@ -0,0 +1,342 @@
+import { Client } from "@googlemaps/google-maps-services-js";
+import { getCache } from "@happyvertical/cache";
+import { InvalidQueryError, AuthenticationError, RateLimitError, GeoError, mapGooglePlaceType, normalizeCountryCode, validateCoordinates } from "../index.js";
+class GoogleMapsProvider {
+  client;
+  apiKey;
+  timeout;
+  maxResults;
+  cache = null;
+  constructor(options) {
+    this.client = new Client({});
+    this.apiKey = options.apiKey;
+    this.timeout = options.timeout || 1e4;
+    this.maxResults = options.maxResults || 10;
+    this.initCache();
+  }
+  /**
+   * Initializes the memory cache for geocoding results
+   */
+  async initCache() {
+    try {
+      this.cache = await getCache({
+        provider: "memory",
+        namespace: "geo:google",
+        defaultTTL: 86400,
+        // 24 hour cache for location data
+        maxSize: 20 * 1024 * 1024,
+        // 20MB
+        maxEntries: 5e3,
+        evictionPolicy: "lru"
+      });
+    } catch (error) {
+      console.warn("Failed to initialize geo cache:", error);
+    }
+  }
+  /**
+   * Generates a cache key for geocoding requests
+   */
+  getCacheKey(type, ...parts) {
+    return `${type}:${parts.join(":")}`;
+  }
+  /**
+   * Look up locations based on a query string
+   */
+  async lookup(query) {
+    if (!query || query.trim().length === 0) {
+      throw new InvalidQueryError(query, "google");
+    }
+    const cacheKey = this.getCacheKey("lookup", query, String(this.maxResults));
+    if (this.cache) {
+      const cached = await this.cache.get(cacheKey);
+      if (cached) {
+        return cached;
+      }
+    }
+    try {
+      const response = await this.client.geocode({
+        params: {
+          address: query,
+          key: this.apiKey
+        },
+        timeout: this.timeout
+      });
+      if (response.data.status === "ZERO_RESULTS") {
+        return [];
+      }
+      if (response.data.status === "REQUEST_DENIED") {
+        throw new AuthenticationError("google");
+      }
+      if (response.data.status === "OVER_QUERY_LIMIT") {
+        throw new RateLimitError("google");
+      }
+      if (response.data.status !== "OK") {
+        throw new GeoError(
+          `Google Maps API error: ${response.data.status}`,
+          "API_ERROR",
+          "google"
+        );
+      }
+      const results = response.data.results.slice(0, this.maxResults);
+      const locations = results.map(
+        (result) => this.mapGoogleResultToLocation(result)
+      );
+      if (this.cache) {
+        await this.cache.set(cacheKey, locations);
+      }
+      return locations;
+    } catch (error) {
+      if (error instanceof GeoError) {
+        throw error;
+      }
+      throw new GeoError(
+        `Failed to lookup location: ${error.message}`,
+        "LOOKUP_FAILED",
+        "google"
+      );
+    }
+  }
+  /**
+   * Reverse geocode from coordinates to location
+   */
+  async reverseGeocode(latitude, longitude) {
+    const validation = validateCoordinates(latitude, longitude);
+    if (!validation.valid) {
+      throw new InvalidQueryError(
+        `${latitude}, ${longitude}: ${validation.error}`,
+        "google"
+      );
+    }
+    const cacheKey = this.getCacheKey(
+      "reverse",
+      String(latitude),
+      String(longitude),
+      String(this.maxResults)
+    );
+    if (this.cache) {
+      const cached = await this.cache.get(cacheKey);
+      if (cached) {
+        return cached;
+      }
+    }
+    try {
+      const response = await this.client.reverseGeocode({
+        params: {
+          latlng: { lat: latitude, lng: longitude },
+          key: this.apiKey
+        },
+        timeout: this.timeout
+      });
+      if (response.data.status === "ZERO_RESULTS") {
+        return [];
+      }
+      if (response.data.status === "REQUEST_DENIED") {
+        throw new AuthenticationError("google");
+      }
+      if (response.data.status === "OVER_QUERY_LIMIT") {
+        throw new RateLimitError("google");
+      }
+      if (response.data.status !== "OK") {
+        throw new GeoError(
+          `Google Maps API error: ${response.data.status}`,
+          "API_ERROR",
+          "google"
+        );
+      }
+      const results = response.data.results.slice(0, this.maxResults);
+      const locations = results.map(
+        (result) => this.mapGoogleResultToLocation(result)
+      );
+      if (this.cache) {
+        await this.cache.set(cacheKey, locations);
+      }
+      return locations;
+    } catch (error) {
+      if (error instanceof GeoError) {
+        throw error;
+      }
+      throw new GeoError(
+        `Failed to reverse geocode: ${error.message}`,
+        "REVERSE_GEOCODE_FAILED",
+        "google"
+      );
+    }
+  }
+  /**
+   * Find POIs near a coordinate using the Places API Nearby Search endpoint.
+   *
+   * Maps to `placesNearby` on the Google Maps Services SDK. Note that Places
+   * Nearby Search is a separate product line from Geocoding: it requires the
+   * Places API to be enabled for the supplied API key and is billed per
+   * request. Results are deduped across multi-type requests by `place_id`.
+   */
+  async findPoisNear(latitude, longitude, radiusMeters, options = {}) {
+    const validation = validateCoordinates(latitude, longitude);
+    if (!validation.valid) {
+      throw new InvalidQueryError(
+        `${latitude}, ${longitude}: ${validation.error}`,
+        "google"
+      );
+    }
+    if (!(radiusMeters > 0) || radiusMeters > 5e4) {
+      throw new InvalidQueryError(
+        `radius ${radiusMeters}m must be in (0, 50000]`,
+        "google"
+      );
+    }
+    const limit = options.limit ?? this.maxResults;
+    if (!Number.isInteger(limit) || limit < 1) {
+      throw new InvalidQueryError(
+        `limit ${limit} must be a positive integer`,
+        "google"
+      );
+    }
+    const types = options.types && options.types.length > 0 ? options.types : [void 0];
+    const cacheKey = this.getCacheKey(
+      "pois",
+      String(latitude),
+      String(longitude),
+      String(radiusMeters),
+      (options.types ?? []).join(","),
+      options.keyword ?? "",
+      options.language ?? "",
+      String(limit)
+    );
+    if (this.cache) {
+      const cached = await this.cache.get(cacheKey);
+      if (cached) return cached;
+    }
+    try {
+      const merged = /* @__PURE__ */ new Map();
+      for (const type of types) {
+        let pageToken;
+        let pagesFetched = 0;
+        const maxPagesPerType = 3;
+        while (pagesFetched < maxPagesPerType) {
+          const params = pageToken ? { pagetoken: pageToken, key: this.apiKey } : {
+            location: { lat: latitude, lng: longitude },
+            radius: radiusMeters,
+            ...type ? { type } : {},
+            ...options.keyword ? { keyword: options.keyword } : {},
+            ...options.language ? { language: options.language } : {},
+            key: this.apiKey
+          };
+          const response = await this.client.placesNearby({
+            params,
+            timeout: this.timeout
+          });
+          if (response.data.status === "ZERO_RESULTS") break;
+          if (response.data.status === "REQUEST_DENIED") {
+            throw new AuthenticationError("google");
+          }
+          if (response.data.status === "OVER_QUERY_LIMIT") {
+            throw new RateLimitError("google");
+          }
+          if (response.data.status === "INVALID_REQUEST" && pageToken) {
+            await new Promise((resolve) => setTimeout(resolve, 2e3));
+            continue;
+          }
+          if (response.data.status !== "OK") {
+            throw new GeoError(
+              `Google Places API error: ${response.data.status}`,
+              "API_ERROR",
+              "google"
+            );
+          }
+          for (const result of response.data.results) {
+            const location = this.mapGooglePoiToLocation(result);
+            if (!merged.has(location.id)) {
+              merged.set(location.id, location);
+            }
+            if (merged.size >= limit) break;
+          }
+          pagesFetched += 1;
+          if (merged.size >= limit) break;
+          pageToken = response.data.next_page_token;
+          if (!pageToken) break;
+          await new Promise((resolve) => setTimeout(resolve, 2e3));
+        }
+        if (merged.size >= limit) break;
+      }
+      const locations = [...merged.values()];
+      if (this.cache) await this.cache.set(cacheKey, locations);
+      return locations;
+    } catch (error) {
+      if (error instanceof GeoError) throw error;
+      throw new GeoError(
+        `Failed to find POIs: ${error.message}`,
+        "POI_SEARCH_FAILED",
+        "google"
+      );
+    }
+  }
+  /**
+   * Map Google Places Nearby Search result to standardized Location. The
+   * Places schema is a superset of Geocoding (adds `name`, `vicinity`,
+   * `types[]` semantics slightly different from geocoding `types`) so this
+   * is a separate mapper from `mapGoogleResultToLocation`.
+   */
+  mapGooglePoiToLocation(result) {
+    const loc = result.geometry?.location;
+    const latitude = loc?.lat ?? 0;
+    const longitude = loc?.lng ?? 0;
+    const name = result.name ? result.vicinity ? `${result.name}, ${result.vicinity}` : result.name : result.vicinity || "Unknown place";
+    return {
+      id: result.place_id,
+      type: "point_of_interest",
+      name,
+      latitude,
+      longitude,
+      addressComponents: {},
+      countryCode: "XX",
+      raw: result
+    };
+  }
+  /**
+   * Map Google Geocoding API result to standardized Location
+   */
+  mapGoogleResultToLocation(result) {
+    const addressComponents = {};
+    let countryCode = "XX";
+    for (const component of result.address_components || []) {
+      const types = component.types;
+      if (types.includes("street_number")) {
+        addressComponents.streetNumber = component.long_name;
+      }
+      if (types.includes("route")) {
+        addressComponents.streetName = component.long_name;
+      }
+      if (types.includes("locality")) {
+        addressComponents.city = component.long_name;
+      }
+      if (types.includes("administrative_area_level_1")) {
+        addressComponents.region = component.long_name;
+      }
+      if (types.includes("country")) {
+        addressComponents.country = component.long_name;
+        countryCode = component.short_name;
+      }
+      if (types.includes("postal_code")) {
+        addressComponents.postalCode = component.long_name;
+      }
+    }
+    const location = result.geometry?.location;
+    const latitude = location?.lat ?? 0;
+    const longitude = location?.lng ?? 0;
+    const type = mapGooglePlaceType(result.types || []);
+    return {
+      id: result.place_id,
+      type,
+      name: result.formatted_address,
+      latitude,
+      longitude,
+      addressComponents,
+      countryCode: normalizeCountryCode(countryCode),
+      raw: result
+    };
+  }
+}
+export {
+  GoogleMapsProvider
+};
+//# sourceMappingURL=google-Ci3_ec7t.js.map

package/dist/chunks/google-Ci3_ec7t.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-Ci3_ec7t.js","sources":["../../src/providers/google.ts"],"sourcesContent":["/**\n * Google Maps provider implementation\n */\n\nimport { Client } from '@googlemaps/google-maps-services-js';\nimport type { CacheAdapter } from '@happyvertical/cache';\nimport { getCache } from '@happyvertical/cache';\nimport type {\n  GeoProvider,\n  GoogleMapsOptions,\n  Location,\n  PoiSearchOptions,\n} from '../shared/types';\nimport {\n  AuthenticationError,\n  GeoError,\n  InvalidQueryError,\n  RateLimitError,\n} from '../shared/types';\nimport {\n  mapGooglePlaceType,\n  normalizeCountryCode,\n  validateCoordinates,\n} from '../shared/utils';\n\n/**\n * Google Maps provider implementation with in-memory caching\n */\nexport class GoogleMapsProvider implements GeoProvider {\n  private client: Client;\n  private apiKey: string;\n  private timeout: number;\n  private maxResults: number;\n  private cache: CacheAdapter | null = null;\n\n  constructor(options: GoogleMapsOptions) {\n    this.client = new Client({});\n    this.apiKey = options.apiKey;\n    this.timeout = options.timeout || 10000;\n    this.maxResults = options.maxResults || 10;\n\n    // Initialize memory cache asynchronously\n    this.initCache();\n  }\n\n  /**\n   * Initializes the memory cache for geocoding results\n   */\n  private async initCache(): Promise<void> {\n    try {\n      this.cache = await getCache({\n        provider: 'memory',\n        namespace: 'geo:google',\n        defaultTTL: 86400, // 24 hour cache for location data\n        maxSize: 20 * 1024 * 1024, // 20MB\n        maxEntries: 5000,\n        evictionPolicy: 'lru',\n      });\n    } catch (error) {\n      // Cache initialization failure shouldn't break the provider\n      console.warn('Failed to initialize geo cache:', error);\n    }\n  }\n\n  /**\n   * Generates a cache key for geocoding requests\n   */\n  private getCacheKey(type: string, ...parts: string[]): string {\n    return `${type}:${parts.join(':')}`;\n  }\n\n  /**\n   * Look up locations based on a query string\n   */\n  async lookup(query: string): Promise<Location[]> {\n    if (!query || query.trim().length === 0) {\n      throw new InvalidQueryError(query, 'google');\n    }\n\n    // Check cache first\n    const cacheKey = this.getCacheKey('lookup', query, String(this.maxResults));\n    if (this.cache) {\n      const cached = await this.cache.get<Location[]>(cacheKey);\n      if (cached) {\n        return cached;\n      }\n    }\n\n    try {\n      const response = await this.client.geocode({\n        params: {\n          address: query,\n          key: this.apiKey,\n        },\n        timeout: this.timeout,\n      });\n\n      if (response.data.status === 'ZERO_RESULTS') {\n        return [];\n      }\n\n      if (response.data.status === 'REQUEST_DENIED') {\n        throw new AuthenticationError('google');\n      }\n\n      if (response.data.status === 'OVER_QUERY_LIMIT') {\n        throw new RateLimitError('google');\n      }\n\n      if (response.data.status !== 'OK') {\n        throw new GeoError(\n          `Google Maps API error: ${response.data.status}`,\n          'API_ERROR',\n          'google',\n        );\n      }\n\n      const results = response.data.results.slice(0, this.maxResults);\n      const locations = results.map((result) =>\n        this.mapGoogleResultToLocation(result),\n      );\n\n      // Cache the result\n      if (this.cache) {\n        await this.cache.set(cacheKey, locations);\n      }\n\n      return locations;\n    } catch (error) {\n      if (error instanceof GeoError) {\n        throw error;\n      }\n\n      throw new GeoError(\n        `Failed to lookup location: ${(error as Error).message}`,\n        'LOOKUP_FAILED',\n        'google',\n      );\n    }\n  }\n\n  /**\n   * Reverse geocode from coordinates to location\n   */\n  async reverseGeocode(\n    latitude: number,\n    longitude: number,\n  ): Promise<Location[]> {\n    const validation = validateCoordinates(latitude, longitude);\n    if (!validation.valid) {\n      throw new InvalidQueryError(\n        `${latitude}, ${longitude}: ${validation.error}`,\n        'google',\n      );\n    }\n\n    // Check cache first\n    const cacheKey = this.getCacheKey(\n      'reverse',\n      String(latitude),\n      String(longitude),\n      String(this.maxResults),\n    );\n    if (this.cache) {\n      const cached = await this.cache.get<Location[]>(cacheKey);\n      if (cached) {\n        return cached;\n      }\n    }\n\n    try {\n      const response = await this.client.reverseGeocode({\n        params: {\n          latlng: { lat: latitude, lng: longitude },\n          key: this.apiKey,\n        },\n        timeout: this.timeout,\n      });\n\n      if (response.data.status === 'ZERO_RESULTS') {\n        return [];\n      }\n\n      if (response.data.status === 'REQUEST_DENIED') {\n        throw new AuthenticationError('google');\n      }\n\n      if (response.data.status === 'OVER_QUERY_LIMIT') {\n        throw new RateLimitError('google');\n      }\n\n      if (response.data.status !== 'OK') {\n        throw new GeoError(\n          `Google Maps API error: ${response.data.status}`,\n          'API_ERROR',\n          'google',\n        );\n      }\n\n      const results = response.data.results.slice(0, this.maxResults);\n      const locations = results.map((result) =>\n        this.mapGoogleResultToLocation(result),\n      );\n\n      // Cache the result\n      if (this.cache) {\n        await this.cache.set(cacheKey, locations);\n      }\n\n      return locations;\n    } catch (error) {\n      if (error instanceof GeoError) {\n        throw error;\n      }\n\n      throw new GeoError(\n        `Failed to reverse geocode: ${(error as Error).message}`,\n        'REVERSE_GEOCODE_FAILED',\n        'google',\n      );\n    }\n  }\n\n  /**\n   * Find POIs near a coordinate using the Places API Nearby Search endpoint.\n   *\n   * Maps to `placesNearby` on the Google Maps Services SDK. Note that Places\n   * Nearby Search is a separate product line from Geocoding: it requires the\n   * Places API to be enabled for the supplied API key and is billed per\n   * request. Results are deduped across multi-type requests by `place_id`.\n   */\n  async findPoisNear(\n    latitude: number,\n    longitude: number,\n    radiusMeters: number,\n    options: PoiSearchOptions = {},\n  ): Promise<Location[]> {\n    const validation = validateCoordinates(latitude, longitude);\n    if (!validation.valid) {\n      throw new InvalidQueryError(\n        `${latitude}, ${longitude}: ${validation.error}`,\n        'google',\n      );\n    }\n    if (!(radiusMeters > 0) || radiusMeters > 50_000) {\n      throw new InvalidQueryError(\n        `radius ${radiusMeters}m must be in (0, 50000]`,\n        'google',\n      );\n    }\n\n    const limit = options.limit ?? this.maxResults;\n    if (!Number.isInteger(limit) || limit < 1) {\n      throw new InvalidQueryError(\n        `limit ${limit} must be a positive integer`,\n        'google',\n      );\n    }\n    const types =\n      options.types && options.types.length > 0 ? options.types : [undefined];\n\n    const cacheKey = this.getCacheKey(\n      'pois',\n      String(latitude),\n      String(longitude),\n      String(radiusMeters),\n      (options.types ?? []).join(','),\n      options.keyword ?? '',\n      options.language ?? '',\n      String(limit),\n    );\n    if (this.cache) {\n      const cached = await this.cache.get<Location[]>(cacheKey);\n      if (cached) return cached;\n    }\n\n    try {\n      const merged = new Map<string, Location>();\n      for (const type of types) {\n        // Places Nearby returns up to 20 results per call and up to 60 total\n        // via `next_page_token`, with Google requiring a short activation\n        // delay after each token is issued. Keep paging per-type until we\n        // either satisfy the caller's `limit`, hit the 3-page ceiling, or\n        // run out of tokens.\n        let pageToken: string | undefined;\n        let pagesFetched = 0;\n        const maxPagesPerType = 3;\n\n        while (pagesFetched < maxPagesPerType) {\n          const params = pageToken\n            ? { pagetoken: pageToken, key: this.apiKey }\n            : {\n                location: { lat: latitude, lng: longitude },\n                radius: radiusMeters,\n                ...(type ? { type } : {}),\n                ...(options.keyword ? { keyword: options.keyword } : {}),\n                ...(options.language\n                  ? { language: options.language as any }\n                  : {}),\n                key: this.apiKey,\n              };\n\n          const response = await this.client.placesNearby({\n            params,\n            timeout: this.timeout,\n          });\n\n          if (response.data.status === 'ZERO_RESULTS') break;\n          if (response.data.status === 'REQUEST_DENIED') {\n            throw new AuthenticationError('google');\n          }\n          if (response.data.status === 'OVER_QUERY_LIMIT') {\n            throw new RateLimitError('google');\n          }\n          if (response.data.status === 'INVALID_REQUEST' && pageToken) {\n            // Google returns INVALID_REQUEST if the page token is polled\n            // before it has activated (typically ≤2s). Back off and retry\n            // one more time rather than aborting the whole call.\n            await new Promise((resolve) => setTimeout(resolve, 2000));\n            continue;\n          }\n          if (response.data.status !== 'OK') {\n            throw new GeoError(\n              `Google Places API error: ${response.data.status}`,\n              'API_ERROR',\n              'google',\n            );\n          }\n\n          for (const result of response.data.results) {\n            const location = this.mapGooglePoiToLocation(result);\n            if (!merged.has(location.id)) {\n              merged.set(location.id, location);\n            }\n            if (merged.size >= limit) break;\n          }\n\n          pagesFetched += 1;\n          if (merged.size >= limit) break;\n\n          pageToken = response.data.next_page_token;\n          if (!pageToken) break;\n          // `pagetoken` isn't activated instantly; Google's docs say to\n          // wait a short moment before using it. 2s is the commonly-cited\n          // activation window.\n          await new Promise((resolve) => setTimeout(resolve, 2000));\n        }\n\n        if (merged.size >= limit) break;\n      }\n\n      const locations = [...merged.values()];\n      if (this.cache) await this.cache.set(cacheKey, locations);\n      return locations;\n    } catch (error) {\n      if (error instanceof GeoError) throw error;\n      throw new GeoError(\n        `Failed to find POIs: ${(error as Error).message}`,\n        'POI_SEARCH_FAILED',\n        'google',\n      );\n    }\n  }\n\n  /**\n   * Map Google Places Nearby Search result to standardized Location. The\n   * Places schema is a superset of Geocoding (adds `name`, `vicinity`,\n   * `types[]` semantics slightly different from geocoding `types`) so this\n   * is a separate mapper from `mapGoogleResultToLocation`.\n   */\n  private mapGooglePoiToLocation(result: any): Location {\n    const loc = result.geometry?.location;\n    const latitude = loc?.lat ?? 0;\n    const longitude = loc?.lng ?? 0;\n    const name = result.name\n      ? result.vicinity\n        ? `${result.name}, ${result.vicinity}`\n        : result.name\n      : result.vicinity || 'Unknown place';\n\n    return {\n      id: result.place_id,\n      type: 'point_of_interest',\n      name,\n      latitude,\n      longitude,\n      addressComponents: {},\n      countryCode: 'XX',\n      raw: result,\n    };\n  }\n\n  /**\n   * Map Google Geocoding API result to standardized Location\n   */\n  private mapGoogleResultToLocation(result: any): Location {\n    // Extract address components\n    const addressComponents: Location['addressComponents'] = {};\n    let countryCode = 'XX';\n\n    for (const component of result.address_components || []) {\n      const types = component.types;\n\n      if (types.includes('street_number')) {\n        addressComponents.streetNumber = component.long_name;\n      }\n      if (types.includes('route')) {\n        addressComponents.streetName = component.long_name;\n      }\n      if (types.includes('locality')) {\n        addressComponents.city = component.long_name;\n      }\n      if (types.includes('administrative_area_level_1')) {\n        addressComponents.region = component.long_name;\n      }\n      if (types.includes('country')) {\n        addressComponents.country = component.long_name;\n        countryCode = component.short_name;\n      }\n      if (types.includes('postal_code')) {\n        addressComponents.postalCode = component.long_name;\n      }\n    }\n\n    // Extract coordinates\n    const location = result.geometry?.location;\n    const latitude = location?.lat ?? 0;\n    const longitude = location?.lng ?? 0;\n\n    // Determine location type\n    const type = mapGooglePlaceType(result.types || []);\n\n    return {\n      id: result.place_id,\n      type,\n      name: result.formatted_address,\n      latitude,\n      longitude,\n      addressComponents,\n      countryCode: normalizeCountryCode(countryCode),\n      raw: result,\n    };\n  }\n}\n"],"names":[],"mappings":"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"}